@iislee/opencodex 2.31.0 → 2.35.0

package/src/clients/config-export.ts

@@ -484,6 +484,29 @@ export function primeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(primeAgentDir(env, home), "models.json");
 }
 
+export function clineHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.CLINE_DATA_DIR?.trim();
+  if (override) return absoluteClientPath(override, home, "CLINE_DATA_DIR");
+
+  const vscodeDir = process.platform === "darwin"
+    ? join(home, "Library", "Application Support", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings")
+    : process.platform === "win32"
+      ? join(env.APPDATA || join(home, "AppData", "Roaming"), "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings")
+      : join(home, ".config", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings");
+
+  if (existsSync(vscodeDir)) return vscodeDir;
+
+  const cliSettingsDir = join(home, ".cline", "data", "settings");
+  if (existsSync(cliSettingsDir) || existsSync(join(home, ".cline"))) return cliSettingsDir;
+
+  return vscodeDir;
+}
+
+/** Cline's canonical providers configuration file. */
+export function clineConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(clineHomeDir(env, home), "providers.json");
+}
+
 /**
  * One proxy-routed model destined for a client config. Deliberately narrower than
  * `CatalogModel` so a serializer cannot reach for a field that does not survive the
@@ -526,7 +549,8 @@ export type ExportClientId =
   | "dsh"
   | "mcode"
   | "zcode"
-  | "prime";
+  | "prime"
+  | "cline";
 
 export interface ExportClientSpec {
   id: ExportClientId;
@@ -725,10 +749,10 @@ export function buildOpencodeProviderBlockFromCatalog(
  * models produce identical bytes. Stability matters because the GUI shows a diffable
  * preview and agents may checksum the payload.
  */
