@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/proxy/socketTracker.ts

@@ -1,639 +0,0 @@
-import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { promisify } from "node:util";
-import { z } from "zod";
-import { logger } from "./logger";
-
-const execFileAsync = promisify(execFile);
-
-type ClientInfo = {
-  port: number | null;
-  pid: number | null;
-  cwd: string | null;
-  projectFolder: string | null;
-};
-
-type CacheEntry = ClientInfo & {
-  expiresAt: number;
-};
-
-type NetstatClient = {
-  pid: number;
-  localPort: number;
-};
-
-// Cache entries: port -> { pid, cwd, projectFolder, expiresAt }
-const cache = new Map<number, CacheEntry>();
-const CACHE_TTL_MS = 5 * 60 * 1000;
-const MAX_CACHE_SIZE = 200;
-const RemotePortSchema = z.number().int().min(1).max(65_535);
-const SocketSchema = z
-  .object({
-    remotePort: RemotePortSchema.nullish(),
-  })
-  .passthrough();
-
-// Deduplicate concurrent lookups for the same port
-const inflight = new Map<number, Promise<ClientInfo>>();
-
-// --- Recent-client scan cache -------------------------------------------
-// `getClientInfo` no longer needs a per-request client port; it scans all
-// current connections to our listen port and returns the freshest. We cache
-// the result for a short window so a burst of requests from one client
-// converges on a single subprocess call.
-const RECENT_CLIENT_TTL_MS = 1000;
-let recentInflight: Promise<ClientInfo> | null = null;
-let recentCache: ClientInfo | null = null;
-let recentCacheExpiresAt = 0;
-
-/** The port the proxy is listening on. Falls back to the dev default. */
-function getProxyPort(): number {
-  // The proxy server exposes its chosen port via the `PROXY_PORT` env var.
-  // Default to the well-known dev port so the scan still works in dev mode
-  // (where `proxy.ts` reads from `getConfig()` instead of an env var).
-  const raw = process.env["PROXY_PORT"];
-  if (raw !== undefined) {
-    const parsed = parseInt(raw, 10);
-    if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535) return parsed;
-  }
-  return 9527;
-}
-
-function getRecentClientFromCache(): ClientInfo | null {
-  if (recentCache === null) return null;
-  if (Date.now() >= recentCacheExpiresAt) {
-    recentCache = null;
-    return null;
-  }
-  return recentCache;
-}
-
-function setRecentClientCache(info: ClientInfo): void {
-  recentCache = info;
-  recentCacheExpiresAt = Date.now() + RECENT_CLIENT_TTL_MS;
-}
-
-function evictCacheIfNeeded(): void {
-  while (cache.size > MAX_CACHE_SIZE) {
-    const oldestKey = cache.keys().next().value;
-    if (oldestKey === undefined) break;
-    cache.delete(oldestKey);
-  }
-}
-
-function getFromCache(port: number): ClientInfo | null {
-  const entry = cache.get(port);
-  if (entry && Date.now() < entry.expiresAt) {
-    return { port: entry.port, pid: entry.pid, cwd: entry.cwd, projectFolder: entry.projectFolder };
-  }
-  if (entry) cache.delete(port);
-  return null;
-}
-
-function setCache(port: number, info: ClientInfo): void {
-  cache.set(port, { ...info, expiresAt: Date.now() + CACHE_TTL_MS });
-  evictCacheIfNeeded();
-}
-
-/**
- * Best-effort remote-port extraction across runtimes. Tries, in order:
- * 1. TanStack Start / Nitro: `request.context.nitro.node.req.socket` (h3
- *    wraps the underlying Node request, where the socket lives).
- * 2. Bun-style: `request.socket` accessor.
- * 3. Direct `socket` / `connection` properties on the request (legacy Node
- *    IncomingMessage-style wrapping).
- * Returns `null` when nothing matches 鈥?the caller will then leave `pid`
- * (and downstream `clientPid`) as `null`.
- */
-export function extractRemotePort(request: Request): number | null {
-  const candidateSockets: unknown[] = [];
-
-  // 1) Nitro / h3 path. TanStack Start attaches the h3 event under
-  //    `request.context.nitro`, and the underlying Node request lives at
-  //    `event.node.req`. The socket may be on `req.socket` or
-  //    `req.connection` depending on the Node version / TLS config.
-  const requestAsUnknown: unknown = request;
-  const ctx = pick(requestAsUnknown, "context");
-  const nitro = pick(ctx, "nitro");
-  const node = pick(nitro, "node");
-  const innerReq = pick(node, "req");
-  const sock = pick(innerReq, "socket") ?? pick(innerReq, "connection");
-  if (sock !== undefined) candidateSockets.push(sock);
-
-  // 2) Bun-style direct socket accessor on the Request.
-  const descriptor = Object.getOwnPropertyDescriptor(request, "socket");
-  if (descriptor !== undefined && descriptor.get === undefined) {
-    candidateSockets.push(descriptor.value);
-  }
-
-  // 3) Raw socket/connection properties on the request itself.
-  const directSocket = pick(requestAsUnknown, "socket");
-  if (directSocket !== undefined) candidateSockets.push(directSocket);
-  const directConnection = pick(requestAsUnknown, "connection");
-  if (directConnection !== undefined) candidateSockets.push(directConnection);
-
-  for (const candidate of candidateSockets) {
-    const parsed = SocketSchema.safeParse(candidate);
-    if (!parsed.success) continue;
-    const remotePort = parsed.data.remotePort;
-    if (remotePort === undefined || remotePort === null) continue;
-    return remotePort;
-  }
-  return null;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return value !== undefined && value !== null && typeof value === "object";
-}
-
-/** Read a property from an `unknown` without triggering lint rules that
- *  forbid type assertions. Returns `undefined` for non-object inputs or
- *  when the property is missing. */
-function pick(value: unknown, key: string): unknown {
-  if (!isObject(value)) return undefined;
-  return value[key];
-}
-
-function parseCommandLine(
-  commandLine: string,
-  sep: string,
-): { cwd: string | null; projectFolder: string | null } {
-  if (!commandLine) return { cwd: null, projectFolder: null };
-  const exeMatch = commandLine.match(/^"([^"]+)"/) || commandLine.match(/^([^\s]+)/);
-  if (exeMatch?.[1] !== undefined) {
-    const exePath = exeMatch[1];
-    const lastSep = exePath.lastIndexOf(sep);
-    if (lastSep > 0) {
-      const exeDir = exePath.substring(0, lastSep);
-      return { cwd: exeDir, projectFolder: exeDir.split(sep).pop() ?? null };
-    }
-  }
-  return { cwd: null, projectFolder: null };
-}
-
-/**
- * Get the working directory and command line for a process by PID.
- */
-async function lookupProcessInfo(
-  pid: number,
-): Promise<{ cwd: string | null; projectFolder: string | null }> {
-  const platform = process.platform;
-
-  try {
-    if (platform === "win32") {
-      const psScript = [
-        `$proc = Get-CimInstance Win32_Process -Filter "ProcessId=${pid}" -ErrorAction SilentlyContinue`,
-        `if ($proc) { Write-Output $proc.CommandLine }`,
-      ].join("; ");
-      const { stdout } = await execFileAsync(
-        "powershell.exe",
-        ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", psScript],
-        {
-          windowsHide: true,
-          timeout: 3000,
-          maxBuffer: 64 * 1024,
-        },
-      );
-      const commandLine = stdout.trim();
-      if (commandLine.length > 0) return parseCommandLine(commandLine, "\\");
-    } else {
-      try {
-        const raw = await readFile(`/proc/${String(pid)}/cmdline`, "utf8");
-        const commandLine = raw.replace(/\0/g, " ").trim();
-        if (commandLine) {
-          return parseCommandLine(commandLine, "/");
-        }
-      } catch {
-        // Fall back to ps
-      }
-
-      if (platform === "darwin") {
-        const { stdout } = await execFileAsync("ps", ["-p", String(pid), "-o", "comm="], {
-          timeout: 3000,
-          maxBuffer: 64 * 1024,
-        });
-        const exePath = stdout.trim();
-        if (exePath) {
-          return parseCommandLine(exePath, "/");
-        }
-      }
-    }
-    return { cwd: null, projectFolder: null };
-  } catch {
-    return { cwd: null, projectFolder: null };
-  }
-}
-
-/**
- * Scan the OS connection table for the freshest client鈫抪roxy connection and
- * return the matching PID plus its cwd/projectFolder.
- */
-async function lookupRecentClient(): Promise<ClientInfo> {
-  const port = getProxyPort();
-  const platform = process.platform;
-  try {
-    if (platform === "win32") {
-      // `Get-NetTCPConnection` can take several seconds on busy Windows
-      // machines, which makes direct-port clients (notably MiMo Code) lose
-      // their PID before the fallback completes. `netstat` streams quickly
-      // and includes the owning process id for established loopback rows.
-      const { stdout } = await execFileAsync("netstat.exe", ["-ano", "-p", "TCP"], {
-        windowsHide: true,
-        timeout: 2000,
-        maxBuffer: 2 * 1024 * 1024,
-      });
-      const client = pickNewestClientFromWindowsNetstat(stdout.split("\n"), port);
-      if (client === null) {
-        return { port: null, pid: null, cwd: null, projectFolder: null };
-      }
-      const { cwd, projectFolder } = await lookupProcessInfo(client.pid);
-      return {
-        port: client.localPort,
-        pid: client.pid,
-        cwd,
-        projectFolder,
-      };
-    }
-
-    // Unix: netstat with -p prints `pid/program` next to each entry. Pick
-    // the row matching our proxy port on the remote side (i.e. the client's
-    // ephemeral port + the proxy's listen port). When multiple clients are
-    // connected we take the highest ephemeral port 鈥?Linux/macOS assign
-    // ports in ascending order, so the largest one is the freshest.
-    const lines = await readUnixEstablishedConnectionLines(port);
-    const clientPid = pickNewestClientPidFromNetstat(lines, port);
-    if (clientPid === null) {
-      return { port: null, pid: null, cwd: null, projectFolder: null };
-    }
-    const { cwd, projectFolder } = await lookupProcessInfo(clientPid);
-    return { port: null, pid: clientPid, cwd, projectFolder };
-  } catch (err) {
-    logger.debug(`[socketTracker] Recent-client lookup failed for port ${port}:`, String(err));
-    return { port: null, pid: null, cwd: null, projectFolder: null };
-  }
-}
-
-/** Parse the output of `netstat -tanp` (or `ss -tanp`) and return the PID
- *  on the most recently opened client-side connection to `proxyPort`. */
-function pickNewestClientPidFromNetstat(lines: string[], proxyPort: number): number | null {
-  const proxyToken = `:${proxyPort}`;
-  type Row = { pid: number; localPort: number; order: number };
-  const candidates: Row[] = [];
-  let order = 0;
-  for (const line of lines) {
-    order++;
-    const cols = line.trim().split(/\s+/);
-    if (cols.length < 5) continue;
-    const localAddr = cols[3] ?? "";
-    const remoteAddr = cols[4] ?? "";
-    const pidField = cols[6] ?? "";
-    // Client-side rows: `RemoteAddress` (5th col) is the proxy's listen port;
-    // `LocalAddress` (4th col) is the client's ephemeral port.
-    if (!remoteAddr.endsWith(proxyToken)) continue;
-    const pidMatch = pidField.match(/^(\d+)/) ?? line.match(/pid=(\d+)/);
-    if (pidMatch === null) continue;
-    const pid = parseInt(pidMatch[1] ?? "", 10);
-    if (!Number.isInteger(pid) || pid <= 0) continue;
-    const localPortMatch = localAddr.match(/:(\d+)$/);
-    const localPort = localPortMatch !== null ? parseInt(localPortMatch[1] ?? "", 10) : 0;
-    candidates.push({ pid, localPort, order });
-  }
-  if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.localPort - a.localPort || b.order - a.order);
-  return candidates[0]?.pid ?? null;
-}
-
-async function readUnixEstablishedConnectionLines(port: number): Promise<string[]> {
-  const commands = [
-    { command: "netstat", args: ["-tanp"] },
-    { command: "ss", args: ["-tanp"] },
-  ];
-  for (const spec of commands) {
-    try {
-      const { stdout } = await execFileAsync(spec.command, spec.args, {
-        timeout: 2000,
-        maxBuffer: 2 * 1024 * 1024,
-      });
-      const portToken = `:${port}`;
-      const lines = stdout
-        .trim()
-        .split("\n")
-        .filter((line) => line.includes(portToken) && line.includes("ESTAB"));
-      if (lines.length > 0) return lines;
-    } catch {
-      // Try the next socket table command.
-    }
-  }
-  return [];
-}
-
-function parseAddressPort(address: string): number | null {
-  const match = address.match(/:(\d+)$/);
-  if (match === null) return null;
-  const parsed = parseInt(match[1] ?? "", 10);
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65_535) return null;
-  return parsed;
-}
-
-function pickNewestClientFromWindowsNetstat(
-  lines: string[],
-  proxyPort: number,
-): NetstatClient | null {
-  const proxyToken = `:${proxyPort}`;
-  type Row = NetstatClient & { order: number };
-  const candidates: Row[] = [];
-  let order = 0;
-
-  for (const line of lines) {
-    order++;
-    const cols = line.trim().split(/\s+/);
-    if (cols.length < 5) continue;
-    const localAddr = cols[1] ?? "";
-    const remoteAddr = cols[2] ?? "";
-    const state = cols[3] ?? "";
-    const pidStr = cols[4] ?? "";
-    if (state !== "ESTABLISHED") continue;
-    if (!remoteAddr.endsWith(proxyToken)) continue;
-
-    const localPort = parseAddressPort(localAddr);
-    if (localPort === null || localPort === proxyPort) continue;
-
-    const pid = parseInt(pidStr, 10);
-    if (!Number.isInteger(pid) || pid <= 0) continue;
-    candidates.push({ pid, localPort, order });
-  }
-
-  if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.localPort - a.localPort || b.order - a.order);
-  const selected = candidates[0];
-  if (selected === undefined) return null;
-  return { pid: selected.pid, localPort: selected.localPort };
-}
-
-export function _pickNewestClientFromWindowsNetstatForTests(
-  lines: string[],
-  proxyPort: number,
-): NetstatClient | null {
-  return pickNewestClientFromWindowsNetstat(lines, proxyPort);
-}
-
-export function _pickNewestClientPidFromNetstatForTests(
-  lines: string[],
-  proxyPort: number,
-): number | null {
-  return pickNewestClientPidFromNetstat(lines, proxyPort);
-}
-
-/** Custom request headers the client (or a wrapper script) may set so we
- *  can identify the originating process without scanning the OS connection
- *  table. Recognized names:
- *   - `X-Agent-Inspector-Client-Pid`
- *   - `X-Agent-Inspector-Client-Port`
- *   - `X-Agent-Inspector-Client-Cwd`
- *   - `X-Agent-Inspector-Client-Project-Folder`
- *  Clients should set these via a small launcher script that exports the
- *  values from `$$` and `pwd` before invoking the AI tool, e.g.:
- *
- *      curl -H "X-Agent-Inspector-Client-Pid: $$" \
- *           -H "X-Agent-Inspector-Client-Cwd: $(pwd)" ...
- */
-const CLIENT_HEADERS = {
-  pid: "x-agent-inspector-client-pid",
-  port: "x-agent-inspector-client-port",
-  cwd: "x-agent-inspector-client-cwd",
-  projectFolder: "x-agent-inspector-client-project-folder",
-} as const;
-
-/** Try to read a positive-integer value out of a header. Returns `null` for
- *  missing / malformed values. */
-function readIntHeader(headers: Headers, name: string): number | null {
-  const raw = headers.get(name);
-  if (raw === null || raw === "") return null;
-  const parsed = parseInt(raw, 10);
-  if (!Number.isInteger(parsed) || parsed < 0) return null;
-  return parsed;
-}
-
-/** Read client-supplied headers. Returns `null` when no PID header is
- *  present 鈥?caller falls back to OS scanning. */
-function readClientHeaders(request: Request): ClientInfo | null {
-  const pid = readIntHeader(request.headers, CLIENT_HEADERS.pid);
-  if (pid === null || pid === 0) return null;
-  const port = readIntHeader(request.headers, CLIENT_HEADERS.port);
-  const cwd = request.headers.get(CLIENT_HEADERS.cwd);
-  const projectFolder = request.headers.get(CLIENT_HEADERS.projectFolder);
-  return {
-    pid,
-    port: port !== null && port > 0 ? port : null,
-    cwd: cwd !== null && cwd !== "" ? cwd : null,
-    projectFolder: projectFolder !== null && projectFolder !== "" ? projectFolder : null,
-  };
-}
-
-/**
- * Get client info (PID, CWD, project folder) for the request that triggered
- * this call. The TanStack Start fetch-API `Request` does not expose the
- * underlying TCP socket (no `request.socket`, no `event.node.req`), so we
- * cannot derive the per-request client port from the request itself.
- *
- * Strategy: enumerate the OS-level TCP connections to our proxy's listen
- * port and pick the most recently established client-side connection. This
- * is essentially "who is currently talking to us" 鈥?for a session with many
- * rapid-fire requests the same client holds a long-lived connection, so
- * consecutive lookups within the cache TTL converge on the same PID.
- *
- * Deduplicates concurrent lookups with a single in-flight promise. Results
- * are cached by PID for `RECENT_CLIENT_TTL_MS` to avoid spawning a
- * `Get-NetTCPConnection` / `ss` subprocess on every single request.
- */
-export async function getClientInfo(request: Request): Promise<ClientInfo> {
-  // Preferred path: explicit client identity in headers. AI coding tools
-  // (or the wrapper scripts that launch them) attach
-  // `X-Agent-Inspector-Client-Pid` (and optionally 鈥?Cwd /
-  // 鈥?Project-Folder / 鈥?Port) so we never have to guess.
-  const fromHeaders = readClientHeaders(request);
-  if (fromHeaders !== null) return fromHeaders;
-
-  const remotePort = extractRemotePort(request);
-  if (remotePort !== null) {
-    const cachedPort = getFromCache(remotePort);
-    if (cachedPort !== null) return cachedPort;
-
-    const existingPortLookup = inflight.get(remotePort);
-    if (existingPortLookup !== undefined) return existingPortLookup;
-
-    const portLookup = lookupClientByPort(remotePort)
-      .then((info) => {
-        setCache(remotePort, info);
-        inflight.delete(remotePort);
-        return info;
-      })
-      .catch((err) => {
-        inflight.delete(remotePort);
-        logger.debug(`[socketTracker] Remote-port lookup failed for ${remotePort}:`, String(err));
-        const fallback: ClientInfo = {
-          port: remotePort,
-          pid: null,
-          cwd: null,
-          projectFolder: null,
-        };
-        setCache(remotePort, fallback);
-        return fallback;
-      });
-
-    inflight.set(remotePort, portLookup);
-    return portLookup;
-  }
-
-  // Fallback: scan the OS connection table for the most recently opened
-  // client鈫抪roxy connection. Best-effort 鈥?in environments with many
-  // long-lived keep-alive connections (browsers, background processes) the
-  // picked connection may not belong to the current request.
-  const cached = getRecentClientFromCache();
-  if (cached !== null) return cached;
-
-  const existing = recentInflight;
-  if (existing) return existing;
-
-  const promise = lookupRecentClient()
-    .then((info) => {
-      setRecentClientCache(info);
-      recentInflight = null;
-      return info;
-    })
-    .catch((err) => {
-      recentInflight = null;
-      logger.debug(`[socketTracker] Recent-client lookup failed:`, String(err));
-      return { port: null, pid: null, cwd: null, projectFolder: null };
-    });
-
-  recentInflight = promise;
-  return promise;
-}
-
-/**
- * Lookup the PID owning a specific client-side local port, then enrich it
- * with the process's cwd / project folder. Used by the identity-injecting
- * native HTTP proxy in `identityProxy.ts`, which has access to
- * `req.socket.remotePort` (the client's ephemeral port) and needs to know
- * which process opened the connection.
- *
- * Results are cached by `clientPort` for `PORT_LOOKUP_TTL_MS` 鈥?a single
- * keep-alive connection typically reuses the same client port for many
- * requests, so we don't want to spawn a subprocess per request.
- */
-const PORT_LOOKUP_TTL_MS = 5 * 60 * 1000;
-const portInfoCache = new Map<number, { info: ClientInfo; expiresAt: number }>();
-
-export async function lookupClientByPort(clientPort: number): Promise<ClientInfo> {
-  if (!Number.isInteger(clientPort) || clientPort <= 0 || clientPort > 65_535) {
-    return { port: null, pid: null, cwd: null, projectFolder: null };
-  }
-  const cached = portInfoCache.get(clientPort);
-  if (cached !== undefined && Date.now() < cached.expiresAt) {
-    return cached.info;
-  }
-  try {
-    const pid = await lookupPidByLocalPort(clientPort);
-    if (pid === null) {
-      const fallback: ClientInfo = {
-        port: clientPort,
-        pid: null,
-        cwd: null,
-        projectFolder: null,
-      };
-      portInfoCache.set(clientPort, { info: fallback, expiresAt: Date.now() + PORT_LOOKUP_TTL_MS });
-      return fallback;
-    }
-    const { cwd, projectFolder } = await lookupProcessInfo(pid);
-    const info: ClientInfo = { port: clientPort, pid, cwd, projectFolder };
-    portInfoCache.set(clientPort, { info, expiresAt: Date.now() + PORT_LOOKUP_TTL_MS });
-    return info;
-  } catch (err) {
-    logger.debug(`[socketTracker] lookupClientByPort(${clientPort}) failed:`, String(err));
-    return { port: clientPort, pid: null, cwd: null, projectFolder: null };
-  }
-}
-
-/** Returns the PID owning `clientPort` on the local machine, or `null`
- *  if the port isn't held by any known process. Cross-platform wrapper
- *  around the OS-specific connection table. */
-async function lookupPidByLocalPort(clientPort: number): Promise<number | null> {
-  const platform = process.platform;
-  try {
-    if (platform === "win32") {
-      // `Get-NetTCPConnection -LocalPort` can enumerate the entire socket table
-      // before filtering on busy machines. `netstat.exe` streams quickly and
-      // avoids PowerShell process startup for this hot lookup path.
-      //
-      // `netstat -ano` lists every TCP connection twice: once for each endpoint.
-      //
-      //   Proto  LocalAddress        RemoteAddress       State            PID
-      //   TCP    [::1]:25949         [::1]:55193         ESTABLISHED     10936   鈫?server-side row (proxy owns the listener)
-      //   TCP    [::1]:55193         [::1]:25949         ESTABLISHED     29356   鈫?client-side row (curl owns the ephemeral port)
-      //
-      // For `clientPort` (the client's ephemeral port) we want the row
-      // whose LOCAL column ends with `:<clientPort>` 鈥?that's the row
-      // attributed to the client process.
-      const { stdout } = await execFileAsync("netstat.exe", ["-ano", "-p", "TCP"], {
-        windowsHide: true,
-        timeout: 2000,
-        maxBuffer: 2 * 1024 * 1024,
-      });
-      const clientToken = `:${clientPort}`;
-      for (const rawLine of stdout.split("\n")) {
-        const line = rawLine.trim();
-        if (line === "") continue;
-        const cols = line.split(/\s+/);
-        if (cols.length < 5) continue;
-        const localAddr = cols[1] ?? "";
-        const state = cols[3] ?? "";
-        if (state !== "ESTABLISHED") continue;
-        if (!localAddr.endsWith(clientToken)) continue;
-        const pidStr = cols[cols.length - 1] ?? "";
-        const parsed = parseInt(pidStr, 10);
-        if (Number.isInteger(parsed) && parsed > 0) return parsed;
-      }
-      return null;
-    }
-    // Unix: try `ss` first, fall back to `lsof`. Both need root or
-    // CAP_NET_ADMIN to see PIDs of processes owned by other users; when
-    // permission is denied the command exits non-zero and we return null.
-    try {
-      const { stdout } = await execFileAsync(
-        "ss",
-        ["-tanp", "state", "established", "sport", `= :${clientPort}`],
-        {
-          timeout: 2000,
-          maxBuffer: 2 * 1024 * 1024,
-        },
-      );
-      const match = stdout.match(/pid=(\d+)/);
-      if (match !== null) {
-        const parsed = parseInt(match[1] ?? "", 10);
-        if (Number.isInteger(parsed) && parsed > 0) return parsed;
-      }
-    } catch {
-      // fall through
-    }
-    try {
-      const { stdout } = await execFileAsync(
-        "lsof",
-        ["-ti", `tcp:${clientPort}`, "-sTCP:ESTABLISHED"],
-        {
-          timeout: 2000,
-          maxBuffer: 64 * 1024,
-        },
-      );
-      const trimmed = stdout.trim().split("\n")[0] ?? "";
-      const parsed = parseInt(trimmed, 10);
-      if (Number.isInteger(parsed) && parsed > 0) return parsed;
-    } catch {
-      // fall through
-    }
-    return null;
-  } catch (err) {
-    logger.debug(`[socketTracker] lookupPidByLocalPort(${clientPort}) failed:`, String(err));
-    return null;
-  }
-}