@yansigit/opencodex 2.31.0

package/src/codex/account-id.ts

@@ -0,0 +1,34 @@
+/** Canonical persisted Codex pool-account id format. */
+export const CODEX_ACCOUNT_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+// Account credentials are persisted in JSON object maps. These names have
+// special meaning on ordinary JavaScript objects and must never be admitted as
+// user-controlled keys.
+const RESERVED_CODEX_ACCOUNT_IDS = new Set(["__proto__", "prototype", "constructor"]);
+
+/**
+ * Stable internal id under which the Codex Desktop login participates in account rotation.
+ * It is reserved and must never be used as a public namespace target or pool-account id.
+ */
+export const MAIN_CODEX_ACCOUNT_ID = "__main__";
+
+export function isValidCodexAccountId(accountId: unknown): accountId is string {
+  return typeof accountId === "string"
+    && accountId !== MAIN_CODEX_ACCOUNT_ID
+    && CODEX_ACCOUNT_ID_RE.test(accountId)
+    && !RESERVED_CODEX_ACCOUNT_IDS.has(accountId.toLowerCase());
+}
+
+type CodexAccountIdentityRow = { id: string; isMain: boolean };
+
+/** Legacy invalid rows remain loadable for cleanup, but never participate in routing. */
+export function isSelectableCodexPoolAccount(account: CodexAccountIdentityRow): boolean {
+  return !account.isMain && isValidCodexAccountId(account.id);
+}
+
+/** A pre-validation pool row that collides with the internal Desktop-account sentinel. */
+export function hasLegacyMainCodexPoolAccount(
+  accounts: readonly CodexAccountIdentityRow[] | undefined,
+): boolean {
+  return accounts?.some(account => !account.isMain && account.id === MAIN_CODEX_ACCOUNT_ID) ?? false;
+}

package/src/codex/account-label.ts

@@ -0,0 +1,47 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { CodexAccount, OcxConfig } from "../types";
+import type { CodexAuthContext } from "./auth-context";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+
+export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
+
+export function createCodexAccountLogLabel(existingLabels: Iterable<string | undefined | null> = []): string {
+  const used = new Set([...existingLabels].filter((value): value is string => !!value));
+  for (let i = 0; i < 16; i++) {
+    const label = `p${randomBytes(3).toString("hex")}`;
+    if (!used.has(label)) return label;
+  }
+  return `p${randomBytes(6).toString("hex").slice(0, 6)}`;
+}
+
+export function fallbackCodexAccountLogLabel(accountId: string): string {
+  return `p${createHash("sha256").update(accountId).digest("hex").slice(0, 6)}`;
+}
+
+export function codexAccountLogLabel(account: CodexAccount): string {
+  return CODEX_ACCOUNT_LOG_LABEL_RE.test(account.logLabel ?? "")
+    ? account.logLabel!
+    : fallbackCodexAccountLogLabel(account.id);
+}
+
+/** Effective durable label for a resolved Codex Pool account. */
+export function codexAuthContextLogLabel(
+  authCtx: CodexAuthContext,
+  config: Pick<OcxConfig, "codexAccounts">,
+): "main" | `p${string}` | undefined {
+  if (authCtx.kind !== "pool" && authCtx.kind !== "main-pool") return undefined;
+  if (authCtx.accountId === MAIN_CODEX_ACCOUNT_ID) return "main";
+  const account = (config.codexAccounts ?? []).find(candidate => candidate.id === authCtx.accountId);
+  return account ? codexAccountLogLabel(account) as `p${string}` : undefined;
+}
+
+export function withCodexAccountLogLabel(
+  account: Omit<CodexAccount, "logLabel"> & Partial<Pick<CodexAccount, "logLabel">>,
+  existingAccounts: readonly CodexAccount[],
+): CodexAccount {
+  if (account.logLabel && CODEX_ACCOUNT_LOG_LABEL_RE.test(account.logLabel)) return account as CodexAccount;
+  return {
+    ...account,
+    logLabel: createCodexAccountLogLabel(existingAccounts.map(existing => existing.logLabel)),
+  };
+}

