switchboard-router 0.9.21 → 0.9.26

package/app/node_modules/next/dist/server/lib/incremental-cache/file-system-cache.js

@@ -310,18 +310,22 @@ class FileSystemCache {
         // Wait for all FS operations to complete.
         await writer.wait();
     }
-    getFilePath(pathname, kind) {
+    getFilePath(key, kind) {
+        let rootDir;
         switch(kind){
             case _responsecache.IncrementalCacheKind.FETCH:
                 // we store in .next/cache/fetch-cache so it can be persisted
                 // across deploys
-                return _path.default.join(this.serverDistDir, '..', 'cache', 'fetch-cache', pathname);
+                rootDir = _path.default.join(this.serverDistDir, '..', 'cache', 'fetch-cache');
+                break;
             case _responsecache.IncrementalCacheKind.PAGES:
-                return _path.default.join(this.serverDistDir, 'pages', pathname);
+                rootDir = _path.default.join(this.serverDistDir, 'pages');
+                break;
             case _responsecache.IncrementalCacheKind.IMAGE:
             case _responsecache.IncrementalCacheKind.APP_PAGE:
             case _responsecache.IncrementalCacheKind.APP_ROUTE:
-                return _path.default.join(this.serverDistDir, 'app', pathname);
+                rootDir = _path.default.join(this.serverDistDir, 'app');
+                break;
             default:
                 throw Object.defineProperty(new Error(`Unexpected file path kind: ${kind}`), "__NEXT_ERROR_CODE", {
                     value: "E479",
@@ -329,6 +333,15 @@ class FileSystemCache {
                     configurable: true
                 });
         }
+        const filePath = _path.default.join(rootDir, key);
+        if (!(filePath.startsWith(rootDir + _path.default.sep) || filePath === rootDir)) {
+            throw Object.defineProperty(new Error(`Invalid file path: ${filePath}`), "__NEXT_ERROR_CODE", {
+                value: "E1468",
+                enumerable: false,
+                configurable: true
+            });
+        }
+        return filePath;
     }
 }
 

package/app/node_modules/next/dist/server/lib/patch-fetch.js

@@ -44,7 +44,7 @@ const _workunitasyncstorageexternal = require("../app-render/work-unit-async-sto
 const _responsecache = require("../response-cache");
 const _cloneresponse = require("./clone-response");
 const _stagedrendering = require("../app-render/staged-rendering");
-const _encodecachetag = require("./encode-cache-tag");
+const _encodeheadersafe = require("./encode-header-safe");
 const isEdgeRuntime = process.env.NEXT_RUNTIME === 'edge';
 const NEXT_PATCH_SYMBOL = Symbol.for('next-patch');
 function isFetchPatched() {
@@ -94,7 +94,7 @@ function validateTags(tags, description) {
             // Encode so a non-ASCII tag can be safely serialized into the
             // `x-next-cache-tags` HTTP header without tripping Node's header
             // validation. Length is checked on the raw input above.
-            validTags.push((0, _encodecachetag.encodeCacheTag)(tag));
+            validTags.push((0, _encodeheadersafe.encodeHeaderSafe)(tag));
         }
         if (validTags.length > _constants1.NEXT_CACHE_TAG_MAX_ITEMS) {
             console.warn(`Warning: exceeded max tag count for ${description}, dropped tags:`, tags.slice(i).join(', '));

package/app/node_modules/next/dist/server/lib/start-server.js

@@ -177,7 +177,7 @@ async function getRequestHandlers({ dir, port, isDev, onDevServerCleanup, server
 async function startServer(serverOptions) {
     const { dir, isDev, hostname, minimalMode, allowRetry, keepAliveTimeout, selfSignedCertificate, serverFastRefresh } = serverOptions;
     let { port } = serverOptions;
-    process.title = `next-server (v${"16.3.0"})`;
+    process.title = `next-server (v${"16.3.4"})`;
     let handlersReady = ()=>{};
     let handlersError = ()=>{};
     let handlersPromise = new Promise((resolve, reject)=>{

package/app/node_modules/next/dist/server/use-cache/handlers.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", {
     getDevTieredCacheHandler: null,
     getPrivateCacheHandler: null,
     initializeCacheHandlers: null,
+    isBuiltInCacheHandler: null,
     isCustomCacheHandler: null,
     isMemoryCacheDisabled: null,
     setCacheHandler: null
@@ -38,6 +39,9 @@ _export(exports, {
     initializeCacheHandlers: function() {
         return initializeCacheHandlers;
     },
+    isBuiltInCacheHandler: function() {
+        return isBuiltInCacheHandler;
+    },
     isCustomCacheHandler: function() {
         return isCustomCacheHandler;
     },
@@ -57,6 +61,7 @@ const handlersSymbol = Symbol.for('@next/cache-handlers');
 const handlersMapSymbol = Symbol.for('@next/cache-handlers-map');
 const handlersSetSymbol = Symbol.for('@next/cache-handlers-set');
 const privateHandlerSymbol = Symbol.for('@next/cache-handlers-private');
+const builtInHandlersSymbol = Symbol.for('@next/cache-handlers-built-in');
 const devFrontHandlersSymbol = Symbol.for('@next/cache-handlers-dev-fronts');
 const devTieredHandlersSymbol = Symbol.for('@next/cache-handlers-dev-tiered');
 const memoryCacheDisabledSymbol = Symbol.for('@next/cache-handlers-memory-disabled');
@@ -80,6 +85,8 @@ function initializeCacheHandlers(cacheMaxMemorySize) {
     debug == null ? void 0 : debug('initializing cache handlers');
     const handlersMap = new Map();
     reference[handlersMapSymbol] = handlersMap;
+    const builtInHandlers = new Set();
+    reference[builtInHandlersSymbol] = builtInHandlers;
     // In development, `cacheMaxMemorySize: 0` would make the built-in default
     // handler a no-op, so every reload would miss. Use a real in-memory size
     // instead so dev stays fast; the "use cache" wrapper forces a dynamic cache
@@ -95,6 +102,7 @@ function initializeCacheHandlers(cacheMaxMemorySize) {
         } else {
             debug == null ? void 0 : debug('setting "default" cache handler from default');
             fallback = (0, _default.createDefaultCacheHandler)(builtInSize);
+            builtInHandlers.add(fallback);
         }
         handlersMap.set('default', fallback);
         if (reference[handlersSymbol].RemoteCache) {
@@ -106,6 +114,7 @@ function initializeCacheHandlers(cacheMaxMemorySize) {
         }
     } else {
         const handler = (0, _default.createDefaultCacheHandler)(builtInSize);
+        builtInHandlers.add(handler);
         debug == null ? void 0 : debug('setting "default" cache handler from default');
         handlersMap.set('default', handler);
         debug == null ? void 0 : debug('setting "remote" cache handler from default');
@@ -166,6 +175,11 @@ function isCustomCacheHandler(kind) {
     }
     return ((_reference_devFrontHandlersSymbol = reference[devFrontHandlersSymbol]) == null ? void 0 : _reference_devFrontHandlersSymbol.has(kind)) ?? false;
 }
+function isBuiltInCacheHandler(kind) {
+    var _reference_handlersMapSymbol, _reference_builtInHandlersSymbol;
+    const handler = (_reference_handlersMapSymbol = reference[handlersMapSymbol]) == null ? void 0 : _reference_handlersMapSymbol.get(kind);
+    return handler !== undefined && Boolean((_reference_builtInHandlersSymbol = reference[builtInHandlersSymbol]) == null ? void 0 : _reference_builtInHandlersSymbol.has(handler));
+}
 function getDevTieredCacheHandler(kind) {
     var _reference_devTieredHandlersSymbol;
     if (!process.env.__NEXT_DEV_SERVER) {

package/app/node_modules/next/dist/server/web/spec-extension/adapters/headers.js

@@ -34,6 +34,66 @@ class ReadonlyHeadersError extends Error {
         throw new ReadonlyHeadersError();
     }
 }
+/**
+ * Builds the read methods for a sealed view that exposes all of `target`.
+ */ function createPassThroughMethods(target, sealed) {
+    return {
+        get: target.get.bind(target),
+        has: target.has.bind(target),
+        getSetCookie: target.getSetCookie.bind(target),
+        keys: target.keys.bind(target),
+        values: target.values.bind(target),
+        entries: target.entries.bind(target),
+        [Symbol.iterator]: target[Symbol.iterator].bind(target),
+        // The native method passes the unsealed target as the callback's `parent`
+        // argument. That is a mutable handle on the underlying headers. Pass the
+        // sealed view instead.
+        forEach (callbackfn, thisArg) {
+            for (const [name, value] of target.entries()){
+                callbackfn.call(thisArg, value, name, sealed);
+            }
+        }
+    };
+}
+/**
+ * Builds the read methods for a sealed view that omits the header names matched
+ * by `isHidden`.
+ */ function createHidingMethods(target, sealed, isHidden) {
+    function* entries() {
+        for (const entry of target.entries()){
+            if (!isHidden(entry[0])) {
+                yield entry;
+            }
+        }
+    }
+    return {
+        entries,
+        [Symbol.iterator]: entries,
+        get: (name)=>isHidden(name) ? null : target.get(name),
+        has: (name)=>isHidden(name) ? false : target.has(name),
+        getSetCookie: ()=>isHidden('set-cookie') ? [] : target.getSetCookie(),
+        *keys () {
+            for (const name of target.keys()){
+                if (!isHidden(name)) {
+                    yield name;
+                }
+            }
+        },
+        *values () {
+            for (const [, value] of entries()){
+                yield value;
+            }
+        },
+        // The native method passes the unsealed target as the callback's `parent`
+        // argument. That is a mutable handle on the underlying headers. Pass the
+        // sealed view instead.
+        forEach (callbackfn, thisArg) {
+            for (const [name, value] of entries()){
+                callbackfn.call(thisArg, value, name, sealed);
+            }
+        }
+    };
+}
 class HeadersAdapter extends Headers {
     constructor(headers){
         // We've already overridden the methods that would be called, so we're just
@@ -98,19 +158,45 @@ class HeadersAdapter extends Headers {
     /**
    * Seals a Headers instance to prevent modification by throwing an error when
    * any mutating method is called.
-   */ static seal(headers) {
-        return new Proxy(headers, {
+   *
+   * The sealed view stays live. Later writes to `headers` remain visible
+   * through it.
+   *
+   * `hidden` omits the given header names from every read operation (`get`,
+   * `has`, `getSetCookie`, `forEach`, and iteration). The names must be
+   * lowercase. The underlying headers are neither copied nor mutated, so hidden
+   * headers remain available to the framework.
+   */ static seal(headers, hidden) {
+        const isHidden = hidden && hidden.size > 0 ? (name)=>hidden.has(name.toLowerCase()) : null;
+        // The methods are built once per sealed view and reused, so repeated access
+        // returns the same function instead of a fresh closure. They are assigned
+        // after the proxy exists because `forEach` hands the proxy to its callback.
+        // Creating the proxy runs no trap, so nothing can read them before then.
+        let methods;
+        const sealed = new Proxy(headers, {
             get (target, prop, receiver) {
                 switch(prop){
                     case 'append':
                     case 'delete':
                     case 'set':
                         return ReadonlyHeadersError.callable;
+                    case Symbol.iterator:
+                        return methods[Symbol.iterator];
+                    case 'get':
+                    case 'has':
+                    case 'getSetCookie':
+                    case 'keys':
+                    case 'values':
+                    case 'entries':
+                    case 'forEach':
+                        return methods[prop];
                     default:
                         return _reflect.ReflectAdapter.get(target, prop, receiver);
                 }
             }
         });
+        methods = isHidden ? createHidingMethods(headers, sealed, isHidden) : createPassThroughMethods(headers, sealed);
+        return sealed;
     }
     /**
    * @param headers

package/app/node_modules/next/dist/shared/lib/router/utils/escape-path-delimiters.js

@@ -10,7 +10,7 @@ Object.defineProperty(exports, "default", {
     }
 });
 function escapePathDelimiters(segment, escapeEncoded) {
-    return segment.replace(new RegExp(`([/#?]${escapeEncoded ? '|%(2f|23|3f|5c)' : ''})`, 'gi'), (char)=>encodeURIComponent(char));
+    return segment.replace(new RegExp(`([/#?\\\\]${escapeEncoded ? '|%(2f|23|3f|5c)' : ''})`, 'gi'), (char)=>encodeURIComponent(char));
 }
 
 //# sourceMappingURL=escape-path-delimiters.js.map

package/app/node_modules/next/dist/telemetry/anonymous-meta.js

@@ -82,7 +82,7 @@ async function getAnonymousMeta() {
         isWsl: _iswsl.default,
         isCI: _ciinfo.isCI,
         ciName: _ciinfo.isCI && _ciinfo.name || null,
-        nextVersion: "16.3.0",
+        nextVersion: "16.3.4",
         agentName: await (0, _agentname.getAgentName)()
     };
     return traits;

package/app/node_modules/next/dist/telemetry/events/swc-load-failure.js

@@ -38,7 +38,7 @@ async function eventSwcLoadFailure(event) {
     telemetry.record({
         eventName: EVENT_PLUGIN_PRESENT,
         payload: {
-            nextVersion: "16.3.0",
+            nextVersion: "16.3.4",
             glibcVersion,
             installedSwcPackages,
             arch: process.arch,

package/app/node_modules/next/dist/telemetry/events/version.js

@@ -12,12 +12,12 @@ const EVENT_VERSION = 'NEXT_CLI_SESSION_STARTED';
 function eventCliSession(nextConfig, event) {
     var _nextConfig_experimental, _nextConfig_experimental_staleTimes, _nextConfig_experimental_staleTimes1, _nextConfig_reactCompiler, _nextConfig_reactCompiler1;
     // This should be an invariant, if it fails our build tooling is broken.
-    if (typeof "16.3.0" !== 'string') {
+    if (typeof "16.3.4" !== 'string') {
         return [];
     }
     const { images, i18n } = nextConfig || {};
     const payload = {
-        nextVersion: "16.3.0",
+        nextVersion: "16.3.4",
         nodeVersion: process.version,
         cliCommand: event.cliCommand,
         isSrcDir: event.isSrcDir,

package/app/node_modules/next/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next",
-  "version": "16.3.0",
+  "version": "16.3.4",
   "description": "The React Framework",
   "main": "./dist/server/next.js",
   "license": "MIT",
@@ -81,8 +81,8 @@
     "next": "./dist/bin/next"
   },
   "dependencies": {
-    "@next/env": "16.3.0",
-    "@swc/helpers": "0.5.15",
+    "@next/env": "16.3.4",
+    "@swc/helpers": "0.5.23",
     "baseline-browser-mapping": "^2.9.19",
     "caniuse-lite": "^1.0.30001579",
     "postcss": "8.5.23",
@@ -111,15 +111,15 @@
     }
   },
   "optionalDependencies": {
-    "sharp": "^0.35.3",
-    "@next/swc-darwin-arm64": "16.3.0",
-    "@next/swc-darwin-x64": "16.3.0",
-    "@next/swc-linux-arm64-gnu": "16.3.0",
-    "@next/swc-linux-arm64-musl": "16.3.0",
-    "@next/swc-linux-x64-gnu": "16.3.0",
-    "@next/swc-linux-x64-musl": "16.3.0",
-    "@next/swc-win32-arm64-msvc": "16.3.0",
-    "@next/swc-win32-x64-msvc": "16.3.0"
+    "sharp": "^0.35.4",
+    "@next/swc-darwin-arm64": "16.3.4",
+    "@next/swc-darwin-x64": "16.3.4",
+    "@next/swc-linux-arm64-gnu": "16.3.4",
+    "@next/swc-linux-arm64-musl": "16.3.4",
+    "@next/swc-linux-x64-gnu": "16.3.4",
+    "@next/swc-linux-x64-musl": "16.3.4",
+    "@next/swc-win32-arm64-msvc": "16.3.4",
+    "@next/swc-win32-x64-msvc": "16.3.4"
   },
   "keywords": [
     "react",

package/app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchboard-app",
-  "version": "0.9.21",
-  "description": "Switchboard — intelligent model routing dashboard",
+  "version": "0.9.26",
+  "description": "Switchboard \u2014 intelligent model routing dashboard",
   "private": true,
   "engines": {
     "node": ">=20.9.0"
@@ -66,7 +66,7 @@
   "optionalDependencies": {
     "better-sqlite3": "^12.6.2"
   },
-  "comment_better_sqlite3": "kept in optionalDependencies so npm install doesn't fail on systems without build tools — sql.js is used as fallback at runtime",
+  "comment_better_sqlite3": "kept in optionalDependencies so npm install doesn't fail on systems without build tools \u2014 sql.js is used as fallback at runtime",
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
     "eslint": "^9.39.4",

package/cli.js

@@ -115,7 +115,9 @@ function commandFor(action = "") {
   return `${commandName}${port === DEFAULT_PORT ? "" : ` --port ${port}`}`;
 }
 
-// C1: bind loopback by default — LAN exposure is an explicit opt-in via --host 0.0.0.0
+// C2: bind all interfaces by default — remote dashboard access works out of
+// the box. Non-local peers sign in with a gateway API key (dashboardGuard
+// session); non-loopback /v1 requires an API key. --host 127.0.0.1 opts out.
 const ALL_INTERFACES = "0.0.0.0";
 
 function isNetworkExposed() {
@@ -575,9 +577,24 @@ async function run() {
         console.log(`Use "${commandFor("restart")}" to replace it.`);
         return 0;
       }
-      console.error(`Port ${port} is already in use by another process (PID: ${remaining.join(", ")}).`);
-      console.error(`Choose another port with --port or stop that process first.`);
-      return 1;
+      // Only listeners that genuinely claim our bind address block startup.
+      // Specific-address listeners (e.g. Tailscale serve holding 100.x.y.z:PORT
+      // and forwarding to loopback) coexist with a wildcard/loopback bind.
+      const portListeners = processTools.findPortListeners(port);
+      const conflictingPids = [
+        ...new Set(portListeners.filter((l) => processTools.listenerConflicts(l, host)).map((l) => l.pid)),
+      ];
+      if (conflictingPids.length > 0) {
+        console.error(`Port ${port} is already in use by another process (PID: ${conflictingPids.join(", ")}).`);
+        console.error(`Choose another port with --port or stop that process first.`);
+        return 1;
+      }
+      const coexisting = portListeners
+        .filter((l) => !processTools.listenerConflicts(l, host))
+        .map((l) => l.address || "unknown");
+      if (coexisting.length > 0) {
+        console.log(`Note: port ${port} also has listeners on other addresses (${[...new Set(coexisting)].join(", ")}) — they will keep their own traffic.`);
+      }
     }
 
     const latestVersion = await checkForUpdate();
@@ -638,7 +655,7 @@ function startServer(latestVersion) {
   // Surface real network exposure for wildcard and specific non-loopback binds.
   if (isNetworkExposed()) {
     const reachableHost = host === ALL_INTERFACES || host === "::" ? getLanIp() : host;
-    if (reachableHost) console.log(`\x1b[33m⚠ Network-exposed: reachable at http://${reachableHost}:${port} (bound ${host}). Use --host 127.0.0.1 for local-only. Non-loopback /v1 requires an API key by default.\x1b[0m`);
+    if (reachableHost) console.log(`\x1b[33m⚠ Network-exposed: dashboard at http://${reachableHost}:${port} (bound ${host}). Remote browsers sign in with a gateway API key; /v1 needs an API key off-loopback. Use --host 127.0.0.1 for local-only.\x1b[0m`);
   }
 
   let consecutiveCrashes = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchboard-router",
-  "version": "0.9.21",
-  "description": "Switchboard CLI — local AI routing gateway (install: npm i -g switchboard-router; run: switchboard)",
+  "version": "0.9.26",
+  "description": "Switchboard CLI \u2014 local AI routing gateway (install: npm i -g switchboard-router; run: switchboard)",
   "bin": {
     "switchboard": "./cli.js",
     "claude-switchboard": "./claude-switchboard.js"
@@ -28,7 +28,6 @@
     "build": "node scripts/build-cli.js",
     "pack:cli": "npm run build && npm pack --pack-destination ..",
     "publish:cli": "npm run build && npm publish",
-    "postinstall": "node hooks/postinstall.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -38,8 +37,8 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
-  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.switchboard/runtime/node_modules by hooks/postinstall.js (and re-checked at runtime by cli.js). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir.",
-  "comment_systray": "System tray uses platform-specific optionalDependencies (esbuild pattern). npm installs only the matching binary for the user's OS/arch. Windows uses PowerShell NotifyIcon (zero binary). Postinstall fallback downloads from GitHub releases if optionalDeps are skipped.",
+  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.switchboard/runtime/node_modules at runtime by cli.js (hooks/sqliteRuntime, self-healing on every start \u2014 the package deliberately ships NO postinstall so npm's allow-scripts guard never fires). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir.",
+  "comment_systray": "System tray uses platform-specific optionalDependencies (esbuild pattern). npm installs only the matching binary for the user's OS/arch. Windows uses PowerShell NotifyIcon (zero binary). Runtime fallback (cli.js ensureTrayRuntime) downloads from GitHub releases if optionalDeps are skipped.",
   "optionalDependencies": {
     "impit-darwin-arm64": "0.14.3",
     "impit-darwin-x64": "0.14.3",

package/src/cli/cliOptions.js

@@ -1,5 +1,8 @@
 const DEFAULT_PORT = 20128;
-const DEFAULT_HOST = "127.0.0.1";
+// Remote-accessible by default: the dashboard answers on all interfaces and
+// gates non-local peers behind API-key sign-in (src/dashboardGuard.js); /v1
+// requires an API key off-loopback. Use --host 127.0.0.1 for a local-only bind.
+const DEFAULT_HOST = "0.0.0.0";
 const COMMANDS = new Set(["start", "status", "stop", "restart", "help", "version"]);
 
 function isLoopbackHost(value) {

package/src/cli/processManager.js

@@ -103,7 +103,83 @@ function findListeningPids(port) {
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5000,
     });
-    return output.split(/\s+/).map(Number).filter((pid) => Number.isInteger(pid) && pid > 1);
+    return output.split(/\s+/).filter((pid) => pid).map(Number).filter((pid) => Number.isInteger(pid) && pid > 1);
+  } catch { return []; }
+}
+
+// ── Listener address awareness ─────────────────────────────────────────────
+// A specific-address listener does not prevent binding another address on the
+// same port: SO_REUSEADDR (set by node and Go listeners) lets specific and
+// wildcard listeners coexist, each keeping its own traffic. This is the
+// Tailscale-serve pattern — tailscaled holds 100.x.y.z:PORT and forwards to
+// 127.0.0.1:PORT, so the app must still be able to take loopback/wildcard.
+
+/** Normalize an lsof NAME / Get-NetTCPConnection LocalAddress value. */
+function parseListenerAddress(raw, type) {
+  let name = String(raw || "").trim().toLowerCase();
+  const typeHint = String(type || "").toLowerCase();
+  let family = null;
+  if (typeHint.includes("v6")) family = 6;
+  else if (typeHint.includes("v4")) family = 4;
+  if (name.startsWith("[")) {
+    // lsof prints IPv6 as [addr]:port
+    const end = name.indexOf("]");
+    name = end === -1 ? name.slice(1) : name.slice(1, end);
+    family = 6;
+  } else if (/^[^:\[\]]+:\d+$/.test(name)) {
+    // host:port with exactly one colon is unambiguous IPv4+port; bare IPv6
+    // literals (Windows LocalAddress) have several colons and stay intact.
+    name = name.replace(/:\d+$/, "");
+  }
+  if (family == null) family = name.includes(":") ? 6 : 4;
+  const wildcard = name === "*" || name === "0.0.0.0" || name === "::" || name === "";
+  return { address: name, family, wildcard };
+}
+
+/** True when a listener would actually prevent/claim the app's bind. */
+function listenerConflicts(listener, bindHost) {
+  const bind = String(bindHost || "0.0.0.0").trim().toLowerCase();
+  const bindFamily = bind.includes(":") ? 6 : 4;
+  const bindWildcard = bind === "0.0.0.0" || bind === "::" || bind === "*";
+  if (!listener || typeof listener !== "object") return true; // unknown → conservative
+  if (listener.wildcard) return listener.family === bindFamily;
+  if (bindWildcard) return false; // specific listener coexists with our wildcard
+  return listener.family === bindFamily && listener.address === bind;
+}
+
+/** All listeners on a port with their bound address: [{pid, address, family, wildcard}]. */
+function findPortListeners(port) {
+  const numericPort = Number(port);
+  if (!Number.isInteger(numericPort) || numericPort < 1 || numericPort > 65535) return [];
+  try {
+    if (process.platform === "win32") {
+      const output = execFileSync("powershell", [
+        "-NonInteractive", "-NoProfile", "-Command",
+        `Get-NetTCPConnection -LocalPort ${numericPort} -State Listen -ErrorAction SilentlyContinue | ForEach-Object { "$($_.LocalAddress) $($_.OwningProcess)" }`,
+      ], { encoding: "utf8", windowsHide: true, timeout: 5000 });
+      return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => {
+        const space = line.lastIndexOf(" ");
+        const parsed = parseListenerAddress(line.slice(0, space));
+        return { pid: Number(line.slice(space + 1)), ...parsed };
+      }).filter((entry) => Number.isInteger(entry.pid) && entry.pid > 1);
+    }
+    const output = execFileSync("lsof", [`-nP`, `-iTCP:${numericPort}`, "-sTCP:LISTEN"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+    const seen = new Set();
+    const listeners = [];
+    for (const line of output.split(/\r?\n/)) {
+      const tokens = line.trim().split(/\s+/);
+      if (tokens.length < 9 || !/^\d+$/.test(tokens[1])) continue;
+      const entry = { pid: Number(tokens[1]), ...parseListenerAddress(tokens[8], tokens[4]) };
+      const key = `${entry.pid}:${entry.address}:${entry.family}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      listeners.push(entry);
+    }
+    return listeners;
   } catch { return []; }
 }
 
@@ -232,6 +308,9 @@ module.exports = {
   acquireLifecycleLock,
   childIsLive,
   findListeningPids,
+  findPortListeners,
+  listenerConflicts,
+  parseListenerAddress,
   getProcessCommand,
   getProcessCwd,
   isPidAlive,