@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/clients/config-export.ts

@@ -107,15 +107,9 @@ export const OPENCODE_API_KEY_ENV = "OPENCODEX_OPENCODE_API_KEY";
 /** Env reference shared by apiKey and the dedicated proxy admission header. */
 export const OPENCODE_API_KEY_ENV_REF = `{env:${OPENCODE_API_KEY_ENV}}`;
 
-/** Env var Pi interpolates. Pi takes bare `$NAME`, not opencode's `{env:NAME}`. */
-export const PI_API_KEY_ENV = "OPENCODEX_API_KEY";
-
-/** Pi's reference form for the admission key. Never the value. */
-export const PI_API_KEY_ENV_REF = `$${PI_API_KEY_ENV}`;
-
 /**
  * Hermes interpolates `${VAR}` anywhere in config.yaml, so the credential stays
- * in the environment exactly as it does for OpenCode and Pi.
+ * in the environment exactly as it does for OpenCode.
  */
 export const HERMES_API_KEY_ENV = "OPENCODEX_HERMES_API_KEY";
 export const HERMES_API_KEY_ENV_REF = `\${${HERMES_API_KEY_ENV}}`;
@@ -125,12 +119,12 @@ export const OPENCLAW_API_KEY_ENV = "OPENCODEX_OPENCLAW_API_KEY";
 export const OPENCLAW_API_KEY_ENV_REF = `\${${OPENCLAW_API_KEY_ENV}}`;
 
 /**
- * Kimi Code reads credentials ONLY from its config file — it never falls back
- * to the shell environment. A loopback bind needs no real admission key, so we
- * emit the same placeholder the Grok managed block uses rather than a user
- * secret; a non-loopback bind is refused by the writer instead of papered over.
+ * Placeholder credential for loopback-only clients (Kimi, Pi). A loopback
+ * bind needs no real admission key, so we emit the same placeholder the Grok
+ * managed block uses rather than a user secret. Pi resolves `apiKey` before
+ * building its model list and hides the provider when an env reference is unset.
  */