package/src/codex/account-lifecycle.ts

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync } from "node:fs";
+import {
+  atomicWriteFile,
+  getConfigPath,
+  saveConfigPreservingClaudeCode,
+  withConfigMutationLockSync,
+} from "../config";
+import { removeCodexAccountCredential } from "./account-store";
+import { clearAccountNeedsReauth } from "./account-runtime-state";
+import { getMainChatgptAccountId } from "./auth-collision";
+import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
+import { clearAccountQuota } from "./quota";
+import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
+import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
+import { clearMainAccountCredentialPresence, clearMainAccountInfoCache } from "./main-account-cache";
+import { forgetCodexAccountPause } from "./account-pause";
+import { clearCodexAccountPin, forgetCodexAccountPriority } from "./account-priority";
+import { codexAccountNamespaceEntries, codexAccountPickerEnabled } from "./account-namespaces";
+import type { OcxConfig } from "../types";
+
+let observedMainChatgptAccountId: string | undefined;
+
+export class CodexAccountDeleteCleanupError extends Error {
+  constructor() {
+    super("Account deletion was saved, but local credential cleanup did not complete. Retry removal.");
+    this.name = "CodexAccountDeleteCleanupError";
+  }
+}
+
+export class CodexAccountDeleteRollbackError extends Error {
+  constructor() {
+    super("Account deletion failed and the previous config could not be restored. Restart before retrying.");
+    this.name = "CodexAccountDeleteRollbackError";
+  }
+}
+
+export function purgeCodexAccountRuntimeState(accountId: string): void {
+  clearAccountNeedsReauth(accountId);
+  clearAccountQuota(accountId);
+  clearThreadAccountMapForAccount(accountId);
+  clearCodexUpstreamHealthForAccount(accountId);
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    clearMainAccountInfoCache();
+    clearMainAccountCredentialPresence();
+  }
+}
+
+function purgeMainCodexAccountRuntimeState(): void {
+  purgeCodexAccountRuntimeState(MAIN_CODEX_ACCOUNT_ID);
+  setMainAccountPlan(null);
+  invalidateCodexWebSocketsForAccount(MAIN_CODEX_ACCOUNT_ID);
+}
+
+/**
+ * The main Codex login is stored under the stable `__main__` alias, while
+ * `~/.codex/auth.json` can be replaced with credentials for another physical
+ * ChatGPT account. Drop alias-keyed runtime state when that identity changes so
+ * cooldown, quota, reauth, and thread affinity do not leak across accounts.
+ */
+export function reconcileMainCodexAccountRuntimeState(): boolean {
+  const currentAccountId = getMainChatgptAccountId();
+  // A missing/malformed auth.json is an unknown identity, not a confirmed account switch. Keep the
+  // prior observation and its safety state until a real account id can be read again.
+  if (currentAccountId === null) return false;
+  const previousAccountId = observedMainChatgptAccountId;
+  observedMainChatgptAccountId = currentAccountId;
+  if (previousAccountId === undefined || previousAccountId === currentAccountId) return false;
+
+  purgeMainCodexAccountRuntimeState();
+  return true;
+}
+
+/**
+ * Apply a transaction-confirmed physical native-login change without waiting for
+ * a later auth.json observation. The caller owns credential commit/rollback.
+ */
+export function applyConfirmedMainCodexAccountTransition(
+  fromAccountId: string,
+  toAccountId: string,
+): boolean {
+  if (!fromAccountId || !toAccountId || fromAccountId === toAccountId) {
+    if (toAccountId) observedMainChatgptAccountId = toAccountId;
+    return false;
+  }
+  observedMainChatgptAccountId = toAccountId;
+  purgeMainCodexAccountRuntimeState();
+  return true;
+}
+
+export function resetMainCodexAccountIdentityTrackingForTests(): void {
+  observedMainChatgptAccountId = undefined;
+  clearMainAccountCredentialPresence();
+}
+
+function restoreRuntimeConfig(target: OcxConfig, snapshot: OcxConfig): void {
+  for (const key of Object.keys(target) as Array<keyof OcxConfig>) delete target[key];
+  Object.assign(target, snapshot);
+}
+
+function restorePersistedConfig(configPath: string, previousBytes: string): void {
+  try {
+    if (readFileSync(configPath, "utf8") === previousBytes) return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  atomicWriteFile(configPath, previousBytes);
+}
+
+/**
+ * Delete a stored account while retaining its selector binding.
+ *
+ * When the runtime config is backed by an existing config.json, commit the config deletion before
+ * credentials or runtime state are destroyed. Transient callers intentionally skip durable config
+ * persistence because they have no durable account row to protect. The whole sequence shares the
+ * config mutation coordinator so a cooperating writer cannot re-add a persisted account between
+ * the durable config commit and credential cleanup.
+ *
+ * Returns true when a picker-visible row disappeared and the catalog must converge.
+ */
+export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string): boolean {
+  let cleanupFailed = false;
+  const pickerVisibilityChanged = withConfigMutationLockSync(() => {
+    const previousConfig = structuredClone(runtimeConfig);
+    const configPath = getConfigPath();
+    const hasPersistedConfig = existsSync(configPath);
+    const previousPersistedConfig = hasPersistedConfig ? readFileSync(configPath, "utf8") : undefined;
+    const hadStoredAccount = (runtimeConfig.codexAccounts ?? [])
+      .some(account => !account.isMain && account.id === accountId);
+    const hadVisiblePickerBinding = hadStoredAccount
+      && codexAccountPickerEnabled(runtimeConfig)
+      && codexAccountNamespaceEntries(runtimeConfig)
+        .some(([, boundAccountId]) => boundAccountId === accountId);
+
+    runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? [])
+      .filter(account => account.isMain || account.id !== accountId);
+    forgetCodexAccountPause(runtimeConfig, accountId);
+    forgetCodexAccountPriority(runtimeConfig, accountId);
+    clearCodexAccountPin(runtimeConfig, accountId);
+    if (runtimeConfig.activeCodexAccountId === accountId) runtimeConfig.activeCodexAccountId = undefined;
+
+    if (previousPersistedConfig !== undefined) {
+      try {
+        // Persist first for durable configs. Destructive cleanup below must never run for a
+        // deletion that failed to commit. Transient configs intentionally skip this write.
+        saveConfigPreservingClaudeCode(runtimeConfig);
+      } catch (error) {
+        restoreRuntimeConfig(runtimeConfig, previousConfig);
+        try {
+          restorePersistedConfig(configPath, previousPersistedConfig);
+        } catch {
+          throw new CodexAccountDeleteRollbackError();
+        }
+        throw error;
+      }
+    }
+
+    try {
+      removeCodexAccountCredential(accountId);
+      purgeCodexAccountRuntimeState(accountId);
+      invalidateCodexWebSocketsForAccount(accountId);
+    } catch {
+      // Do not throw through the mutation coordinator after config.json committed: that would roll
+      // back only the SQLite generation transaction, not the already-atomic file replacement.
+      cleanupFailed = true;
+    }
+
+    return hadVisiblePickerBinding;
+  });
+
+  if (cleanupFailed) throw new CodexAccountDeleteCleanupError();
+  return pickerVisibilityChanged;
+}

