@bitkyc08/opencodex 2.68.0-preview.20260927 → 2.69.0-preview.20260928

package/src/server/management/model-rows.ts

@@ -26,12 +26,15 @@ import {
   nativeReasoningEfforts,
   uniqueCatalogModelsForPublicList,
   shouldIncludeAccountBoundNativeOpenAi,
+  catalogModelEfforts,
 } from "../../codex/catalog";
+import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../../codex/catalog/native-models";
 import type { ExportModel } from "../../clients/config-export";
 import { providerContextCap } from "../../providers/context-cap";
-import { isVisionReasoningEffort } from "../../reasoning-effort";
+import { isVisionReasoningEffort, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import type { OcxConfig } from "../../types";
+import { enrichProviderFromRegistry } from "../../providers/derive";
 import { ensureCodexEntitlementFreshness } from "../../codex/model-entitlements";
 import { fetchAllModels } from "./shared";
 import { initialModelSelectionPending, pendingModelSelectionProviders } from "../../providers/initial-model-selection";
@@ -56,6 +59,21 @@ export type ManagementModelRow = Partial<CatalogModel> & {
   fastRowAvailable?: boolean;
   displayNameOverride?: string;
   displayNameSource?: "operator" | "provider" | "fallback";
+  /**
+   * The modality declaration a per-model editor writes, read from the same sources the runtime
+   * consults. It is separate from the row's own `inputModalities` because that one is the
+   * CATALOG value: an editor that pre-fills from the catalog while writing the declaration shows
+   * one thing and saves another, so its own writes never appear to take.
+   */
+  inputModalitiesDeclared?: string[];
+  /** Exact stored context override, distinct from the effective catalog window. */
+  contextWindowDeclared?: number;
+  /**
+   * True when the provider config actually CHANGES reasoning for this model. A persisted key is
+   * not proof of an operator edit — OpenCodex itself writes the registry ladder into the provider
+   * config — so this compares values against what the model would inherit anyway.
+   */
+  reasoningOverridden?: boolean;
 };
 
 /** Resolve the exact text and source shown for one routed discovered model. */
@@ -76,6 +94,163 @@ export function effectiveManagementDisplayName(
   return { displayName: catalogModelSlug(model), displayNameSource: "fallback" };
 }
 
+/**
+ * The modality declaration an editor writes, resolved the way the runtime resolves it: an exact
+ * `modelCapabilities` entry first, then the legacy `modelInputModalities` record, both after the
+ * registry has filled in whatever the saved config predates.
+ */
+export function declaredModelInputModalities(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+): string[] | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const enriched = {
+    ...provider,
+    ...(provider.modelInputModalities ? { modelInputModalities: { ...provider.modelInputModalities } } : {}),
+    ...(provider.modelCapabilities ? { modelCapabilities: { ...provider.modelCapabilities } } : {}),
+  };
+  enrichProviderFromRegistry(providerName, enriched);
+  const declared = enriched.modelCapabilities?.[modelId]?.inputModalities
+    ?? modelRecordValue(enriched.modelInputModalities, modelId);
+  return Array.isArray(declared) && declared.length > 0 ? [...declared] : undefined;
+}
+
+/**
+ * The ladder that actually applies to this model: an explicit declaration wins, then the
+ * registry-enriched provider map, then the pinned native OpenAI table for a resold native id,
+ * then the catalog's own effort hints.
+ *
+ * The registry enrichment is not optional. The catalog reads the enriched provider, so a registry
+ * declaration (google-antigravity's `gemini-3.8-flash`, for one) IS the model's ladder; reading
+ * the saved config alone would report no ladder for a model that has one.
+ *
+ * The catalog's own hints are the one source that costs a file read per lookup. `catalogLadders`
+ * is the batched form of it: a roster projection resolves every routed id once and passes the map
+ * down, instead of asking `catalogModelEfforts` per row and re-parsing the same file each time.
+ * Omitting it keeps the single-model behaviour for every other caller.
+ */
+export type CatalogLadderLookup = ReadonlyMap<string, string[]>;
+
+/** Catalog entries for routed rows carry the Codex-facing `provider/model` slug, never the bare id. */
+function catalogLadder(ladders: CatalogLadderLookup | undefined, providerName: string, modelId: string): string[] | undefined {
+  const slug = routedSlug(providerName, modelId);
+  return ladders ? ladders.get(slug) : catalogModelEfforts([slug]).get(slug);
+}
+
+export function effectiveModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, declaredEfforts?: string[], catalogLadders?: CatalogLadderLookup): string[] | undefined {
+  // An empty array is a declaration, not an absence: the operator stored "this model has no
+  // reasoning rungs", and falling through to the inherited ladder here would report a ladder the
+  // row does not have and hand it back to the editor on the next refresh.
+  if (Array.isArray(declaredEfforts)) return declaredEfforts;
+  const provider = config.providers[providerName];
+  if (provider) {
+    const enriched = {
+      ...provider,
+      ...(provider.modelReasoningEfforts ? { modelReasoningEfforts: { ...provider.modelReasoningEfforts } } : {}),
+    };
+    enrichProviderFromRegistry(providerName, enriched);
+    const raw = modelRecordValue(enriched.modelReasoningEfforts, modelId) ?? enriched.reasoningEfforts;
+    // Mirrors `configuredReasoningEfforts`, the reader the wire actually uses: a stored array is a
+    // declaration even when it sanitizes down to nothing, and only a missing entry inherits.
+    if (Array.isArray(raw)) return sanitizeCodexReasoningEfforts(raw) ?? [];
+  }
+  // A provider reselling a native OpenAI id inherits that model's pinned ladder.
+  if (SUPPORTED_NATIVE_OPENAI_SLUGS.has(modelId)) {
+    const native = nativeReasoningEfforts(modelId);
+    if (native.length > 0) return native;
+  }
+  const hits = catalogLadder(catalogLadders, providerName, modelId);
+  if (hits && hits.length > 0) return hits;
+  return undefined;
+}
+
+export function effectiveModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, declaredDefault?: string, efforts?: string[]): string | undefined {
+  if (declaredDefault) return declaredDefault;
+  const provider = config.providers[providerName];
+  if (provider) {
+    const stored = modelRecordValue(provider.modelDefaultReasoningEfforts, modelId);
+    if (stored) return stored;
+  }
+  if (efforts && efforts.length > 0) {
+    // The default is the ladder's own preference order, not its first entry: a model offering
+    // low..high defaults to medium, and only a ladder that omits it falls back to low.
+    if (efforts.includes("medium")) return "medium";
+    if (efforts.includes("low")) return "low";
+    return efforts[0];
+  }
+  return undefined;
+}
+
+/**
+ * Whether the saved config really overrides reasoning for this model, decided by VALUE rather
+ * than by key presence.
+ *
+ * The distinction is the whole point: OpenCodex writes the registry ladder (and its default) into
+ * the provider config itself, so a bare `hasOwnProperty` test reports every registry-declared
+ * model as hand-edited. An entry that resolves to the same ladder and default the model would
+ * inherit anyway is not an override, and an editor that pre-fills an "override" checkbox from one
+ * claims an edit nobody made.
+ */
+export function reasoningOverrideFor(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): boolean {
+  const provider = config.providers[providerName];
+  if (!provider) return false;
+  const owns = (record: Record<string, unknown> | undefined) =>
+    !!record && Object.prototype.hasOwnProperty.call(record, modelId);
+  const ownsEfforts = owns(provider.modelReasoningEfforts as Record<string, unknown> | undefined);
+  const ownsDefault = owns(provider.modelDefaultReasoningEfforts as Record<string, unknown> | undefined);
+  if (!ownsEfforts && !ownsDefault) return false;
+  if (ownsEfforts) {
+    // `undefined` (nothing known) and `[]` (pinned to no rungs) are different facts, and joining
+    // both to "" would report a pinned-empty ladder as no override at all.
+    const ladderKey = (values: string[] | undefined) => (values === undefined ? null : values.join(","));
+    const effective = effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
+    const inherited = inheritedModelReasoningEfforts(config, providerName, modelId, catalogLadders);
+    if (ladderKey(effective) !== ladderKey(inherited)) return true;
+  }
+  if (ownsDefault) {
+    const effective = effectiveModelDefaultReasoningEffort(config, providerName, modelId);
+    const inherited = inheritedModelDefaultReasoningEffort(config, providerName, modelId, catalogLadders);
+    if (effective !== inherited) return true;
+  }
+  return false;
+}
+
+/** The ladder this model inherits when no per-model override exists. */
+export function inheritedModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string[] | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const record = provider.modelReasoningEfforts;
+  if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
+    return effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
+  }
+  const next = { ...record };
+  delete next[modelId];
+  const stripped = { ...provider, modelReasoningEfforts: next };
+  const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
+  return effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders);
+}
+
+/** The default this model inherits when no per-model default override exists. */
+export function inheritedModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const record = provider.modelDefaultReasoningEfforts;
+  if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
+    return effectiveModelDefaultReasoningEffort(
+      config, providerName, modelId, undefined, effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders),
+    );
+  }
+  const next = { ...record };
+  delete next[modelId];
+  const stripped = { ...provider, modelDefaultReasoningEfforts: next };
+  const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
+  return effectiveModelDefaultReasoningEffort(
+    view, providerName, modelId, undefined, effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders),
+  );
+}
+
 /**
  * The exact row list `/api/models` returns. Extracted so `/api/client-config` exports the
  * models the GUI's Models tab shows — including this function's `disabled` computation,
@@ -190,6 +365,11 @@ export async function listManagementModelRows(
   // Custom metadata wins when a physical live/static row resolves to the same Codex-facing
   // slug, while a combo keeps the same precedence it has in routing and /v1/models.
   const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));
+  // One catalog read for the whole roster. Every `catalogModelEfforts` call parses the catalog
+  // file and scans it once per requested slug, so resolving these per row (and twice per row, as
+  // the guard and the value) re-read the same file thousands of times on a large roster.
+  const routedSlugs = publicModels.filter(m => m.provider !== "combo").map(m => routedSlug(m.provider, m.id));
+  const catalogLadders = catalogModelEfforts([...new Set(routedSlugs)]);
   const dedupedRouted = publicModels.map((m): ManagementModelRow | null => {
     // Codex-facing slug (one "/", slug-codec); disabledModels compares tolerate both forms.
     const namespaced = catalogModelSlug(m);
@@ -197,6 +377,16 @@ export async function listManagementModelRows(
     const contextCap = providerContextCap(config, m.provider);
     const nativeAlias = m.provider === "combo" && m.nativeAlias === true;
     const displayName = effectiveManagementDisplayName(config, m);
+    const routed = m.provider !== "combo";
+    // Resolved once each: the spread below used to evaluate the same helpers again for the guard.
+    const reasoningEfforts = routed
+      ? effectiveModelReasoningEfforts(config, m.provider, m.id, m.reasoningEfforts, catalogLadders)
+      : undefined;
+    const defaultReasoningEffort = routed
+      ? effectiveModelDefaultReasoningEffort(config, m.provider, m.id, m.defaultReasoningEffort, reasoningEfforts)
+      : undefined;
+    const inputModalitiesDeclared = routed ? declaredModelInputModalities(config, m.provider, m.id) : undefined;
+    const contextWindowDeclared = routed ? config.providers[m.provider]?.modelContextWindows?.[m.id] : undefined;
     return {
       ...m,
       ...displayName,
@@ -205,6 +395,14 @@ export async function listManagementModelRows(
         (!nativeAlias && stored === namespaced) || slugEquals(stored, m.provider, m.id)
       )),
       ...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
+      // A routed row inherits nothing about reasoning or modalities from the row spread above:
+      // the catalog only carries what discovery reported, so the effective answers are resolved
+      // here, where the config and the registry are both in hand.
+      ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
+      ...(defaultReasoningEffort !== undefined ? { defaultReasoningEffort } : {}),
+      ...(routed ? { reasoningOverridden: reasoningOverrideFor(config, m.provider, m.id, catalogLadders) } : {}),
+      ...(inputModalitiesDeclared !== undefined ? { inputModalitiesDeclared } : {}),
+      ...(contextWindowDeclared !== undefined ? { contextWindowDeclared } : {}),
     };
   }).filter((row): row is ManagementModelRow => row !== null);
   // Manual OpenAI rows retain their routed selector but replace the bare dashboard row.

package/src/server/management/oauth-account-routes.ts

@@ -19,6 +19,7 @@ import {
   getLoginStatus,
   isPublicOAuthProvider,
   listOAuthProviders,
+  OAUTH_PROVIDERS,
   publicOAuthAuthenticationErrorMessage,
   startLoginFlow,
   submitManualLoginCode,
@@ -199,6 +200,13 @@ function metaMuseConsentRequired(provider: string, principal: ManagementContext[
   }, 403);
 }
 
+function genericOAuthProviderConfig(provider: string, config: ManagementContext["config"]) {
+  const configured = config.providers[provider];
+  if (configured) return configured;
+  const definition = OAUTH_PROVIDERS[provider];
+  return definition?.resolveProviderConfig?.(config) ?? definition?.providerConfig;
+}
+
 export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, principal, syncClaudeAgentDefsBestEffort } = ctx;
 
@@ -384,7 +392,10 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const quotaMode = providerOAuthAccountQuotaMode(provider);
     const quotaProvider = config.providers[provider];
     const { getAccountSet } = await import("../../oauth/store");
-    const { kiroAutoSelection } = await import("../../oauth/generic-account-failover");
+    const { isGenericFailoverProvider, kiroAutoSelection } = await import("../../oauth/generic-account-failover");
+    const effectiveProvider = genericOAuthProviderConfig(provider, config);
+    const supportsPause = effectiveProvider !== undefined
+      && isGenericFailoverProvider(provider, effectiveProvider);
     const {
       oauthAccountHealthFields,
       projectOAuthAccountHealth,
@@ -404,6 +415,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
               reauthReason: summary.needsReauth === true ? "refresh_failed" : undefined,
             });
           return { ...summary, ...oauthAccountHealthFields(provider, summary.id, health), quotaMode,
+            ...(supportsPause ? { paused: full?.paused === true } : {}),
             ...(provider === "kiro" && full ? kiroAutoSelection(full) : {}) };
         }),
       };
@@ -449,8 +461,15 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
     if (!body.accountId) return jsonResponse({ error: "missing accountId" }, 400);
-    const { setActiveAccount } = await import("../../oauth/store");
-    if (!(await setActiveAccount(provider, body.accountId))) return jsonResponse({ error: "account not found" }, 404);
+    const { getAccountCredentialWithStatus, setActiveAccount } = await import("../../oauth/store");
+    const current = getAccountCredentialWithStatus(provider, body.accountId);
+    if (!current) return jsonResponse({ error: "account not found" }, 404);
+    if (current.paused) return jsonResponse({ error: "account is paused" }, 409);
+    if (!(await setActiveAccount(provider, body.accountId))) {
+      const latest = getAccountCredentialWithStatus(provider, body.accountId);
+      if (!latest) return jsonResponse({ error: "account not found" }, 404);
+      return jsonResponse({ error: latest.paused ? "account is paused" : "account selection changed" }, 409);
+    }
     const { forgetGenericFailoverRoster } = await import("../../oauth/generic-account-failover");
     forgetGenericFailoverRoster(provider);
     // Seed the rotation cursor on the operator's pick, or a sticky round-robin ring hands the
@@ -472,6 +491,47 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     return jsonResponse({ ok: true, provider, activeAccountId: body.accountId });
   }
 
+  if (url.pathname === "/api/oauth/accounts/pause" && req.method === "PUT") {
+    const body = await readManagementJsonBodyOr(req, {});
+    if (!isPlainRecord(body)) return jsonResponse({ error: "body must be an object" }, 400);
+    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
+    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    if (typeof body.accountId !== "string" || body.accountId.length === 0) {
+      return jsonResponse({ error: "missing accountId" }, 400);
+    }
+    if (typeof body.paused !== "boolean") return jsonResponse({ error: "paused must be a boolean" }, 400);
+
+    const { isGenericFailoverProvider } = await import("../../oauth/generic-account-failover");
+    const effectiveProvider = genericOAuthProviderConfig(provider, config);
+    if (!effectiveProvider || !isGenericFailoverProvider(provider, effectiveProvider)) {
+      return jsonResponse({ error: "account pause is not supported for this OAuth provider" }, 400);
+    }
+
+    const { setAccountPaused } = await import("../../oauth/store");
+    const result = await setAccountPaused(provider, body.accountId, body.paused);
+    if (result.status === "not-found") return jsonResponse({ error: "account not found" }, 404);
+
+    if (result.activeAccountChanged) {
+      const { genericPoolKey, seedPoolRotationAccount } = await import("../../oauth/pool-kernel");
+      seedPoolRotationAccount(genericPoolKey(provider), result.activeAccountId);
+      const { clearModelCache } = await import("../../codex/model-cache");
+      const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
+      clearModelCache(provider);
+      clearGatherRoutedModelsInflight();
+      const { clearProviderQuotaCache } = await import("../../providers/quota");
+      clearProviderQuotaCache();
+    }
+
+    return jsonResponse({
+      ok: true,
+      provider,
+      accountId: body.accountId,
+      paused: body.paused,
+      activeAccountId: result.activeAccountId,
+      activeAccountChanged: result.activeAccountChanged,
+    });
+  }
+
   // The unified pool-settings contract (#695 wp5c). The three legacy paths keep working and
   // keep their own shapes -- goldens pin them -- but this is the one an operator or a dashboard
   // should read, because it answers with the same keys for every kind and DECLARES which of

package/src/server/management/route-registry.ts

@@ -277,6 +277,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PUT", path: "/api/disabled-models", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-discovery", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-presets", module: "server/management/model-routes", mutates: true },
+  { method: "PUT", path: "/api/model-settings", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-visibility", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/selected-models", module: "server/management/model-routes", mutates: true },
   // server/management/native-integration-routes
@@ -319,6 +320,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/providers/keys", module: "server/management/oauth-account-routes", mutates: true },
   { method: "PUT", path: "/api/oauth/accounts/active", module: "server/management/oauth-account-routes", mutates: true },
   { method: "PUT", path: "/api/oauth/accounts/alias", module: "server/management/oauth-account-routes", mutates: true },
+  { method: "PUT", path: "/api/oauth/accounts/pause", module: "server/management/oauth-account-routes", mutates: true },
   { method: "PUT", path: "/api/oauth/accounts/pool", module: "server/management/oauth-account-routes", mutates: true },
   { method: "PUT", path: "/api/providers/keys/active", module: "server/management/oauth-account-routes", mutates: true },
   { method: "PUT", path: "/api/providers/keys/alias", module: "server/management/oauth-account-routes", mutates: true },

package/src/server/port-reclaim.ts

@@ -18,6 +18,16 @@ export type ListenPidScan =
   | { ok: true; pids: number[] }
   | { ok: false; error?: string };
 
+/** One listening socket with its bound local address (host part only). */
+export interface ListenEntry {
+  pid: number;
+  address: string;
+}
+
+export type ListenEntryScan =
+  | { ok: true; listeners: ListenEntry[] }
+  | { ok: false; error?: string };
+
 export type ReclaimListenPortOptions = WaitForPortOptions & {
   /**
    * When true AND `onlyKillPids` is a non-empty allowlist, those PIDs may be
@@ -60,12 +70,49 @@ export type ReclaimListenPortOptions = WaitForPortOptions & {
   sleepMs?: (ms: number) => Promise<void>;
 };
 
+/** Split `host:port`/`[v6]:port` on a numeric port boundary; returns the host part. */
+function listenHost(token: string): string {
+  const bracketed = /^(\[[0-9a-fA-F:.]+\]):/.exec(token);
+  if (bracketed) return bracketed[1].slice(1, -1).toLowerCase();
+  // Only a trailing :<digits> is a port; a bare "::" or hostname wildcard has none.
+  const withPort = /^(.*):(\d+)$/.exec(token);
+  return (withPort ? withPort[1] : token).toLowerCase();
+}
+
+/** Normalize a listen-address host: strips brackets and the IPv4-mapped prefix. */
+export function normalizeListenAddress(token: string): string {
+  let host = listenHost(token);
+  if (host.startsWith("::ffff:")) host = host.slice(7);
+  return host;
+}
+
+/** Normalize a bare bind address (no port): drops brackets, keeps bare IPv6 whole. */
+function bareListenAddress(address: string): string {
+  let host = address.replace(/^\[|\]$/g, "").toLowerCase();
+  if (host.startsWith("::ffff:")) host = host.slice(7);
+  return host;
+}
+
+const WILDCARD_LISTEN_HOSTS = new Set(["", "*", "0.0.0.0", "::"]);
+
 /**
- * Parse `netstat -ano` (Windows) / `netstat -anlp` listen lines for a port.
- * Exported for unit tests.
+ * Whether a socket bound to `listenerAddress` also serves connections to `bound` —
+ * exact match, or a wildcard listener, or a wildcard `bound` (the caller listens on
+ * every address). IPv4-mapped IPv6 forms of the same address are equalized first.
  */
-export function parseListenPidsFromNetstat(output: string, port: number): number[] {
-  const pids = new Set<number>();
+export function listenAddressServes(listenerAddress: string, bound: string): boolean {
+  const listener = normalizeListenAddress(listenerAddress);
+  const want = bareListenAddress(bound);
+  return WILDCARD_LISTEN_HOSTS.has(listener) || WILDCARD_LISTEN_HOSTS.has(want)
+    || listener === want;
+}
+
+/**
+ * Parse `netstat -ano` (Windows) / `netstat -anlp` listen lines for a port, keeping
+ * each distinct PID/address pair. Exported for unit tests.
+ */
+export function parseListenEntriesFromNetstat(output: string, port: number): ListenEntry[] {
+  const entries = new Map<string, ListenEntry>();
   const portSuffix = `:${port}`;
   for (const rawLine of output.split(/\r?\n/)) {
     const line = rawLine.trim();
@@ -88,9 +135,66 @@ export function parseListenPidsFromNetstat(output: string, port: number): number
       : unixPid
         ? Number(unixPid[1])
         : NaN;
-    if (Number.isSafeInteger(pid) && pid > 0) pids.add(pid);
+    if (Number.isSafeInteger(pid) && pid > 0) {
+      const address = normalizeListenAddress(parts[localIdx]);
+      entries.set(`${pid}|${address}`, { pid, address });
+    }
   }
-  return [...pids];
+  return [...entries.values()];
+}
+
+/** Parse netstat LISTEN owners, deduplicating PIDs after preserving their addresses. */
+export function parseListenPidsFromNetstat(output: string, port: number): number[] {
+  return [...new Set(parseListenEntriesFromNetstat(output, port).map(entry => entry.pid))];
+}
+
+/**
+ * Parse `ss -Hltnp` rows for a port, keeping each distinct PID/address pair. A row
+ * without a `pid=` attribution (another user's socket) is dropped rather than
+ * reported unverifiable. Exported for unit tests.
+ */
+export function parseListenEntriesFromSs(output: string, port: number): ListenEntry[] {
+  const entries = new Map<string, ListenEntry>();
+  const portSuffix = `:${port}`;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!/^LISTEN\b/i.test(line)) continue;
+    const parts = line.split(/\s+/);
+    // LISTEN <recv-q> <send-q> <local-addr:port> <peer-addr:port> users:(...)
+    const localIdx = parts.findIndex(part => part.endsWith(portSuffix) || part.endsWith(`]:${port}`));
+    if (localIdx < 0) continue;
+    const pidMatch = /pid=(\d+)/.exec(line);
+    const pid = pidMatch ? Number(pidMatch[1]) : NaN;
+    if (Number.isSafeInteger(pid) && pid > 0) {
+      const address = normalizeListenAddress(parts[localIdx]);
+      entries.set(`${pid}|${address}`, { pid, address });
+    }
+  }
+  return [...entries.values()];
+}
+
+/**
+ * Parse `lsof -nP -iTCP:<port> -sTCP:LISTEN` output (without -t), keeping each
+ * distinct PID/address pair. The NAME column is the last address token, optionally
+ * followed by `(LISTEN)`; skip the header and nonnumeric PIDs. Exported for tests.
+ */
+export function parseListenEntriesFromLsof(output: string, port: number): ListenEntry[] {
+  const entries = new Map<string, ListenEntry>();
+  const portSuffix = `:${port}`;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || /^COMMAND\b/.test(line)) continue;
+    const parts = line.split(/\s+/);
+    const pid = /^\d+$/.test(parts[1] ?? "") ? Number(parts[1]) : NaN;
+    if (!Number.isSafeInteger(pid) || pid <= 0) continue;
+    let addressIdx = parts.length - 1;
+    if (/^\(.*\)$/.test(parts[addressIdx] ?? "")) addressIdx -= 1;
+    const address = parts[addressIdx] ?? "";
+    if (!address.endsWith(portSuffix) && !address.endsWith(`]:${port}`)) continue;
+    const normalized = normalizeListenAddress(address);
+    entries.set(`${pid}|${normalized}`, { pid, address: normalized });
+  }
+  return [...entries.values()];
 }
 
 function normalizeListenPidScan(result: ListenPidScan | number[]): ListenPidScan {
@@ -121,50 +225,84 @@ function readWindowsNetstatAno(): string {
 }
 
 /**
- * Scan for PIDs currently LISTENing on `port`.
- * Distinguishes probe failure (`ok: false`) from a successful empty result.
+ * Scan for the sockets currently LISTENing on `port`, with each listener's bound
+ * local address. Distinguishes probe failure (`ok: false`) from a successful empty
+ * result. POSIX backends are tried in order — `lsof`, `ss` (iproute2, the only
+ * scanner on minimal Linux installs), then `netstat` — and a missing scanner falls
+ * through to the next instead of failing the scan.
  */
-export function scanListenPids(port: number): ListenPidScan {
+export function scanListenEntries(port: number): ListenEntryScan {
   if (!Number.isFinite(port) || port <= 0 || port > 65535) {
     return { ok: false, error: "invalid port" };
   }
+  const scanned = Math.trunc(port);
   try {
     if (process.platform === "win32") {
-      return { ok: true, pids: parseListenPidsFromNetstat(readWindowsNetstatAno(), port) };
+      return { ok: true, listeners: parseListenEntriesFromNetstat(readWindowsNetstatAno(), scanned) };
     }
+    const errors: string[] = [];
     try {
-      const output = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      const output = execFileSync("lsof", ["-nP", `-iTCP:${scanned}`, "-sTCP:LISTEN"], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "ignore"],
         timeout: 3000,
       });
-      return {
-        ok: true,
-        pids: output
-          .split(/\r?\n/)
-          .map(line => Number(line.trim()))
-          .filter(pid => Number.isSafeInteger(pid) && pid > 0),
-      };
-    } catch (lsofErr) {
-      try {
-        const output = execFileSync("netstat", ["-anlp"], {
-          encoding: "utf-8",
-          stdio: ["ignore", "pipe", "ignore"],
-          timeout: 3000,
-        });
-        return { ok: true, pids: parseListenPidsFromNetstat(output, Math.trunc(port)) };
-      } catch (netstatErr) {
-        return {
-          ok: false,
-          error: `lsof/netstat unavailable: ${String(lsofErr)} / ${String(netstatErr)}`,
-        };
-      }
+      return { ok: true, listeners: parseListenEntriesFromLsof(output, scanned) };
+    } catch (error) {
+      errors.push(`lsof: ${String(error)}`);
+    }
+    try {
+      const output = execFileSync("ss", ["-Hltnp"], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 3000,
+      });
+      return { ok: true, listeners: parseListenEntriesFromSs(output, scanned) };
+    } catch (error) {
+      errors.push(`ss: ${String(error)}`);
+    }
+    try {
+      const output = execFileSync("netstat", ["-anlp"], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 3000,
+      });
+      return { ok: true, listeners: parseListenEntriesFromNetstat(output, scanned) };
+    } catch (error) {
+      errors.push(`netstat: ${String(error)}`);
     }
