@yansigit/opencodex 2.33.0 → 2.35.0

package/src/cli/models-runtime.ts

@@ -22,6 +22,10 @@ const USAGE = `Usage:
   ocx models <enable|disable> <provider/model|native-model> [--native] [--json]
   ocx models provider <name> <on|off> [--json]
   ocx models selected <provider> [--set <id,id...>|--clear] [--json]
+  ocx models preset show [--provider <name>] [--json]
+  ocx models preset apply <provider> [--all] [--json]
+  ocx models new-policy [on|off] [--provider <name>] [--json]
+  ocx models new-arrivals [--json]
   ocx models context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>> [--json]
   ocx models shadow <status|set> [model|-] [--enabled <on|off>] [--json]`;
 
@@ -162,6 +166,94 @@ async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`${provider}: ${models.length ? models.join(", ") : "all models"}`]);
 }
 
+
+interface ModelPresetView {
+  mode: string;
+  appliedVersion?: number;
+  availableVersion: number;
+  presetIds: string[];
+  presetCount: number;
+  totalCount: number;
+  fallback?: string;
+}
+
+function presetLine(name: string, view: ModelPresetView): string {
+  const parts = [`${name}: mode=${view.mode}`];
+  if (view.appliedVersion !== undefined && view.appliedVersion !== view.availableVersion) {
+    parts.push(`applied v${view.appliedVersion}, available v${view.availableVersion}`);
+  } else {
+    parts.push(`preset v${view.availableVersion}`);
+  }
+  parts.push(`(${view.presetCount} of ${view.totalCount} models)`);
+  if (view.fallback) parts.push(`fallback=${view.fallback}`);
+  return parts.join(" ");
+}
+
+async function preset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "show").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "show") {
+    const only = takeOption(args, "--provider")?.trim();
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<{ providers?: Record<string, ModelPresetView> }>("/api/model-presets", {}, deps);
+    const providers = result.providers ?? {};
+    const entries = Object.entries(providers).filter(([name]) => !only || name === only);
+    const lines = entries.length > 0
+      ? entries.map(([name, view]) => presetLine(name, view))
+      // A provider with no shipped preset is not an error: it simply has nothing to curate.
+      : [only ? `${only}: no model preset is shipped for this provider` : "no providers have a shipped model preset"];
+    printData(only ? providers[only] ?? {} : result, wantsJson, lines);
+    return;
+  }
+  if (action !== "apply") throw new CliUsageError(`unknown preset action '${action}'`, USAGE);
+  const provider = args.shift()?.trim();
+  const all = takeFlag(args, "--all");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  rejectArgs(args, USAGE);
+  const mode = all ? "all" : "preset";
+  const result = await runtimeRequest<{ selected?: string[]; fallback?: string; appliedVersion?: number }>(
+    "/api/model-presets",
+    { method: "PUT", body: JSON.stringify({ provider, mode }) },
+    deps,
+  );
+  const selectedIds = result.selected ?? [];
+  const line = result.fallback === "preset-empty"
+    // Never silently narrow to nothing: empty means ALL, so a zero-match preset keeps what was
+    // there and says so.
+    ? `${provider}: preset matched no models — selection unchanged (fallback to all)`
+    : all
+      ? `${provider}: showing all models (allowlist cleared)`
+      : `${provider}: preset v${result.appliedVersion ?? "?"} applied — ${selectedIds.length} models selected`;
+  printData(result, wantsJson, [line]);
+}
+
+async function newPolicy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const state = args[0] && !args[0].startsWith("--") ? args.shift()!.toLowerCase() : undefined;
+  const provider = takeOption(args, "--provider")?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (state !== undefined && state !== "on" && state !== "off") throw new CliUsageError("new policy must be on or off", USAGE);
+  rejectArgs(args, USAGE);
+  if (!state) {
+    const result = await runtimeRequest<{ policy: string; providers: Record<string, string> }>("/api/model-discovery", {}, deps);
+    const value = provider ? result.providers[provider] ?? "inherit" : result.policy;
+    printData(provider ? { provider, policy: value } : result, wantsJson, [`${provider ?? "global"}: ${value}`]);
+    return;
+  }
+  const result = await runtimeRequest<{ baselineBootstrapped?: boolean }>("/api/model-discovery", {
+    method: "PUT", body: JSON.stringify({ policy: state, provider: provider ?? null }),
+  }, deps);
+  printData(result, wantsJson, [`${provider ?? "global"}: ${state}${result.baselineBootstrapped ? " (current models recorded as known)" : ""}`]);
+}
+
+async function newArrivals(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ recentArrivals: Record<string, Array<{ id: string; at: string; state: string }>> }>("/api/model-discovery", {}, deps);
+  const lines = Object.entries(result.recentArrivals).flatMap(([provider, rows]) => rows.map(row => `${provider}/${row.id}  [${row.state}]  ${row.at}`));
+  printData(result.recentArrivals, wantsJson, lines.length ? lines : ["no recent model arrivals"]);
+}
+
 async function context(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "status").toLowerCase();