package/src/codex/account-namespace-match.ts

@@ -0,0 +1,63 @@
+import { isValidCodexAccountId } from "./account-id";
+
+/** Config-only sentinel for the Codex Desktop account; outside the pool-account id grammar. */
+export const MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET = "@main";
+
+export const CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR =
+  "combo alias must not use a configured Codex account namespace";
+
+const CODEX_ACCOUNT_ID_NAMESPACE_COLLISION_ERROR =
+  "account id must not collide with a configured Codex account namespace";
+
+/** Provider ids are compared case-insensitively at namespace admission boundaries. */
+export function codexProviderNamespaceKey(value: string): string {
+  return value.toLowerCase();
+}
+
+export function hasCodexAccountNamespace(
+  namespaces: unknown,
+  namespace: string,
+): boolean {
+  return !!namespaces
+    && typeof namespaces === "object"
+    && !Array.isArray(namespaces)
+    && Object.hasOwn(namespaces, namespace);
+}
+
+export function codexAccountNamespaceProviderCollisionError(
+  namespaces: unknown,
+  providerName: string,
+): string | undefined {
+  const normalizedProvider = codexProviderNamespaceKey(providerName);
+  const collides = !!namespaces
+    && typeof namespaces === "object"
+    && !Array.isArray(namespaces)
+    && Object.keys(namespaces)
+      .some(namespace => codexProviderNamespaceKey(namespace) === normalizedProvider);
+  return collides
+    ? "provider name must not collide with a configured Codex account namespace"
+    : undefined;
+}
+
+export function codexAccountIdNamespaceCollisionError(
+  namespaces: unknown,
+  accountId: string,
+): string | undefined {
+  return hasCodexAccountNamespace(namespaces, accountId)
+    ? CODEX_ACCOUNT_ID_NAMESPACE_COLLISION_ERROR
+    : undefined;
+}
+
+export function codexAccountNamespaceForModel(
+  namespaces: unknown,
+  modelId: string,
+): string | undefined {
+  const slash = modelId.indexOf("/");
+  if (slash <= 0) return undefined;
+  const namespace = modelId.slice(0, slash);
+  return hasCodexAccountNamespace(namespaces, namespace) ? namespace : undefined;
+}
+
+export function isValidCodexAccountNamespaceTarget(accountId: unknown): accountId is string {
+  return accountId === MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET || isValidCodexAccountId(accountId);
+}

