@iislee/opencodex 2.11.0 → 2.35.0

package/src/clients/effective-status.ts

@@ -18,10 +18,11 @@ import { probePi } from "./probes/pi";
 import { probeGrok } from "./probes/grok";
 import { probeOpencode } from "./probes/opencode";
 import { probeAgy } from "./probes/agy";
+import { probeCline } from "./probes/cline";
 import { readCcSwitchCurrentProfiles, type CcSwitchProfile } from "./probes/cc-switch";
 import { readPaseoProviderCommands, type PaseoProviderCommand } from "./probes/paseo";
 
-export type ClientId = "claude" | "codex" | "pi" | "grok" | "opencode" | "agy";
+export type ClientId = "claude" | "codex" | "pi" | "grok" | "opencode" | "agy" | "cline";
 
 export type ClientVerdict = "ocx" | "direct" | "mixed" | "missing" | "unknown";
 
@@ -70,6 +71,7 @@ export interface EffectiveStatusOpts {
     grok?: typeof probeGrok;
     opencode?: typeof probeOpencode;
     agy?: typeof probeAgy;
+    cline?: typeof probeCline;
     ccSwitch?: typeof readCcSwitchCurrentProfiles;
     paseo?: typeof readPaseoProviderCommands;
   };
@@ -82,6 +84,7 @@ const CLIENT_LABELS: Record<ClientId, string> = {
   grok: "Grok Build",
   opencode: "OpenCode",
   agy: "Antigravity (agy)",
+  cline: "Cline",
 };
 
 /** Map client id → CC Switch `app_type` column (when present). */
@@ -90,6 +93,7 @@ const CC_SWITCH_APP: Partial<Record<ClientId, string>> = {
   codex: "codex",
   grok: "grokbuild",
   opencode: "opencode",
+  cline: "cline",
 };
 
 /** Map client id → Paseo `agents.providers` key. */