@@ -236,6 +328,9 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "disable") action = () => visibility(false, argv, deps);
   else if (sub === "provider") action = () => providerVisibility(argv, deps);
   else if (sub === "selected") action = () => selected(argv, deps);
+  else if (sub === "preset") action = () => preset(argv, deps);
+  else if (sub === "new-policy") action = () => newPolicy(argv, deps);
+  else if (sub === "new-arrivals") action = () => newArrivals(argv, deps);
   else if (sub === "context") action = () => context(argv, deps);
   else if (sub === "shadow") action = () => shadow(argv, deps);
   if (!action) return null;

package/src/cli/models.ts

@@ -11,7 +11,7 @@ import {
   isDeclaredReasoningEffort,
   modelRecordValue,
 } from "../reasoning-effort";
-import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
+import { encodedModelIdCollides, resolveSlugSelection, routedSlug } from "../providers/slug-codec";
 import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
@@ -277,11 +277,17 @@ async function handleCustomRemove(args: string[]): Promise<void> {
 
   const config = loadConfig();
   const existing = config.customModels ?? [];
-  const matchingIndexes = existing.flatMap((model, index) => (
-    target.includes("/")
-      ? slugEquals(target, model.provider, model.modelId)
-      : model.id === target
-  ) ? [index] : []);
+  // Slug matching goes through the shared resolver so this command sees the same collision
+  // class catalog filtering and persisted sync see (#2491). `slugEquals` compares the raw and
+  // encoded spellings of ONE id, so a selector written in the native slash form matched only
+  // that row while the dash form matched both — the two relations disagreed on the same
+  // config. Removal stays exact-or-refuse: an ambiguous selector still aborts below, which is
+  // the right default for a destructive command.
+  const matchingIndexes = existing.flatMap((model, index) => {
+    if (!target.includes("/")) return model.id === target ? [index] : [];
+    const resolved = resolveSlugSelection(model.provider, target, [model.modelId]);
+    return resolved.matched.length > 0 ? [index] : [];
+  });
   if (matchingIndexes.length === 0) fail(`custom model "${target}" not found`);
   if (matchingIndexes.length > 1) {
     fail(`custom model selector "${target}" is ambiguous; use the custom model id`);
@@ -422,7 +428,7 @@ export async function handleModels(args: string[]): Promise<void> {
     handleCustomList(rest);
     return;
   }
-  if (["live", "edit", "enable", "disable", "provider", "selected", "context", "shadow"].includes(subcommand ?? "")) {
+  if (["live", "edit", "enable", "disable", "provider", "selected", "preset", "context", "shadow"].includes(subcommand ?? "")) {
     const { handleModelsRuntimeCommand } = await import("./models-runtime");
     const code = await handleModelsRuntimeCommand(subcommand!, rest);
     if (code !== null) process.exitCode = code;

package/src/cli/provider-runtime.ts

@@ -11,6 +11,13 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { providerQuotaLine } from "./account-extended";
+import type { ProviderQuotaReportDto } from "./account-api";
+
+interface ProviderQuotasDto {
+  generatedAt?: number;
+  reports?: ProviderQuotaReportDto[];
+}
 
 const USAGE = `Usage:
   ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
@@ -107,8 +114,15 @@ async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const refresh = takeFlag(args, "--refresh");
   rejectArgs(args, USAGE);
-  const result = await runtimeRequest(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
-  printData(result, wantsJson, summaryLines(result));
+  const result = await runtimeRequest<ProviderQuotasDto>(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
+  // `summaryLines` is a depth-1 flattener: it renders a non-scalar array as "N item(s)", which
+  // collapsed the whole report to a count and made the command useless for its stated purpose
+  // (#2565). Render one line per report with the same formatter `ocx account refresh` uses.
+  const reports = Array.isArray(result?.reports) ? result.reports : [];
+  const lines = reports.length > 0
+    ? reports.map(report => providerQuotaLine(report.provider, report))
+    : ["no quota reports available"];
+  printData(result, wantsJson, lines);
 }
 
 async function presets(argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/registry.ts

@@ -165,10 +165,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "A selection-order change applies from the next unbound request and never moves a bound thread.",
     ],
   },
+  {
+    name: "alias",
+    usage: "ocx alias <list|set|rm|defaults> ...",
+    summary: "Manage short provider and model names.",
+  },
   {
     name: "models",
     aliases: ["model"],
-    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
+    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|preset|context|shadow> ...",
     summary: "List models and manage custom (manually registered) models.",
     details: [
       "List available models from static config with no subcommand (liveModels may add more at runtime).",

package/src/cli/telemetry-commands.ts

@@ -0,0 +1,25 @@
+import { TelemetryLedger } from "../telemetry/ledger";
+import type { OcxConfig } from "../types";
+
+export function runTelemetryCommand(args: string[], config: OcxConfig): number {
+  if (args[0] !== "status") {
+    console.error("Usage: ocx telemetry status");
+    return 1;
+  }
+  const ledger = new TelemetryLedger();
+  try {
+    const records = ledger.listRecords();
+    console.log(`Telemetry failures: ${records.length}`);
+    for (const record of records) {
+      console.log(`${record.fingerprint}  ${record.status}  count=${record.count}  lastSeen=${new Date(record.lastSeen).toISOString()}`);
+    }
+    if ((config as OcxConfig & { autonomousRemediation?: { enabled?: boolean; instanceId?: string } }).autonomousRemediation?.enabled === true) {
+      console.log("Autonomous remediation: enabled");
+    } else {
+      console.log("Autonomous remediation: disabled");
+    }
+    return 0;
+  } finally {
+    ledger.close();
+  }
+}

package/src/cli/v2.ts

@@ -15,7 +15,7 @@ import { dirname } from "node:path";
 import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
-import { loadConfig, saveConfig } from "../config";
+import { deleteConfigTopLevelKey, loadConfig, saveConfig } from "../config";
 import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 
 export interface V2CliDeps {
@@ -88,18 +88,24 @@ function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
 
 export function v2StatusLine(enabled: boolean): string {
   return enabled
-    ? "multi_agent_v2: ON — v2 multi-agent surface active"
-    : "multi_agent_v2: OFF — v1 multi-agent surface (default install)";
+    ? "multi_agent_v2: ON — global V2 override active"
+    : "multi_agent_v2: OFF — model catalog pins and defaults decide the surface";
 }
 
-export function multiAgentModeLine(mode: string): string {
+export function multiAgentModeLine(mode: string, keepNativeChatGptOnV1 = false): string {
   switch (mode) {
     case "v1": return "multi_agent_mode: v1 — ALL models forced to v1 surface (upstream pins overridden)";
-    case "v2": return "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
+    case "v2": return keepNativeChatGptOnV1
+      ? "multi_agent_mode: v2 hybrid — ChatGPT-native models use v1; routed models use v2"
+      : "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
     default: return "multi_agent_mode: default — upstream model pins respected (sol/terra=v2, luna=v1, rest=codex flag)";
   }
 }
 
+function requiresGlobalV2Disabled(multiAgentMode: string | undefined, keepNativeChatGptOnV1: boolean): boolean {
+  return multiAgentMode === "v2" && keepNativeChatGptOnV1;
+}
+
 export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
   const log = deps.log ?? console;
   const isEnabled = deps.isEnabled ?? isMultiAgentV2Enabled;
@@ -109,9 +115,13 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
   if (verb === "status") {
     log.log(v2StatusLine(isEnabled()));
     const cfg = loadConfig();
-    log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
+    const mode = cfg.multiAgentMode ?? "default";
+    const keepNativeV1 = cfg.keepNativeChatGptOnV1 === true;
+    log.log(multiAgentModeLine(mode, keepNativeV1));
     log.log(cfg.keepNativeChatGptOnV1 === true
-      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2"
+      ? requiresGlobalV2Disabled(mode, keepNativeV1) && isEnabled()
+        ? "keep_native_chatgpt_on_v1: CONFLICT — global multi_agent_v2 overrides the native v1 catalog pin; run 'ocx v2 keep-native-v1 on' to reconcile"
+        : "keep_native_chatgpt_on_v1: ON — global V2 override is off; ChatGPT-native rows use v1 and routed rows use v2 when mode is v2"
       : "keep_native_chatgpt_on_v1: OFF");
     const threads = getLogicalMaxThreads();
     log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
@@ -186,14 +196,14 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     }
     const cfg = loadConfig();
     if (modeArg !== "default") {
-      const target = modeArg === "v2";
+      const target = modeArg === "v2" && cfg.keepNativeChatGptOnV1 !== true;
       const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
       if (!transition.ok) {
         log.error(`multi-agent mode transition failed: ${transition.error}`);
         return 1;
       }
     }
-    if (modeArg === "default") delete cfg.multiAgentMode;
+    if (modeArg === "default") deleteConfigTopLevelKey(cfg, "multiAgentMode");
     else cfg.multiAgentMode = modeArg as "v1" | "v2";
     saveConfig(cfg);
     try {
@@ -216,8 +226,15 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     const cfg = loadConfig();
     const next = flag === "on";
     const already = cfg.keepNativeChatGptOnV1 === true === next;
+    if (next && requiresGlobalV2Disabled(cfg.multiAgentMode, true)) {
+      const transition = transitionMultiAgentV2(false, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+      if (!transition.ok) {
+        log.error(`keep-native-v1 transition failed: ${transition.error}`);
+        return 1;
+      }
+    }
     if (next) cfg.keepNativeChatGptOnV1 = true;
-    else delete cfg.keepNativeChatGptOnV1;
+    else deleteConfigTopLevelKey(cfg, "keepNativeChatGptOnV1");
     saveConfig(cfg);
     try {
       const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
@@ -243,6 +260,13 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
   }
 
   const want = verb === "on";
+  if (want) {
+    const cfg = loadConfig();
+    if (requiresGlobalV2Disabled(cfg.multiAgentMode, cfg.keepNativeChatGptOnV1 === true)) {
+      log.error("v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first.");
+      return 1;
+    }
+  }
   const transition = transitionMultiAgentV2(want, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
   if (!transition.ok) {
     log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${transition.error}`);

package/src/codex/account-pause.ts

@@ -1,4 +1,5 @@
 import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
 
 /** Whether an account is administratively excluded from future pool selection. */
 export function isCodexAccountPaused(config: OcxConfig, accountId: string): boolean {
@@ -12,7 +13,7 @@ export function setCodexAccountPaused(config: OcxConfig, accountId: string, paus
   else pausedIds.delete(accountId);
 
   if (pausedIds.size > 0) config.pausedCodexAccountIds = [...pausedIds];
-  else delete config.pausedCodexAccountIds;
+  else deleteConfigTopLevelKey(config, "pausedCodexAccountIds");
 }
 
 export function forgetCodexAccountPause(config: OcxConfig, accountId: string): void {

package/src/codex/account-priority.ts

@@ -1,6 +1,7 @@
 import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 import { DEFAULT_ACCOUNT_PRIORITY, normalizeAccountPriority } from "./pool-rotation";
 import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
 
 /**
  * Which ids may carry a selection order: any pool account, plus the synthetic
@@ -34,7 +35,7 @@ export function setCodexAccountPriority(config: OcxConfig, accountId: string, pr
   else entries.set(accountId, priority);
 
   if (entries.size > 0) config.codexAccountPriorities = Object.fromEntries(entries);
-  else delete config.codexAccountPriorities;
+  else deleteConfigTopLevelKey(config, "codexAccountPriorities");
 }
 
 export function forgetCodexAccountPriority(config: OcxConfig, accountId: string): void {
@@ -78,6 +79,6 @@ export function setCodexAccountPin(config: OcxConfig, accountId: string): void {
 /** Release the pin. With `accountId` given, only when it is the pinned account. */
 export function clearCodexAccountPin(config: OcxConfig, accountId?: string): void {
   if (accountId === undefined || config.activeCodexAccountPinned === accountId) {
-    delete config.activeCodexAccountPinned;
+    deleteConfigTopLevelKey(config, "activeCodexAccountPinned");
   }
 }

package/src/codex/app-server-processes.ts

@@ -260,6 +260,23 @@ export function isCodexAppServerCommandLine(commandLine: string, executable?: st
   }
   if (tokens.length === 0) return false;
   if (isCodeModeHostProcess(tokens)) return true;
+  // An npm-installed Codex runs as a PAIR: `node /usr/local/bin/codex app-server` and the
+  // vendored native binary that wrapper spawns. Only the child used to match, so
+  // `--restart-codex` signalled the child while its supervisor kept holding the socket -
+  // which is what "PID(s) still running after SIGTERM" was reporting on Linux.
+  //
+  // The codex-shaped token must be IMMEDIATELY next. Skipping interpreter flags to reach
+  // it looks tempting and is wrong: interpreter options take values, so a generic skip
+  // reads the value of `node --require codex app-server worker.js` as the entrypoint.
+  // Supporting flags needs a real Node/Bun/Deno entrypoint parser, not a loop over
+  // hyphens; the observed wrappers put the path first, so this stays narrow on purpose.
+  //
+  // Dropping only the interpreter and re-running the ordinary scan is what preserves the
+  // subcommand discipline below: `node <codex> exec 'hi'` stays unmatched exactly like
+  // `codex exec 'hi'` does.
+  if (isInterpreterToken(tokens[0]!) && tokens.length > 1 && isCodexExecutableToken(tokens[1]!)) {
+    tokens = tokens.slice(1);
+  }
   if (!isCodexExecutableToken(tokens[0]!)) return false;
 
   let i = 1;
@@ -740,6 +757,28 @@ const CATALOG_STATE_TTL_MS = 5_000;
  */
 const CATALOG_STATE_UNKNOWN_TTL_MS = 250;
 
+/**
+ * How long a real observation may still be SERVED after it expires, while a refresh
+ * runs behind it (#2499).
+ *
+ * The probe is advisory and, on Windows, slow: `Invoke-CimMethod GetOwner` costs
+ * ~0.4s per candidate process, so a cold probe routinely outlives the 5s TTL and
+ * every turn that misses the cache pays for it on the request path. Serving the
+ * previous reading immediately keeps that cost off the turn without pretending it is
+ * fresh -- the refresh it triggers is what makes the next reading current.
+ *
+ * Measured from expiry rather than from when the reading was taken, so a `fresh`
+ * entry stays servable for its own TTL plus this bound. Anchoring it to expiry keeps
+ * the stale window independent of the TTL -- a cap on total age would quietly turn
+ * this path off if the TTL were ever raised past it.
+ *
+ * Bounded rather than unlimited: if the refresh keeps failing, an observation this
+ * old stops being evidence about the machine and it is better to wait for a real one.
+ * `unknown` is never served this way -- it is a failure to observe, not an
+ * observation, and it already has its own short window for exactly that reason.
+ */
+export const CATALOG_STATE_MAX_STALE_MS = 60_000;
+
 export function catalogStateTtlMs(state: CodexAppServerCatalogState): number {
   return state === "unknown" ? CATALOG_STATE_UNKNOWN_TTL_MS : CATALOG_STATE_TTL_MS;
 }
@@ -835,6 +874,14 @@ export function collectCodexAppServerCatalogState(
  * - 선택한 방식: retain the synchronous API and use async PowerShell plus an identity-scoped in-flight refresh, short cache, and invalidation generation only for Windows requests.
  * - 다른 대안 대신 이 방식을 선택한 이유: it fixes unrelated `/healthz` starvation without widening the process-matching or restart contract.
  * - 장점, 단점 및 영향: concurrent turns share one CIM walk, invalidated pre-write results cannot repopulate the cache, and the event loop stays responsive; a cold v2 turn can still await the bounded advisory probe.
+ *
+ * [Decision Log · #2499]
+ * - 목적과 의도: a cold probe outlives its own 5s TTL on Windows (~435ms per candidate process for `Invoke-CimMethod GetOwner`), so the cache expires before it can serve and the miss lands on a turn.
+ * - 기존 구현 및 제약 조건: the reading is advisory, and only `fresh` authorizes positive guidance (`src/server/responses/collaboration.ts`); `unknown` is a failure to observe rather than an observation.
+ * - 검토한 주요 대안: drop the per-process GetOwner fan-out (issue suggestion 1), or widen the TTL past the probe duration (suggestion 3).
+ * - 선택한 방식: serve an expired reading immediately when its generation still matches, bounded by `CATALOG_STATE_MAX_STALE_MS`, never for `unknown`, and refresh behind it; a failed refresh no longer evicts the reading it was refreshing.
+ * - 다른 대안 대신 이 방식을 선택한 이유: the fan-out change alters what "could not verify the owner" means for the current-user scoping contract and needs its own ground-truth comparison; a wider TTL still pays the probe on every human-paced turn.
+ * - 장점, 단점 및 영향: after the first probe the request path never waits; a server that stopped between readings can be described as `fresh` for up to the stale bound; a catalog write still invalidates immediately through the generation, and the cold path is unchanged.
  */
 export async function collectCodexAppServerCatalogStateForRequest(
   io: CodexAppServerProcessIo = {},
@@ -853,16 +900,30 @@ export async function collectCodexAppServerCatalogStateForRequest(
     catalogMtimeMs: io.catalogMtimeMs,
     now: io.now,
   };
-  if (requestCatalogStateCache
+  const cached = requestCatalogStateCache
     && requestCatalogStateCache.generation === generation
     && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity)
-    && now - requestCatalogStateCache.atMs < catalogStateTtlMs(requestCatalogStateCache.status.state)) {
-    return requestCatalogStateCache.status;
+    ? requestCatalogStateCache
+    : null;
+  if (cached && now - cached.atMs < catalogStateTtlMs(cached.status.state)) {
+    return cached.status;
   }
+  // An expired real reading is still worth handing back while the refresh runs. It
+  // cannot have been invalidated by an ocx catalog write: every such write calls
+  // `resetCodexAppServerCatalogStateCache`, which advances the generation and drops
+  // this entry, so a generation match means no write has landed since it was taken.
+  // What it can miss is an app-server that started or stopped meanwhile -- and a
+  // server started after the reading is newer than the catalog, which is the `fresh`
+  // this entry already says.
+  const servableStale = cached
+    && cached.status.state !== "unknown"
+    && now - cached.atMs < catalogStateTtlMs(cached.status.state) + CATALOG_STATE_MAX_STALE_MS
+    ? cached.status
+    : null;
   if (requestCatalogStateFlight
     && requestCatalogStateFlight.generation === generation
     && sameRequestCatalogStateIdentity(requestCatalogStateFlight.identity, identity)) {
-    return requestCatalogStateFlight.promise;
+    return servableStale ?? requestCatalogStateFlight.promise;
   }
 
   const refresh = async (): Promise<CodexAppServerCatalogStatus> => {
@@ -920,7 +981,18 @@ export async function collectCodexAppServerCatalogStateForRequest(
     if (requestCatalogStateGeneration !== generation) {
       return { state: "unknown" as const, processes: [], catalogMtimeMs: null };
     }
-    if (requestCatalogStateFlight === flight) {
+    // A refresh that failed must not evict a real reading. Before this function
+    // served stale entries, caching `unknown` cost at most the 250ms that state
+    // is allowed to live. Now that an expired observation is what callers are
+    // handed, overwriting one with `unknown` would take the answer AWAY from
+    // them on a transient failure -- `unknown` is not servable, so the next
+    // caller waits for a probe instead of getting the reading it would have had.
+    // Keep the observation and let its own age retire it.
+    const wouldEvictAnObservation = status.state === "unknown"
+      && requestCatalogStateCache?.generation === generation
+      && requestCatalogStateCache.status.state !== "unknown"
+      && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity);
+    if (requestCatalogStateFlight === flight && !wouldEvictAnObservation) {
       requestCatalogStateCache = {
         generation,
         identity,
@@ -934,7 +1006,9 @@ export async function collectCodexAppServerCatalogStateForRequest(
   });
   flight = { generation, identity, promise };
   requestCatalogStateFlight = flight;
-  return flight.promise;
+  // `promise` already absorbs its own failures, so leaving it unawaited here cannot
+  // surface as an unhandled rejection; the next caller picks up whatever it stored.
+  return servableStale ?? flight.promise;
 }
 
 /**

package/src/codex/auth-api.ts

@@ -209,21 +209,61 @@ function codexAccountPersistenceConflict(
     : undefined;
 }
 
+/**
+ * The exact label `parseUsageQuota` emits for the Codex Spark window (quota.ts).
+ * Matching on the label rather than on "is a custom window" is load-bearing: the same array
+ * carries Cursor's First-party models / API usage, Anthropic's Fable / Opus / Sonnet,
+ * Antigravity's Gem / Cla, Kimi's subscription credits and a dozen dynamic provider meters.
+ */
+const CODEX_SPARK_WINDOW_LABEL = "GPT-5.3-Codex-Spark Weekly";
+
+/**
+ * Drop the Spark window unless the operator asked for it (default hidden).
+ *
+ * Applied at the DTO boundary, never at parse or cache time: custom windows participate in
+ * quota-presence checks, snapshot reconciliation and capacity aggregation, so removing Spark
+ * upstream of this point would change routing state rather than display.
+ *
+ * Both GUI surfaces funnel through here — the Codex Auth rows directly, and /api/provider-quotas
+ * via listCodexAuthAccountsSnapshot — so one filter covers both. Filtering only one would leave
+ * the other still rendering the row the operator switched off.
+ */
+export function withSparkVisibility<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
+  quota: T,
+): T {
+  if (!quota?.customWindows?.length) return quota;
+  if (loadConfig().showCodexSparkQuota === true) return quota;
+  const kept = quota.customWindows.filter(window => window.label !== CODEX_SPARK_WINDOW_LABEL);
+  if (kept.length === quota.customWindows.length) return quota;
+  // An empty list is dropped rather than serialized: an absent field and an empty array should
+  // not be two different ways of saying "no custom windows" on the wire.
+  const next = { ...quota } as Record<string, unknown>;
+  if (kept.length > 0) next.customWindows = kept;
+  else delete next.customWindows;
+  return next as T;
+}
+
+
 function quotaForPlan<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
   quota: T,
   plan: unknown,
 ): T {
-  if (!quota || !isThirtyDayOnlyCodexPlan(plan)) return quota;
+  const visible = withSparkVisibility(quota);
+  if (!visible || !isThirtyDayOnlyCodexPlan(plan)) return visible;
+  const quotaWindows = visible;
   return {
-    ...(quota.monthlyPercent !== undefined ? { monthlyPercent: quota.monthlyPercent } : {}),
-    ...(quota.monthlyResetAt !== undefined ? { monthlyResetAt: quota.monthlyResetAt } : {}),
+    ...(quotaWindows.monthlyPercent !== undefined ? { monthlyPercent: quotaWindows.monthlyPercent } : {}),
+    ...(quotaWindows.monthlyResetAt !== undefined ? { monthlyResetAt: quotaWindows.monthlyResetAt } : {}),
     // A 30-day plan can still carry a burst window, and it blocks the account on its own.
     // Dropping it here would show a healthy card for an account upstream is refusing (#1791).
-    ...(quota.shortPercent !== undefined ? { shortPercent: quota.shortPercent } : {}),
-    ...(quota.shortResetAt !== undefined ? { shortResetAt: quota.shortResetAt } : {}),
-    ...(quota.shortWindowSeconds !== undefined ? { shortWindowSeconds: quota.shortWindowSeconds } : {}),
-    ...(quota.resetCredits !== undefined ? { resetCredits: quota.resetCredits } : {}),
-    ...("updatedAt" in quota ? { updatedAt: quota.updatedAt } : {}),
+    ...(quotaWindows.fiveHourPercent !== undefined ? { fiveHourPercent: quotaWindows.fiveHourPercent } : {}),
+    ...(quotaWindows.fiveHourResetAt !== undefined ? { fiveHourResetAt: quotaWindows.fiveHourResetAt } : {}),
+    ...(quotaWindows.shortPercent !== undefined ? { shortPercent: quotaWindows.shortPercent } : {}),
+    ...(quotaWindows.shortResetAt !== undefined ? { shortResetAt: quotaWindows.shortResetAt } : {}),
+    ...(quotaWindows.shortWindowSeconds !== undefined ? { shortWindowSeconds: quotaWindows.shortWindowSeconds } : {}),
+    ...(quotaWindows.customWindows !== undefined ? { customWindows: quotaWindows.customWindows } : {}),
+    ...(quotaWindows.resetCredits !== undefined ? { resetCredits: quotaWindows.resetCredits } : {}),
+    ...("updatedAt" in quotaWindows ? { updatedAt: quotaWindows.updatedAt } : {}),
   } as T;
 }
 

package/src/codex/auth-context.ts

@@ -29,7 +29,6 @@ import {
   entitledCodexAccountIdsForModel,
   isDirectCallerEntitledToCodexModel,
   resolveCodexModelEntitlements,
-  type CodexModelEntitlementSnapshot,
 } from "./model-entitlements";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
@@ -334,9 +333,7 @@ export interface ResolveCodexAuthContextOptions {
   getMainAccountToken?: typeof getMainAccountToken;
   primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void>;
   /** Test seam for account-gated native model discovery. */
-  resolveCodexModelEntitlements?: (
-    config: Pick<OcxConfig, "codexAccounts">,
-  ) => Promise<CodexModelEntitlementSnapshot>;
+  resolveCodexModelEntitlements?: typeof resolveCodexModelEntitlements;
   /** Direct requests admitted with a proxy bearer substitute the stored native-main credential. */
   substituteMainCredentialForDirect?: boolean;
   /** Test seam for a Direct request's own forwarded ChatGPT credential. */
@@ -381,28 +378,34 @@ export async function resolveCodexAuthContext(
     return { kind: "main", accountId: null };
   }
   const affinityKey = fixedAccountId === undefined ? codexPoolAffinityKey(headers) : undefined;
-  const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
-    ? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config)
-    : undefined;
-  const modelEligibleAccountIds = entitlementSnapshot
-    ? entitledCodexAccountIdsForModel(entitlementSnapshot, options.modelId)
-    : undefined;
   // Retained startup recovery makes the physical main identity ineligible. Routing
   // can still preserve service by selecting a healthy configured pool account.
   const nativeMainTrafficBlocked = isNativeMainTrafficBlocked();
   const selectionAdmission = options.beginCodexAccountSelection?.();
   const nativeMainReadsForbidden = nativeMainTrafficBlocked || selectionAdmission?.mainProfileDraining === true;
-  const selectionOptions = {
-    // Temporary switch drain keeps the candidate until the atomic claim rejects
-    // it. Retained recovery makes main wholly ineligible so pool routing continues.
-    nativeMainSelectionOnly: !nativeMainTrafficBlocked
-      && selectionAdmission?.mainProfileDraining === true,
-    isMainAccountTokenLive: options.isMainAccountTokenLive,
-    modelEligibleAccountIds,
-  };
   let accountId: string;
   const quotaScope = codexQuotaScopeForModel(options.modelId);
   try {
+    const excludeAccountIds = nativeMainReadsForbidden
+      ? new Set([MAIN_CODEX_ACCOUNT_ID])
+      : undefined;
+    const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
+      ? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config, { excludeAccountIds })
+      : undefined;
+    const entitledAccountIds = entitlementSnapshot
+      ? entitledCodexAccountIdsForModel(entitlementSnapshot, options.modelId)
+      : undefined;
+    const modelEligibleAccountIds = entitledAccountIds
+      ? new Set([...entitledAccountIds].filter(candidate => !excludeAccountIds?.has(candidate)))
+      : undefined;
+    const selectionOptions = {
+      // Temporary switch drain keeps the candidate until the atomic claim rejects
+      // it. Retained recovery makes main wholly ineligible so pool routing continues.
+      nativeMainSelectionOnly: !nativeMainTrafficBlocked
+        && selectionAdmission?.mainProfileDraining === true,
+      isMainAccountTokenLive: options.isMainAccountTokenLive,
+      modelEligibleAccountIds,
+    };
     // A pre-drain selector reserves the native identity while reconciliation and
     // routing inspect it. Selectors arriving after the fence skip reconciliation
     // and may still route to non-main pool accounts without touching switch state.