package/src/codex/account-namespaces.ts

@@ -0,0 +1,195 @@
+import type { CodexAccount, OcxConfig } from "../types";
+import { COMBO_NAMESPACE } from "../combos/types";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import {
+  POLICY_NAMESPACE,
+  routingProfileAliasNamespacePrefixes,
+} from "../routing/profile-namespace";
+import {
+  CODEX_ACCOUNT_LOG_LABEL_RE,
+  createCodexAccountLogLabel,
+  fallbackCodexAccountLogLabel,
+} from "./account-label";
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import {
+  codexAccountIdNamespaceCollisionError,
+  codexProviderNamespaceKey,
+  MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
+} from "./account-namespace-match";
+
+export { isValidCodexAccountNamespaceTarget } from "./account-namespace-match";
+
+const RESERVED_NAMESPACE_KEYS = new Set([
+  "__proto__",
+  "prototype",
+  "constructor",
+  COMBO_NAMESPACE,
+  OPENAI_CODEX_PROVIDER_ID,
+  POLICY_NAMESPACE,
+].map(codexProviderNamespaceKey));
+const PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS = 16;
+
+function comboAliasNamespaces(config: Pick<OcxConfig, "combos">): string[] {
+  return Object.values(config.combos ?? {}).flatMap((combo) => {
+    const alias = typeof combo?.alias === "string" ? combo.alias.trim() : "";
+    const slash = alias.indexOf("/");
+    return slash > 0 ? [alias.slice(0, slash)] : [];
+  });
+}
+
+function privateAccountSelectorCandidates(accountIds: Iterable<string>): Set<string> {
+  const candidates = new Set<string>();
+  for (const accountId of accountIds) {
+    candidates.add(accountId);
+    candidates.add(fallbackCodexAccountLogLabel(accountId));
+  }
+  return candidates;
+}
+
+function defaultPublicAccountSelector(
+  account: Pick<CodexAccount, "id" | "logLabel">,
+  allPrivateCandidates: ReadonlySet<string>,
+): string {
+  const privateCandidates = new Set(allPrivateCandidates);
+  privateCandidates.add(account.id);
+  privateCandidates.add(fallbackCodexAccountLogLabel(account.id));
+  if (CODEX_ACCOUNT_LOG_LABEL_RE.test(account.logLabel ?? "")
+    && !privateCandidates.has(account.logLabel!)) return account.logLabel!;
+
+  // Legacy or hand-edited rows may predate persisted random log labels. Allocate a fresh public
+  // selector rather than exposing the stable, id-derived fallback used only to redact old logs.
+  for (let attempt = 0; attempt < PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS; attempt += 1) {
+    const selector = createCodexAccountLogLabel(privateCandidates);
+    if (!privateCandidates.has(selector)) return selector;
+  }
+  throw new Error("Unable to allocate a unique Codex account selector");
+}
+
+function claimNamespace(requested: string, used: Set<string>): string {
+  let namespace = requested;
+  let suffix = 2;
+  while (used.has(namespace)) namespace = `${requested}-${suffix++}`;
+  used.add(namespace);
+  return namespace;
+}
+
+/** Collect every public namespace that a generated account selector must not claim. */
+function occupiedNamespaces(
+  config: Pick<OcxConfig, "combos" | "providers" | "routingProfiles">,
+): Set<string> {
+  return new Set([
+    ...Object.keys(config.providers).map(codexProviderNamespaceKey),
+    ...comboAliasNamespaces(config),
+    ...routingProfileAliasNamespacePrefixes(config),
+    ...RESERVED_NAMESPACE_KEYS,
+  ]);
+}
+
+/** Build an initial account-selector map without deriving public selectors from aliases or ids. */
+export function defaultCodexAccountNamespaces(
+  config: Pick<OcxConfig, "codexAccounts" | "combos" | "providers" | "routingProfiles">,
+): Record<string, string> {
+  const namespaces: Record<string, string> = {};
+  const used = occupiedNamespaces(config);
+  const accounts = config.codexAccounts ?? [];
+  const privateCandidates = privateAccountSelectorCandidates(
+    accounts
+      .filter(account => account.id !== MAIN_CODEX_ACCOUNT_ID)
+      .map(account => account.id),
+  );
+  for (const candidate of privateCandidates) used.add(candidate);
+
+  namespaces[claimNamespace("main", used)] = MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET;
+  for (const account of accounts) {
+    if (account.isMain || !isValidCodexAccountId(account.id)) continue;
+    const namespace = claimNamespace(defaultPublicAccountSelector(account, privateCandidates), used);
+    namespaces[namespace] = account.id;
+  }
+  return namespaces;
+}
+
+/**
+ * Initialize generated selectors only for an explicit opt-in with no existing bindings.
+ * A true result means the map was replaced and the caller must persist the updated config.
+ */
+export function initializeDefaultCodexAccountNamespaces(
+  config: Pick<
+    OcxConfig,
+    | "codexAccountPickerEnabled"
+    | "codexAccountNamespaces"
+    | "codexAccounts"
+    | "combos"
+    | "providers"
+    | "routingProfiles"
+  >,
+): boolean {
+  if (config.codexAccountPickerEnabled !== true
+    || Object.keys(config.codexAccountNamespaces ?? {}).length > 0) return false;
+
+  const namespaces = defaultCodexAccountNamespaces(config);
+  config.codexAccountNamespaces = namespaces;
+  return true;
+}
+
+/**
+ * Add one account to a generated map without renaming or replacing explicit existing entries.
+ * The account-creation layer must reject a new id that already equals an existing selector key.
+ * A true result means the map was mutated in place; callers must persist the updated config.
+ */
+export function appendDefaultCodexAccountNamespace(
+  config: Pick<
+    OcxConfig,
+    "codexAccountNamespaces" | "codexAccounts" | "combos" | "providers" | "routingProfiles"
+  >,
+  account: Pick<CodexAccount, "id" | "isMain" | "logLabel">,
+): boolean {
+  const namespaces = config.codexAccountNamespaces;
+  if (account.isMain
+    || !isValidCodexAccountId(account.id)
+    || !namespaces
+    || Object.keys(namespaces).length === 0
+    || codexAccountIdNamespaceCollisionError(namespaces, account.id)
+    || Object.values(namespaces).includes(account.id)) return false;
+
+  const used = occupiedNamespaces(config);
+  for (const namespace of Object.keys(namespaces)) used.add(namespace);
+  const privateCandidates = privateAccountSelectorCandidates([
+    ...(config.codexAccounts ?? [])
+      .filter(existing => existing.id !== MAIN_CODEX_ACCOUNT_ID)
+      .map(existing => existing.id),
+    ...Object.values(namespaces),
+    account.id,
+  ]);
+  for (const candidate of privateCandidates) used.add(candidate);
+  const namespace = claimNamespace(defaultPublicAccountSelector(account, privateCandidates), used);
+  namespaces[namespace] = account.id;
+  return true;
+}
+
+export function isMainCodexAccountTarget(accountId: string): boolean {
+  return accountId === MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET || accountId === MAIN_CODEX_ACCOUNT_ID;
+}
+
+function normalizeCodexAccountNamespaceTarget(accountId: string): string {
+  return isMainCodexAccountTarget(accountId)
+    ? MAIN_CODEX_ACCOUNT_ID
+    : accountId;
+}
+
+export function codexAccountNamespaceEntries(
+  config: Pick<OcxConfig, "codexAccountNamespaces">,
+): Array<[string, string]> {
+  return Object.entries(config.codexAccountNamespaces ?? {})
+    .map(([namespace, accountId]) => [namespace, normalizeCodexAccountNamespaceTarget(accountId)]);
+}
+
+/**
+ * Whether generated account-qualified rows are enabled for catalog discovery.
+ * A non-empty hand-written map predating the explicit override remains enabled.
+ */
+export function codexAccountPickerEnabled(
+  config: Pick<OcxConfig, "codexAccountNamespaces" | "codexAccountPickerEnabled">,
+): boolean {
+  return (config.codexAccountPickerEnabled === undefined || config.codexAccountPickerEnabled === true)
+    && Object.keys(config.codexAccountNamespaces ?? {}).length > 0;
+}

