@bitkyc08/opencodex 2.58.0 → 2.60.0

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/management/route-registry.ts

@@ -38,8 +38,17 @@ export type ExemptionReason =
   | "test-seam"
   /** The CLI reaches the same data through a local transport instead of HTTP. */
   | "local-transport"
+  /** Machine scrape target whose HTTP exposition is the operator contract. */
+  | "scrape-target"
   /** Older clients use this alias; the current CLI drives its declared replacement. */
   | "compatibility-alias"
+  /**
+   * A read-only POST whose purpose is to bind an interactive confirmation to the mutation that
+   * immediately follows it. There is no standalone thing for a CLI to do with one: the plan is
+   * only meaningful to the caller that is about to commit it, and a scripted caller drives the
+   * mutation directly.
+   */
+  | "interactive-preview"
   /** Unreachable in the live dispatch order; delete rather than expose. */
   | "dead"
   /**
@@ -159,6 +168,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside history deletion uses the dashboard journal cleanup; the CLI has history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
+  { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/preview", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode", exempt: { reason: "interactive-preview", why: "Plans one Aside profile's change so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives the profile toggle or restore directly." } },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside profile history deletion uses the dashboard journal cleanup; the CLI has scoped history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode" },
   // server/management/codex-prompt-routes
@@ -197,6 +207,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: false },
   { method: "DELETE", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Retiring one rollback row is a dashboard-local cleanup; the CLI verb that would drive it is owed by a later work-phase and is not implemented here.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/restore", module: "server/management/integration-routes", mutates: true },
+  { method: "POST", path: "/api/client-integrations/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an apply, overwrite or disable so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives PUT /api/client-integrations/{clientId} directly." } },
+  { method: "POST", path: "/api/client-integrations/restore/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an undo so drift is shown before a restore rather than discovered by a rejected mutation. Read-only, and useful only to the caller about to commit; a scripted caller drives POST /api/client-integrations/restore directly." } },
   // server/management/lab-automation-routes
   { method: "GET", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/automation/runs", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
@@ -234,6 +246,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/storage/trash/restore", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/debug", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/storage/cleanup-policy", module: "server/management/logs-usage-routes", mutates: true },
+  // server/management/metrics-routes
+  { method: "GET", path: "/api/metrics", module: "server/management/metrics-routes", mutates: false, exempt: { reason: "scrape-target", why: "This machine scrape target exposes authenticated text exposition for monitoring systems; a CLI JSON verb would be a different contract." } },
   // server/management/model-routes
   { method: "GET", path: "/api/aliases", module: "server/management/model-routes", mutates: false },
   { method: "GET", path: "/api/catalog", module: "server/management/model-routes", mutates: false },

package/src/server/management/shared.ts

@@ -245,12 +245,19 @@ export function requestLogDto(
  * share the same fetch, the same per-provider cache (dedups Codex's frequent /v1/models polling),
  * and the same stale fallback when a provider blips, instead of a parallel uncached copy.
  */
-export async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+export async function fetchAllModels(
+  config: OcxConfig,
+  /** Filled with each provider's content revision as of the moment its rows were chosen. */
+  providerContentRevisions?: Map<string, string>,
+): Promise<CatalogModel[]> {
   const { gatherRoutedModels } = await import("../../codex/catalog");
   const baseline = captureInitialSelectionBaseline(config);
-  if (!baseline) return gatherRoutedModels(config);
+  if (!baseline) return gatherRoutedModels(config, providerContentRevisions ? { providerContentRevisions } : undefined);
   const outcomes: Array<{ provider: string; state: "authoritative" | "degraded" }> = [];
-  const models = await gatherRoutedModels(config, { providerModelOutcomes: outcomes });
+  const models = await gatherRoutedModels(config, {
+    providerModelOutcomes: outcomes,
+    ...(providerContentRevisions ? { providerContentRevisions } : {}),
+  });
   finalizeInitialModelSelection(config, baseline, uniqueCatalogModelsForPublicList(models),
     outcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider));
   return models;

package/src/server/management/system-restart.ts