@@ -99,6 +103,7 @@ const PASEO_PROVIDER: Partial<Record<ClientId, string>> = {
   agy: "antigravity-acp",
   claude: "claude",
   codex: "codex",
+  cline: "cline",
 };
 
 export interface ProxyTarget {
@@ -220,13 +225,14 @@ export async function readClientsEffectiveStatus(
   const grokFn = opts.probes?.grok ?? probeGrok;
   const opencodeFn = opts.probes?.opencode ?? probeOpencode;
   const agyFn = opts.probes?.agy ?? probeAgy;
+  const clineFn = opts.probes?.cline ?? probeCline;
   const ccSwitchFn = opts.probes?.ccSwitch ?? readCcSwitchCurrentProfiles;
   const paseoFn = opts.probes?.paseo ?? readPaseoProviderCommands;
 
   const emptyProfiles: CcSwitchProfile[] = [];
   const emptyPaseo: PaseoProviderCommand[] = [];
 
-  const [ccProfiles, paseoCommands, claude, codex, pi, grok, opencode, agy] = await Promise.all([
+  const [ccProfiles, paseoCommands, claude, codex, pi, grok, opencode, agy, cline] = await Promise.all([
     safeProbeAsync("cc-switch", () => Promise.resolve(ccSwitchFn({ home })), emptyProfiles),
     safeProbeAsync("paseo", () => Promise.resolve(paseoFn({ home })), emptyPaseo),
     safeProbeAsync("claude", () => Promise.resolve(claudeFn({ home })), {
@@ -247,6 +253,9 @@ export async function readClientsEffectiveStatus(
     safeProbeAsync("agy", () => Promise.resolve(agyFn({ home })), {
       present: false, baseUrl: null, model: null, configPaths: [] as string[], notes: ["probe failed"], binary: null,
     }),
+    safeProbeAsync("cline", () => Promise.resolve(clineFn({ home })), {
+      present: false, baseUrl: null, model: null, configPaths: [] as string[], notes: ["probe failed"], binary: null,
+    }),
   ]);
 
   const clients: ClientEffectiveStatus[] = [];
@@ -372,6 +381,25 @@ export async function readClientsEffectiveStatus(
     });
   }
 
+  // Cline
+  {
+    const raw = cline;
+    const { verdict, viaOcx } = verdictFromBaseUrl(raw.baseUrl, proxy, { present: raw.present });
+    clients.push({
+      id: "cline",
+      label: CLIENT_LABELS.cline,
+      present: raw.present,
+      viaOcx,
+      verdict: raw.present ? (raw.baseUrl ? verdict : "unknown") : "missing",
+      baseUrl: raw.baseUrl,
+      model: raw.model,
+      configPaths: raw.configPaths,
+      launcher: paseoLauncher("cline", paseoCommands) ?? (raw.binary ? "cline" : null),
+      switcher: switcherFor("cline", ccProfiles),
+      notes: raw.notes,
+    });
+  }
+
   return {
     generatedAt: Date.now(),
     proxy: {

package/src/clients/probes/cline.ts

@@ -0,0 +1,81 @@
+/**
+ * Cline effective-status probe.
+ * Reads providers.json and checks for opencodex / openai-compatible configuration.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { clineConfigPath, clineHomeDir } from "../config-export";
+
+export interface ClineProbeResult {
+  present: boolean;
+  baseUrl: string | null;
+  model: string | null;
+  configPaths: string[];
+  notes: string[];
+  binary: string | null;
+}
+
+function resolveBinary(name: string): string | null {
+  try {
+    const which = (globalThis as { Bun?: { which?: (cmd: string) => string | null } }).Bun?.which;
+    if (typeof which === "function") {
+      return which(name) ?? null;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function probeCline(opts: { home: string; env?: NodeJS.ProcessEnv } = { home: "" }): ClineProbeResult {
+  const notes: string[] = [];
+  const binary = resolveBinary("cline");
+  const configPath = clineConfigPath(opts.env, opts.home);
+  const homeDir = clineHomeDir(opts.env, opts.home);
+  const exists = existsSync(configPath);
+  const dirExists = existsSync(homeDir);
+  const present = exists || dirExists || Boolean(binary);
+
+  if (!exists) {
+    if (present) {
+      notes.push("Cline installation detected, but providers.json is not configured yet.");
+    }
+    return {
+      present,
+      baseUrl: null,
+      model: null,
+      configPaths: existsSync(homeDir) ? [homeDir] : [configPath],
+      notes,
+      binary,
+    };
+  }
+
+  let baseUrl: string | null = null;
+  let model: string | null = null;
+
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      lastUsedProvider?: string;
+      providers?: Record<string, { settings?: { baseUrl?: string; model?: string; provider?: string } }>;
+    };
+    const providers = parsed?.providers ?? {};
+    const ocxProvider = providers.opencodex ?? providers["openai-compatible"];
+    if (ocxProvider?.settings?.baseUrl) {
+      baseUrl = ocxProvider.settings.baseUrl;
+      model = ocxProvider.settings.model ?? null;
+    } else if (parsed?.lastUsedProvider && providers[parsed.lastUsedProvider]?.settings?.baseUrl) {
+      const active = providers[parsed.lastUsedProvider]!;
+      baseUrl = active.settings?.baseUrl ?? null;
+      model = active.settings?.model ?? null;
+    }
+  } catch (error) {
+    notes.push(`Could not read providers.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  return {
+    present: true,
+    baseUrl,
+    model,
+    configPaths: [configPath],
+    notes,
+    binary,
+  };
+}

package/src/codex/account-label.ts

@@ -1,8 +1,31 @@
 import { createHash, randomBytes } from "node:crypto";
-import type { CodexAccount } from "../types";
+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}$/;
 
+/**
+ * Account log labels come in two families (#2699):
+ *
+ * - `p<hex6>` (plus the literal `main`) — a Codex pool account.
+ * - `o<hex6>` — a non-Codex OAuth provider account (xai, cursor, and siblings).
+ *
+ * Both are sha256-derived digests, never an email and never a raw provider account id. That is
+ * a privacy requirement, not a formatting preference: these labels are written to the usage log
+ * and served over the management API.
+ *
+ * hex6 is 16.7M values, so two accounts CAN collide and merge into one reported row. That is a
+ * reporting inaccuracy at operator scale, not a correctness or privacy failure, and it is the
+ * accepted cost of keeping the existing `p` format byte-compatible.
+ */
+export const OAUTH_ACCOUNT_LOG_LABEL_RE = /^o[a-f0-9]{6}$/;
+export const ACCOUNT_LOG_LABEL_RE = /^(?:main|[po][a-f0-9]{6})$/;
+
+export function oauthAccountLogLabel(accountId: string, provider = ""): string {
+  return `o${createHash("sha256").update(`${provider}\0${accountId}`).digest("hex").slice(0, 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++) {
@@ -22,6 +45,17 @@ export function codexAccountLogLabel(account: CodexAccount): string {
     : 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[],

package/src/codex/account-lifecycle.ts

@@ -1,3 +1,10 @@
+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";
@@ -5,18 +12,43 @@ import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { clearAccountQuota } from "./quota";
 import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
-import { clearMainAccountInfoCache } from "./main-account-cache";
+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();
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    clearMainAccountInfoCache();
+    clearMainAccountCredentialPresence();
+  }
+}
+
+function purgeMainCodexAccountRuntimeState(): void {
+  purgeCodexAccountRuntimeState(MAIN_CODEX_ACCOUNT_ID);
+  setMainAccountPlan(null);
+  invalidateCodexWebSocketsForAccount(MAIN_CODEX_ACCOUNT_ID);
 }
 
 /**
@@ -34,22 +66,107 @@ export function reconcileMainCodexAccountRuntimeState(): boolean {
   observedMainChatgptAccountId = currentAccountId;
   if (previousAccountId === undefined || previousAccountId === currentAccountId) return false;
 
-  purgeCodexAccountRuntimeState(MAIN_CODEX_ACCOUNT_ID);
-  setMainAccountPlan(null);
-  invalidateCodexWebSocketsForAccount(MAIN_CODEX_ACCOUNT_ID);
+  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);
 }
 
-export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string): void {
-  removeCodexAccountCredential(accountId);
-  runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? [])
-    .filter(account => account.isMain || account.id !== accountId);
-  forgetCodexAccountPause(runtimeConfig, accountId);
-  if (runtimeConfig.activeCodexAccountId === accountId) runtimeConfig.activeCodexAccountId = undefined;
-  purgeCodexAccountRuntimeState(accountId);
-  invalidateCodexWebSocketsForAccount(accountId);
+/**
+ * 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-namespaces.ts

@@ -1,6 +1,10 @@
 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,
@@ -21,6 +25,7 @@ const RESERVED_NAMESPACE_KEYS = new Set([
   "constructor",
   COMBO_NAMESPACE,
   OPENAI_CODEX_PROVIDER_ID,
+  POLICY_NAMESPACE,
 ].map(codexProviderNamespaceKey));
 const PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS = 16;
 
@@ -68,17 +73,21 @@ function claimNamespace(requested: string, used: Set<string>): string {
   return namespace;
 }
 
-function occupiedNamespaces(config: Pick<OcxConfig, "combos" | "providers">): Set<string> {
+/** 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">,
+  config: Pick<OcxConfig, "codexAccounts" | "combos" | "providers" | "routingProfiles">,
 ): Record<string, string> {
   const namespaces: Record<string, string> = {};
   const used = occupiedNamespaces(config);
@@ -99,13 +108,39 @@ export function defaultCodexAccountNamespaces(
   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">,
+  config: Pick<
+    OcxConfig,
+    "codexAccountNamespaces" | "codexAccounts" | "combos" | "providers" | "routingProfiles"
+  >,
   account: Pick<CodexAccount, "id" | "isMain" | "logLabel">,
 ): boolean {
   const namespaces = config.codexAccountNamespaces;
@@ -147,3 +182,14 @@ export function codexAccountNamespaceEntries(
   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

@@ -1,4 +1,5 @@
 import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
 
 /** Whether an account is administratively excluded from future pool selection. */
 export function isCodexAccountPaused(config: OcxConfig, accountId: string): boolean {
@@ -12,7 +13,7 @@ export function setCodexAccountPaused(config: OcxConfig, accountId: string, paus
   else pausedIds.delete(accountId);
 
   if (pausedIds.size > 0) config.pausedCodexAccountIds = [...pausedIds];
-  else delete config.pausedCodexAccountIds;
+  else deleteConfigTopLevelKey(config, "pausedCodexAccountIds");
 }
 
 export function forgetCodexAccountPause(config: OcxConfig, accountId: string): void {

package/src/codex/account-priority.ts

@@ -0,0 +1,84 @@
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { DEFAULT_ACCOUNT_PRIORITY, normalizeAccountPriority } from "./pool-rotation";
+import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
+
+/**
+ * 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 deleteConfigTopLevelKey(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) {
+    deleteConfigTopLevelKey(config, "activeCodexAccountPinned");
+  }
+}

package/src/codex/account-store.ts

@@ -386,6 +386,19 @@ function findFreshCredentialForGrant(
   return null;
 }
 
+async function notePlanFromRefreshedAccessToken(
+  id: string,
+  accessToken: string,
+  generation: number,
+): Promise<void> {
+  try {
+    const { noteCodexAccountAccessToken } = await import("./plan-from-token");
+    noteCodexAccountAccessToken(id, accessToken, generation);
+  } catch {
+    // Derived plan metadata must not fail credential refresh.
+  }
+}
+
 export async function getValidCodexToken(id: string): Promise<CodexTokenResult> {
   const record = readCodexAccountRecord(id);
   const cred = record?.deletedAt == null ? record?.credential : undefined;
@@ -415,10 +428,12 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
         if (!saveCodexAccountCredentialIfGeneration(id, current.generation, refreshed.credential)) {
           throw new CodexCredentialGenerationConflictError();
         }
+        const generation = current.generation + 1;
+        await notePlanFromRefreshedAccessToken(id, refreshed.credential.accessToken, generation);
         return {
           accessToken: refreshed.credential.accessToken,
           chatgptAccountId: refreshed.credential.chatgptAccountId,
-          generation: current.generation + 1,
+          generation,
         };
       }
       return getValidCodexToken(id);
@@ -491,11 +506,22 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
       throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`);
     }
     const data = (await res.json()) as { access_token: string; refresh_token?: string; expires_in: number };
+    // Guard against a missing/non-finite/negative expires_in (malformed upstream
+    // response): a NaN expiry would never compare as expired, and a negative
+    // duration would stamp an already-past expiry — both block refresh semantics.
+    const expiresIn =
+      typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
+        ? data.expires_in
+        : 3600;
+    // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
+    // Number.isFinite but overflows to Infinity once multiplied by 1000.
+    const expiresAt = Date.now() + expiresIn * 1000;
+    const safeExpiresAt = Number.isFinite(expiresAt) ? expiresAt : Date.now() + 3600 * 1000;
 
     const updated: CodexAccountCredentials = {
       accessToken: data.access_token,
       refreshToken: data.refresh_token ?? lockedCred.refreshToken,
-      expiresAt: Date.now() + data.expires_in * 1000,
+      expiresAt: safeExpiresAt,
       chatgptAccountId: lockedCred.chatgptAccountId,
     };
     if (!saveCodexAccountCredentialIfGeneration(id, startGeneration, updated)) {
@@ -509,6 +535,7 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
   flight = { promise: refreshPromise, startedAt: Date.now(), abort };
   refreshLocks.set(refreshGrantFingerprint, flight);
   const result = await refreshPromise;
+  await notePlanFromRefreshedAccessToken(id, result.accessToken, result.generation);
   return {
     accessToken: result.accessToken,
     chatgptAccountId: result.chatgptAccountId,