@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/codex/auth-api/account-list.ts

@@ -1,3 +1,4 @@
+import { getMainAccountExternalUsageWarning, type MainAccountExternalUsageWarning } from "../main-account-external-usage";
 import { codexCreditsDtoField, hasCodexCreditsObservation, pruneCodexCredits } from "../credits";
 import type { CodexCredits } from "../credits";
 import { getMainChatgptAccountId } from "../auth-collision";
@@ -8,6 +9,7 @@ import type { StoredAccountQuota } from "../quota";
 import { ConfigMutationLockError, mutatePersistedConfig } from "../../config";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
+import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
 import { getCodexAccountPriority } from "../account-priority";
 import { getCodexAccountAutoSwitchThresholdOverride } from "../account-auto-switch";
 import { clearThreadAccountMapForAccount, isCodexAccountPlanExcluded, reconcileCodexActiveAfterExclusion } from "../routing";
@@ -15,7 +17,7 @@ import { codexPlanValue, isThirtyDayOnlyCodexPlan } from "../plan";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "../account-runtime-state";
 import { getValidMainAccountToken, MainAccountTokenRefreshError, MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 import { captureConfigGeneration } from "../../lib/state-store-sweeper";
-import { captureMainAccountIdentityGeneration, getMainAccountCredentialPresence, getMainAccountInfoCache, isMainAccountIdentityGenerationLive } from "../main-account-cache";
+import { captureMainAccountIdentityGeneration, getMainAccountCredentialPresence, getMainAccountInfoCache, getObservedMainQuotaIdentityKey, isMainAccountIdentityGenerationLive } from "../main-account-cache";
 import type { CodexQuotaRefreshOutcome } from "../quota-refresh-outcome";
 import { getMainAccountHardLockStatus } from "../main-account-hard-lock";
 import type { MainAccountHardLockStatus } from "../main-account-hard-lock";
@@ -139,6 +141,7 @@ export function poolAccountDto(
     paused,
     priority,
     autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(config, account.id),
+    creditsAfterLimit: codexAccountUsesCreditsAfterLimit(config, account.id),
     quota: quota ? { ...quota } : null,
     ...codexCreditsDtoField(config, account.id, poolQuotaHistoryIdentity(account.id) ?? null),
     needsReauth: needsReauth || health.status === "reauth_required",
@@ -165,6 +168,8 @@ export interface CodexAuthAccountDto {
   priority: number;
   /** Null inherits the global usage-switch threshold; 0 disables it for this account. */
   autoSwitchThresholdOverride: number | null;
+  /** False keeps the account out of selection while one of its usage windows is full. */
+  creditsAfterLimit?: boolean;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   credits?: CodexCredits;
   needsReauth?: boolean;
@@ -183,7 +188,7 @@ export interface CodexAuthAccountDto {
   healthAction?: string;
   quotaProbeSkipped?: true;
   quotaRefresh?: CodexQuotaRefreshOutcome;
-  mainAccountHardLock?: MainAccountHardLockStatus;
+  mainAccountHardLock?: MainAccountHardLockStatus & { externalUsage?: MainAccountExternalUsageWarning };
 }
 
 export interface FreshPoolPlanUpdate {
@@ -371,9 +376,11 @@ export async function listCodexAuthAccountsSnapshot(
     logLabel: "main",
     isMain: true,
     paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
-    mainAccountHardLock: getMainAccountHardLockStatus(runtimeConfig),
+    mainAccountHardLock: { ...getMainAccountHardLockStatus(runtimeConfig),
+      externalUsage: getMainAccountExternalUsageWarning(getObservedMainQuotaIdentityKey()) },
     priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+    creditsAfterLimit: codexAccountUsesCreditsAfterLimit(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     hasCredential: hasMainCredential,
     needsReauth: mainNeedsReauth,
     ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),

package/src/codex/auth-api/routes.ts

@@ -6,6 +6,7 @@ import { readUsageSnapshotForManagement } from "../../usage/log";
 import { getAccountQuotaHistory, listAccountQuotas } from "../quota";
 import { deleteCodexAccount } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
+import { setAllCodexAccountsCreditsAfterLimit, setCodexAccountCreditsAfterLimit } from "../account-credit-use";
 import { clearCodexAccountPin, isCodexAccountPriorityKey, pinnedCodexAccountId, setCodexAccountPin, setCodexAccountPriority } from "../account-priority";
 import { codexAccountPinDrainReason, codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
 import { DEFAULT_ACCOUNT_PRIORITY, MAX_ACCOUNT_PRIORITY, MIN_ACCOUNT_PRIORITY, normalizeAccountPoolStickyLimit, normalizeCodexAccountPoolStrategy, parseAccountPoolStickyLimit, parseCodexAccountPoolStrategy, parseAccountPriority } from "../pool-rotation";
@@ -114,6 +115,39 @@ export async function handleCodexAuthAPI(
     });
   }
 
+  // Pool accounts and `__main__`, like pause. Spending is opt-in: an account not on the list is
+  // skipped by the next selection while a usage window is full, and a bound thread is released
+  // through the usual block reason, so nothing is cleared here. `{ all }` is the dashboard's
+  // global switch: on lists every current account, off clears the list.
+  if (url.pathname === "/api/codex-auth/accounts/credits" && req.method === "PUT") {
+    const parsed: unknown = await req.json().catch(() => null);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return jsonResponse({ error: "body must be an object" }, 400);
+    }
+    const body = parsed as { id?: unknown; creditsAfterLimit?: unknown; all?: unknown };
+    const runtimeConfig = getRuntimeConfig(config);
+    if (body.all !== undefined) {
+      if (typeof body.all !== "boolean") return jsonResponse({ error: "all must be a boolean" }, 400);
+      const ids = [MAIN_CODEX_ACCOUNT_ID, ...(runtimeConfig.codexAccounts ?? [])
+        .filter(isSelectableCodexPoolAccount)
+        .map(account => account.id)];
+      setAllCodexAccountsCreditsAfterLimit(runtimeConfig, ids, body.all);
+      saveRuntimeConfig(config, runtimeConfig);
+      return jsonResponse({ ok: true, all: body.all, ids: runtimeConfig.creditCodexAccountIds ?? [] });
+    }
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (id !== MAIN_CODEX_ACCOUNT_ID && !isValidCodexAccountId(id)) return jsonResponse({ error: "Invalid account id format" }, 400);
+    if (typeof body.creditsAfterLimit !== "boolean") return jsonResponse({ error: "creditsAfterLimit must be a boolean" }, 400);
+
+    const exists = id === MAIN_CODEX_ACCOUNT_ID
+      || (runtimeConfig.codexAccounts ?? []).some(account => isSelectableCodexPoolAccount(account) && account.id === id);
+    if (!exists) return jsonResponse({ error: "Account not found" }, 404);
+
+    setCodexAccountCreditsAfterLimit(runtimeConfig, id, body.creditsAfterLimit);
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true, id, creditsAfterLimit: body.creditsAfterLimit });
+  }
+
   // Deliberately a route of its own rather than a field on the alias PATCH: aliases
   // are display-only and reject __main__, while selection order is routing metadata
   // that the Desktop account must be able to carry. Re-ordering never kicks a live

package/src/codex/auth-context.ts

@@ -1,3 +1,4 @@
+import { noteMainAccountActivity } from "./main-account-external-usage";
 import { codexAccountPriorityFailbackEnabled } from "./account-priority";
 import type { PoolQuotaWriter } from "./quota-types";
 import { createHash, timingSafeEqual } from "node:crypto";
@@ -63,13 +64,14 @@ import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./cata
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse } from "../bridge";
-import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
+import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, getMainPolicyQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
+import { codexAccountUsesCreditsAfterLimit, codexUsageLimitResetAt } from "./account-credit-use";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { captureConfigGeneration } from "../lib/state-store-sweeper";
 import { extractAccountId, extractEmail } from "../oauth/chatgpt";
 import {
-  MAIN_ACCOUNT_HARD_LOCK_PERCENT,
+  resolveMainAccountHardLockThresholds,
   getMainAccountHardLockStatus,
   isMainAccountHardLockEnabled,
   isMainAccountHardLocked,
@@ -117,7 +119,7 @@ function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
  *
  * Read-free by construction, which is what makes it usable on the fenced side. Every input is
  * config, policy, or in-memory runtime state: the pin fields, the paused list, the cached quota
- * score, and `callerMatchesObservedMain`, which compares HMAC digests against the observed
+ * score, the main policy quota the hard lock and the credits switch read, and `callerMatchesObservedMain`, which compares HMAC digests against the observed
  * credential record in `main-account-cache.ts`. Nothing here opens a file.
  *
  * `candidate` is the pin before the hard-lock question, because the caller still owes the
@@ -141,6 +143,7 @@ export function requestOwnedMainPinState(
     candidate,
     preserve: candidate && !(callerMatchesObservedMain(headers)
       && (isMainAccountHardLocked(policy)
+        || mainCreditsHoldResetAt(policy) !== undefined
         || getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope)?.cooldownUntil)),
   };
 }