@@ -36,6 +36,7 @@ import { isServiceViable } from "../../service";
 import { readRuntimePort } from "../../config/process-state";
 import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
 import { selfLaunchArgv } from "../../lib/self-launch-argv";
+import { spendLedgerRestartEnvironment } from "../../lib/spend-ledger-owner";
 import {
   MEMORY_DRAIN_RESTART_MS,
   REPLACEMENT_READY_TIMEOUT_MS,
@@ -225,8 +226,12 @@ function spawnDetachedStart(
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
     try {
-      const env: NodeJS.ProcessEnv = { ...process.env };
-      delete env.OCX_SERVICE;
+      const sourceEnv: NodeJS.ProcessEnv = { ...process.env };
+      delete sourceEnv.OCX_SERVICE;
+      const env = spendLedgerRestartEnvironment(
+        sourceEnv,
+        waitForHealthBeforeParentExit ? undefined : process.pid,
+      );
       child = spawn(process.execPath, launchArgs, {
         detached: true,
         stdio: "ignore",

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

@@ -39,6 +39,7 @@ import {
 } from "../../lib/codex-restart-contract";
 import { jsonResponse } from "../auth-cors";
 import { getInspectionCounters } from "../relay";
+import { spendLedgerDiagnosticsSnapshot } from "../../lib/spend-reservation-ledger";
 import type {
   performCodexRestart,
   readCodexAppServerState,
@@ -60,6 +61,7 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       version,
       uptime: process.uptime(),
       pid: process.pid,
+      spendLedger: spendLedgerDiagnosticsSnapshot(),
     });
   }
   if (url.pathname === "/api/system/memory" && req.method === "GET") {

package/src/server/management/usage-aggregate-cache.ts

@@ -66,6 +66,7 @@ const pinnedAggregates = new Set<RetainedUsageAggregate>();
 let baseFlight: Promise<UsageAggregateResult> | null = null;
 const filteredFlights = new Map<string, Promise<UsageAggregateResult>>();
 const retainedFilteredAggregates = new Map<string, RetainedUsageAggregate>();
+const MAX_CONCURRENT_FILTERED_AGGREGATES = 4;
 
 function currentTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -283,6 +284,9 @@ export async function getFilteredUsageAggregate(filter: {
   ]);
   const existing = filteredFlights.get(key);
   if (existing) return existing;
+  if (filteredFlights.size >= MAX_CONCURRENT_FILTERED_AGGREGATES) {
+    throw new Error("too many concurrent filtered usage aggregates");
+  }
 
   const flight = refreshFilteredAggregate(key, normalizedFilter, fixedWindow);
   filteredFlights.set(key, flight);

package/src/server/management-api.ts

@@ -63,6 +63,7 @@ import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
 import { handleStorageLogGuardRoutes } from "./management/storage-log-guard-routes";
 import { handleRequestHistoryRoutes } from "./management/request-history-routes";
 import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
+import { handleMetricsRoutes } from "./management/metrics-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
@@ -276,6 +277,7 @@ export async function handleManagementAPI(
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
+    ??     handleMetricsRoutes(ctx)
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))

package/src/server/management-auth.ts

@@ -12,7 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { adminApiTokenFilePath } from "../lib/admin-secrets";
+import { adminApiTokenFilePath, opencodeCatalogToken } from "../lib/admin-secrets";
 import {
   LOCAL_MANAGEMENT_CAPABILITY_HEADER,
   LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
@@ -297,6 +297,7 @@ export function createManagementSessionControl(state: ManagementAuthState): Mana
  */
 export type ManagementPrincipal =
   | "admin-token"
+  | "opencode-catalog-token"
   | "gui-session"
   | "gui-pair-capability"
   | "local-read-capability"
@@ -484,6 +485,16 @@ function requestManagementCredential(req: Request): string | null {
     || null;
 }
 
+function isOpencodeCatalogRequest(req: Request): boolean {
+  if (req.method !== "GET") return false;
+  try {
+    const url = new URL(req.url);
+    return url.pathname === "/api/models" && url.search === "";
+  } catch {
+    return false;
+  }
+}
+
 function resolveManagementAdmission(
   req: Request,
   state: ManagementAuthState,
@@ -500,6 +511,9 @@ function resolveManagementAdmission(
   else if (state.available) {
     const actual = requestManagementCredential(req);
     if (actual && equalSecret(actual, state.token)) principal = "admin-token";
+    else if (actual && isOpencodeCatalogRequest(req) && equalSecret(actual, opencodeCatalogToken(state.token))) {
+      principal = "opencode-catalog-token";
+    }
     else if (config && authorizeGuiSessionRequest(req, config, state).ok) principal = "gui-session";
   }
   if (principal) admittedManagementRequests.set(req, principal);

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.
 //

package/src/server/readiness.ts

@@ -3,10 +3,30 @@
  *
  * `GET /healthz` answers "is the process alive and serving HTTP?" the instant the
  * listener binds. Readiness is stricter: the proxy is "ready" only after the
- * post-startup Codex catalog/config sync (`syncModelsToCodex`) has settled with
- * `ok=true` and no catalog-sync warning. Until then the process is live (Codex can
- * open a socket) but not ready (a request would race the sync or hit a stale
- * catalog), so clients should back off.
+ * post-startup Codex catalog/config sync (`syncModelsToCodex`) has SETTLED and
+ * reported `ok=true`. Until it settles the process is live (Codex can open a
+ * socket) but not ready — a request would race the sync — so clients back off.
+ *
+ * What readiness is NOT (#5181): it is not a verdict on the local Codex client's
+ * artifacts. A nonempty `warning` used to be terminal here, which made a
+ * degradation of files written into the local Codex home permanently un-ready a
+ * proxy that was serving every other provider correctly. In a single-replica
+ * Kubernetes deployment that removed the only Service endpoint.
+ *
+ * `ok` and `warning` are separate fields in the sync result because they answer
+ * separate questions, and the gate must not conflate them. `ok` is the sync's own
+ * verdict on whether the essential work — config injection, and the write
+ * admission that precedes it — succeeded. `warning` names a degradation the sync
+ * itself decided to continue past: no catalog source so Codex keeps its native
+ * catalog, combos omitted from the catalog, a conversation-history relabel left
+ * to Codex's own writer, or a caught catalog-refresh exception after which
+ * injection still runs and still reports its own `ok`. None of those stops this
+ * process from accepting HTTP or routing to a provider, so none of them may close
+ * the gate.
+ *
+ * That boundary is not new, only extended: the Claude Code roster reconciliation
+ * in `src/cli/claude-agent-startup-sync.ts` already delays the ready transition
+ * without being allowed to fail it, on the same reasoning.
  *
  * Design contract (per P1 review):
  *  - NO module-global mutable state. Each `startServer` invocation gets its own
@@ -65,8 +85,11 @@ export interface SyncOutcomeLike {
 
 /**
  * Drive the gate from the post-startup sync. Awaits `syncFn`; the gate goes to
- * `ready` ONLY on `ok=true` with no nonempty warning. A throw, `null`, `ok=false`,
- * or a nonempty warning transitions to `failed`. Used directly by `handleStart`
+ * `ready` on `ok=true`. A throw, `null`, or `ok !== true` transitions to
+ * `failed`; a nonempty `warning` does not, because the sync that produced it
+ * still reported the essential work done (see the file header, #5181). A throw
+ * and `null` stay terminal because neither is a classified outcome: the startup
+ * path did not reach a verdict, so the gate cannot claim one. Used by `handleStart`
  * so the startup transition is unit-testable without spawning the proxy. Returns
  * the raw sync outcome so a caller that also needs the #1046 write flags (did the
  * sync actually write the catalog/cache?) can keep them without a second call.
@@ -90,10 +113,6 @@ export async function runStartupReadinessSync(
     gate.markFailed();
     return result;
   }
-  if (result.warning !== undefined && result.warning !== "") {
-    gate.markFailed();
-    return result;
-  }
   gate.markReady();
   return result;
 }