package/src/codex/account-pause.ts

@@ -0,0 +1,20 @@
+import type { OcxConfig } from "../types";
+
+/** Whether an account is administratively excluded from future pool selection. */
+export function isCodexAccountPaused(config: OcxConfig, accountId: string): boolean {
+  return config.pausedCodexAccountIds?.includes(accountId) ?? false;
+}
+
+/** Persist the account's pool eligibility without changing credentials or runtime health. */
+export function setCodexAccountPaused(config: OcxConfig, accountId: string, paused: boolean): void {
+  const pausedIds = new Set(config.pausedCodexAccountIds ?? []);
+  if (paused) pausedIds.add(accountId);
+  else pausedIds.delete(accountId);
+
+  if (pausedIds.size > 0) config.pausedCodexAccountIds = [...pausedIds];
+  else delete config.pausedCodexAccountIds;
+}
+
+export function forgetCodexAccountPause(config: OcxConfig, accountId: string): void {
+  setCodexAccountPaused(config, accountId, false);
+}

package/src/codex/account-priority.ts

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

package/src/codex/account-runtime-state.ts

@@ -0,0 +1,31 @@
+import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+
+const reauthAccounts = new Set<string>();
+let lastReconciledGeneration = 0;
+let liveAccountIds = new Set<string>();
+
+export function markAccountNeedsReauth(id: string, writerGeneration = captureConfigGeneration()): void {
+  if (writerGeneration < lastReconciledGeneration && !liveAccountIds.has(id)) return;
+  reauthAccounts.add(id);
+}
+
+export function reconcileCodexReauthState(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const id of reauthAccounts) {
+    if (context.codexAccountIds.has(id)) continue;
+    reauthAccounts.delete(id);
+    removed += 1;
+  }
+  liveAccountIds = new Set(context.codexAccountIds);
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function isAccountNeedsReauth(id: string): boolean {
+  return reauthAccounts.has(id);
+}
+
+export function clearAccountNeedsReauth(id: string): void {
+  reauthAccounts.delete(id);
+}