@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/codex/app-server-processes.ts

@@ -14,7 +14,7 @@ import {
   resolveTrustedWindowsPowerShellExe,
   resolveTrustedWindowsTaskkillExe,
 } from "../lib/windows-elevation";
-import { readCodexCatalogPath } from "./catalog/parsing";
+import { readCodexCatalogPath } from "./paths";
 
 export const STALE_CODEX_APP_SERVER_HINT =
   "If Codex still shows an older model list, run `ocx sync --restart-codex`: it restarts the long-lived app-server "
@@ -332,6 +332,32 @@ export function isCodexAppServerCommandLine(commandLine: string, executable?: st
   return false;
 }
 
+/**
+ * True when the command line is ANY live Codex session, not just an app-server.
+ *
+ * The update-blocking contract needs the broader reading: an interactive TUI, a
+ * one-shot `codex exec`, or an app-server all have the package's binaries in use,
+ * so every subcommand counts. The executable identity stays exactly as strict as
+ * {@link isCodexAppServerCommandLine} - only the argv discipline is dropped. A
+ * coincidental codex-shaped argument can never open this matcher.
+ */
+export function isCodexSessionCommandLine(commandLine: string, executable?: string): boolean {
+  const trimmed = commandLine.trim();
+  let tokens = tokenizeCommandLine(trimmed);
+  if (executable) {
+    if (isCodeModeHostToken(executable) || isCodexExecutableToken(executable)) return true;
+  }
+  if (tokens.length === 0) return false;
+  if (isCodeModeHostProcess(tokens)) return true;
+  // Same interpreter unwrap the app-server matcher uses: a codex-shaped token must
+  // immediately follow the interpreter so an interpreter flag value is never read
+  // as the entrypoint.
+  if (isInterpreterToken(tokens[0]!) && tokens.length > 1 && isCodexExecutableToken(tokens[1]!)) {
+    tokens = tokens.slice(1);
+  }
+  return isCodexExecutableToken(tokens[0]!);
+}
+
 function parseUnixProcStatusUid(status: string): number | undefined {
   const match = /^Uid:\s+(\d+)/m.exec(status);
   if (!match) return undefined;
@@ -339,7 +365,7 @@ function parseUnixProcStatusUid(status: string): number | undefined {
   return Number.isSafeInteger(uid) ? uid : undefined;
 }
 
-function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
+function listUnixProcSnapshots(uid: number | undefined, requireComplete = true): ProcessSnapshot[] {
   // procfs missing on a Linux-shaped platform is an enumeration failure, not
   // "no processes" — the staleness collector must not read it as not_running.
   if (!existsSync("/proc")) throw new Error("procfs_unavailable");
@@ -359,8 +385,10 @@ function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
       const commandLine = argv.join(" ").trim();
       if (!commandLine) continue;
       out.push({ pid, commandLine, executable: argv[0], uid: processUid });
-    } catch {
-      /* process exited mid-scan */
+    } catch (error) {
+      // Complete observations may ignore only disappearance. Restart target
+      // enumeration can skip an unreadable PID while retaining verified ones.
+      if (requireComplete && (error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
     }
   }
   return out;
@@ -518,10 +546,10 @@ async function listWindowsSnapshotsAsync(): Promise<ProcessSnapshot[]> {
   return parseWindowsSnapshotOutput(output);
 }
 
-function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined): ProcessSnapshot[] {
+function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined, requireComplete = true): ProcessSnapshot[] {
   if (platform === "win32") return listWindowsSnapshots();
   if (platform === "darwin") return listDarwinSnapshots(getuid());
-  return listUnixProcSnapshots(getuid());
+  return listUnixProcSnapshots(getuid(), requireComplete);
 }
 
 export interface ListProcessSnapshotsOptions {
@@ -565,7 +593,7 @@ export function listCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): C
     // Restart/kill contract (#476): enumeration failure means no targets —
     // never signal a process we could not verify.
     try {
-      snapshots = defaultListSnapshots(platform, getuid);
+      snapshots = defaultListSnapshots(platform, getuid, false);
     } catch {
       snapshots = [];
     }
@@ -581,6 +609,68 @@ export function listCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): C
   return matched;
 }
 