+    return { ok: false, error: `no listener scanner available (${errors.join(" / ")})` };
   } catch (error) {
     return { ok: false, error: String(error) };
   }
 }
 
+/**
+ * Scan for PIDs currently LISTENing on `port`.
+ * Distinguishes probe failure (`ok: false`) from a successful empty result.
+ */
+export function scanListenPids(port: number): ListenPidScan {
+  const scan = scanListenEntries(port);
+  if (!scan.ok) return { ok: false, error: scan.error };
+  return { ok: true, pids: [...new Set(scan.listeners.map(entry => entry.pid))] };
+}
+
+/**
+ * PIDs LISTENing on `port` that actually serve `address`: listeners bound to that
+ * exact address plus wildcards (0.0.0.0/::). A listener on a different loopback or
+ * interface address (e.g. 127.0.0.2 while the tunnel binds 127.0.0.1) never receives
+ * the connection and must not block or qualify a readiness check.
+ */
+export function scanListenPidsForAddress(port: number, address = "127.0.0.1"): ListenPidScan {
+  const scan = scanListenEntries(port);
+  if (!scan.ok) return { ok: false, error: scan.error };
+  const pids = new Set<number>();
+  for (const entry of scan.listeners) {
+    if (listenAddressServes(entry.address, address)) pids.add(entry.pid);
+  }
+  return { ok: true, pids: [...pids] };
+}
+
 /** Best-effort PIDs currently LISTENing on `port`. Empty on probe failure. */
 export function listListenPids(port: number): number[] {
   const scan = scanListenPids(port);