-export function normalizeExportModels(models: readonly ExportModel[]): ExportModel[] {
+export function normalizeExportModels(models: readonly ExportModel[] = []): ExportModel[] {
   const seen = new Set<string>();
   const unique: ExportModel[] = [];
-  for (const model of models) {
+  for (const model of models ?? []) {
     if (seen.has(model.namespaced)) continue;
     seen.add(model.namespaced);
     unique.push(model);
@@ -1379,6 +1403,42 @@ function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig {
   };
 }
 
+export interface ClineProviderSettings {
+  provider: string;
+  baseUrl: string;
+  apiKey?: string;
+  model?: string;
+}
+
+export interface ClineProviderBlock {
+  settings: ClineProviderSettings;
+  tokenSource?: string;
+}
+
+export interface ClineGeneratedConfig {
+  version: number;
+  providers: Record<string, ClineProviderBlock>;
+}
+
+function buildClineClientConfig(ctx: ExportContext): ClineGeneratedConfig {
+  const models = normalizeExportModels(ctx.models);
+  const defaultModel = models[0]?.namespaced ?? "opencodex";
+  return {
+    version: 1,
+    providers: {
+      [OPENCODE_PROVIDER_ID]: {
+        settings: {
+          provider: "openai-compatible",
+          baseUrl: ctx.baseUrl.replace(/\/v1\/?$/, "") + "/v1",
+          apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+          model: defaultModel,
+        },
+        tokenSource: "manual",
+      },
+    },
+  };
+}
+
 /**
  * Per-client model counts, read back off the SERIALIZED document rather than
  * recomputed from the input rows: `modelsWithoutLimits` drives a GUI line about
@@ -1390,6 +1450,11 @@ function summarizeOpencode(document: unknown): { modelCount: number; modelsWitho
   return { modelCount: models.length, modelsWithoutLimits: models.filter(model => !model.limit).length };
 }
 
+function summarizeCline(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const provider = (document as ClineGeneratedConfig | undefined)?.providers?.[OPENCODE_PROVIDER_ID];
+  return { modelCount: provider ? 1 : 0, modelsWithoutLimits: 0 };
+}
+
 function summarizePi(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
   const models = (document as PiGeneratedConfig | undefined)?.providers?.[OPENCODE_PROVIDER_ID]?.models ?? [];
   return { modelCount: models.length, modelsWithoutLimits: models.filter(model => model.contextWindow === undefined).length };
@@ -1522,6 +1587,11 @@ function buildPrimeContribution(ctx: ExportContext): ManagedContribution {
   return singleFragment("prime", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
+function buildClineContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildClineClientConfig(ctx);
+  return singleFragment("cline", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
+}
+
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
   opencode: {
     id: "opencode",
@@ -1675,6 +1745,18 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // from this initial loopback-only integration — same stance as OMP's.
     loopbackOnly: true,
   },
+  cline: {
+    id: "cline",
+    filename: "providers.json",
+    destination: env => clineConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Cline reads a non-secret placeholder from providers.json; loopback needs no key.",
+    build: buildClineClientConfig,
+    format: "json",
+    summarize: summarizeCline,
+    buildContribution: buildClineContribution,
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];

package/src/clients/effective-status.ts

@@ -18,10 +18,11 @@ import { probePi } from "./probes/pi";
 import { probeGrok } from "./probes/grok";
 import { probeOpencode } from "./probes/opencode";
 import { probeAgy } from "./probes/agy";
+import { probeCline } from "./probes/cline";
 import { readCcSwitchCurrentProfiles, type CcSwitchProfile } from "./probes/cc-switch";
 import { readPaseoProviderCommands, type PaseoProviderCommand } from "./probes/paseo";
 
-export type ClientId = "claude" | "codex" | "pi" | "grok" | "opencode" | "agy";
+export type ClientId = "claude" | "codex" | "pi" | "grok" | "opencode" | "agy" | "cline";
 
 export type ClientVerdict = "ocx" | "direct" | "mixed" | "missing" | "unknown";
 
@@ -70,6 +71,7 @@ export interface EffectiveStatusOpts {
     grok?: typeof probeGrok;
     opencode?: typeof probeOpencode;
     agy?: typeof probeAgy;
+    cline?: typeof probeCline;
     ccSwitch?: typeof readCcSwitchCurrentProfiles;
     paseo?: typeof readPaseoProviderCommands;
   };
@@ -82,6 +84,7 @@ const CLIENT_LABELS: Record<ClientId, string> = {
   grok: "Grok Build",
   opencode: "OpenCode",
   agy: "Antigravity (agy)",
+  cline: "Cline",
 };
 
 /** Map client id → CC Switch `app_type` column (when present). */
@@ -90,6 +93,7 @@ const CC_SWITCH_APP: Partial<Record<ClientId, string>> = {
   codex: "codex",
   grok: "grokbuild",
   opencode: "opencode",
+  cline: "cline",
 };
 
 /** Map client id → Paseo `agents.providers` key. */
@@ -99,6 +103,7 @@ const PASEO_PROVIDER: Partial<Record<ClientId, string>> = {
   agy: "antigravity-acp",
   claude: "claude",
   codex: "codex",
+  cline: "cline",
 };
 
 export interface ProxyTarget {
@@ -220,13 +225,14 @@ export async function readClientsEffectiveStatus(
   const grokFn = opts.probes?.grok ?? probeGrok;
   const opencodeFn = opts.probes?.opencode ?? probeOpencode;
   const agyFn = opts.probes?.agy ?? probeAgy;
+  const clineFn = opts.probes?.cline ?? probeCline;
   const ccSwitchFn = opts.probes?.ccSwitch ?? readCcSwitchCurrentProfiles;
   const paseoFn = opts.probes?.paseo ?? readPaseoProviderCommands;
 
   const emptyProfiles: CcSwitchProfile[] = [];
   const emptyPaseo: PaseoProviderCommand[] = [];
 
-  const [ccProfiles, paseoCommands, claude, codex, pi, grok, opencode, agy] = await Promise.all([
+  const [ccProfiles, paseoCommands, claude, codex, pi, grok, opencode, agy, cline] = await Promise.all([
     safeProbeAsync("cc-switch", () => Promise.resolve(ccSwitchFn({ home })), emptyProfiles),
     safeProbeAsync("paseo", () => Promise.resolve(paseoFn({ home })), emptyPaseo),
     safeProbeAsync("claude", () => Promise.resolve(claudeFn({ home })), {
@@ -247,6 +253,9 @@ export async function readClientsEffectiveStatus(
     safeProbeAsync("agy", () => Promise.resolve(agyFn({ home })), {
       present: false, baseUrl: null, model: null, configPaths: [] as string[], notes: ["probe failed"], binary: null,
     }),
+    safeProbeAsync("cline", () => Promise.resolve(clineFn({ home })), {
+      present: false, baseUrl: null, model: null, configPaths: [] as string[], notes: ["probe failed"], binary: null,
+    }),
   ]);
 
   const clients: ClientEffectiveStatus[] = [];
@@ -372,6 +381,25 @@ export async function readClientsEffectiveStatus(
     });
   }
 
+  // Cline
+  {
+    const raw = cline;
+    const { verdict, viaOcx } = verdictFromBaseUrl(raw.baseUrl, proxy, { present: raw.present });
+    clients.push({
+      id: "cline",
+      label: CLIENT_LABELS.cline,
+      present: raw.present,
+      viaOcx,
+      verdict: raw.present ? (raw.baseUrl ? verdict : "unknown") : "missing",
+      baseUrl: raw.baseUrl,
+      model: raw.model,
+      configPaths: raw.configPaths,
+      launcher: paseoLauncher("cline", paseoCommands) ?? (raw.binary ? "cline" : null),
+      switcher: switcherFor("cline", ccProfiles),
+      notes: raw.notes,
+    });
+  }
+
   return {
     generatedAt: Date.now(),
     proxy: {

package/src/clients/probes/cline.ts

@@ -0,0 +1,81 @@
+/**
+ * Cline effective-status probe.
+ * Reads providers.json and checks for opencodex / openai-compatible configuration.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { clineConfigPath, clineHomeDir } from "../config-export";
+
+export interface ClineProbeResult {
+  present: boolean;
+  baseUrl: string | null;
+  model: string | null;
+  configPaths: string[];
+  notes: string[];
+  binary: string | null;
+}
+
+function resolveBinary(name: string): string | null {
+  try {
+    const which = (globalThis as { Bun?: { which?: (cmd: string) => string | null } }).Bun?.which;
+    if (typeof which === "function") {
+      return which(name) ?? null;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function probeCline(opts: { home: string; env?: NodeJS.ProcessEnv } = { home: "" }): ClineProbeResult {
+  const notes: string[] = [];
+  const binary = resolveBinary("cline");
+  const configPath = clineConfigPath(opts.env, opts.home);
+  const homeDir = clineHomeDir(opts.env, opts.home);
+  const exists = existsSync(configPath);
+  const dirExists = existsSync(homeDir);
+  const present = exists || dirExists || Boolean(binary);
+
+  if (!exists) {
+    if (present) {
+      notes.push("Cline installation detected, but providers.json is not configured yet.");
+    }
+    return {
+      present,
+      baseUrl: null,
+      model: null,
+      configPaths: existsSync(homeDir) ? [homeDir] : [configPath],
+      notes,
+      binary,
+    };
+  }
+
+  let baseUrl: string | null = null;
+  let model: string | null = null;
+
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      lastUsedProvider?: string;
+      providers?: Record<string, { settings?: { baseUrl?: string; model?: string; provider?: string } }>;
+    };
+    const providers = parsed?.providers ?? {};
+    const ocxProvider = providers.opencodex ?? providers["openai-compatible"];
+    if (ocxProvider?.settings?.baseUrl) {
+      baseUrl = ocxProvider.settings.baseUrl;
+      model = ocxProvider.settings.model ?? null;
+    } else if (parsed?.lastUsedProvider && providers[parsed.lastUsedProvider]?.settings?.baseUrl) {
+      const active = providers[parsed.lastUsedProvider]!;
+      baseUrl = active.settings?.baseUrl ?? null;
+      model = active.settings?.model ?? null;
+    }
+  } catch (error) {
+    notes.push(`Could not read providers.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  return {
+    present: true,
+    baseUrl,
+    model,
+    configPaths: [configPath],
+    notes,
+    binary,
+  };
+}

package/src/codex/account-label.ts

@@ -5,6 +5,27 @@ import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 
 export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
 
+/**
+ * Account log labels come in two families (#2699):
+ *
+ * - `p<hex6>` (plus the literal `main`) — a Codex pool account.
+ * - `o<hex6>` — a non-Codex OAuth provider account (xai, cursor, and siblings).
+ *
+ * Both are sha256-derived digests, never an email and never a raw provider account id. That is
+ * a privacy requirement, not a formatting preference: these labels are written to the usage log
+ * and served over the management API.
+ *
+ * hex6 is 16.7M values, so two accounts CAN collide and merge into one reported row. That is a
+ * reporting inaccuracy at operator scale, not a correctness or privacy failure, and it is the
+ * accepted cost of keeping the existing `p` format byte-compatible.
+ */
+export const OAUTH_ACCOUNT_LOG_LABEL_RE = /^o[a-f0-9]{6}$/;
+export const ACCOUNT_LOG_LABEL_RE = /^(?:main|[po][a-f0-9]{6})$/;
+
+export function oauthAccountLogLabel(accountId: string, provider = ""): string {
+  return `o${createHash("sha256").update(`${provider}\0${accountId}`).digest("hex").slice(0, 6)}`;
+}
+
 export function createCodexAccountLogLabel(existingLabels: Iterable<string | undefined | null> = []): string {
   const used = new Set([...existingLabels].filter((value): value is string => !!value));
   for (let i = 0; i < 16; i++) {

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

@@ -17,7 +17,8 @@ import {
 import { readCodexCatalogPath } from "./catalog/parsing";
 
 export const STALE_CODEX_APP_SERVER_HINT =
-  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex).";
+  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex). "
+  + "On Windows the desktop app itself may also need a full restart (ocx sync --restart-desktop-app).";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -259,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;
@@ -505,6 +523,7 @@ export function formatStaleCodexAppServerWarning(
     `WARNING: ${processes.length} Codex app-server process(es) still running (PID${processes.length === 1 ? "" : "s"}: ${pids}). `
     + "Disk catalog/cache were updated, but Codex may keep showing the old model list until those processes restart. "
     + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to send SIGTERM only to matching app-server processes. "
+    + "On Windows the desktop app itself may also need a full restart (`ocx sync --restart-desktop-app`). "
     + "Active turns may be interrupted."
   );
 }
@@ -738,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;
 }
@@ -833,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 = {},
@@ -851,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> => {
@@ -918,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,
@@ -932,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,59 @@ 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.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;
 }
 
@@ -1806,7 +1844,7 @@ export async function handleCodexAuthAPI(
   }
 
   if (url.pathname === "/api/codex-auth/login" && req.method === "POST") {
-    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean };
+    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean; openBrowser?: unknown };
     const requestedAccountId = body.id?.trim();
     const reauth = body.reauth === true;
     if (requestedAccountId && !isValidCodexAccountId(requestedAccountId)) {
@@ -1840,7 +1878,9 @@ export async function handleCodexAuthAPI(
 
       // Open the browser server-side (same pattern as /api/oauth/login in management-api.ts).
       // The GUI's window.open is popup-blocked because it runs after an await, not a direct click.
-      if (result.url) {
+      // Both login routes share one resolver so this surface cannot drift from the other.
+      const { shouldOpenBrowserForLogin } = await import("../oauth/open-browser-choice");
+      if (result.url && shouldOpenBrowserForLogin(body.openBrowser, runtimeConfig)) {
         const { openUrl } = await import("../lib/open-url");
         openUrl(result.url);
       }