@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/app-server-restart-service.ts

@@ -34,6 +34,7 @@ import type {
   CodexRestartResponse,
 } from "../lib/codex-restart-contract";
 import { getServerListenPort } from "../server/lifecycle";
+import type { DesktopPickerState } from "./desktop-app/picker-freshness";
 
 async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
   const { restartCodexDesktopApp } = await import("./desktop-app-restart");
@@ -47,9 +48,40 @@ async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
   };
 }
 
+async function defaultDesktopPickerState(): Promise<DesktopPickerState> {
+  const { readCodexDesktopPickerState } = await import("./desktop-app/picker-freshness");
+  return readCodexDesktopPickerState();
+}
+
+async function defaultCatalogBinding(): Promise<string | null> {
+  const { readCodexCatalogBinding } = await import("./desktop-app/picker-freshness");
+  return readCodexCatalogBinding();
+}
+
+async function readBinding(io: CodexRestartServiceIo): Promise<string | null | undefined> {
+  try {
+    return await (io.catalogBinding ?? defaultCatalogBinding)();
+  } catch {
+    // Distinct from null ("binds no catalog"): an unreadable binding cannot prove sameness.
+    return undefined;
+  }
+}
+
+async function readPickerState(io: CodexRestartServiceIo): Promise<DesktopPickerState> {
+  try {
+    return await (io.desktopPickerState ?? defaultDesktopPickerState)();
+  } catch {
+    return "unknown";
+  }
+}
+
 export interface CodexRestartServiceIo {
   /** Desktop-restart seam, so a route test cannot terminate the developer's own Codex. */
   restartDesktopApp?: () => Promise<CodexDesktopRestartSummary>;
+  /** Whether the desktop picker predates the catalog; decides if the shell must restart. */
+  desktopPickerState?: () => Promise<DesktopPickerState>;
+  /** The catalog config.toml binds, read before and after the sync to catch a rebinding. */
+  catalogBinding?: () => Promise<string | null>;
   /** Process-layer seam, forwarded to every app-server-processes call. */
   processIo?: CodexAppServerProcessIo;
   /** Catalog refresh seam. Resolves to whether a catalog or cache write happened. */
@@ -133,6 +165,7 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   // roster; stopping app-servers before the write would hand the replacement the
   // same stale file it just lost.
   let synced = false;
+  const bindingBefore = await readBinding(io);
   try {
     const port = (io.listenPort ?? getServerListenPort)();
     synced = await (io.syncCatalog ?? defaultSyncCatalog)(port);
@@ -146,15 +179,33 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   (io.resetStateCache ?? resetCodexAppServerCatalogStateCache)();
   const before = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});
 
-  // Done here, before the early returns, because the model picker lives in the DESKTOP
-  // app: "no app-server is running" is not a reason to leave a stale roster on screen,
-  // and an operator who pressed restart still wants the app back on the current catalog.
+  // Decided here, before the early returns, because the model picker lives in the DESKTOP
+  // app: "no app-server is running" is not a reason to leave a stale roster on screen.
+  //
+  // The shell restarts only when its picker predates the catalog (#4761). Quitting it
+  // discards composer drafts, unsent picker selections and pending approvals, and when
+  // the picker is already current the app-server restart below is all the operator
+  // needs: the desktop respawns its app-server child, which rereads config and catalog.
+  // An unreadable picker state takes the full restart, the behaviour before #4761.
   //
   // allowHandoff is false and that is deliberate. The handoff waits for the CALLING
   // process to exit, and this runs inside a long-lived proxy that does not, so every
   // handoff started here would sit out its window and fail after the operator had
   // already been told it was handed off. An honest refusal beats that.