+/**
+ * Enumeration outcome for callers that must DEFER on an unreadable process table.
+ *
+ * {@link listCodexAppServerProcesses} maps enumeration failure to an empty list because its
+ * kill contract must never signal a process it could not verify. The Codex CLI update
+ * workflow needs the opposite reading: "no matches" and "could not look" lead to different
+ * decisions, and only the first one may allow an install to proceed.
+ */
+export type CodexAppServerProcessScan =
+  | Readonly<{ kind: "observed"; processes: readonly CodexAppServerProcess[] }>
+  | Readonly<{ kind: "unavailable" }>;
+
+function scanProcessSnapshots(
+  io: CodexAppServerProcessIo,
+  matches: (commandLine: string, executable?: string) => boolean,
+): CodexAppServerProcessScan {
+  const platform = io.platform ?? process.platform;
+  const getuid = io.getuid ?? (() => {
+    try {
+      return typeof process.getuid === "function" ? process.getuid() : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+  let snapshots: ProcessSnapshot[];
+  try {
+    snapshots = io.listSnapshots ? io.listSnapshots() : defaultListSnapshots(platform, getuid);
+  } catch {
+    return Object.freeze({ kind: "unavailable" as const });
+  }
+  const seen = new Set<number>();
+  const matched: CodexAppServerProcess[] = [];
+  for (const snapshot of snapshots) {
+    if (seen.has(snapshot.pid)) continue;
+    if (!matches(snapshot.commandLine, snapshot.executable)) continue;
+    seen.add(snapshot.pid);
+    matched.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
+  }
+  return Object.freeze({ kind: "observed" as const, processes: Object.freeze(matched) });
+}
+
+/** Same matcher and snapshot sources as {@link listCodexAppServerProcesses}, failing closed. */
+export function scanCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): CodexAppServerProcessScan {
+  return scanProcessSnapshots(io, isCodexAppServerCommandLine);
+}
+
+/**
+ * {@link isCodexSessionCommandLine} over the same snapshot sources, failing closed.
+ *
+ * Any live Codex session counts - TUI, exec or app-server all hold the installed
+ * package open while npm would be replacing it, and a missed TUI was the reported
+ * source of a half-written install on Linux. The kill path keeps the narrower
+ * {@link isCodexAppServerCommandLine} because a signal must never leave its
+ * verified contract; this scan decides whether it is SAFE to install, so it may
+ * only err toward deferring.
+ */
+export function scanCodexSessionProcesses(io: CodexAppServerProcessIo = {}): CodexAppServerProcessScan {
+  // Shared installs may be held open by another readable user's session. This
+  // read-only scan is broader than the unchanged same-user restart/kill path.
+  return scanProcessSnapshots({ ...io, getuid: io.getuid ?? (() => undefined) }, isCodexSessionCommandLine);
+}
+
 export function formatStaleCodexAppServerWarning(
   processes: readonly { pid: number }[],
 ): string {

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/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

@@ -632,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 {
@@ -783,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);

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

package/src/codex/catalog/build-entries.ts

@@ -48,7 +48,7 @@ import { NATIVE_RESERVE_MODEL } from "./native-models";
 import { isReserveCatalogProjection, type ReserveCatalogProjection } from "./reserve";
 import { deriveEntry, finishUpstreamNativeEntry, isExactComboCatalogEntry } from "./derive-entry";
 import { PICKER_ORDER_PRIORITY_BASE, SPAWN_PRIORITY_FIELD } from "./subagent-roster";
-import { applyConfiguredUltraFast } from "./configured-tiers";
+import { applyConfiguredUltraFast, configuredUltraFastSlugs } from "./configured-tiers";
 import { applyNativeUltraFastTier } from "./native-ultrafast";
 
 export interface ObservedCatalogEntryBuildInput {
@@ -111,6 +111,14 @@ export function buildCatalogEntries(
     accountNativeSlugs,
     accountNativeSlugsBySelector,
   });
+  // Live discovery does not run the disk merge; use the same captured declarations and row fences.
+  const configured = configuredUltraFastSlugs(goModels);
+  for (const entry of entries) {
+    if (typeof entry.slug !== "string" || !entry.slug.includes("/")
+      || isNativeAliasCatalogEntry(entry) || isExactComboCatalogEntry(entry, exactComboSlugs)
+      || trustedAccountBoundNativeCatalogSlug(entry) !== undefined) continue;
+    applyConfiguredUltraFast(entry, undefined, configured.has(entry.slug), false);
+  }
   applyFullModelPickerOrder(entries, modelPickerOrder);
   return entries;
 }

package/src/codex/catalog/combo-member.ts

@@ -100,7 +100,7 @@ import type {
   CatalogSourceEvidence,
   CatalogTrustedOpenAiApiPolicySnapshot,
 } from "../convergence-types";
-import { applyProviderConfigHints, configuredAutoCompactTokenLimit, positiveSafeInteger } from "./model-hints";
+import { applyProviderConfigHints, configuredAutoCompactTokenLimit, positiveSafeInteger, withVisionSidecarInput } from "./model-hints";
 
 /** Model ids each provider must retain for combo catalog derivation (OCX-111). */
 export function configuredComboTargetModelsByProvider(
@@ -219,6 +219,7 @@ export function resolveComboCatalogMember(
   callerFallback?: ComboCatalogMemberFallback,
   metadataModelIdCaseFold?: boolean,
   metadataConfigDir?: string,
+  visionSidecarEnabled = true,
 ): CatalogModel | undefined {
   const existing = memberByKey.get(targetKey(target));
   const prov = providers.get(target.provider);
@@ -227,6 +228,16 @@ export function resolveComboCatalogMember(
   // is unusable for catalog derivation while the provider is off.
   if (prov?.disabled === true) return undefined;
 
+  /** Preserve custom modality overrides while filling missing provider metadata. */
+  const withProviderHints = (model: CatalogModel): CatalogModel => {
+    const hinted = prov
+      ? applyProviderConfigHints(target.provider, prov, model, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir, visionSidecarEnabled)
+      : model;
+    return model.catalogKind === CODEX_CUSTOM_MODEL_CATALOG_KIND && model.inputModalities !== undefined
+      ? withVisionSidecarInput({ ...hinted, inputModalities: [...model.inputModalities] }, prov, visionSidecarEnabled)
+      : hinted;
+  };
+
   const withFallbackMetadata = (member: CatalogModel): CatalogModel => {
     const contextWindow = typeof member.contextWindow === "number" && member.contextWindow > 0
       ? member.contextWindow
@@ -276,7 +287,7 @@ export function resolveComboCatalogMember(
     // supplies a vision sidecar. Apply the same provider hints used for thin
     // rows before deriving a combo from this complete row.
     const hinted = prov && isModelVisionSidecarConsumer(prov, existing.id)
-      ? applyProviderConfigHints(target.provider, prov, existing, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir)
+      ? withProviderHints(existing)
       : existing;
     const capped = applyProviderContextCap(hinted.contextWindow, contextCap);
     if (capped === undefined || capped === existing.contextWindow) {
@@ -298,9 +309,7 @@ export function resolveComboCatalogMember(
     id: target.model,
     provider: target.provider,
   };
-  const hinted = prov
-    ? applyProviderConfigHints(target.provider, prov, base, contextCap, metadataModelIdCaseFold, undefined, metadataConfigDir)
-    : base;
+  const hinted = withProviderHints(base);
   const hintedContext = typeof hinted.contextWindow === "number" && hinted.contextWindow > 0
     ? hinted.contextWindow
     : undefined;

package/src/codex/catalog/configured-tiers.ts

@@ -12,7 +12,7 @@ export function supportsConfiguredUltraFast(policy: ResolvedFastPolicy | undefin
     && policy.fastWire.canonicalToWire.ultrafast === "ultrafast";
 }
 
-/** Carry captured capability to the pure merge without treating persisted metadata as authority. */
+/** Carry captured capability to catalog projection without treating persisted metadata as authority. */
 export function configuredUltraFastSlugs(models: readonly CatalogModel[]): ReadonlySet<string> {
   const declarations = new Map<string, boolean>();
   for (const model of models) {