fix(codex): preserve cache affinity across model detours

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.53.0",
+  "version": "2.52.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

src/codex/routing.ts

@@ -1505,6 +1505,34 @@ function hasCodexQuotaHeadroom(
   return usage < threshold;
 }
 
+/**
+ * Whether quota may retire shared state while cache affinity is active.
+ *
+ * New/unbound selection still uses {@link hasCodexQuotaHeadroom}; only preservation of an
+ * existing shared selection or thread binding gets the exhaustion boundary.
+ */
+function hasCodexSharedStateQuotaHeadroom(
+  config: OcxConfig,
+  accountId: string,
+  selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
+): boolean {
+  if (
+    config.pool?.cacheAffinity !== true
+    || normalizeAccountPoolStrategy(config.accountPoolStrategy) !== "quota"
+  ) {
+    return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now);
+  }
+  const threshold = config.pool?.autoSwitchThreshold;
+  if (typeof threshold === "number" && threshold <= 0) return true;
+  const usage = computeCodexUsageScore(
+    getAccountQuota(accountId),
+    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
+  );
+  return isUnknownUsage(usage) || usage < 100;
+}
+
 /**
  * Fill-first: keep selectable active under threshold; otherwise advance to the next
  * eligible id in stable sorted order after the current active (wrapping).
@@ -2028,7 +2056,8 @@ function isHealthySharedCodexSelection(
   selectionOptions: CodexAccountUsabilityOptions | undefined,
 ): boolean {
   return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
-    && hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, accountId, selectionOptions, now)
+    && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope)
     && !shouldFailover(config, accountId, now);
 }
 
@@ -2418,7 +2447,7 @@ export function resolveCodexAccountForThreadDetailed(
     // the account has already told this thread it cannot serve it.
     const quotaRefused = hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope);
     const healthyForSharedAffinity = selectableForSharedState
-      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
+      && hasCodexSharedStateQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
       && !quotaRefused
       && !failoverReady;
     if (
@@ -2523,7 +2552,7 @@ export function resolveCodexAccountForThreadDetailed(
     sharedSelectionOptions,
   );
   const activeHealthyForSharedSelection = activeSelectableForSharedState
-    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, active, sharedSelectionOptions, now)
     && !shouldFailover(config, active, now);
   if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
     const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);

structure/providers/openai-tiers.md

@@ -278,8 +278,11 @@ has headroom, auth resolution validates the caller bearer's own gated-model rost
 request-owned credential before stored-Pool selection. The credential never enters Pool persistence,
 affinity, entitlement cache, or health state, and this decision never reads the physical main credential.
 If the caller lacks the requested model, a stored-account model detour may serve the request without
-clearing the healthy shared main pin. A paused or quota-drained main skips this exception and follows the
-ordinary Pool promotion path.
+clearing the healthy shared main pin. With quota-strategy cache affinity, the same detour preserves an
+ordinary added-account binding and shared selection beyond the proactive-switch threshold until genuine
+exhaustion; pause, cooldown, reauthentication, quota refusal, and failover evidence still retire shared
+state normally. A paused or quota-drained main skips the request-owned credential exception and follows
+the ordinary Pool promotion path.
 
 > Decision record: [ADR-0086](../decisions/ADR-0086-public-provider-contract.md)
 

tests/codex-integration/codex-routing.test.ts

@@ -2452,6 +2452,32 @@ describe("codex account selection order", () => {
     expect(resolveCodexAccountForThread("model-gated-task", config, now + 2, "shared")).toBe("b");
   });
 
+  test("cache affinity preserves an over-threshold shared binding across a model detour", () => {
+    const config = orderedConfig({
+      accountPoolStrategy: "quota",
+      activeCodexAccountId: "a",
+      activeCodexAccountPinned: "a",
+      autoSwitchThreshold: 80,
+      pool: { cacheAffinity: true },
+    });
+    const now = Date.now();
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 10);
+
+    expect(resolveCodexAccountForThread("cache-affine-model-detour", config, now, "shared")).toBe("a");
+    updateAccountQuota("a", 90);
+    expect(resolveCodexAccountForThreadDetailed(
+      "cache-affine-model-detour",
+      config,
+      now + 1,
+      "shared",
+      { modelEligibleAccountIds: new Set(["b"]) },
+    )).toEqual({ status: "selected", accountId: "b" });
+
+    expect(getEffectiveActiveCodexAccountId(config)).toBe("a");
+    expect(resolveCodexAccountForThread("cache-affine-model-detour", config, now + 2, "shared")).toBe("a");
+  });
+
   test("repeated model-gated round-robin requests reuse a separate detour affinity", () => {
     const now = 1_800_000_000_000;
     const threadId = "model-detour-affinity";