-export const KIMI_LOOPBACK_PLACEHOLDER = "opencodex-loopback";
+export const LOOPBACK_API_KEY_PLACEHOLDER = "opencodex-loopback";
 
 /**
  * Gajae's `apiKeyEnv` is env-name-only and fail-closed. Its sibling `apiKey`
@@ -728,7 +722,7 @@ function buildPiClientConfig(ctx: ExportContext): PiGeneratedConfig {
       [OPENCODE_PROVIDER_ID]: {
         baseUrl: ctx.baseUrl,
         api: PI_API_DIALECT,
-        apiKey: PI_API_KEY_ENV_REF,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
         models,
       },
     },
@@ -808,7 +802,7 @@ function buildKimiClientConfig(ctx: ExportContext): KimiGeneratedConfig {
       [OPENCODE_PROVIDER_ID]: {
         type: "openai",
         base_url: ctx.baseUrl,
-        api_key: KIMI_LOOPBACK_PLACEHOLDER,
+        api_key: LOOPBACK_API_KEY_PLACEHOLDER,
       },
     },
     models,
@@ -949,15 +943,14 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     id: "pi",
     filename: "pi-models.json",
     destination: () => join(homedir(), ".pi", "agent", "models.json"),
-    apiKeyEnv: PI_API_KEY_ENV,
-    exportHint: `export ${PI_API_KEY_ENV}=<your key>`,
+    apiKeyEnv: "",
+    exportHint: "Pi reads a non-secret placeholder from models.json; loopback needs no key.",
     build: buildPiClientConfig,
     format: "json",
     summarize: summarizePi,
     buildContribution: buildPiContribution,
-    // No header field in Pi's provider block (and the schema is unverified
-    // against a real install), so there is nowhere to put the dedicated
-    // admission header a remote bind requires.
+    // No header field in Pi's provider block, so there is nowhere to put the
+    // dedicated admission header a remote bind requires.
     loopbackOnly: true,
   },
   hermes: {

package/src/codex/account-lifecycle.ts

@@ -7,6 +7,7 @@ import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } f
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
 import { clearMainAccountCredentialPresence, clearMainAccountInfoCache } from "./main-account-cache";
 import { forgetCodexAccountPause } from "./account-pause";
+import { clearCodexAccountPin, forgetCodexAccountPriority } from "./account-priority";
 import type { OcxConfig } from "../types";
 
 let observedMainChatgptAccountId: string | undefined;
@@ -74,6 +75,8 @@ export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string):
   runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? [])
     .filter(account => account.isMain || account.id !== accountId);
   forgetCodexAccountPause(runtimeConfig, accountId);
+  forgetCodexAccountPriority(runtimeConfig, accountId);
+  clearCodexAccountPin(runtimeConfig, accountId);
   if (runtimeConfig.activeCodexAccountId === accountId) runtimeConfig.activeCodexAccountId = undefined;
   purgeCodexAccountRuntimeState(accountId);
   invalidateCodexWebSocketsForAccount(accountId);

package/src/codex/account-namespaces.ts

@@ -1,6 +1,10 @@
 import type { CodexAccount, OcxConfig } from "../types";
 import { COMBO_NAMESPACE } from "../combos/types";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import {
+  POLICY_NAMESPACE,
+  routingProfileAliasNamespacePrefixes,
+} from "../routing/profile-namespace";
 import {
   CODEX_ACCOUNT_LOG_LABEL_RE,
   createCodexAccountLogLabel,
@@ -21,6 +25,7 @@ const RESERVED_NAMESPACE_KEYS = new Set([
   "constructor",
   COMBO_NAMESPACE,
   OPENAI_CODEX_PROVIDER_ID,
+  POLICY_NAMESPACE,
 ].map(codexProviderNamespaceKey));
 const PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS = 16;
 
@@ -68,17 +73,21 @@ function claimNamespace(requested: string, used: Set<string>): string {
   return namespace;
 }
 
-function occupiedNamespaces(config: Pick<OcxConfig, "combos" | "providers">): Set<string> {
+/** Collect every public namespace that a generated account selector must not claim. */
+function occupiedNamespaces(
+  config: Pick<OcxConfig, "combos" | "providers" | "routingProfiles">,
+): Set<string> {
   return new Set([
     ...Object.keys(config.providers).map(codexProviderNamespaceKey),
     ...comboAliasNamespaces(config),
+    ...routingProfileAliasNamespacePrefixes(config),
     ...RESERVED_NAMESPACE_KEYS,
   ]);
 }
 
 /** Build an initial account-selector map without deriving public selectors from aliases or ids. */
 export function defaultCodexAccountNamespaces(
-  config: Pick<OcxConfig, "codexAccounts" | "combos" | "providers">,
+  config: Pick<OcxConfig, "codexAccounts" | "combos" | "providers" | "routingProfiles">,
 ): Record<string, string> {
   const namespaces: Record<string, string> = {};
   const used = occupiedNamespaces(config);
@@ -99,13 +108,39 @@ export function defaultCodexAccountNamespaces(
   return namespaces;
 }
 
+/**
+ * Initialize generated selectors only for an explicit opt-in with no existing bindings.
+ * A true result means the map was replaced and the caller must persist the updated config.
+ */
+export function initializeDefaultCodexAccountNamespaces(
+  config: Pick<
+    OcxConfig,
+    | "codexAccountPickerEnabled"
+    | "codexAccountNamespaces"
+    | "codexAccounts"
+    | "combos"
+    | "providers"
+    | "routingProfiles"
+  >,
+): boolean {
+  if (config.codexAccountPickerEnabled !== true
+    || Object.keys(config.codexAccountNamespaces ?? {}).length > 0) return false;
+
+  const namespaces = defaultCodexAccountNamespaces(config);
+  config.codexAccountNamespaces = namespaces;
+  return true;
+}
+
 /**
  * Add one account to a generated map without renaming or replacing explicit existing entries.
  * The account-creation layer must reject a new id that already equals an existing selector key.
  * A true result means the map was mutated in place; callers must persist the updated config.
  */
 export function appendDefaultCodexAccountNamespace(
-  config: Pick<OcxConfig, "codexAccountNamespaces" | "codexAccounts" | "combos" | "providers">,
+  config: Pick<
+    OcxConfig,
+    "codexAccountNamespaces" | "codexAccounts" | "combos" | "providers" | "routingProfiles"
+  >,
   account: Pick<CodexAccount, "id" | "isMain" | "logLabel">,
 ): boolean {
   const namespaces = config.codexAccountNamespaces;
@@ -147,3 +182,14 @@ export function codexAccountNamespaceEntries(
   return Object.entries(config.codexAccountNamespaces ?? {})
     .map(([namespace, accountId]) => [namespace, normalizeCodexAccountNamespaceTarget(accountId)]);
 }
+
+/**
+ * Whether generated account-qualified rows are enabled for catalog discovery.
+ * A non-empty hand-written map predating the explicit override remains enabled.
+ */
+export function codexAccountPickerEnabled(
+  config: Pick<OcxConfig, "codexAccountNamespaces" | "codexAccountPickerEnabled">,
+): boolean {
+  return (config.codexAccountPickerEnabled === undefined || config.codexAccountPickerEnabled === true)
+    && Object.keys(config.codexAccountNamespaces ?? {}).length > 0;
+}

package/src/codex/account-priority.ts

@@ -0,0 +1,83 @@
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { DEFAULT_ACCOUNT_PRIORITY, normalizeAccountPriority } from "./pool-rotation";
+import type { OcxConfig } from "../types";
+
+/**
+ * Which ids may carry a selection order: any pool account, plus the synthetic
+ * `__main__` Desktop login. Owned here rather than by the config schema because
+ * every writer needs it — the schema rejects a bad key on load, but the management
+ * API has to reject one before `setCodexAccountPriority` persists it as an own
+ * property that the schema would then reject, degrading the whole map.
+ */
+export function isCodexAccountPriorityKey(key: unknown): key is string {
+  return key === MAIN_CODEX_ACCOUNT_ID || isValidCodexAccountId(key);
+}
+
+/**
+ * Persisted selection order for one account: higher numbers are used earlier.
+ * Stored as a config sidecar rather than a `codexAccounts` row field because the
+ * Codex Desktop login (`__main__`) has no row and must be orderable too.
+ */
+export function getCodexAccountPriority(config: OcxConfig, accountId: string): number {
+  return codexAccountPriorityLookup(config)(accountId);
+}
+
+/**
+ * Write one account's selection order. The default is stored as absence, so a
+ * pool that was never ordered keeps no map at all and routing takes its fast path.
+ * Entries are rebuilt through `Object.fromEntries` so a reserved key such as
+ * `__proto__` becomes an own data property instead of invoking a prototype setter.
+ */
+export function setCodexAccountPriority(config: OcxConfig, accountId: string, priority: number): void {
+  const entries = new Map(Object.entries(config.codexAccountPriorities ?? {}));
+  if (priority === DEFAULT_ACCOUNT_PRIORITY) entries.delete(accountId);
+  else entries.set(accountId, priority);
+
+  if (entries.size > 0) config.codexAccountPriorities = Object.fromEntries(entries);
+  else delete config.codexAccountPriorities;
+}
+
+export function forgetCodexAccountPriority(config: OcxConfig, accountId: string): void {
+  setCodexAccountPriority(config, accountId, DEFAULT_ACCOUNT_PRIORITY);
+}
+
+/**
+ * Stable lookup for one selection pass. Routing calls this once per pick and
+ * hands the closure to `selectPriorityTier`, so a pool without stored order pays
+ * a single map read rather than one per candidate.
+ */
+export function codexAccountPriorityLookup(config: OcxConfig): (accountId: string) => number {
+  const priorities = config.codexAccountPriorities;
+  if (!priorities) return () => DEFAULT_ACCOUNT_PRIORITY;
+  return accountId => (
+    Object.hasOwn(priorities, accountId)
+      ? normalizeAccountPriority(priorities[accountId])
+      : DEFAULT_ACCOUNT_PRIORITY
+  );
+}
+
+/**
+ * The account an operator most recently selected by hand. While pinned, priority
+ * never preempts upward: the pin is a tier *ceiling* for round-robin/fill-first --
+ * `selectPriorityTier` skips every tier above the pinned account's, so higher-ordered
+ * accounts are suppressed rather than the pinned one being guaranteed -- and a veto in
+ * the quota path, until the account crosses the auto-switch threshold.
+ */
+export function pinnedCodexAccountId(config: OcxConfig): string | undefined {
+  return config.activeCodexAccountPinned;
+}
+
+export function isCodexAccountPinned(config: OcxConfig, accountId: string): boolean {
+  return config.activeCodexAccountPinned === accountId;
+}
+
+export function setCodexAccountPin(config: OcxConfig, accountId: string): void {
+  config.activeCodexAccountPinned = accountId;
+}
+
+/** 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;
+  }
+}

package/src/codex/auth-api.ts

@@ -15,20 +15,33 @@ import {
 } from "./account-store";
 import { deleteCodexAccount, reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "./account-pause";
+import {
+  clearCodexAccountPin,
+  getCodexAccountPriority,
+  isCodexAccountPriorityKey,
+  pinnedCodexAccountId,
+  setCodexAccountPin,
+  setCodexAccountPriority,
+} from "./account-priority";
 import {
   claimDueCodexQuotaRecoveryProbes,
   clearCodexAccountCooldown,
   clearThreadAccountMapForAccount,
   getEffectiveActiveCodexAccountId,
+  isEffectiveCodexAccountPinned,
   reconcileCodexActiveAfterExclusion,
   resetCodexRoutingForManualSelection,
   settleCodexQuotaRecoveryProbe,
 } from "./routing";
 import {
+  DEFAULT_ACCOUNT_PRIORITY,
+  MAX_ACCOUNT_PRIORITY,
+  MIN_ACCOUNT_PRIORITY,
   normalizeAccountPoolStickyLimit,
   normalizeAccountPoolStrategy,
   parseAccountPoolStickyLimit,
   parseAccountPoolStrategy,
+  parseAccountPriority,
 } from "./pool-rotation";
 import { checkAccountIdCollision, getMainChatgptAccountId, readCodexTokens, readCodexTokensResult } from "./auth-collision";
 export { checkAccountIdCollision, getMainChatgptAccountId } from "./auth-collision";
@@ -191,6 +204,7 @@ function poolAccountDto(
   quotaResult: PoolQuotaResult,
   hasCredential: boolean,
   paused: boolean,
+  priority: number,
 ): CodexAuthAccountDto {
   const quota = quotaForPlan(quotaResult.quota, account.plan);
   const needsReauth = !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id);
@@ -203,6 +217,7 @@ function poolAccountDto(
     ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
     isMain: false,
     paused,
+    priority,
     quota: quota ? { ...quota } : null,
     needsReauth,
     hasCredential,
@@ -644,6 +659,8 @@ export interface CodexAuthAccountDto {
   logLabel?: string;
   isMain: boolean;
   paused: boolean;
+  /** Selection order; higher is used earlier. Always present, 0 when unset. */
+  priority: number;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   needsReauth?: boolean;
   hasCredential: boolean;
@@ -1017,6 +1034,7 @@ export async function listCodexAuthAccountsSnapshot(
         { quota: null, needsReauth: true },
         false,
         isCodexAccountPaused(runtimeConfig, accountId),
+        getCodexAccountPriority(runtimeConfig, accountId),
       )];
     }
     const resultGeneration = quotaResult.credentialGeneration ?? quotaResult.freshCredentialGeneration;
