@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/codex/quota.ts

@@ -1,3 +1,4 @@
+import { parseCodexCredits } from "./credits";
 import { forgetMainAccountUsage, observeMainAccountUsage, type FreshWindow } from "./main-account-external-usage";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, openSync, readSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
@@ -11,7 +12,7 @@ import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaW
 
 import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
 import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
-import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT, resetAtToMs } from "./quota-types";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT, hasSpendableCodexCredits, resetAtToMs } from "./quota-types";
 import type { PoolQuotaWriter, StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
 
 export type { StoredAccountQuota, WhamUsageResponse } from "./quota-types";
@@ -83,10 +84,12 @@ function mayCommitAccountQuota(accountId: string, writerGeneration: number): boo
 // actually exhausted account is still eligible for threshold rotation.
 export const CODEX_UNKNOWN_USAGE_SCORE = 101;
 export function isCodexQuotaExhausted(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent" | "credits"> | null,
   plan?: unknown,
+  allowCredits = false,
 ): boolean {
   if (!quota) return false;
+  if (allowCredits && hasSpendableCodexCredits(quota)) return false;
   // The burst window counts on EVERY plan. It is upstream-enforced independently, so an
   // account at 100% there is blocked regardless of which longer window governs its plan;
   // omitting it would route traffic straight into a 429 (#1791).
@@ -118,10 +121,11 @@ export function codexQuotaWindowForPlan(plan?: unknown): "monthly" | "weekly" {
 }
 
 export function isCompleteCodexQuotaRecoverySnapshot(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent" | "credits"> | null,
   plan?: unknown,
+  allowCredits = false,
 ): boolean {
-  if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
+  if (!quota || isCodexQuotaExhausted(quota, plan, allowCredits)) return false;
   // Recovery still fails closed on MISSING EVIDENCE — a credits-only or windowless payload
   // carries no usage reading at all and must never clear a cooldown. What it does not do is
   // fail closed on an unfamiliar plan NAME, which only ever meant "cooled forever".
@@ -277,6 +281,10 @@ function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolea
 function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
   return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota);
 }
+
+function snapshotHasCredits(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.resetCredits !== undefined || quota.credits !== undefined;
+}
 /**
  * Publish parsed display quota and separately validated policy evidence after writer checks.
  * A null policy observation retains only the matching main identity's previous evidence;
@@ -296,7 +304,7 @@ export function setAccountQuotaFromParsed(
 ): void {
   quota = withoutRetiredCodexQuota(quota);
   policyQuota = withoutRetiredCodexQuota(policyQuota);
-  if (!quota || (!snapshotHasUsage(quota) && quota.resetCredits === undefined)) return;
+  if (!quota || (!snapshotHasUsage(quota) && !snapshotHasCredits(quota))) return;
   if (!mayCommitAccountQuota(accountId, writerGeneration)) return;
   const isMain = accountId === MAIN_CODEX_ACCOUNT_ID;
   if (isMain && mainWriter && !isMainQuotaWriterLive(mainWriter)) return;
@@ -343,7 +351,7 @@ export function setAccountQuotaFromParsed(
   }
   schedulePersistAccountQuotas();
   // Credits carry the previous usage tuple; they must not refresh its observation clock.
-  if (!(quota.resetCredits !== undefined && !snapshotHasUsage(quota))) {
+  if (!(snapshotHasCredits(quota) && !snapshotHasUsage(quota))) {
     if (!isMain && policyQuota && livePoolEvidence) observeCodexLowQuota(accountId, policyQuota);
     notifyCodexQuotaSnapshot(accountId, next);
   }
@@ -363,7 +371,11 @@ function mergeAccountQuota(
   quota = withoutRetiredCodexQuota(quota) ?? {};
   existing = withoutRetiredCodexQuota(existing ?? null) ?? undefined;
   const next: StoredAccountQuota = { updatedAt };
-  const creditsOnly = quota.resetCredits !== undefined && !snapshotHasUsage(quota);
+  const creditsOnly = snapshotHasCredits(quota) && !snapshotHasUsage(quota);
+  // An explicit empty/invalid credits summary retracts the old balance. Partial headers
+  // retain the original observation clock instead of extending its spending authority.
+  if (quota.credits !== undefined) next.credits = quota.credits;
+  else if (existing?.credits !== undefined) next.credits = existing.credits;
 
   if (creditsOnly) {
     if (existing?.weeklyPercent !== undefined) next.weeklyPercent = existing.weeklyPercent;
@@ -373,7 +385,8 @@ function mergeAccountQuota(
     if (existing?.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
     assignCarriedShort(next, existing, updatedAt, policyEvidence);
     if (existing?.customWindows !== undefined) next.customWindows = existing.customWindows;
-    next.resetCredits = quota.resetCredits;
+    if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
+    else if (existing?.resetCredits !== undefined) next.resetCredits = existing.resetCredits;
     return stampCodexQuotaUsageObservation(next, quota, existing);
   }
 
@@ -525,7 +538,7 @@ export function withoutRetiredCodexQuota<T extends Omit<StoredAccountQuota, "upd
   const next = { ...quota };
   if (kept.length > 0) next.customWindows = kept;
   else delete next.customWindows;
-  return snapshotHasUsage(next) || next.resetCredits !== undefined ? next as T : null;
+  return snapshotHasUsage(next) || snapshotHasCredits(next) ? next as T : null;
 }
 
 export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?: string }): Omit<StoredAccountQuota, "updatedAt"> | null {
@@ -644,6 +657,7 @@ export function updateAccountQuota(
     ...(existing?.monthlyResetAt !== undefined ? { monthlyResetAt: existing.monthlyResetAt } : {}),
     ...(existing?.customWindows !== undefined ? { customWindows: existing.customWindows } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
+    ...(existing?.credits !== undefined ? { credits: existing.credits } : {}),
     updatedAt: Date.now(),
   };
   assignCarriedShort(quota, existing, quota.updatedAt);
@@ -702,6 +716,20 @@ function readMainPolicyQuota(value: unknown): MainPolicyQuota | null {
     if (typeof number === "number" && Number.isFinite(number) && number >= 0) quota[field] = number;
   }
   if (quota.monthlyPercent !== undefined && raw.monthlyIsPrimaryWindow === true) quota.monthlyIsPrimaryWindow = true;
+  // Retain the independent credit timestamp on restart; it still expires at its original deadline.
+  if (raw.credits === null) quota.credits = null;
+  else if (raw.credits && typeof raw.credits === "object" && !Array.isArray(raw.credits)) {
+    const stored = raw.credits as Record<string, unknown>;
+    if (typeof stored.observedAt === "number" && Number.isFinite(stored.observedAt) && stored.observedAt >= 0) {
+      quota.credits = { observedAt: stored.observedAt };
+      for (const key of ["hasCredits", "unlimited", "overageLimitReached", "allowed"] as const) {
+        if (typeof stored[key] === "boolean") quota.credits[key] = stored[key];
+      }
+      if (typeof stored.balance === "number" && Number.isFinite(stored.balance) && stored.balance >= 0) {
+        quota.credits.balance = stored.balance;
+      }
+    }
+  }
   return { identityKey: entry.identityKey, quota };
 }
 
@@ -845,7 +873,7 @@ function filterMainPolicyMonthlyQuota(
   delete filtered.monthlyResetAt;
   delete filtered.monthlyIsPrimaryWindow;
   // Null retains the matching prior observation; an empty object would merge away evidence.
-  return hasKnownQuotaValue(filtered) || filtered.resetCredits !== undefined ? filtered : null;
+  return hasKnownQuotaValue(filtered) || snapshotHasCredits(filtered) ? filtered : null;
 }
 
 /**
@@ -876,21 +904,44 @@ function isMeasuredLongWindow(window: WhamUsageWindow | null | undefined): boole
   return isExplicitLongWindow(window) && normalizeUsagePercent(window?.used_percent) !== undefined;
 }
 
+/** Absent/null controls impose no veto; a present control requires reached:false. */
+function spendControlAllowsCredits(control: unknown): boolean | undefined {
+  if (control === undefined || control === null) return undefined;
+  return typeof control === "object" && !Array.isArray(control)
+    && "reached" in control && control.reached === false;
+}
+
 /**
  * Normalize WHAM windows into the display snapshot, preserving declared short-window shape.
  * Finite percentages are clamped for compatibility; policy callers must validate raw readings
- * separately. Return null when neither a quota value/window nor reset credits are available.
+ * separately. Return null when no usage window or credit observation/retraction is available.
  */
 export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuota, "updatedAt"> | null {
   const resetCredits = typeof data.rate_limit_reset_credits?.available_count === "number"
     ? data.rate_limit_reset_credits.available_count
     : undefined;
 
-  if (!data.rate_limit) {
-    return resetCredits !== undefined ? { resetCredits } : null;
-  }
-
   const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
+  const creditsAllowed = spendControlAllowsCredits(data.spend_control);
+  if (resetCredits !== undefined) quota.resetCredits = resetCredits;
+  if (data.credits !== undefined) {
+    quota.credits = null;
+    const parsed = parseCodexCredits(data.credits);
+    if (parsed) {
+      const balance = parsed.balance === undefined ? undefined : Number(parsed.balance);
+      quota.credits = {
+        observedAt: Date.now(),
+        ...(parsed.hasCredits !== undefined ? { hasCredits: parsed.hasCredits } : {}),
+        ...(parsed.unlimited !== undefined ? { unlimited: parsed.unlimited } : {}),
+        ...(parsed.overageLimitReached !== undefined ? { overageLimitReached: parsed.overageLimitReached } : {}),
+        // Included-plan refusal is precisely when opted-in credits take over, not a credit veto.
+        // A declared spending control permits credits only with an explicit unreached verdict.
+        ...(creditsAllowed !== undefined ? { allowed: creditsAllowed } : {}),
+        ...(balance !== undefined && Number.isFinite(balance) ? { balance } : {}),
+      };
+    }
+  } else if (data.rate_limit?.allowed === false || creditsAllowed === false) quota.credits = null;
+  if (!data.rate_limit) return snapshotHasCredits(quota) ? quota : null;
   const thirtyDayOnly = codexQuotaWindowForPlan(data.plan_type) === "monthly";
   const primaryWindow = data.rate_limit.primary_window;
   const secondaryWindow = data.rate_limit.secondary_window;
@@ -951,7 +1002,7 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
 
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
-  return hasKnownQuotaValue(quota) || resetCredits !== undefined ? quota : null;
+  return hasKnownQuotaValue(quota) || snapshotHasCredits(quota) ? quota : null;
 }
 
 

package/src/codex/refresh.ts

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { invalidateCodexModelsCache, syncCatalogModels } from "./catalog";
 import type { ComboCatalogOmission } from "./catalog/aggregation";
-import { CODEX_MODELS_CACHE_PATH } from "./paths";
-import { atomicWriteFile } from "../config";
+import { getCodexHome } from "./paths";
+import { withCatalogWriteSerialization, CatalogWritePermitRefusal } from "./catalog-write-serialization";
+import { replaceCodexModelsCache } from "./internal/catalog-writer";
 import type { OcxConfig } from "../types";
 import type { CodexCatalogSyncOptions } from "./catalog/sync";
 
@@ -14,8 +16,12 @@ export interface CodexCatalogRefreshResult {
   cacheSynced: boolean;
   comboOmissions: ComboCatalogOmission[];
   refreshOutcome?: "committed" | "refused";
-  /** Desired OFF observed under K during the catalog commit; no cache write either. */
-  skippedReason?: "desired_disabled";
+  /**
+   * Desired OFF observed under K during the catalog commit, or a write refused because it would
+   * empty routed namespaces config.json does not back (#6529); no cache write either way.
+   */
+  skippedReason?: "desired_disabled" | "unbacked_routed_removal" | "foreign_owner" | "owner_unknown";
+  protectedRoutedNamespaces?: number;
 }
 
 interface RefreshDeps {
@@ -31,8 +37,13 @@ const defaultDeps: RefreshDeps = {
 };
 
 export function syncCodexModelsCacheFromCatalog(catalogPath: string): void {
-  const content = readFileSync(catalogPath, "utf8");
-  atomicWriteFile(CODEX_MODELS_CACHE_PATH, content);
+  const owningCodexHome = getCodexHome();
+  const outcome = withCatalogWriteSerialization(owningCodexHome, permit =>
+    replaceCodexModelsCache(permit, owningCodexHome, {
+      path: join(owningCodexHome, "models_cache.json"),
+      content: readFileSync(catalogPath, "utf8"),
+    }), { intent: "cache", writer: "cache-from-catalog" });
+  if (outcome.kind === "unavailable") throw new CatalogWritePermitRefusal(`Catalog cache synchronization unavailable (${outcome.reason}).`);
 }
 
 /**
@@ -50,9 +61,9 @@ export async function refreshCodexModelCatalog(
   const catalogExists = deps.existsSync(result.path);
   const catalogWritten = result.catalogWritten === true;
   const comboOmissions = result.comboOmissions ?? [];
-  if (result.skippedReason === "desired_disabled" || result.refreshOutcome === "refused") {
-    // The commit path observed OFF under K. Invalidate nothing: rewriting the
-    // models cache here would be exactly the routed-cache write the skip refused.
+  if (result.skippedReason !== undefined || result.refreshOutcome === "refused") {
+    // The commit path observed OFF, or an unbacked routed removal, under K. Invalidate
+    // nothing: rewriting the models cache here would be exactly the write the skip refused.
     return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
   }
   if (!catalogExists) {

package/src/codex/routing/cooldown-math.ts

@@ -3,7 +3,7 @@ import {
   CODEX_UNKNOWN_USAGE_SCORE,
 } from "../quota";
 import { isThirtyDayOnlyCodexPlan } from "../plan";
-import { isTerminalShortWindow } from "../quota-types";
+import { hasSpendableCodexCredits, isTerminalShortWindow, type CodexSpendableCredits } from "../quota-types";
 import type { CodexQuotaScope } from "./health-store";
 import type { TransientProbeGrant } from "./thread-affinity";
 
@@ -107,7 +107,8 @@ export function computeCodexUsageScore(quota: {
   shortPercent?: number;
   shortResetAt?: number;
   shortObservedAt?: number;
-} | null, plan?: unknown, now: number = Date.now()): number {
+  credits?: CodexSpendableCredits | null;
+} | null, plan?: unknown, now: number = Date.now(), allowCredits = false): number {
   if (!quota) return CODEX_UNKNOWN_USAGE_SCORE;
   const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
   const longWindows = isThirtyDayOnlyCodexPlan(plan)
@@ -126,10 +127,15 @@ export function computeCodexUsageScore(quota: {
   // correct for uncertainty and wrong for a measured refusal: the account stays selected,
   // `applyQuotaAutoSwitch` never fires, and the pool wedges on an exhausted credential.
   if (knownLong.length === 0) {
-    return isTerminalShortWindow(quota, now) ? CODEX_EXHAUSTED_USAGE_PERCENT : CODEX_UNKNOWN_USAGE_SCORE;
+    return isTerminalShortWindow(quota, now)
+      ? (allowCredits && hasSpendableCodexCredits(quota, now)) ? CODEX_EXHAUSTED_USAGE_PERCENT - 1 : CODEX_EXHAUSTED_USAGE_PERCENT
+      : CODEX_UNKNOWN_USAGE_SCORE;
   }
   const values = finite(quota.shortPercent) ? [...knownLong, quota.shortPercent] : knownLong;
-  return Math.max(...values);
+  const score = Math.max(...values);
+  // Keep included-capacity accounts ahead of a paid overage account, but do not
+  // classify the latter as exhausted solely from its subscription percentages.
+  return (allowCredits && hasSpendableCodexCredits(quota, now)) ? Math.min(score, CODEX_EXHAUSTED_USAGE_PERCENT - 1) : score;
 }
 
 // `isTerminalShortWindow` moved to ../quota-types, the leaf the dashboard can import. Routing

package/src/codex/routing/selection.ts

@@ -1,5 +1,5 @@
 import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
-import { isCodexAccountHeldForCredits } from "../account-credit-use";
+import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use";
 import { isCodexAccountPaused } from "../account-pause";
 import { codexAccountPriorityLookup, pinnedCodexAccountId } from "../account-priority";
 import { isSelectableCodexPoolAccount } from "../account-id";
@@ -16,7 +16,7 @@ import {
 } from "../pool-rotation";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "../quota";
 import { codexPlanKey } from "../plan";
-import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan, hasMainAccountRefreshGrant } from "../main-account";
+import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
 import type { OcxConfig } from "../../types";
 import { CODEX_FAILURE_WINDOW_MS, computeCodexUsageScore } from "./cooldown-math";
 import {
@@ -220,7 +220,6 @@ export function getEligiblePoolAccounts(
   if (
     excludeId !== MAIN_CODEX_ACCOUNT_ID
     && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
-    && (!isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID) || hasMainAccountRefreshGrant())
     && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
     // The main login is not in `config.codexAccounts`, so it never passes through the
@@ -293,6 +292,7 @@ export function hasCodexQuotaHeadroom(
     getAccountQuota(accountId),
     getPoolAccountPlanForSelection(config, accountId, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, accountId),
   );
   if (isUnknownUsage(usage)) return true;
   return usage < threshold;
@@ -344,6 +344,7 @@ export function hasCodexSharedStateQuotaHeadroom(
     getAccountQuota(accountId),
     getPoolAccountPlanForSelection(config, accountId, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, accountId),
   );
   return isUnknownUsage(usage) || usage < 100;
 }
@@ -537,7 +538,7 @@ export function sharedStateSelectionOptions(
   selectionOptions?: CodexAccountUsabilityOptions,
 ): Pick<
   CodexAccountUsabilityOptions,
-  "nativeMainSelectionOnly" | "isMainAccountTokenLive"
+  "nativeMainSelectionOnly" | "isMainAccountTokenLive" | "requestOwnedMainCredential"
 > | undefined {
   if (!selectionOptions) return undefined;
   return {
@@ -547,6 +548,9 @@ export function sharedStateSelectionOptions(
     ...(selectionOptions.isMainAccountTokenLive
       ? { isMainAccountTokenLive: selectionOptions.isMainAccountTokenLive }
       : {}),
+    ...(selectionOptions.requestOwnedMainCredential !== undefined
+      ? { requestOwnedMainCredential: selectionOptions.requestOwnedMainCredential }
+      : {}),
   };
 }
 
@@ -585,6 +589,7 @@ export function pickLowerUsageAccount(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
       now,
+      codexAccountUsesCreditsAfterLimit(config, id),
     );
     if (usage < bestUsage) {
       best = id;
@@ -608,6 +613,7 @@ export function pickLowestUsageAmong(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
       now,
+      codexAccountUsesCreditsAfterLimit(config, id),
     );
     if (usage < bestUsage) {
       best = id;
@@ -785,6 +791,7 @@ export function applyQuotaAutoSwitch(
     quota,
     getPoolAccountPlanForSelection(config, active, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, active),
   );
   // Unknown usage is not evidence that a user's explicit selection crossed the
   // threshold. Wait for quota priming instead of rotating among guesses.

package/src/codex/routing.ts

@@ -1,3 +1,4 @@
+import { codexAccountUsesCreditsAfterLimit } from "./account-credit-use";
 import { clearIdleWindowSteering, pickIdleWindowAccount } from "./routing/idle-window";
 import { getEffectiveCodexAutoSwitchThreshold } from "./account-auto-switch";
 import { codexQuotaHasFreshUsage } from "./quota-observation-freshness";
@@ -522,7 +523,7 @@ function pickAffinityPriorityFailback(
       || now - quota.updatedAt >= CODEX_PRIORITY_FAILBACK_REFRESH_MS
       || (quota.shortObservedAt !== undefined
         && now - quota.shortObservedAt >= CODEX_PRIORITY_FAILBACK_REFRESH_MS)) return false;
-    const usage = computeCodexUsageScore(quota, plan, now);
+    const usage = computeCodexUsageScore(quota, plan, now, codexAccountUsesCreditsAfterLimit(config, id));
     const threshold = getEffectiveCodexAutoSwitchThreshold(config, id);
     return !isUnknownUsage(usage) && usage < 100 && (threshold <= 0 || usage < threshold);
   });
@@ -575,7 +576,7 @@ function previewReusableAffinityAccount(
       const usage = computeCodexUsageScore(
         getAccountQuota(entry.accountId),
         getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions),
-      now,
+        now, codexAccountUsesCreditsAfterLimit(config, entry.accountId),
       );
       // Preview must agree with resolve: this is the second copy of the same rule, and the
       // suite asserts the two answer identically.
@@ -605,7 +606,7 @@ function resetFirstAffinityReplacement(
 ): string | null {
   const threshold = getEffectiveCodexAutoSwitchThreshold(config, entry.accountId);
   if (threshold <= 0) return null;
-  const usage = computeCodexUsageScore(getAccountQuota(entry.accountId), getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions), now);
+  const usage = computeCodexUsageScore(getAccountQuota(entry.accountId), getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, entry.accountId));
   if (!mayRebindAffinityForQuota(config, entry.accountId, usage, threshold, selectionOptions)) return null;
   const candidates = getEligiblePoolAccounts(config, entry.accountId, now, quotaScope, selectionOptions, true)
     // Headroom alone answers true for an UNMEASURED account, which is the right default for an
@@ -618,7 +619,7 @@ function resetFirstAffinityReplacement(
       return !isUnknownUsage(computeCodexUsageScore(
         getAccountQuota(id),
         getPoolAccountPlanForSelection(config, id, selectionOptions),
-        now,
+        now, codexAccountUsesCreditsAfterLimit(config, id),
       ));
     });
   return pickResetFirstCodexAccount(config, candidates, now, selectionOptions);
@@ -664,10 +665,9 @@ function pickCacheSafeQuotaReplacement(
   ).filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now));
   const best = pickLowestUsageAmong(config, candidates, selectionOptions, now);
   if (best === null || best === boundAccountId) return null;
-  const bestUsage = computeCodexUsageScore(
-    getAccountQuota(best),
+  const bestUsage = computeCodexUsageScore(getAccountQuota(best),
     getPoolAccountPlanForSelection(config, best, selectionOptions),
-    now,
+    now, codexAccountUsesCreditsAfterLimit(config, best),
   );
   return bestUsage < boundUsage ? best : null;
 }
@@ -698,7 +698,7 @@ function reevaluateAffinityQuota(
     ? computeCodexUsageScore(
         getAccountQuota(entry.accountId),
         getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions),
-      now,
+        now, codexAccountUsesCreditsAfterLimit(config, entry.accountId),
       )
     : 0;
   // One bar, used for BOTH the rebind decision and the re-score interval. Keying the short
@@ -823,7 +823,7 @@ export function previewCodexAccountForRequest(
     const usage = computeCodexUsageScore(
       getAccountQuota(active),
       getPoolAccountPlanForSelection(config, active, selectionOptions),
-      now,
+      now, codexAccountUsesCreditsAfterLimit(config, active),
     );
     if (!isUnknownUsage(usage) && usage >= threshold) {
       active = pickLowerUsageAccount(config, active, usage, now, quotaScope, selectionOptions);

package/src/codex/runtime.ts

@@ -5,6 +5,7 @@ import { delimiter, join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocation";
 import { resolveCodexHomeDir } from "./home";
+import { decodeOverlayState } from "./shim-state-file";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 
 export type CodexRuntimeSource =
@@ -516,13 +517,18 @@ function shimCandidates(deps: ResolveCodexRuntimeDeps): string[] {
   const platform = deps.platform ?? process.platform;
   try {
     const state = JSON.parse(read(join(configDir, "codex-shim.json"), "utf8")) as {
+      schema?: unknown;
+      mode?: unknown;
       wrapperPath?: unknown;
       originalPath?: unknown;
       backupPath?: unknown;
       wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
     };
+    const overlay = decodeOverlayState(state, configDir);
+    if ((state.schema !== undefined || state.mode !== undefined) && !overlay) return [];
     const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
-    const out: string[] = [];
+    const out: string[] = overlay && isSpawnableCodexCandidate(overlay.launcherPath, platform)
+      ? [overlay.launcherPath] : [];
     for (const file of files) {
       for (const value of [file.backupPath, file.originalPath, file.wrapperPath]) {
         if (typeof value !== "string" || value.length === 0) continue;

package/src/codex/shim-diagnostics.ts

@@ -0,0 +1,80 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { SHIM_MARKER, UNIX_SHIM_REVISION_MARKER } from "./shim-templates";
+import { readStateResult, stateFiles, statePath } from "./shim-state-file";
+import { overlayDiagnostic } from "./shim-overlay";
+
+export function isShim(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").includes(SHIM_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function isHealthyShim(path: string, platform: NodeJS.Platform): boolean {
+  try {
+    const content = readFileSync(path, "utf8");
+    if (content.length < 180 || !content.includes(SHIM_MARKER) || !content.includes("ensure")) return false;
+    if (platform !== "win32" && !content.includes(UNIX_SHIM_REVISION_MARKER)) return false;
+    if (platform !== "win32" && (lstatSync(path).mode & 0o111) === 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CodexShimDiagnostic {
+  installed: boolean;
+  healthy: boolean;
+  summary: string;
+  runnable?: boolean;
+  active?: boolean | null;
+}
+
+/** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */
+export function diagnoseCodexShim(): CodexShimDiagnostic {
+  const result = readStateResult();
+  const state = result.state;
+  if (!state) {
+    if (result.present) {
+      return {
+        installed: true,
+        healthy: false,
+        runnable: false,
+        active: null,
+        summary: result.warning ?? `Codex autostart shim state is invalid or corrupt at ${statePath()}. Reinstall or remove the shim.`,
+      };
+    }
+    return {
+      installed: false,
+      healthy: false,
+      summary: "Codex autostart shim is not installed.",
+    };
+  }
+  if (state.mode === "path-overlay") return overlayDiagnostic(state);
+  const files = stateFiles(state);
+  const healthy = files.length > 0 && files.every(file => file.preserveOnly
+    ? existsSync(file.backupPath) && !existsSync(file.originalPath)
+    : existsSync(file.wrapperPath)
+      && (existsSync(file.backupPath) || (file.realPath ? existsSync(file.realPath) : false))
+      && isHealthyShim(file.wrapperPath, state.platform));
+  const summary = files.map(file => {
+    const wrapper = existsSync(file.wrapperPath)
+      ? isShim(file.wrapperPath)
+        ? "shim present"
+        : "present but not an opencodex shim"
+      : "missing";
+    const backup = existsSync(file.backupPath) ? "present" : "missing";
+    return `Codex autostart shim: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  }).join("\n");
+  // Presence alone is not health: a damaged wrapper still reads "shim present", so state the verdict.
+  const migration = healthy && state.platform !== "win32"
+    ? " Legacy Unix shim installed in place; automatic repair does not migrate it. Run ocx codex-shim install, then source the printed codex-shell-env.sh path and add that line after PATH setup in your shell startup file."
+    : "";
+  return { installed: true, healthy, summary: healthy ? `${summary}${migration}`
+    : `${summary}\nCodex autostart shim is unhealthy. Run ocx codex-shim install to repair it.` };
+}
+
+export function codexShimStatus(): string {
+  return diagnoseCodexShim().summary;
+}

package/src/codex/shim-fingerprint.ts

@@ -1,5 +1,7 @@
 import {
   closeSync,
+  constants,
+  fstatSync,
   existsSync,
   lstatSync,
   linkSync,
@@ -33,8 +35,9 @@ interface StableShimPathProbe {
 }
 
 function readShimProbePrefix(path: string): string {
-  const fd = openSync(path, "r");
+  const fd = openSync(path, process.platform === "win32" ? "r" : constants.O_RDONLY | constants.O_NONBLOCK);
   try {
+    if (process.platform !== "win32" && !fstatSync(fd).isFile()) throw new Error("Shim probe entry is not a regular file");
     const buffer = Buffer.allocUnsafe(CODEX_SHIM_PROBE_BYTES);
     const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
     return buffer.toString("utf8", 0, bytesRead);
@@ -162,14 +165,16 @@ function shimPathFingerprint(path: string): ShimPathFingerprint | null {
  * fails EEXIST on an occupied destination. Checking existence and then renaming
  * would reintroduce exactly the race this function exists to close.
  */
-function restoreWithoutReplacing(from: string, to: string): void {
+function restoreWithoutReplacing(from: string, to: string, guard?: () => void): void {
   const source = lstatSync(from);
   if (source.isSymbolicLink()) {
     symlinkSync(readlinkSync(from), to);
+    guard?.();
     unlinkSync(from);
     return;
   }
   linkSync(from, to);
+  guard?.();
   unlinkSync(from);
 }