@@ -510,15 +513,28 @@ export class CodexAccountCooldownError extends Error {
 export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
   readonly resetAt?: number;
 
-  constructor(resetAt?: number) {
+  constructor(resetAt?: number, thresholds = resolveMainAccountHardLockThresholds(undefined)) {
     super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
     this.name = "CodexMainAccountHardLockError";
     this.resetAt = resetAt;
-    this.message = `Codex main account is blocked by the ${MAIN_ACCOUNT_HARD_LOCK_PERCENT}% main-account quota policy.`
+    this.message = `Codex main account is blocked by the main-account quota policy (5h ≥ ${thresholds.short}%, weekly ≥ ${thresholds.long}%).`
       + " Choose another account, wait for quota to reset, or disable codexMainAccountHardLock in Settings.";
   }
 }
 
+/** The main login may not spend credits and one of its usage windows is full (#6334). */
+export class CodexMainAccountCreditsOffError extends CodexAccountCooldownError {
+  readonly resetAt?: number;
+
+  constructor(resetAt?: number) {
+    super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
+    this.name = "CodexMainAccountCreditsOffError";
+    this.resetAt = resetAt;
+    this.message = "Codex main account reached its usage limit, and spending ChatGPT credits is off for it."
+      + " Choose another account, wait for the limit to reset, or allow the main account under \"Use credits\" in Codex Auth.";
+  }
+}
+
 export class CodexReserveUnavailableError extends CodexAccountCooldownError {
   constructor() {
     super(MAIN_CODEX_ACCOUNT_ID, 0);
@@ -577,7 +593,8 @@ export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
 }
 
 export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
-  "codexMainAccountHardLock" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
+  "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
+  | "creditCodexAccountIds"
 >>;
 
 interface CodexAuthMaterializationOptions {
@@ -700,10 +717,28 @@ export function unwrapUpstreamRetryEvidenceError(error: unknown): unknown {
   return error;
 }
 
-function assertMainAccountPolicy(config: Pick<OcxConfig, "codexMainAccountHardLock"> | undefined): void {
-  if (!config) return;
-  const status = getMainAccountHardLockStatus(config);
-  if (status.state === "blocked") throw new CodexMainAccountHardLockError(status.resetAt);
+/**
+ * When the main login's full window ends, if credits are off for it and a window is full (#6334).
+ * Same evidence the hard lock reads, and no plan lookup: the plan can live in the physical auth
+ * file, which several callers are forbidden to open, so every long window counts instead.
+ */
+function mainCreditsHoldResetAt(config: Pick<OcxConfig, "creditCodexAccountIds">): number | undefined {
+  if (codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)) return undefined;
+  return codexUsageLimitResetAt(getMainPolicyQuota(), undefined, Date.now());
+}
+
+function assertMainAccountPolicy(
+  config: Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "creditCodexAccountIds"> | undefined,
+): void {
+  if (config) {
+    const status = getMainAccountHardLockStatus(config);
+    if (status.state === "blocked") throw new CodexMainAccountHardLockError(status.resetAt, status.thresholds);
+    const creditsResetAt = mainCreditsHoldResetAt(config);
+    if (creditsResetAt !== undefined) throw new CodexMainAccountCreditsOffError(creditsResetAt);
+  }
+  // Only an admitted request is opencodex's own use of the main account. Counting a refused one
+  // would hide outside usage from the warning exactly while the lock is holding.
+  noteMainAccountActivity();
 }
 
 /** No auth-file I/O: an unsigned claim alone never identifies a caller as stored main. */
@@ -826,6 +861,9 @@ export function cooldownAccountLabel(accountId: string): string {
  */
 export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSelector?: string): string {
   if (err instanceof CodexMainAccountHardLockError
+    // A credits-off refusal is a configuration policy, not a cooldown: clearing a cooldown
+    // cannot lift it, so its own wording (wait for the reset or allow credits) is the remedy.
+    || err instanceof CodexMainAccountCreditsOffError
     || err instanceof CodexReserveUnavailableError
     // A transient-hold refusal is not a quota cooldown. Its own wording is the only accurate
     // one, and the quota recovery advice below would send the operator after a cooldown that
@@ -874,6 +912,7 @@ export class CodexThreadAffinityExpiredError extends Error {
 
 export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
   return !(cause instanceof CodexMainAccountHardLockError)
+    && !(cause instanceof CodexMainAccountCreditsOffError)
     && !(cause instanceof CodexAccountValidationPendingError)
     && !(cause instanceof CodexReserveUnavailableError)
     && !(cause instanceof CodexCredentialGenerationConflictError)
@@ -1428,7 +1467,9 @@ export async function resolveCodexAuthContext(
       releaseTransientProbeGrant();
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
-      if (cause instanceof CodexMainAccountHardLockError) throw cause;
+      // Policy refusals, including one that lands while the token refresh was in flight, are not
+      // authentication failures: they must stay reset-bound 429s and never mark a valid login.
+      if (cause instanceof CodexMainAccountHardLockError || cause instanceof CodexMainAccountCreditsOffError) throw cause;
       if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
         markAccountNeedsReauth(accountId, writerGeneration);
       }

package/src/codex/catalog/discovered-natives.ts

@@ -21,6 +21,7 @@ export const DISCOVERED_NATIVE_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
  */
 export const DISCOVERED_NATIVE_RENEW_INTERVAL_MS = 60 * 60 * 1000;
 const FILE_NAME = "discovered-native-models.json";
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
 
 export interface DiscoveredNativeModel {
   slug: string;
@@ -35,6 +36,13 @@ let models: DiscoveredNativeModel[] = [];
 let fingerprint = "[]";
 let generation = 0;
 
+function containsLoneSurrogate(value: unknown): boolean {
+  if (typeof value === "string") return LONE_SURROGATE.test(value);
+  if (Array.isArray(value)) return value.some(containsLoneSurrogate);
+  if (!value || typeof value !== "object") return false;
+  return Object.entries(value).some(([key, child]) => LONE_SURROGATE.test(key) || containsLoneSurrogate(child));
+}
+
 /** Validate untrusted roster rows without filesystem effects; keep upstream capability metadata. */
 export function validateDiscoveredNativeRows(rows: unknown): Record<string, unknown>[] {
   if (!Array.isArray(rows)) return [];
@@ -56,8 +64,10 @@ export function validateDiscoveredNativeRows(rows: unknown): Record<string, unkn
     try {
       const serialized = JSON.stringify(row);
       if (Buffer.byteLength(serialized, "utf8") > DISCOVERED_NATIVE_MAX_ROW_BYTES) continue;
+      const cloned = JSON.parse(serialized) as Record<string, unknown>;
+      if (containsLoneSurrogate(cloned)) continue;
       if (accepted.size >= DISCOVERED_NATIVE_MAX_ROWS && !accepted.has(row.slug)) continue;
-      accepted.set(row.slug, JSON.parse(serialized) as Record<string, unknown>);
+      accepted.set(row.slug, cloned);
     } catch { /* Cyclic/non-JSON rows cannot be persisted or sent to Codex. */ }
   }
   return [...accepted.values()];

package/src/codex/catalog/gather-capture.ts

@@ -121,6 +121,8 @@ export interface ModelsAuthResolution {
   readonly apiKey: string | undefined;
   readonly observed: boolean;
   readonly oauthAccountId?: string;
+  /** Upstream user id carried by the OAuth snapshot (Zed); distinct from the store slot id. */
+  readonly oauthProviderUserId?: string;
   readonly oauthGeneration?: string;
   readonly oauthApiBaseUrl?: string;
   readonly oauthProjectId?: string;
@@ -417,6 +419,7 @@ export function captureProviderGather(
     finalMethod: request.method,
     finalUrl: request.url,
     filter: capturedField(discovery.spec, "filter"),
+    preferFirst: capturedField(discovery.spec, "preferFirst"),
     maxResponseBytes: discovery.maxResponseBytes,
     maxModels: discovery.maxModels,
     trustedOpenAiApi,
@@ -446,7 +449,9 @@ export function captureGatherFlight(
   const authResolver = createAuthResolver(providerAuthOutcomes);
   const comboTargetsByProvider = configuredComboTargetModelsByProvider(config);
   const providers = Object.entries(config.providers)
-    .filter(([, provider]) => provider.disabled !== true)
+    // A decision service (canonical TypeSafe or a self-hosted `jev-decision` row) owns no model
+    // transport: never probe its endpoint for /models and never publish its model id as routable.
+    .filter(([, provider]) => provider.disabled !== true && provider.adapter !== "jev-decision")
     .map(([name, provider]) => captureProviderGather(
       name,
       provider,

package/src/codex/catalog/model-hints.ts

@@ -604,7 +604,12 @@ export function modelInputModalities(
   ))) {
     return ["text", "image"];
   }
-  return undefined;
+  // OpenGateway publishes modalities as { input: [...], output: [...] }, not an array.
+  // Append this fallback after all recognized signals so existing providers keep their
+  // resolution, and retain Codex's closed enum rather than advertising output modalities.
+  const nestedInput = normalizedStringList(plainRecord(item.modalities)?.input, 8, 24)
+    ?.filter(value => value === "text" || value === "image" || value === "audio");
+  return nestedInput && nestedInput.length > 0 ? nestedInput : undefined;
 }
 
 /**
@@ -688,6 +693,9 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
       // real values. Appended after the recognized fields for the same reason as the
       // llama.cpp entries above: no provider that already resolves changes behavior.
       capabilityRecord?.context_length,
+      // OpenGateway publishes a top-level context_window. Keep this last so catalogs
+      // already resolving through any recognized field retain their existing window.
+      item.context_window,
     );
   const maxInputTokens = positiveSafeInteger(limits?.max_input_tokens, item.max_input_tokens);
   const maxOutputTokens = positiveSafeInteger(

package/src/codex/catalog/provider-models.ts

@@ -62,6 +62,7 @@ import { fetchCodeBuddyModels } from "../../adapters/codebuddy/live-models";
 import { resolveProfileByBaseUrl } from "../../adapters/coding-agent/profile";
 import { fetchDevinUsableModels } from "../../adapters/devin/live-models";
 import { resolveDevinApiBaseUrl } from "../../oauth/devin/api-base";
+import { resolveZedModels } from "../../providers/zed";
 import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import {
   COMBO_NAMESPACE,
@@ -152,6 +153,7 @@ export function observedModelsAuthResolver(
         observed: true,
         oauthAccountId: observation.snapshot.accountId,
         oauthGeneration: observation.snapshot.generation,
+        ...(observation.snapshot.providerUserId ? { oauthProviderUserId: observation.snapshot.providerUserId } : {}),
         ...(observation.snapshot.apiBaseUrl ? { oauthApiBaseUrl: observation.snapshot.apiBaseUrl } : {}),
         ...(observation.snapshot.projectId ? { oauthProjectId: observation.snapshot.projectId } : {}),
       };
@@ -263,6 +265,7 @@ export async function fetchProviderModelsWithAuth(
           observed: false,
           oauthAccountId: snapshot.accountId,
           oauthGeneration: snapshot.generation,
+          ...(snapshot.providerUserId ? { oauthProviderUserId: snapshot.providerUserId } : {}),
           ...(snapshot.apiBaseUrl ? { oauthApiBaseUrl: snapshot.apiBaseUrl } : {}),
           ...(snapshot.projectId ? { oauthProjectId: snapshot.projectId } : {}),
         }))
@@ -342,6 +345,63 @@ export async function fetchProviderModelsWithAuth(
       stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias) : configured,
     ), "degraded");
   }
+  if (name === "zed" && prov.adapter === "zed") {
+    if (!apiKey || !auth.oauthAccountId || !auth.oauthProviderUserId) return observed(configured, "degraded");
+    // Zed's roster and short-lived inference token are both account-scoped. Keep the
+    // catalog cache bound to the same pair so a multi-account switch cannot reuse a stale
+    // roster even when the provider destination is unchanged.
+    const authorityIdentity = createHash("sha256")
+      .update(JSON.stringify([auth.oauthAccountId, apiKey])).digest("hex");
+    const cached = getFreshCached(name, ttlMs, Date.now(), authorityIdentity);
+    if (cached) {
+      return observed(
+        withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cached, contextCap, metadataModelIdCaseFold, captured.effectiveAlias)),
+        "authoritative",
+      );
+    }
+    const stale = getStaleCached(name, authorityIdentity);
+    if (isModelsFetchCoolingDown(name, undefined, undefined, authorityIdentity) && stale) {
+      return observed(
+        withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, stale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias)),
+        "degraded",
+      );
+    }
+    const zedFetch = (prov as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch;
+    try {
+      const live = await resolveZedModels(
+        // Zed signs with its own user id; the slot id only keys the catalog cache above.
+        { userId: auth.oauthProviderUserId, accessToken: apiKey },
+        { signal: AbortSignal.timeout(8_000), ...(zedFetch ? { fetchFn: zedFetch } : {}) },
+      );
+      const discovered = live.models.map(model => {
+        const reasoningEfforts = sanitizeCodexReasoningEfforts(model.supportedEffortLevels);
+        return {
+          id: model.id,
+          provider: name,
+          ...(model.contextLength ? { contextWindow: model.contextLength } : {}),
+          ...(model.maxOutputTokens ? { maxOutputTokens: model.maxOutputTokens } : {}),
+          ...(model.supportsImages ? { inputModalities: ["text", "image"] } : {}),
+          ...(reasoningEfforts?.length ? { reasoningEfforts } : {}),
+          ...catalogHintsFromProviderConfig(name, prov, model.id, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
+        } as CatalogModel;
+      });
+      const forCache = withConfiguredRetention(discovered, { retainComboTargets: false });
+      if (!setCached(name, forCache, Date.now(), cacheGeneration, authorityIdentity)) {
+        return observed(withConfiguredRetention(configured), "degraded");
+      }
+      markProviderDiscoveryOk(name, live.models.length);
+      return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
+    } catch {
+      if (isCurrentCacheGeneration()) {
+        markModelsFetchFailure(name, undefined, authorityIdentity);
+        markProviderDiscoveryFailed(name, { reason: "provider" });
+      }
+      return observed(
+        withConfiguredRetention(stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias) : configured),
+        "degraded",
+      );
+    }
+  }
   if (prov.adapter === "qoder") {
     if (!apiKey) return observed(configured, "degraded");
     const profile = resolveQoderProfile(prov.baseUrl);

package/src/codex/catalog/routed-gather.ts

@@ -528,7 +528,16 @@ async function gatherRoutedModelsUncached(
     else warnUncataloguedComboOnce(id, combo, members, localOmissions);
   }
   replaceLastComboCatalogOmissions(localOmissions);
-  all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
+  // Preserve declaratively ordered discovery (and cold-start seed order); other presets
+  // retain their historical alphabetical order. Renamed/custom transport scoping still applies.
+  // Read the captured discovery policy, never the live registry: a flight must keep the
+  // authority it was captured under even if the registry changes mid-gather.
+  const orderedProviders = new Set(activeProviders
+    .filter(({ discovery }) => (discovery.spec?.preferFirst?.length ?? 0) > 0)
+    .map(({ name }) => name));
+  all.sort((a, b) => (a.provider === b.provider
+    ? orderedProviders.has(a.provider) ? 0 : a.id.localeCompare(b.id)
+    : a.provider.localeCompare(b.provider)));
   // Provider-derived rows keyed by their Codex-facing slug: a custom override replaces the row
   // with the same slug below, so that row's provider capability metadata is the inheritance source.
   const replacedByRoutedSlug = new Map(all.map(model => [routedSlug(model.provider, model.id), model]));
@@ -737,10 +746,26 @@ async function gatherRoutedModelsUncached(
     }
     return mergedWithAutoCompact;
   });
-  // Custom rows override discovered rows that encode to the same Codex-facing slug.
-  const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));
-  const deduped = all.filter(m => !customKeys.has(routedSlug(m.provider, m.id)));
-  const models = [...deduped, ...customModels];
+  // Custom rows override discovered rows that encode to the same Codex-facing slug. A provider whose
+  // captured discovery declares an order (preferFirst) keeps each replacement in the discovered row's
+  // slot; every other provider keeps the historical order of discovered rows followed by custom rows.
+  const customBySlug = new Map<string, CatalogModel[]>();
+  for (const custom of customModels) {
+    const key = routedSlug(custom.provider, custom.id);
+    const bucket = customBySlug.get(key);
+    if (bucket) bucket.push(custom);
+    else customBySlug.set(key, [custom]);
+  }
+  const placedInSlot = new Set<string>();
+  const models: CatalogModel[] = all.flatMap(model => {
+    const key = routedSlug(model.provider, model.id);
+    const replacements = customBySlug.get(key);
+    if (!replacements) return [model];
+    if (!orderedProviders.has(model.provider) || placedInSlot.has(key)) return [];
+    placedInSlot.add(key);
+    return replacements;
+  });
+  models.push(...customModels.filter(custom => !placedInSlot.has(routedSlug(custom.provider, custom.id))));
   // ponytail: catalog-scale scan; index ids by provider if catalog growth makes this measurable.
   const aliasDisplayNames = new Map(activeProviders.flatMap(({ name, provider }) => {
     const providerModels = models.filter(model => model.provider === name);

package/src/codex/convergence-types.ts

@@ -14,7 +14,7 @@
  * behavior at its own commit, which a runtime placeholder here would break.
  */
 import type { OcxConfig } from "../types";
-import type { ProviderModelDiscoveryFilter } from "../providers/registry";
+import type { ProviderModelDiscoveryFilter, ProviderModelDiscoveryPredicate } from "../providers/registry";
 
 /**
  * The non-CAS JSON record for the Codex integration.
@@ -448,6 +448,7 @@ export interface CatalogProviderDiscoveryPolicySnapshot {
   readonly finalMethod: "GET" | "POST";
   readonly finalUrl: string;
   readonly filter: CatalogDiscoveryPolicyField<ProviderModelDiscoveryFilter | undefined>;
+  readonly preferFirst: CatalogDiscoveryPolicyField<readonly ProviderModelDiscoveryPredicate[] | undefined>;
   readonly maxResponseBytes: number;
   readonly maxModels: number;
   readonly trustedOpenAiApi: CatalogTrustedOpenAiApiPolicySnapshot;

package/src/codex/main-account-external-usage.ts

@@ -0,0 +1,62 @@
+/** Advisory fresh-observation detector. No persistence, timers, or merged quota reads. */
+export const EXTERNAL_USAGE_QUIET_MS = 30 * 60_000;
+export const EXTERNAL_USAGE_TTL_MS = 6 * 60 * 60_000;
+export type FreshWindow = { kind: "short" | "long"; percent: number; resetAtMs: number };
+export type MainAccountExternalUsageWarning = {
+  window: "short" | "long";
+  fromPercent: number;
+  toPercent: number;
+  observedAt: number;
+};
+type Reading = { percent: number; resetAtMs: number; observedAt: number;
+  warning?: MainAccountExternalUsageWarning };
+let baseline: { identityKey: string; perWindow: Partial<Record<FreshWindow["kind"], Reading>> } | undefined;
+let lastActivity = -Infinity;
+
+export function noteMainAccountActivity(now = Date.now()): void {
+  lastActivity = now;
+}
+
+/** Only validated usage with a known reset from this observation reaches the baseline. */
+export function observeMainAccountUsage(identityKey: string, windows: FreshWindow[], now = Date.now()): void {
+  if (baseline?.identityKey !== identityKey) baseline = { identityKey, perWindow: {} };
+  for (const window of windows) {
+    if (!Number.isFinite(window.percent) || window.percent < 0 || window.percent > 100
+      || !Number.isFinite(window.resetAtMs) || window.resetAtMs <= 0) continue;
+    const previous = baseline.perWindow[window.kind];
+    const sameEpisode = previous?.resetAtMs === window.resetAtMs;
+    let warning = sameEpisode ? previous?.warning : undefined;
+    if (sameEpisode && previous && window.percent - previous.percent >= 1
+      && lastActivity < previous.observedAt - EXTERNAL_USAGE_QUIET_MS) {
+      warning = { window: window.kind, fromPercent: previous.percent,
+        toPercent: window.percent, observedAt: now };
+    }
+    baseline.perWindow[window.kind] = { percent: window.percent, resetAtMs: window.resetAtMs,
+      observedAt: now, ...(warning ? { warning } : {}) };
+  }
+}
+
+export function forgetMainAccountUsage(): void {
+  baseline = undefined;
+}
+
+export function getMainAccountExternalUsageWarning(
+  identityKey: string | undefined, now = Date.now(),
+): MainAccountExternalUsageWarning | undefined {
+  if (!identityKey || baseline?.identityKey !== identityKey) return undefined;
+  for (const kind of ["short", "long"] as const) {
+    const reading = baseline.perWindow[kind];
+    if (!reading?.warning) continue;
+    if (now >= reading.resetAtMs || now - reading.warning.observedAt >= EXTERNAL_USAGE_TTL_MS) {
+      delete reading.warning;
+      continue;
+    }
+    return { ...reading.warning };
+  }
+  return undefined;
+}
+
+export function resetMainAccountExternalUsageForTests(): void {
+  forgetMainAccountUsage();
+  lastActivity = -Infinity;
+}

package/src/codex/main-account-hard-lock.ts

@@ -1,6 +1,6 @@
 import type { OcxConfig } from "../types";
 import { getMainPolicyQuota } from "./quota";
-import { MAIN_ACCOUNT_HARD_LOCK_PERCENT } from "./quota-types";
+import { MAIN_ACCOUNT_HARD_LOCK_PERCENT, MAIN_ACCOUNT_HARD_LOCK_SHORT_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT } from "./quota-types";
 
 export { MAIN_ACCOUNT_HARD_LOCK_PERCENT };
 
@@ -9,9 +9,19 @@ export interface MainAccountHardLockStatus {
   state: "off" | "unknown" | "ready" | "blocked";
   /** Unix milliseconds; absent when a blocking observation has no future reset. */
   resetAt?: number;
+  thresholds: { short: number; long: number };
+  window?: "short" | "long";
 }
 
-type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock">;
+type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds">;
+
+export function resolveMainAccountHardLockThresholds(config: PolicyConfig | undefined): { short: number; long: number } {
+  const valid = (value: unknown, fallback: number): number => typeof value === "number"
+    && Number.isInteger(value) && value >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT && value <= 100 ? value : fallback;
+  const long = valid(config?.codexMainAccountHardLockThresholds?.long, MAIN_ACCOUNT_HARD_LOCK_PERCENT);
+  const short = valid(config?.codexMainAccountHardLockThresholds?.short, MAIN_ACCOUNT_HARD_LOCK_SHORT_PERCENT);
+  return { short: Math.min(short, long), long };
+}
 
 /**
  * Whether the main-account hard lock applies to this config (#5694).
@@ -31,11 +41,11 @@ function resetTimestamp(value: number | undefined): number | undefined {
   return value < 10_000_000_000 ? value * 1000 : value;
 }
 
-type WindowReading = { percent: number | undefined; resetAt: number | undefined };
+type WindowReading = { kind: "short" | "long"; percent: number | undefined; resetAt: number | undefined };
 
 /**
  * The windows that govern the lock. The 5h and weekly windows each govern on their own, so either
- * one at 98% blocks even while the other has headroom. Monthly governs only a monthly-only account:
+ * one at its configured threshold blocks even while the other has headroom. Monthly governs only a monthly-only account:
  * supplementary monthly data on a 5h/weekly account never becomes a lock. The list is never empty,
  * so a record with no readings at all classifies as unknown rather than vacuously ready.
  */
@@ -44,9 +54,9 @@ function governingWindows(quota: NonNullable<ReturnType<typeof getMainPolicyQuot
     || quota.shortWindowSeconds !== undefined;
   const hasWeekly = quota.weeklyPercent !== undefined || quota.weeklyResetAt !== undefined;
   const windows: WindowReading[] = [];
-  if (hasShort) windows.push({ percent: quota.shortPercent, resetAt: quota.shortResetAt });
-  if (hasWeekly) windows.push({ percent: quota.weeklyPercent, resetAt: quota.weeklyResetAt });
-  if (windows.length === 0) windows.push({ percent: quota.monthlyPercent, resetAt: quota.monthlyResetAt });
+  if (hasShort) windows.push({ kind: "short", percent: quota.shortPercent, resetAt: quota.shortResetAt });
+  if (hasWeekly) windows.push({ kind: "long", percent: quota.weeklyPercent, resetAt: quota.weeklyResetAt });
+  if (windows.length === 0) windows.push({ kind: "long", percent: quota.monthlyPercent, resetAt: quota.monthlyResetAt });
   return windows;
 }
 
@@ -60,22 +70,23 @@ export function getMainAccountHardLockStatus(
   config: PolicyConfig,
   now = Date.now(),
 ): MainAccountHardLockStatus {
-  if (!isMainAccountHardLockEnabled(config)) return { enabled: false, state: "off" };
+  const thresholds = resolveMainAccountHardLockThresholds(config);
+  if (!isMainAccountHardLockEnabled(config)) return { enabled: false, state: "off", thresholds };
   const quota = getMainPolicyQuota();
-  if (!quota) return { enabled: true, state: "unknown" };
+  if (!quota) return { enabled: true, state: "unknown", thresholds };
   const windows = governingWindows(quota);
-  const blocking = windows.filter(w => validPercent(w.percent) && w.percent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT);
+  const blocking = windows.filter(w => validPercent(w.percent) && w.percent >= thresholds[w.kind]);
   if (blocking.length > 0) {
     // The lock holds until every blocking window reads lower or is authoritatively absent, so the earliest possible unlock is
     // the latest blocking reset. One blocking window without a future reset makes it unknowable.
     // A predicted reset is not evidence of recovery; fresh lower usage or validated WHAM absence releases.
     const resets = blocking.map(w => resetTimestamp(w.resetAt));
     const resetAt = resets.every(r => r !== undefined && r > now) ? Math.max(...(resets as number[])) : undefined;
-    return { enabled: true, state: "blocked", ...(resetAt !== undefined ? { resetAt } : {}) };
+    return { enabled: true, state: "blocked", thresholds, window: blocking[0]!.kind, ...(resetAt !== undefined ? { resetAt } : {}) };
   }
   // Unknown admits, so an unreadable window never hides a blocking one and never blocks alone.
-  if (windows.some(w => !validPercent(w.percent))) return { enabled: true, state: "unknown" };
-  return { enabled: true, state: "ready" };
+  if (windows.some(w => !validPercent(w.percent))) return { enabled: true, state: "unknown", thresholds };
+  return { enabled: true, state: "ready", thresholds };
 }
 
 export function isMainAccountHardLocked(config: PolicyConfig, now = Date.now()): boolean {