@@ -1035,6 +1053,7 @@ export async function listCodexAuthAccountsSnapshot(
       effectiveQuotaResult,
       true,
       isCodexAccountPaused(runtimeConfig, accountId),
+      getCodexAccountPriority(runtimeConfig, accountId),
     )];
   });
   const fetchedMainGeneration = mainResult.identityGeneration ?? captureMainAccountIdentityGeneration();
@@ -1055,6 +1074,7 @@ export async function listCodexAuthAccountsSnapshot(
     plan: mainInfo.plan,
     isMain: true,
     paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+    priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     hasCredential: hasMainCredential,
     needsReauth: mainNeedsReauth,
     quota: mainInfo.quota ? {
@@ -1297,6 +1317,53 @@ export async function handleCodexAuthAPI(
     });
   }
 
+  // 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
+  // thread, so there is no affinity clearing and no appliesImmediately here.
+  if (url.pathname === "/api/codex-auth/accounts/priority" && req.method === "PUT") {
+    let parsedBody: unknown;
+    try { parsedBody = await req.json(); } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (typeof parsedBody !== "object" || parsedBody === null || Array.isArray(parsedBody)) {
+      return jsonResponse({ error: "body must be an object" }, 400);
+    }
+    const body = parsedBody as { id?: unknown; priority?: unknown };
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!isCodexAccountPriorityKey(id)) {
+      return jsonResponse({ error: "Invalid account id format" }, 400);
+    }
+
+    let priority = DEFAULT_ACCOUNT_PRIORITY;
+    if (body.priority !== null) {
+      const parsed = parseAccountPriority(body.priority);
+      if (parsed === null) {
+        return jsonResponse({
+          error: `priority must be null or an integer ${MIN_ACCOUNT_PRIORITY}-${MAX_ACCOUNT_PRIORITY}`,
+        }, 400);
+      }
+      priority = parsed;
+    }
+
+    const runtimeConfig = getRuntimeConfig(config);
+    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);
+
+    setCodexAccountPriority(runtimeConfig, id, priority);
+    // Both a pin and an order are the operator saying which account to use, so the newer
+    // statement wins. Without this a pin made before any order existed — an ordinary
+    // account switch — would outrank the order forever: it blocks preemption and caps
+    // every eligibility list at its own tier until that account drains or is paused.
+    clearCodexAccountPin(runtimeConfig);
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({
+      ok: true,
+      id,
+      priority,
+      activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
+    });
+  }
+
   if (url.pathname === "/api/codex-auth/accounts/pause-exhausted" && req.method === "PUT") {
     const runtimeConfig = getRuntimeConfig(config);
     const result = await pauseExhaustedCodexAccounts(
@@ -1359,6 +1426,15 @@ export async function handleCodexAuthAPI(
       if (!exists) return jsonResponse({ error: "Account not found" }, 400);
     }
     runtimeConfig.activeCodexAccountId = body.accountId ?? undefined;
+    // "Use this account now" outranks selection order until the account is spent:
+    // persisted here rather than in resetCodexRoutingForManualSelection, which is
+    // runtime state only. A null id clears the selection instead of making one, so it
+    // must release the pin rather than record one: pinning the `targetAccountId`
+    // fallback would leave a pin that no effective active account matches, which
+    // `isEffectiveCodexAccountPinned` reports as unpinned while the tier filter still
+    // honours it as a ceiling — invisibly capping the pool at the main account's tier.
+    if (body.accountId == null) clearCodexAccountPin(runtimeConfig);
+    else setCodexAccountPin(runtimeConfig, targetAccountId);
     resetCodexRoutingForManualSelection(targetAccountId);
     saveRuntimeConfig(config, runtimeConfig);
     return jsonResponse({ ok: true, activeCodexAccountId: body.accountId, appliesImmediately: true });
@@ -1368,6 +1444,13 @@ export async function handleCodexAuthAPI(
     const runtimeConfig = getRuntimeConfig(config);
     return jsonResponse({
       activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
+      pinned: isEffectiveCodexAccountPinned(runtimeConfig),
+      // Which account carries the pin, not just whether the active one does. Under
+      // round-robin or fill-first the pin caps the tier ceiling at its own tier while the
+      // strategy cursor moves freely inside that tier, so `pinned` alone goes false on a
+      // sibling's turn even though the pin is still suppressing every higher tier. The id
+      // lets a surface mark the account the operator actually chose.
+      pinnedAccountId: pinnedCodexAccountId(runtimeConfig) ?? null,
       autoSwitchThreshold: runtimeConfig.autoSwitchThreshold ?? 80,
       upstreamFailoverThreshold: runtimeConfig.upstreamFailoverThreshold ?? 3,
       accountPoolStrategy: normalizeAccountPoolStrategy(runtimeConfig.accountPoolStrategy),

package/src/codex/auth-context.ts

@@ -112,15 +112,18 @@ export class CodexPoolAuthenticationError extends Error {
   }
 }
 
+export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
+  "OpenCodex local native-main profile maintenance is active; retry this request";
+
 export class CodexMainProfileDrainingError extends Error {
   constructor() {
-    super("Native Codex main profile is switching; retry this request");
+    super(CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
     this.name = "CodexMainProfileDrainingError";
   }
 }
 
 export function codexMainProfileDrainingResponse(): Response {
-  const response = formatErrorResponse(503, "server_busy", "Native Codex main profile is switching; retry this request");
+  const response = formatErrorResponse(503, "server_busy", CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
   const headers = new Headers(response.headers);
   headers.set("Retry-After", "1");
   return new Response(response.body, { status: response.status, headers });

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

@@ -736,6 +736,17 @@ function modelInputModalities(
     value === "text" || value === "image" || value === "audio"
   ));
   if (explicit && explicit.length > 0) return explicit;
+  const architecture = plainRecord(item.architecture);
+  const architectureModality = typeof architecture?.modality === "string"
+    ? normalizedMetadataString(architecture.modality, 64)
+    : undefined;
+  if (architectureModality?.includes("->")) {
+    const [rawInput = ""] = architectureModality.split("->");
+    const inferred = rawInput
+      .split("+")
+      .filter(value => value === "text" || value === "image" || value === "audio");
+    if (inferred.length > 0) return [...new Set(inferred)];
+  }
   if (capabilityRecord?.vision === false) return ["text"];
   if (capabilityRecord?.vision === true || capabilities?.some(value => value === "vision" || value === "image-input")) {
     return ["text", "image"];

package/src/codex/catalog/sync.ts

@@ -2,7 +2,8 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { expandUserPath, readConfigDiagnostics, websocketsEnabled } from "../../config";
+import { expandUserPath, loadConfig, readConfigDiagnostics, websocketsEnabled } from "../../config";
+import { shouldSyncCodexOnStart } from "../desired-state";
 import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, getCodexHome, readRootTomlString, resolveCodexConfigPath } from "../paths";
 import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, isModelsFetchCoolingDown, markModelsFetchFailure, setCached } from "../model-cache";
 import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
@@ -652,6 +653,8 @@ interface RetainedCatalogSyncResult {
   path: string;
   catalogWritten: boolean;
   comboOmissions: ComboCatalogOmission[];
+  /** `desired_disabled` observed under K after the provider await; nothing was written. */
+  skippedReason?: "desired_disabled";
 }
 
 interface RetainedCatalogSyncWrite {
@@ -965,6 +968,20 @@ export async function syncCatalogModels(config: OcxConfig): Promise<RetainedCata
   };
   const goModels = await gatherRoutedModels(config, { comboOmissions });
   const committed = withCatalogWriteSerialization(owningCodexHome, permit => {
+    // Desired state can flip OFF during the provider await above. The catalog
+    // evidence revalidation below cannot see that — intent lives in our config,
+    // not in the catalog files — so the policy is re-read here, under K, right
+    // before the only write. A lost race becomes the discriminated skip instead
+    // of a routed catalog/cache surviving a completed disable.
+    if (!shouldSyncCodexOnStart(loadConfig())) {
+      return {
+        added: 0,
+        path: prepared.catalogPath,
+        catalogWritten: false,
+        comboOmissions,
+        skippedReason: "desired_disabled" as const,
+      };
+    }
     const current = revalidateRetainedCatalogSync(config, prepared);
     if (current === null) return null;
     return writeRetainedCatalogSync({
@@ -1049,6 +1066,11 @@ export function invalidateCodexModelsCacheWithPermit(
   owningCodexHome: string,
 ): boolean {
   try {
+    // This permit is a REACQUISITION: refreshCodexModelCatalog's commit released
+    // K before this rewrite runs, so the commit-path desired-state check cannot
+    // cover it. A disable landing in that gap must not be overwritten by a
+    // routed cache write — re-read intent under this permit, same as the commit.
+    if (!shouldSyncCodexOnStart(loadConfig())) return false;
     const catalogPath = readCodexCatalogPath();
     if (!existsSync(catalogPath)) return false;
     const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));

package/src/codex/codex-write-lock.ts

@@ -66,7 +66,8 @@ export type CodexWriteLockRefusalReason =
 
 export type CodexWriteLockResult<T> =
   | { status: "acquired"; value: T; waitedMs: number; lockId: string }
-  | { status: "busy"; reason: "deadline" | "cancelled"; retryable: true; waitedMs: number }
+  | { status: "skipped"; reason: "desired_disabled" | "desired_enabled"; waitedMs: number }
+  | { status: "busy"; reason: "deadline" | "cancelled"; retryable: true; waitedMs: number; lockId: string }
   | {
       status: "refused";
       reason: CodexWriteLockRefusalReason;
@@ -124,6 +125,14 @@ export interface CodexWriteCommitContext {
   readonly coordinator: CodexCoordinatorTransaction;
 }
 
+/** A synchronous under-lock policy re-read proved the requested apply stale. */
+export class CodexWriteLockSkipped extends Error {
+  constructor(readonly reason: "desired_disabled" | "desired_enabled") {
+    super(reason);
+    this.name = "CodexWriteLockSkipped";
+  }
+}
+
 /** Rejects an `async` callback at typecheck; a cast thenable is caught at runtime. */
 type Synchronous<T> = T extends PromiseLike<unknown> ? never : T;
 
@@ -291,7 +300,7 @@ export async function withCodexWriteLock<T>(
   const waited = (): number => Math.round(performance.now() - started);
 
   for (;;) {
-    if (signal?.aborted) return { status: "busy", reason: "cancelled", retryable: true, waitedMs: waited() };
+    if (signal?.aborted) return { status: "busy", reason: "cancelled", retryable: true, waitedMs: waited(), lockId: target.lockId };
 
     let transaction: ReturnType<typeof openCodexCoordinatorTransaction> | undefined;
     try {
@@ -306,7 +315,7 @@ export async function withCodexWriteLock<T>(
           error instanceof Error ? error.message : "The Codex write lock could not be opened.");
       }
       if (performance.now() >= deadline) {
-        return { status: "busy", reason: "deadline", retryable: true, waitedMs: waited() };
+        return { status: "busy", reason: "deadline", retryable: true, waitedMs: waited(), lockId: target.lockId };
       }
       await sleepJittered(deadline - performance.now(), signal);
       continue;
@@ -345,13 +354,16 @@ export async function withCodexWriteLock<T>(
       return { status: "acquired", value: value as T, waitedMs: waited(), lockId: target.lockId };
     } catch (error) {
       transaction.rollback();
+      if (error instanceof CodexWriteLockSkipped) {
+        return { status: "skipped", reason: error.reason, waitedMs: waited() };
+      }
       if (error instanceof CodexWriteLockStaleAdmission) {
         return refuse("authority_not_proven",
           "The admitted state changed before the commit could be made under the lock.");
       }
       if (isBusyError(error)) {
         if (performance.now() >= deadline) {
-          return { status: "busy", reason: "deadline", retryable: true, waitedMs: waited() };
+          return { status: "busy", reason: "deadline", retryable: true, waitedMs: waited(), lockId: target.lockId };
         }
         await sleepJittered(deadline - performance.now(), signal);
         continue;