@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/server/management/config-routes.ts

@@ -110,7 +110,7 @@ import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from ".
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
 import type { PersistedUsageAttempt } from "../../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
-import { withProviderServiceTierDTO } from "./provider-capability-config";
+import { withProviderCatalogCapabilityDTO } from "./provider-capability-config";
 import { applySystemEnvToggle } from "../system-env";
 import { getCachedStartupHealth, invalidateStartupHealthCache } from "../startup-health-cache";
 import { runWindowsTrayAction } from "../windows-tray-control";
@@ -186,7 +186,8 @@ interface ClientIntegrationSyncOutcome {
 export async function syncEnabledClientIntegrations(
   port: number | undefined,
   config: OcxConfig,
-  deps: Pick<ManagementContext["deps"], "fetchAllModels" | "writeDesktop3pConfig"> = {},
+  deps: Pick<ManagementContext["deps"],
+    "fetchAllModels" | "refreshOwnedCatalogIntegrations" | "writeDesktop3pConfig"> = {},
 ): Promise<ClientIntegrationSyncOutcome[]> {
   if (port === undefined) return [];
   const { claudeDesktopIntegrationEnabled, grokIntegrationEnabled } = await import("../../codex/desired-state");
@@ -235,7 +236,8 @@ export async function syncEnabledClientIntegrations(
   }
 
   const { refreshOwnedCatalogIntegrations } = await import("../../integrations/catalog-refresh");
-  out.push(...await refreshOwnedCatalogIntegrations({
+  const refreshOwned = deps.refreshOwnedCatalogIntegrations ?? refreshOwnedCatalogIntegrations;
+  out.push(...await refreshOwned({
     models: async () => {
       const { loadExportModels } = await import("./model-rows");
       return loadExportModels(config);
@@ -266,7 +268,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
   const readStartupHealth = deps.getCachedStartupHealth ?? getCachedStartupHealth;
   if (url.pathname === "/api/config" && req.method === "GET") {
-    return jsonResponse(withProviderServiceTierDTO(safeConfigDTO(config), config));
+    return jsonResponse(withProviderCatalogCapabilityDTO(safeConfigDTO(config), config));
   }
 
   if (url.pathname === "/api/config" && req.method === "PUT") {
@@ -324,6 +326,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       // Absent means off, same convention: the GUI renders a plain switch without
       // needing to know that `undefined` and `false` mean the same thing here.
       ultraFastTier: config.ultraFastTier === true,
+      // Absent means on by default: the GUI renders a switch enabled unless explicit false.
+      fastRows: config.fastRows !== false,
       codexMainAccountHardLock: config.codexMainAccountHardLock === true,
       mainAccountHardLock: getMainAccountHardLockStatus(config),
       // Absent means the historical auto-open, so the GUI can render the toggle
@@ -425,6 +429,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexQuotaAutoRefresh?: unknown;
       oauthOpenBrowser?: unknown;
       ultraFastTier?: unknown;
+      fastRows?: unknown;
       codexMainAccountHardLock?: unknown;
       codexDesktopAuthless?: unknown;
       codexClientCompaction?: unknown;
@@ -436,10 +441,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       && body.codexQuotaAutoRefresh === undefined
       && body.oauthOpenBrowser === undefined
       && body.ultraFastTier === undefined
+      && body.fastRows === undefined
       && body.codexMainAccountHardLock === undefined
       && body.codexDesktopAuthless === undefined
       && body.codexClientCompaction === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, codexMainAccountHardLock, codexDesktopAuthless, or codexClientCompaction" }, 400);
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, fastRows, codexMainAccountHardLock, codexDesktopAuthless, or codexClientCompaction" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
@@ -457,6 +463,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (body.ultraFastTier !== undefined && typeof body.ultraFastTier !== "boolean") {
       return jsonResponse({ error: "ultraFastTier boolean is required" }, 400);
     }
+    if (body.fastRows !== undefined && typeof body.fastRows !== "boolean") {
+      return jsonResponse({ error: "fastRows boolean is required" }, 400);
+    }
     if (body.codexMainAccountHardLock !== undefined && typeof body.codexMainAccountHardLock !== "boolean") {
       return jsonResponse({ error: "codexMainAccountHardLock boolean is required" }, 400);
     }
@@ -512,6 +521,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       hasOauthOpenBrowser: Object.hasOwn(config, "oauthOpenBrowser"),
       ultraFastTier: config.ultraFastTier,
       hasUltraFastTier: Object.hasOwn(config, "ultraFastTier"),
+      fastRows: config.fastRows,
+      hasFastRows: Object.hasOwn(config, "fastRows"),
       codexMainAccountHardLock: config.codexMainAccountHardLock,
       hasCodexMainAccountHardLock: Object.hasOwn(config, "codexMainAccountHardLock"),
       codexDesktopAuthless: config.codexDesktopAuthless,
@@ -523,6 +534,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     let pickerIsEnabled = pickerWasEnabled;
     const authlessWasEnabled = config.codexDesktopAuthless === true;
     const clientCompactionWasEnabled = config.codexClientCompaction === true;
+    const fastRowsWasEnabled = config.fastRows !== false;
     try {
       if (typeof body.codexAutoStart === "boolean") {
         config.codexAutoStart = body.codexAutoStart;
@@ -550,6 +562,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       // default, and a written `false` would survive as a decision nobody made.
       if (body.ultraFastTier === true) config.ultraFastTier = true;
       else if (body.ultraFastTier === false) deleteConfigTopLevelKey(config, "ultraFastTier");
+      if (body.fastRows === false) config.fastRows = false;
+      else if (body.fastRows === true) deleteConfigTopLevelKey(config, "fastRows");
       if (body.codexMainAccountHardLock === true) config.codexMainAccountHardLock = true;
       else if (body.codexMainAccountHardLock === false) deleteConfigTopLevelKey(config, "codexMainAccountHardLock");
       if (body.codexDesktopAuthless === true) config.codexDesktopAuthless = true;
@@ -592,6 +606,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (previousSettings.hasUltraFastTier) {
         config.ultraFastTier = previousSettings.ultraFastTier;
       } else deleteConfigTopLevelKey(config, "ultraFastTier");
+      if (previousSettings.hasFastRows) {
+        config.fastRows = previousSettings.fastRows;
+      } else deleteConfigTopLevelKey(config, "fastRows");
       if (previousSettings.hasCodexMainAccountHardLock) {
         config.codexMainAccountHardLock = previousSettings.codexMainAccountHardLock;
       } else deleteConfigTopLevelKey(config, "codexMainAccountHardLock");
@@ -609,6 +626,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     }
     const authlessIsEnabled = config.codexDesktopAuthless === true;
     const clientCompactionIsEnabled = config.codexClientCompaction === true;
+    const fastRowsIsEnabled = config.fastRows !== false;
+    const fastRowsChanged = fastRowsWasEnabled !== fastRowsIsEnabled;
     const desktopSwitchesChanged = authlessWasEnabled !== authlessIsEnabled
       || clientCompactionWasEnabled !== clientCompactionIsEnabled;
     // Catalog convergence is not config injection, and the comment that used to sit here said
@@ -616,9 +635,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     // injector, which is why flipping either switch left `config.toml` in its old shape until
     // a separate `ocx sync` (#4809). Both halves are needed when a Desktop switch changes; a
     // picker-only update still refreshes just the catalog.
-    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled || desktopSwitchesChanged
+    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled || desktopSwitchesChanged || fastRowsChanged
       ? await convergeCodexCatalog()
       : undefined;
+    if (fastRowsChanged) {
+      const { readRuntimePort } = await import("../../config/process-state");
+      const runtime = (deps.readRuntimePort ?? readRuntimePort)(process.pid);
+      await syncEnabledClientIntegrations(runtime?.port, config, deps);
+    }
     // Injection second, matching `syncModelsToCodex`: the injected `model_catalog_json` should
     // point at a catalog that has already settled. And it runs here rather than inside the save
     // because coordinated Codex writes acquire the Codex write lock N before the config mutation
@@ -641,6 +665,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexQuotaAutoRefresh: quotaAutoRefreshSettings(config),
       oauthOpenBrowser: config.oauthOpenBrowser !== false,
       catalogRefreshPending,
+      fastRows: config.fastRows !== false,
       codexDesktopAuthless: authlessIsEnabled,
       codexClientCompaction: clientCompactionIsEnabled,
       codexDesktopSwitches,

package/src/server/management/provider-capability-config.ts

@@ -1,11 +1,7 @@
 import { booleanRecordConfigError } from "../../config/provider-validation";
 import type { OcxConfig } from "../../types";
 
-/**
- * Provider-management validation that belongs to the provider editor, not the
- * request-authentication/CORS boundary. Keeping this here lets the editor
- * evolve its capability schema without widening the auth-cors security surface.
- */
+/** Provider-management validation shared by provider editor write paths. */
 export function providerServiceTierConfigError(name: unknown, provider: unknown): string | null {
   if (typeof name !== "string" || !provider || typeof provider !== "object" || Array.isArray(provider)) {
     return null;
@@ -17,7 +13,20 @@ export function providerServiceTierConfigError(name: unknown, provider: unknown)
   return error ? `provider ${name} ${error}` : null;
 }
 
-function publicServiceTierRecord(value: unknown): Record<string, boolean> | undefined {
+export function providerCatalogCapabilityConfigError(name: unknown, provider: unknown): string | null {
+  const serviceTierError = providerServiceTierConfigError(name, provider);
+  if (serviceTierError) return serviceTierError;
+  if (typeof name !== "string" || !provider || typeof provider !== "object" || Array.isArray(provider)) {
+    return null;
+  }
+  const error = booleanRecordConfigError(
+    (provider as { modelSuppressSyntheticMax?: unknown }).modelSuppressSyntheticMax,
+    "modelSuppressSyntheticMax",
+  );
+  return error ? `provider ${name} ${error}` : null;
+}
+
+function publicBooleanRecord(value: unknown): Record<string, boolean> | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const entries = Object.entries(value).filter(([model, supported]) =>
     model.trim().length > 0 && typeof supported === "boolean",
@@ -40,9 +49,28 @@ export function withProviderServiceTierDTO(dto: unknown, config: OcxConfig): unk
   for (const [name, provider] of Object.entries(config.providers)) {
     const dtoProvider = providers[name];
     if (!dtoProvider || typeof dtoProvider !== "object" || Array.isArray(dtoProvider)) continue;
-    const capabilities = publicServiceTierRecord(provider.modelSupportsServiceTier);
+    const capabilities = publicBooleanRecord(provider.modelSupportsServiceTier);
     if (capabilities === undefined) continue;
     projectedProviders[name] = { ...(dtoProvider as Record<string, unknown>), modelSupportsServiceTier: capabilities };
   }
   return { ...root, providers: projectedProviders };
 }
+
+/** Project all catalog-only model capability maps across the dashboard config boundary. */
+export function withProviderCatalogCapabilityDTO(dto: unknown, config: OcxConfig): unknown {
+  const projected = withProviderServiceTierDTO(dto, config);
+  if (!projected || typeof projected !== "object" || Array.isArray(projected)) return projected;
+  const root = projected as { providers?: unknown };
+  if (!root.providers || typeof root.providers !== "object" || Array.isArray(root.providers)) return projected;
+
+  const providers = root.providers as Record<string, unknown>;
+  const projectedProviders: Record<string, unknown> = { ...providers };
+  for (const [name, provider] of Object.entries(config.providers)) {
+    const dtoProvider = providers[name];
+    if (!dtoProvider || typeof dtoProvider !== "object" || Array.isArray(dtoProvider)) continue;
+    const capabilities = publicBooleanRecord(provider.modelSuppressSyntheticMax);
+    if (capabilities === undefined) continue;
+    projectedProviders[name] = { ...(dtoProvider as Record<string, unknown>), modelSuppressSyntheticMax: capabilities };
+  }
+  return { ...root, providers: projectedProviders };
+}

package/src/server/management/provider-routes.ts

@@ -1,4 +1,5 @@
 import { modelCapabilitiesConfigError, mergeModelCapabilities } from "../../config/provider-validation";
+import { DECLARABLE_HOSTED_TOOL_TYPES } from "../../responses/hosted-tool-policy";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
@@ -103,7 +104,7 @@ import {
   type ProviderEditorConfigDTO,
   type ProviderEditorProviderDTO,
 } from "../auth-cors";
-import { providerServiceTierConfigError } from "./provider-capability-config";
+import { providerCatalogCapabilityConfigError } from "./provider-capability-config";
 import { providerEmptyToolOutputConfigError } from "../../config/provider-validation";
 import { applySystemEnvToggle } from "../system-env";
 import {
@@ -264,7 +265,7 @@ function providerEditorCandidate(
     // the seed check must only pin the canonical transport/auth keys.
     const providerError = providerManagementConfigError(name, transportCandidate, { allowOperatorOverlays: true })
       ?? providerEmptyToolOutputConfigError(name, transportCandidate)
-      ?? providerServiceTierConfigError(name, transportCandidate);
+      ?? providerCatalogCapabilityConfigError(name, transportCandidate);
     if (providerError) return { ok: false, status: 400, error: providerError, code: "invalid_provider" };
     providers[name] = merged;
   }
@@ -516,7 +517,14 @@ function applyProviderPatchFields(
       delete next.modelContextWindows;
     } else {
       if (!isPlainRecord(value)) return { error: "modelContextWindows must be a plain object or null" };
-      const windows: Record<string, number> = { ...(next.modelContextWindows ?? {}) };
+      // A prototype-named model id must survive the merge: assigning
+      // "__proto__" on an ordinary object invokes the inherited setter instead
+      // of creating an own property, so the PATCH would report success while
+      // silently dropping that override.
+      const windows: Record<string, number> = Object.assign(
+        Object.create(null),
+        next.modelContextWindows ?? {},
+      );
       for (const [model, window] of Object.entries(value)) {
         if (!model.trim()) return { error: "modelContextWindows keys must be nonblank model ids" };
         if (window === null) {
@@ -639,6 +647,29 @@ function applyProviderPatchFields(
     }
     touched = true;
   }
+  if (Object.hasOwn(rawBody, "modelSuppressSyntheticMax")) {
+    const value = rawBody.modelSuppressSyntheticMax;
+    if (value === null) {
+      delete next.modelSuppressSyntheticMax;
+    } else {
+      if (!isPlainRecord(value)) return { error: "modelSuppressSyntheticMax must be a plain object or null" };
+      const capabilities: Record<string, boolean> = { ...(next.modelSuppressSyntheticMax ?? {}) };
+      for (const [model, suppressed] of Object.entries(value)) {
+        if (!model.trim()) return { error: "modelSuppressSyntheticMax keys must be nonblank model ids" };
+        if (suppressed === null) {
+          delete capabilities[model];
+          continue;
+        }
+        if (typeof suppressed !== "boolean") {
+          return { error: "modelSuppressSyntheticMax values must be booleans or null" };
+        }
+        capabilities[model] = suppressed;
+      }
+      if (Object.keys(capabilities).length > 0) next.modelSuppressSyntheticMax = capabilities;
+      else delete next.modelSuppressSyntheticMax;
+    }
+    touched = true;
+  }
   if (Object.hasOwn(rawBody, "noStructuredOutputModels")) {
     const value = rawBody.noStructuredOutputModels;
     if (value === null) {
@@ -665,6 +696,26 @@ function applyProviderPatchFields(
     }
     touched = true;
   }
+  if (Object.hasOwn(rawBody, "unsupportedHostedTools")) {
+    const value = rawBody.unsupportedHostedTools;
+    if (value === null) {
+      delete next.unsupportedHostedTools;
+    } else {
+      const error = nonBlankStringArrayConfigError(value, "unsupportedHostedTools");
+      if (error) return { error };
+      const tools = normalizeNonBlankStringArray(value as string[]);
+      const unknownTool = tools.find(tool => !DECLARABLE_HOSTED_TOOL_TYPES.has(tool));
+      if (unknownTool !== undefined) {
+        return {
+          error: `unsupportedHostedTools must name only hosted tool types: `
+            + `${[...DECLARABLE_HOSTED_TOOL_TYPES].join(", ")}`,
+        };
+      }
+      if (tools.length > 0) next.unsupportedHostedTools = tools;
+      else delete next.unsupportedHostedTools;
+    }
+    touched = true;
+  }
   if (Object.hasOwn(rawBody, "retainModels")) {
     const value = rawBody.retainModels;
     if (value === null) {
@@ -864,8 +915,10 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       modelPinnedReasoningEfforts: p.modelPinnedReasoningEfforts,
       modelAutoCompactTokenLimits: p.modelAutoCompactTokenLimits,
       modelSupportsServiceTier: p.modelSupportsServiceTier,
+      modelSuppressSyntheticMax: p.modelSuppressSyntheticMax,
       noStructuredOutputModels: p.noStructuredOutputModels,
       noJsonSchemaModels: p.noJsonSchemaModels,
+      unsupportedHostedTools: p.unsupportedHostedTools,
       retainModels: p.retainModels,
       omitReasoningEffortWithToolsModels: p.omitReasoningEffortWithToolsModels,
       upstreamHttpVersion: p.upstreamHttpVersion,
@@ -1093,8 +1146,8 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     if (rawProvider.upstreamWebsocket !== undefined && typeof rawProvider.upstreamWebsocket !== "boolean") {
       return jsonResponse({ error: "upstreamWebsocket must be a boolean" }, 400);
     }
-    const serviceTierError = providerServiceTierConfigError(name, transportCandidate);
-    if (serviceTierError) return jsonResponse({ error: serviceTierError }, 400);
+    const catalogCapabilityError = providerCatalogCapabilityConfigError(name, transportCandidate);
+    if (catalogCapabilityError) return jsonResponse({ error: catalogCapabilityError }, 400);
     const prov = stripCodexRuntimeProviderFields(transportCandidate as unknown as OcxProviderConfig);
     // PATCH already clears on null; POST persisted the body as submitted, so a `null` here
     // reached disk and the next loadConfig() refused it. Canonicalize to absent, which is what
@@ -1257,19 +1310,18 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       || Object.hasOwn(body.provider, "modelPinnedReasoningEfforts")
       || latest?.pinnedReasoningEffort !== undefined || latest?.modelPinnedReasoningEfforts !== undefined;
     // New registration also edits discovery/disabled-model state; stage those
-    // side effects with the pin draft instead of mutating live state before validation.
-    const registrationDraft = pinsOwned && !latest ? {
+    // side effects with the registration draft instead of mutating live state
+    // before validation.
+    const registrationDraft = !latest ? {
       ...config,
       ...(config.modelDiscovery === undefined ? {} : { modelDiscovery: structuredClone(config.modelDiscovery) }),
     } : undefined;
     initializeProviderModelSelection(name, prov, latest, registrationDraft ?? config);
     const candidate = stripRegistryOnlyStaticHeaders(name, prov);
-    if (pinsOwned) {
-      const draft = { ...(registrationDraft ?? config), providers: { ...config.providers, [name]: candidate },
-        ...(body.setDefault === true ? { defaultProvider: name } : {}) };
-      const validation = validateConfigCandidate(draft);
-      if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
-    }
+    const draft = { ...(registrationDraft ?? config), providers: { ...config.providers, [name]: candidate },
+      ...(body.setDefault === true ? { defaultProvider: name } : {}) };
+    const validation = validateConfigCandidate(draft);
+    if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
     const previous = Object.getOwnPropertyDescriptor(config.providers, name);
     const rollback = pinsOwned ? captureConfigTopLevelRollback(config, ["defaultProvider", "modelDiscovery", "disabledModels"]) : undefined;
     try {
@@ -1397,8 +1449,8 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
           ?? providerEmptyToolOutputConfigError(name, next);
       if (providerError) return jsonResponse({ error: providerError }, 400);
       if (!canonicalBudgetOnly) {
-        const serviceTierError = providerServiceTierConfigError(name, next);
-        if (serviceTierError) return jsonResponse({ error: serviceTierError }, 400);
+        const catalogCapabilityError = providerCatalogCapabilityConfigError(name, next);
+        if (catalogCapabilityError) return jsonResponse({ error: catalogCapabilityError }, 400);
         // Same DNS gate as POST and re-enable: the canonical built-in OpenAI forward
         // provider may resolve through Clash/Mihomo fake-IP DNS (198.18.0.0/15), so the
         // ordinary PATCH must not reject the very same destination the provider was
@@ -1444,9 +1496,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
           return;
         }
         if (!canonicalBudgetOnly) {
-          const serviceTierError = providerServiceTierConfigError(name, replay.next);
-          if (serviceTierError) {
-            replayError = serviceTierError;
+          const catalogCapabilityError = providerCatalogCapabilityConfigError(name, replay.next);
+          if (catalogCapabilityError) {
+            replayError = catalogCapabilityError;
             return;
           }
         }

package/src/server/proxy-liveness.ts

@@ -21,6 +21,12 @@ export interface HealthzIdentity {
   uptime?: unknown;
   pid?: unknown;
   port?: unknown;
+  /**
+   * Which listener answered: the standalone/hub server omits it, and the connected-client
+   * machine listener reports `"client"` (src/client/machine-listener.ts). It is the only
+   * on-the-wire way to tell those two apart, because both bind `config.port ?? 10100`.
+   */
+  role?: unknown;
   restartCapability?: unknown;
   providerReloadCapability?: unknown;
   guiPairCapability?: unknown;
@@ -63,6 +69,22 @@ export const SERVICE_STOP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"> =
   attempts: 3,
 };
 
+/**
+ * Probe budget for a decision whose wrong answer starts a DUPLICATE proxy (#5004).
+ *
+ * `start` used the 750ms single-attempt default for both the pre-bind owner probe and
+ * (implicitly) the busy-port question behind the ephemeral hop. On Windows that answered
+ * "nothing is listening" for a proxy the previous command had just refused to shadow, and
+ * the hop then spawned a second instance that took over this home's pid/runtime records
+ * and re-pointed Codex at itself. A single unanswered probe is not evidence of absence
+ * when the failure mode is a duplicate instance, so the start path borrows the numbers
+ * the stop path already uses for the mirror-image decision.
+ */
+export const START_OWNERSHIP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"> = {
+  timeoutMs: 1500,
+  attempts: 3,
+};
+
 export interface LiveProxy {
   pid: number | null;
   port: number;
@@ -78,6 +100,16 @@ export interface LiveProxy {
    * healthz body predates the field.
    */
   version?: string;
+  /**
+   * Role the live listener reported on `/healthz`, when it reported one: `"client"` for the
+   * connected-client machine listener, absent for a standalone or hub proxy.
+   *
+   * Liveness deliberately still ACCEPTS a client-role listener — see `isOpencodexHealthz`.
+   * The role is carried so a caller that needs a management plane (src/cli/runtime-api.ts)
+   * can refuse one, while `stop` and orphan cleanup keep finding the process they must act
+   * on. Absent for a proxy whose healthz body predates the field.
+   */
+  role?: string;
 }
 
 /**
@@ -101,6 +133,13 @@ export function probeHostname(hostname: string | undefined): string {
  * `service: "opencodex"` marker, plus the legacy `{status, version, uptime}` trio so a
  * still-running pre-identity proxy (e.g. right after `ocx update`) is not mistaken for a
  * foreign server and shadow-started over.
+ *
+ * The connected-client machine listener answers with the same `service: "opencodex"` marker
+ * and an extra `role: "client"`, and it is accepted here on purpose. Liveness answers "is one
+ * of our processes listening on this port", which is exactly what `ocx stop`, orphan cleanup,
+ * and duplicate-start avoidance need: rejecting the client role would make those paths blind to
+ * a real opencodex process and let them shadow-start over it. Callers that additionally need a
+ * management plane discriminate on `LiveProxy.role` instead of narrowing this predicate.
  */
 export function isOpencodexHealthz(body: HealthzIdentity | null): boolean {
   if (!body) return false;
@@ -114,7 +153,7 @@ export async function proxyIdentityAt(
   port: number,
   opts: { hostname?: string; expectedPid?: number } = {},
   io: LivenessIo = {},
-): Promise<{ pid: number | null; version?: string } | null> {
+): Promise<{ pid: number | null; version?: string; role?: string } | null> {
   const fetchFn = io.fetchFn ?? directLocalHttpFetch;
   const sleepFn = io.sleepFn ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
   const nowFn = io.nowFn ?? Date.now;
@@ -139,7 +178,14 @@ export async function proxyIdentityAt(
       if (opts.expectedPid !== undefined && pid !== null && pid !== opts.expectedPid) return null;
       // Guarded the same way `pid` is: a non-string version is absent, not coerced.
       const version = typeof body?.version === "string" ? body.version : undefined;
-      return version === undefined ? { pid } : { pid, version };
+      // Same guard for the role, for the same reason: absent on a standalone/hub proxy and on
+      // a legacy body, and never coerced from a non-string.
+      const role = typeof body?.role === "string" ? body.role : undefined;
+      return {
+        pid,
+        ...(version === undefined ? {} : { version }),
+        ...(role === undefined ? {} : { role }),
+      };
     } catch {
       // Transport failure (timeout / refused) — retry while budget remains; a proxy that
       // has only just begun listening can miss a single short probe (#764).
@@ -203,6 +249,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
           hostname: runtime.hostname,
           source: "runtime",
           ...(identity.version === undefined ? {} : { version: identity.version }),
+          ...(identity.role === undefined ? {} : { role: identity.role }),
         };
       }
     }
@@ -226,6 +273,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
         hostname: record.hostname,
         source: "runtime",
         ...(identity.version === undefined ? {} : { version: identity.version }),
+        ...(identity.role === undefined ? {} : { role: identity.role }),
       };
     }
   }
@@ -241,11 +289,58 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
       hostname: config.hostname,
       source: "config",
       ...(identity.version === undefined ? {} : { version: identity.version }),
+      ...(identity.role === undefined ? {} : { role: identity.role }),
     };
   }
   return null;
 }
 
+/**
+ * Loopback addresses to ask about a port whose holder must be identified before a
+ * decision that is destructive when it answers "nobody".
+ *
+ * A listener and a probe can disagree about what "loopback" means, and on Windows they
+ * do. `startServer` canonicalizes a `localhost` bind to 127.0.0.1 precisely because
+ * Windows resolves the name IPv6-first (src/server/index.ts), while `probeHostname`
+ * hands the literal name back and leaves the family choice to the resolver. A probe that
+ * lands on `::1` while the listener holds `127.0.0.1` reports an empty port that another
+ * process is demonstrably serving. Both literal addresses are therefore asked, cheapest
+ * question first: the extra one costs a refused connection, and skipping it costs a
+ * duplicate proxy.
+ *
+ * A non-loopback bind (a LAN address, a named host) gets exactly one candidate — the
+ * address it was configured with. Guessing another interface for it would answer a
+ * different question than the caller asked.
+ */
+export function loopbackProbeHosts(hostname: string | undefined): string[] {
+  const primary = probeHostname(hostname);
+  if (primary === "127.0.0.1" || /^localhost$/i.test(primary)) return ["127.0.0.1", "[::1]"];
+  if (primary === "[::1]") return ["[::1]", "127.0.0.1"];
+  return [primary];
+}
+
+/**
+ * Identity-checked answer to "who holds this exact port", independent of the pid file
+ * and the runtime-port record.
+ *
+ * `findLiveProxy` answers "is a proxy of this home alive", and it can only do that from
+ * recorded state plus the configured port. This answers the narrower question a start
+ * has to ask before it walks away from a busy port: an opencodex listening THERE, right
+ * now, whatever this home's records say about it. Returns null only after every
+ * candidate address has failed the identity check with the caller's full probe budget.
+ */
+export async function probePortOwner(
+  port: number,
+  opts: { hostname?: string } = {},
+  io: LivenessIo = {},
+): Promise<{ pid: number | null; hostname: string; version?: string; role?: string } | null> {
+  for (const hostname of loopbackProbeHosts(opts.hostname)) {
+    const identity = await proxyIdentityAt(port, { hostname }, io);
+    if (identity) return { ...identity, hostname };
+  }
+  return null;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Readiness (/readyz) strict probe.
 //