-  const desktop = await (io.restartDesktopApp ?? defaultRestartDesktopApp)();
+  //
+  // A sync that rebinds model_catalog_json without rewriting the catalog bytes leaves the
+  // catalog mtime older than the shell, yet the shell loaded the previous binding. Seen
+  // across this request's own sync, that is proof of staleness, so it skips the probe.
+  const bindingAfter = await readBinding(io);
+  const rebound = bindingBefore === undefined || bindingAfter === undefined || bindingBefore !== bindingAfter;
+  const picker: DesktopPickerState = rebound ? "stale" : await readPickerState(io);
+  const desktop: CodexDesktopRestartSummary = picker === "current" || picker === "not_running"
+    ? {
+      attempted: false, stopped: [], surviving: [], relaunch: "skipped",
+      reason: picker === "current" ? "picker_current" : "no_targets",
+      pickerState: picker,
+    }
+    : { ...await (io.restartDesktopApp ?? defaultRestartDesktopApp)(), pickerState: picker };
 
   const nothingToDo = (): CodexRestartResponse => ({
     desktopApp: desktop,

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

@@ -10,6 +10,7 @@ import { ConfigMutationLockError, mutatePersistedConfig } from "../../config";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
 import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
+import { codexAccountUsesRemainingQuota } from "../account-use-remaining";
 import { getCodexAccountPriority } from "../account-priority";
 import { getCodexAccountAutoSwitchThresholdOverride } from "../account-auto-switch";
 import { clearThreadAccountMapForAccount, isCodexAccountPlanExcluded, reconcileCodexActiveAfterExclusion } from "../routing";
@@ -143,6 +144,7 @@ export function poolAccountDto(
     priority,
     autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(config, account.id),
     creditsAfterLimit: codexAccountUsesCreditsAfterLimit(config, account.id),
+    useRemainingQuota: codexAccountUsesRemainingQuota(config, account.id),
     quota: quota ? { ...quota } : null,
     ...codexCreditsDtoField(config, account.id, poolQuotaHistoryIdentity(account.id) ?? null),
     needsReauth: needsReauth || health.status === "reauth_required",
@@ -171,6 +173,7 @@ export interface CodexAuthAccountDto {
   autoSwitchThresholdOverride: number | null;
   /** False keeps the account out of selection while one of its usage windows is full. */
   creditsAfterLimit?: boolean;
+  useRemainingQuota?: boolean;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   credits?: CodexCredits;
   needsReauth?: boolean;
@@ -405,6 +408,7 @@ export async function listCodexAuthAccountsSnapshot(
       priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       creditsAfterLimit: codexAccountUsesCreditsAfterLimit(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      useRemainingQuota: codexAccountUsesRemainingQuota(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       hasCredential: hasMainCredential,
       needsReauth: mainNeedsReauth,
       ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),

package/src/codex/auth-api/account-pause-group.ts

@@ -1,10 +1,9 @@
+import { observeSignedInCodexIdentity } from "../signed-in-identity";
 import { lstatSync } from "node:fs";
 import type { OcxConfig } from "../../types";
-import { inspectChatGptDomainClaim, extractEmail } from "../../oauth/chatgpt";
-import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../account-id";
 import { readCodexTokensResult } from "../auth-collision";
 import type { CodexTokenReadResult } from "../auth-collision";
-import { getCodexAccountCredential } from "../account-store";
+import { linkedCodexAccountIds } from "../account-identity";
 import { resolveCodexHomeDir } from "../home";
 import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
 import { withNativeMainSharedClaim } from "../native-main-claim";
@@ -12,7 +11,6 @@ import { MAX_AUTH_BYTES, readBounded, resolveNativeProfileContext } from "../nat
 import { NativeProfileError } from "../native-profile-types";
 import { isNativeMainClaimUnavailable, nativeMainProfileBusyResponse } from "./http";
 
-type AccountIdentity = { accountId: string; email: string };
 type MainAuth = CodexTokenReadResult | { status: "api-key-only" };
 
 /** A valid API-key login has no ChatGPT identity; anything else unreadable stays unknown. */
@@ -32,50 +30,6 @@ function readMainAuth(authPath: string): MainAuth {
   }
 }
 
-function identity(accountId: unknown, email: unknown): AccountIdentity | undefined {
-  const normalizedEmail = typeof email === "string" ? email.trim().toLowerCase() : undefined;
-  return typeof accountId === "string" && accountId.trim() && normalizedEmail
-    ? { accountId: accountId.trim(), email: normalizedEmail }
-    : undefined;
-}
-
-/** Resolve only existing entries, under native-main ownership, never on the request path. */
-function linkedAccountIds(config: OcxConfig, selectedId: string, main: MainAuth): string[] | undefined {
-  // Unknown main identity must not produce a successful but incomplete pause.
-  if (main.status === "unreadable" || main.status === "invalid") return undefined;
-  const identities = new Map<string, AccountIdentity | undefined>();
-  if (main.status === "ok") {
-    const tokens = main.tokens;
-    if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string"
-      || (tokens.id_token !== undefined && typeof tokens.id_token !== "string")) return undefined;
-    const claims = [tokens.id_token, tokens.access_token]
-      .filter((token): token is string => typeof token === "string")
-      .map(inspectChatGptDomainClaim);
-    if (claims.some(claim => claim.kind === "invalid")) return undefined;
-    const claimIds = claims.flatMap(claim => claim.kind === "valid" ? [claim.accountId] : []);
-    // organizations[] describes memberships, not the selected workspace. Never use its first row.
-    const accountId = tokens.account_id.trim() || claimIds[0];
-    if (claimIds.some(claim => claim !== accountId)) return undefined;
-    // Both tokens must name the same member; otherwise the bearer's identity is unknown.
-    const emails = new Set([extractEmail(tokens.id_token), extractEmail(undefined, tokens.access_token)]
-      .flatMap(email => email?.trim() ? [email.trim().toLowerCase()] : []));
-    if (emails.size > 1) return undefined;
-    identities.set(MAIN_CODEX_ACCOUNT_ID, identity(accountId, [...emails][0]));
-  }
-  for (const account of config.codexAccounts ?? []) {
-    if (!isSelectableCodexPoolAccount(account)) continue;
-    const credential = getCodexAccountCredential(account.id);
-    identities.set(account.id, identity(credential?.chatgptAccountId, account.email));
-  }
-  const selected = identities.get(selectedId);
-  // Missing identity evidence never links unrelated logins, including members of one workspace.
-  if (!selected) return [selectedId];
-  return [selectedId, ...[...identities].flatMap(([id, candidate]) => (
-    id !== selectedId && candidate?.accountId === selected.accountId && candidate.email === selected.email
-      ? [id] : []
-  ))];
-}
-
 /** Hold admission throughout; claim the physical main whenever its home exists. */
 export async function withCodexAccountPauseGroup(
   config: OcxConfig,
@@ -92,13 +46,15 @@ export async function withCodexAccountPauseGroup(
       // Only positive absence permits Pool-only publication. A dangling symlink or access
       // failure is not absence; do not create a home just to coordinate an unused main login.
       if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") return nativeMainProfileBusyResponse();
-      const ids = linkedAccountIds(config, selectedId, { status: "missing" });
+      const ids = linkedCodexAccountIds(config, selectedId, { status: "missing" });
+      if (ids) observeSignedInCodexIdentity();
       return ids ? publish(ids) : nativeMainProfileBusyResponse();
     }
     const context = resolveNativeProfileContext({ codexHome });
     return await withNativeMainSharedClaim(context, async () => {
       const main = readMainAuth(context.authPath);
-      const ids = linkedAccountIds(config, selectedId, main);
+      const ids = linkedCodexAccountIds(config, selectedId, main);
+      if (ids) observeSignedInCodexIdentity(main.status === "ok" ? main.tokens : undefined);
       return ids ? publish(ids) : nativeMainProfileBusyResponse();
     });
   } catch (error) {

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

@@ -0,0 +1,57 @@
+import { getSignedInCodexIdentity } from "../signed-in-identity";
+import type { OcxConfig } from "../../types";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
+import { clearCodexAccountPin, pinnedCodexAccountId } from "../account-priority";
+import { clearThreadAccountMapForAccount, previewCodexAccountForRequest } from "../routing";
+import { forgetManualPreference } from "../routing/active-account";
+import { withCodexAccountPauseGroup } from "./account-pause-group";
+import { MAIN_CODEX_ACCOUNT_ID } from "../account-id";
+import { getRuntimeConfig, saveRuntimeConfig } from "./runtime-config";
+import { jsonResponse } from "./http";
+
+/** Management owns the native-main claim; publish before releasing any runtime bindings. */
+export async function handleCodexAccountPreservation(req: Request, config: OcxConfig): Promise<Response> {
+  let update: { enabled: boolean; applyToBound: boolean } | undefined;
+  if (req.method === "PUT") {
+    const body: unknown = await req.json().catch(() => null);
+    if (!body || typeof body !== "object" || Array.isArray(body)
+      || !("enabled" in body) || typeof body.enabled !== "boolean"
+      || Object.keys(body).some(key => key !== "enabled" && key !== "applyToBound")
+      || ("applyToBound" in body && typeof body.applyToBound !== "boolean")) {
+      return jsonResponse({ error: "enabled and optional applyToBound must be booleans" }, 400);
+    }
+    const applyToBound = "applyToBound" in body && body.applyToBound === true;
+    if (applyToBound && !body.enabled) return jsonResponse({ error: "applyToBound requires enabled: true" }, 400);
+    update = { enabled: body.enabled, applyToBound };
+  }
+  const runtime = getRuntimeConfig(config);
+  return withCodexAccountPauseGroup(runtime, MAIN_CODEX_ACCOUNT_ID, affectedAccountIds => {
+    const releasedPin = update?.applyToBound === true && affectedAccountIds.includes(pinnedCodexAccountId(runtime) ?? "");
+    if (update) {
+      const rollback = captureConfigTopLevelRollback(runtime, ["codexPreserveSignedInAccount", "activeCodexAccountPinned"]);
+      try {
+        runtime.codexPreserveSignedInAccount = update.enabled;
+        if (releasedPin) clearCodexAccountPin(runtime);
+        saveRuntimeConfig(config, runtime);
+      } catch (error) { rollback(); throw error; }
+      if (update.applyToBound) {
+        for (const id of affectedAccountIds) {
+          clearThreadAccountMapForAccount(id);
+          forgetManualPreference(id);
+        }
+      }
+    }
+    const enabled = runtime.codexPreserveSignedInAccount === true;
+    const nextAccountId = previewCodexAccountForRequest(null, runtime);
+    return jsonResponse({
+      ok: true, enabled, affectedAccountIds, identityKnown: getSignedInCodexIdentity() !== undefined,
+      nextAccountId,
+      nextUsesSignedInQuota: nextAccountId !== null && affectedAccountIds.includes(nextAccountId),
+      pinnedAccountId: pinnedCodexAccountId(runtime) ?? null,
+      bindings: update?.applyToBound ? "released-for-next-request" : "retained",
+      releasedPin,
+      priorityFailbackEnabled: runtime.codexAccountPriorityFailback === true,
+      fallbackConsumesSignedInQuota: true,
+    });
+  });
+}

package/src/codex/auth-api/pool-mode-gate.ts

@@ -25,6 +25,7 @@ import type { PoolQuotaResult } from "./pool-quota-probe";
 import { fetchMainAccountInfoAttempt, fetchMainAccountInfo, MAIN_CACHE_TTL } from "./main-account-probe";
 import { fetchPoolAccountQuota, PoolQuotaProbeBusyError, POOL_CACHE_TTL, POOL_QUOTA_REFRESH_CONCURRENCY } from "./pool-quota-probe";
 import { getRuntimeConfig, configuredPoolAccount, mapWithConcurrency } from "./runtime-config";
+import { trackBackgroundWork } from "../../lib/background-work";
 
 let primeInFlight: Promise<void> | null = null;
 let lastPriorityFailbackPrimeAt: number | undefined;
@@ -259,7 +260,9 @@ export async function primeCodexPoolQuotas(
       && now - lastPriorityFailbackPrimeAt < CODEX_PRIORITY_FAILBACK_REFRESH_MS) return;
     lastPriorityFailbackPrimeAt = now;
   }
-  primeInFlight = (async () => {
+  // Tracked because most callers do not await it, yet it holds the native-main claim
+  // database open; whoever removes that directory settles it first (see background-work).
+  primeInFlight = trackBackgroundWork(`codex-pool-quota-prime:${reason}`, (async () => {
     const pool = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
     const stale = pool.filter(a => {
       const q = getAccountQuota(a.id);
@@ -344,7 +347,7 @@ export async function primeCodexPoolQuotas(
     if (process.env.OPENCODEX_DEBUG_QUOTA === "1") {
       console.warn(`[codex-quota] prime done (reason=${reason}, pool=${pool.length}, refreshed=${stale.length})`);
     }
-  })().finally(() => { primeInFlight = null; });
+  })().finally(() => { primeInFlight = null; }));
   return primeInFlight;
 }
 

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

@@ -1,5 +1,7 @@
+import { handleCodexAccountPreservation } from "./account-preservation";
 import { persistCodexAccountSelection } from "./account-selection";
 import { CODEX_ACCOUNT_LOG_LABEL_RE, codexAccountLogLabel } from "../account-label";
+import { handleUseRemainingQuotaRoute } from "./use-remaining-route";
 import { poolQuotaHistoryIdentity, readCodexAccountRecord } from "../account-store";
 import { estimateCodexQuotaCapacity, insufficientCodexCapacity } from "../quota-capacity";
 import type { CodexCapacityResult } from "../quota-capacity";
@@ -34,6 +36,12 @@ export async function handleCodexAuthAPI(
   convergeCodexCatalog?: CodexAuthCatalogConvergence,
   principal?: import("../../server/management-auth").ManagementPrincipal,
 ): Promise<Response | null> {
+  if (url.pathname === "/api/codex-auth/preserve-signed-in" && (req.method === "GET" || req.method === "PUT")) {
+    return handleCodexAccountPreservation(req, config);
+  }
+  if (url.pathname === "/api/codex-auth/accounts/use-remaining" && (req.method === "GET" || req.method === "PUT")) {
+    return handleUseRemainingQuotaRoute(req, url, config);
+  }
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "GET") {
     const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
     return jsonResponse({ accounts: await listCodexAuthAccounts(config, forceRefresh) });

package/src/codex/auth-api/use-remaining-route.ts

@@ -0,0 +1,36 @@
+import type { OcxConfig } from "../../types";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
+import { MAIN_CODEX_ACCOUNT_ID, isValidCodexAccountId } from "../account-id";
+import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
+import { codexAccountUsesRemainingQuota, setCodexAccountUseRemainingQuota } from "../account-use-remaining";
+import { getMainAccountHardLockStatus } from "../main-account-hard-lock";
+import { configuredPoolAccount, getRuntimeConfig, saveRuntimeConfig } from "./runtime-config";
+import { jsonResponse } from "./http";
+
+/** Called only behind the existing Codex management authentication boundary. */
+export async function handleUseRemainingQuotaRoute(req: Request, url: URL, config: OcxConfig): Promise<Response> {
+  const parsed: unknown = req.method === "PUT" ? await req.json().catch(() => null) : { id: url.searchParams.get("id") };
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return jsonResponse({ error: "body must be an object" }, 400);
+  const body = parsed as { id?: unknown; useRemainingQuota?: unknown };
+  if (typeof body.id !== "string" || (body.id !== MAIN_CODEX_ACCOUNT_ID && !isValidCodexAccountId(body.id))) {
+    return jsonResponse({ error: "Invalid account id format" }, 400);
+  }
+  const runtime = getRuntimeConfig(config);
+  if (body.id !== MAIN_CODEX_ACCOUNT_ID && !configuredPoolAccount(runtime, body.id)) return jsonResponse({ error: "Account not found" }, 404);
+  if (req.method === "PUT") {
+    if (typeof body.useRemainingQuota !== "boolean") return jsonResponse({ error: "useRemainingQuota must be a boolean" }, 400);
+    const rollback = captureConfigTopLevelRollback(runtime, ["codexUseRemainingQuotaAccountIds"]);
+    try {
+      setCodexAccountUseRemainingQuota(runtime, body.id, body.useRemainingQuota);
+      saveRuntimeConfig(config, runtime);
+    } catch (error) {
+      rollback();
+      throw error;
+    }
+  }
+  return jsonResponse({ ok: true, id: body.id,
+    useRemainingQuota: codexAccountUsesRemainingQuota(runtime, body.id),
+    autoSwitchThreshold: getEffectiveCodexAutoSwitchThreshold(runtime, body.id),
+    ...(body.id === MAIN_CODEX_ACCOUNT_ID ? { mainAccountHardLock: getMainAccountHardLockStatus(runtime) } : {}),
+  });
+}

package/src/codex/auth-api.ts

@@ -33,7 +33,6 @@ export {
 } from "./auth-api/pool-mode-gate";
 export { createResetCreditWhamClient } from "./auth-api/reset-credit-service";
 export type { CodexAuthCatalogConvergence } from "./auth-api/login-flow";
-export { handleCodexAuthAPI } from "./auth-api/routes";
 import { getEffectiveActiveCodexAccountId } from "./routing";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import type { OcxConfig } from "../types";

package/src/codex/auth-context.ts

@@ -51,6 +51,7 @@ import {
 // The half-open TRANSIENT-HOLD lease (#4701). Not the quota-cooldown probe lease imported from
 // ./routing above -- different module, different domain, and a request never holds both.
 import { releaseTransientProbe } from "../routing/probe-lease";
+import { trackBackgroundWork } from "../lib/background-work";
 import {
   codexConversationIdentity,
   recordCodexThreadLineage,
@@ -66,7 +67,8 @@ import {
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
-import { formatErrorResponse } from "../bridge";
+import { formatErrorResponse, formatUsageLimitReachedResponse } from "../bridge";
+import { nextCodexPoolRecoveryAt } from "./routing/pool-recovery";
 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";
@@ -523,6 +525,11 @@ export class CodexAccountCooldownError extends Error {
 
 export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
   readonly resetAt?: number;
+  /**
+   * Earliest known recovery of another stored pool account, set only when an unpinned pool
+   * selection reached main (#7046). A hint for the client's retry time; never routing input.
+   */
+  poolRecoveryAt?: number;
 
   constructor(resetAt?: number, thresholds = resolveMainAccountHardLockThresholds(undefined)) {
     super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
@@ -625,7 +632,7 @@ export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
 
 export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
   "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
-  | "creditCodexAccountIds" | "codexAccounts"
+  | "creditCodexAccountIds" | "codexAccounts" | "codexUseRemainingQuotaAccountIds"
 >>;
 
 interface CodexAuthMaterializationOptions {
@@ -776,7 +783,7 @@ function mainCreditsHoldResetAt(config: Pick<OcxConfig, "creditCodexAccountIds">
 }
 
 function assertMainAccountPolicy(
-  config: Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "creditCodexAccountIds"> | undefined,
+  config: Pick<OcxConfig, "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "creditCodexAccountIds" | "codexUseRemainingQuotaAccountIds"> | undefined,
 ): void {
   if (config) {
     const status = getMainAccountHardLockStatus(config);
@@ -935,16 +942,40 @@ export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSele
     + ` (source: ${err.cooldownSource ?? "default"}).${recovery}`;
 }
 
+/**
+ * The soonest a main hard-lock refusal is worth retrying: a sibling pool account's known
+ * recovery when it comes first, otherwise main's own reset (#7046). A pool hint is held to at
+ * least {@link MAIN_HARD_LOCK_MIN_POOL_RETRY_MS} so a hold about to lapse cannot turn the refusal
+ * into a tight retry loop. Null when neither time is known and still in the future.
+ */
+export const MAIN_HARD_LOCK_MIN_POOL_RETRY_MS = 60_000;
+export function mainHardLockRetryAt(err: CodexMainAccountHardLockError, now: number): number | null {
+  const future = (value: number | undefined): number | null =>
+    typeof value === "number" && Number.isFinite(value) && value > now ? value : null;
+  const main = future(err.resetAt);
+  const pool = future(err.poolRecoveryAt);
+  const poolRetryAt = pool === null ? null : Math.max(pool, now + MAIN_HARD_LOCK_MIN_POOL_RETRY_MS);
+  if (poolRetryAt !== null && (main === null || poolRetryAt < main)) return poolRetryAt;
+  return main;
+}
+
 /** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
 export function cooldownErrorResponse(
   err: CodexAccountCooldownError,
   now = Date.now(),
   accountSelector?: string,
 ): Response {
+  if (err instanceof CodexMainAccountHardLockError) {
+    // A local policy refusal with a known horizon, not a transient throttle (#7046): Codex keeps
+    // a Goal active and sleeps through `rate_limit_exceeded` for the whole Retry-After, but
+    // stops on `usage_limit_reached` and shows the reset. The guard itself is unchanged.
+    const retryAt = mainHardLockRetryAt(err, now);
+    return formatUsageLimitReachedResponse(cooldownErrorMessage(err, accountSelector), retryAt,
+      retryAt === null ? null : Math.max(1, Math.ceil((retryAt - now) / 1000)));
+  }
   const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
   const headers = new Headers(res.headers);
-  if (!(err instanceof CodexReserveUnavailableError)
-    && (!(err instanceof CodexMainAccountHardLockError) || err.resetAt !== undefined)) {
+  if (!(err instanceof CodexReserveUnavailableError)) {
     headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
   }
   return new Response(res.body, { status: res.status, headers });
@@ -1044,11 +1075,51 @@ async function awaitMainAccountPolicyBindingSettled(
   if (!settled) throw new CodexMainProfileDrainingError();
 }
 
+/**
+ * Resolve the credential for one Codex turn. A main hard-lock reached through unpinned pool
+ * selection is annotated with the earliest known pool recovery, so the refusal can name a retry
+ * time that a sibling account may meet (#7046).
+ */
 export async function resolveCodexAuthContext(
   headers: Headers,
   config: OcxConfig,
   mode: CodexAccountMode,
   options: ResolveCodexAuthContextOptions = {},
+): Promise<CodexAuthContext> {
+  // Filled by the inner resolver with the request's own fenced model evidence, so the hint obeys it.
+  const eligibility: RecoveryHintEligibility = {};
+  try {
+    return await resolveCodexAuthContextUnannotated(headers, config, mode, options, eligibility);
+  } catch (error) {
+    if (error instanceof CodexMainAccountHardLockError && mode === "pool" && options.accountId === undefined
+      && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
+      && !requiresReserveAuthorization(options.codexAuthPolicy ?? config, options.modelId, options.admission)
+      // An account-gated model with no resolved roster has no known eligible sibling.
+      && (!options.modelId || !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
+        || eligibility.modelEligibleAccountIds !== undefined)) {
+      try {
+        const now = Date.now();
+        error.poolRecoveryAt = nextCodexPoolRecoveryAt(config, now, codexQuotaScopeForModel(options.modelId), {
+          deniedAccountIds: eligibility.deniedModelAccountIds,
+          eligibleAccountIds: eligibility.modelEligibleAccountIds,
+        });
+      } catch { /* the hint is optional; the refusal stands without it */ }
+    }
+    throw error;
+  }
+}
+
+interface RecoveryHintEligibility {
+  modelEligibleAccountIds?: ReadonlySet<string>;
+  deniedModelAccountIds?: ReadonlySet<string>;
+}
+
+async function resolveCodexAuthContextUnannotated(
+  headers: Headers,
+  config: OcxConfig,
+  mode: CodexAccountMode,
+  options: ResolveCodexAuthContextOptions = {},
+  eligibility: RecoveryHintEligibility = {},
 ): Promise<CodexAuthContext> {
   const writerGeneration = captureConfigGeneration();
   const policy = options.codexAuthPolicy ?? config;
@@ -1256,6 +1327,7 @@ export async function resolveCodexAuthContext(
     const modelEligibleAccountIds = entitledAccountIds
       ? new Set([...entitledAccountIds].filter(candidate => !excludeAccountIds?.has(candidate)))
       : undefined;
+    eligibility.modelEligibleAccountIds = modelEligibleAccountIds;
     // #4768: the flagships stay visible and never fail closed, so this is evidence routing may
     // ORDER by, not evidence it may refuse on. Read synchronously from rosters discovery has
     // already gathered -- no upstream fetch joins the request path for the most commonly
@@ -1273,6 +1345,7 @@ export async function resolveCodexAuthContext(
       undefined,
       { excludeAccountIds },
     );
+    eligibility.deniedModelAccountIds = deniedModelAccountIds;
     const selectionOptions = {
       // Temporary switch drain keeps the candidate until the atomic claim rejects
       // it. Retained recovery makes main wholly ineligible so pool routing continues.
@@ -1475,9 +1548,10 @@ export async function resolveCodexAuthContext(
     if (options.primeCodexPoolQuotas) {
       void options.primeCodexPoolQuotas(config, reason).catch(() => {});
     } else {
-      import("./auth-api")
+      // Tracked from the import on: the prime registers itself only once the module resolves.
+      void trackBackgroundWork(`codex-pool-quota-prime-import:${reason}`, import("./auth-api")
         .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, reason))
-        .catch(() => {});
+        .catch(() => {}));
     }
   }
   // Snapshot (not just the deadline) so a refused request can report WHY it is cooled:

package/src/codex/autostart-health.ts

@@ -35,6 +35,7 @@ export interface StartupHealthInputs {
   shimHealthy: boolean;
   platform: NodeJS.Platform;
   diagnosticStale?: boolean;
+  shimActivationPending?: boolean;
   routingAdoption?: RoutingAdoptionEvidence;
 }
 
@@ -55,6 +56,8 @@ export interface StartupHealth {
   serviceConflict: boolean;
   shimInstalled: boolean;
   shimHealthy: boolean;
+  /** Intact PATH-overlay shim this process could not see active; activate it rather than repair it. */
+  shimActivationPending?: boolean;
   shimCoverage: ShimCoverage;
   serviceSupported: boolean;
   platform: NodeJS.Platform;
@@ -171,6 +174,7 @@ export function collectStartupHealth(
     serviceSupported: service.supported,
     shimInstalled: shim.installed,
     shimHealthy: shim.healthy,
+    ...(shim.activationPending ? { shimActivationPending: true } : {}),
     platform: process.platform,
     ...(routingAdoption ? { routingAdoption } : {}),
   });

package/src/codex/catalog/auto-review.ts

@@ -480,20 +480,37 @@ function configHasProviderAutoReview(config: Pick<OcxConfig, "providers">): bool
     provider.autoReviewModel !== undefined || provider.autoReviewModelOverrides !== undefined);
 }
 
+/**
+ * The global override selector, when the operator enabled it and named a model.
+ *
+ * Occupies the same slot as Codex's root `auto_review_model` fallback and wins over it: an
+ * enabled Model-settings choice is the operator's explicit pick, while a disabled or blank block
+ * leaves the root selector in charge. Provider-scoped stamps keep their precedence separately.
+ */
+export function resolveAutoReviewOverrideSelector(
+  config?: Pick<OcxConfig, "autoReviewOverride">,
+): string | undefined {
+  const block = config?.autoReviewOverride;
+  if (block?.enabled !== true) return undefined;
+  const model = typeof block.model === "string" ? block.model.trim() : "";
+  return model.length > 0 ? model : undefined;
+}
+
 /** Apply the root Codex auto-review selector after the final catalog merge. */
 export function finalizeAutoReviewModelOverride(
   models: RawEntry[] | undefined,
   sourceModels: readonly RawEntry[] = [],
-  config?: Pick<OcxConfig, "providers">,
+  config?: Pick<OcxConfig, "providers" | "autoReviewOverride">,
 ): AutoReviewModelOverrideResult {
   if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(
     models.filter(entry => !isCodexControlPlaneModel(entry.slug)),
     sourceModels.filter(entry => !isCodexControlPlaneModel(entry.slug)),
   );
+  const rootValue = resolveAutoReviewOverrideSelector(config) ?? readConfiguredAutoReviewModel();
   if (config && configHasProviderAutoReview(config)) {
-    return applyConfiguredAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), config, sourceModels);
+    return applyConfiguredAutoReviewModelOverride(models, rootValue, config, sourceModels);
   }
-  return applyAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), sourceModels);
+  return applyAutoReviewModelOverride(models, rootValue, sourceModels);
 }
 /**
  * Why an account-gated native model stopped being offered, but only when the answer is one the