@coseung2/opencodex 2.8.0-cs.12 → 2.8.0-cs.14

package/src/codex/auth-context.ts

@@ -7,7 +7,8 @@ import {
   isCodexAccountGenerationLive,
 } from "./account-store";
 import { ConfigMutationLockError } from "../config";
-import { markAccountNeedsReauth } from "./account-runtime-state";
+import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
+import { isCodexAccountPaused } from "./account-pause";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
@@ -38,6 +39,8 @@ export type CodexAuthContext =
       generation: number;
       accessToken: string;
       chatgptAccountId: string;
+      /** Exact account selector: suppresses Pool rotation and failover. */
+      fixedAccount?: boolean;
       /**
        * Set when this request was admitted through an active quota cooldown as
        * the account's single probe. Must be echoed into the upstream outcome so
@@ -57,6 +60,8 @@ export type CodexAuthContext =
       writerGeneration: number;
       accessToken: string;
       chatgptAccountId: string;
+      /** Exact account selector: suppresses Pool rotation and failover. */
+      fixedAccount?: boolean;
       /** See `pool.probeLeaseId`. */
       probeLeaseId?: string;
       quotaScope?: CodexQuotaScope;
@@ -100,8 +105,8 @@ export class CodexAuthContextError extends Error {
 }
 
 export class CodexPoolAuthenticationError extends Error {
-  constructor() {
-    super("OpenAI account pool has no usable account credential");
+  constructor(message = "OpenAI account pool has no usable account credential") {
+    super(message);
     this.name = "CodexPoolAuthenticationError";
   }
 }
@@ -154,22 +159,31 @@ export function cooldownAccountLabel(accountId: string): string {
  * as HTTP. The bare "cooling down" string left users with no route but commenting out the
  * injected `openai_base_url` in config.toml.
  */
-export function cooldownErrorMessage(err: CodexAccountCooldownError): string {
+export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSelector?: string): string {
   const until = new Date(err.cooldownUntil).toISOString();
   const scope = err.quotaScope === "spark"
     ? "Spark quota"
     : err.quotaScope === "shared"
       ? "shared native quota"
       : null;
-  return `Selected Codex account (${cooldownAccountLabel(err.accountId)})${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
-    + ` (source: ${err.cooldownSource ?? "default"}).`
-    + ` Run 'ocx account list openai' to find the id, then`
-    + ` 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.`;
+  const selected = accountSelector
+    ? `Selected Codex account selector (${accountSelector})`
+    : `Selected Codex account (${cooldownAccountLabel(err.accountId)})`;
+  const recovery = accountSelector
+    ? " This request is pinned to that selector and will not switch accounts; choose another account-qualified model or retry later."
+    : " Run 'ocx account list openai' to find the id, then"
+      + " 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.";
+  return `${selected}${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
+    + ` (source: ${err.cooldownSource ?? "default"}).${recovery}`;
 }
 
 /** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
-export function cooldownErrorResponse(err: CodexAccountCooldownError, now = Date.now()): Response {
-  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err));
+export function cooldownErrorResponse(
+  err: CodexAccountCooldownError,
+  now = Date.now(),
+  accountSelector?: string,
+): Response {
+  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
   const headers = new Headers(res.headers);
   headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
   return new Response(res.body, { status: res.status, headers });
@@ -195,6 +209,8 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
 
 export interface ResolveCodexAuthContextOptions {
   excludeAccountId?: string;
+  /** Resolve exactly this account without consulting or mutating Pool selection. */
+  accountId?: string;
   /** Final native model selected for this request, used to select its quota group. */
   modelId?: string;
 }
@@ -206,14 +222,20 @@ export async function resolveCodexAuthContext(
   options: ResolveCodexAuthContextOptions = {},
 ): Promise<CodexAuthContext> {
   const writerGeneration = captureConfigGeneration();
-  if (mode === "direct") {
+  const fixedAccountId = options.accountId;
+  if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
+    throw new Error("Codex auth context cannot select and exclude an account simultaneously");
+  }
+  if (mode === "direct" && fixedAccountId === undefined) {
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     return { kind: "main", accountId: null };
   }
   reconcileMainCodexAccountRuntimeState();
   const threadId = headers.get("x-codex-parent-thread-id");
   const quotaScope = codexQuotaScopeForModel(options.modelId);
-  const resolution = options.excludeAccountId
+  const resolution = fixedAccountId !== undefined
+    ? { status: "selected" as const, accountId: fixedAccountId }
+    : options.excludeAccountId
     ? (() => {
         const accountId = pickAlternateCodexAccount(config, options.excludeAccountId!, Date.now(), quotaScope);
         return accountId
@@ -223,13 +245,28 @@ export async function resolveCodexAuthContext(
     : resolveCodexAccountForThreadDetailed(threadId, config, Date.now(), quotaScope);
   if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
   let accountId = resolution.status === "selected" ? resolution.accountId : null;
-  if (!accountId) throw new CodexPoolAuthenticationError();
+  if (!accountId) {
+    throw new CodexPoolAuthenticationError(
+      fixedAccountId !== undefined ? "Selected Codex account is unavailable" : undefined,
+    );
+  }
+  if (fixedAccountId !== undefined) {
+    if (isCodexAccountPaused(config, accountId)) {
+      throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+    }
+    if (isAccountNeedsReauth(accountId)) {
+      throw new CodexPoolAuthenticationError("Selected Codex account needs reauthentication");
+    }
+    if (!isCodexAccountUsable(config, accountId)) {
+      throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+    }
+  }
   // Lazy prime: if the selected account has no quota yet, the pool is likely
   // unprimed (dashboard never opened, or startup prime was blocked). Kick a
   // best-effort prime so the NEXT routing decision has real scores. This never
   // blocks the current request, and the helper's single-flight guard collapses
   // repeated triggers into one pass.
-  if (!getAccountQuota(accountId)) {
+  if (fixedAccountId === undefined && !getAccountQuota(accountId)) {
     import("./auth-api")
       .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
       .catch(() => {});
@@ -244,6 +281,9 @@ export async function resolveCodexAuthContext(
   let probeLeaseId: string | undefined;
   let probeQuotaScope: CodexQuotaScope | undefined;
   if (cooldownUntil) {
+    if (fixedAccountId !== undefined) {
+      throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
+    }
     probeQuotaScope = cooldown?.quotaScope;
     probeLeaseId = probeQuotaScope
       ? tryAcquireCodexQuotaScopeProbeLease(accountId, probeQuotaScope) ?? undefined
@@ -260,7 +300,9 @@ export async function resolveCodexAuthContext(
       // Nothing will reach upstream, so give the probe back instead of burning it.
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
-      throw new CodexPoolAuthenticationError();
+      throw new CodexPoolAuthenticationError(
+        fixedAccountId !== undefined ? "Selected Codex account is unavailable" : undefined,
+      );
     }
     return {
       kind: "main-pool",
@@ -268,6 +310,7 @@ export async function resolveCodexAuthContext(
       writerGeneration,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
@@ -283,6 +326,7 @@ export async function resolveCodexAuthContext(
       generation: token.generation,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
@@ -312,7 +356,8 @@ export function applyCodexAuthContextToProvider(
   ctx: CodexAuthContext,
   mode: CodexAccountMode | undefined,
 ): OcxRuntimeProviderConfig {
-  if (mode !== "pool" || (ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
+  if ((ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
+  if (mode !== "pool" && ctx.fixedAccount !== true) return provider;
   return {
     ...provider,
     _codexAccountOverride: {

package/src/codex/catalog/metadata.ts

@@ -35,14 +35,18 @@ import { filterSupportedNativeSlugs } from "./parsing";
 import type { RawEntry } from "./parsing";
 import { readCurrentCatalogOrCache, unique } from "./bundled";
 
+export const NATIVE_DAYBREAK_BLUE_MODEL = "gpt-daybreak-blue-latest";
+
 export const NATIVE_OPENAI_MODELS = [
   "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
   "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
+  NATIVE_DAYBREAK_BLUE_MODEL,
 ];
 
 export const DOCUMENTED_NATIVE_OPENAI_ADDITIONS = [
   "gpt-5.3-codex-spark",
   "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
+  NATIVE_DAYBREAK_BLUE_MODEL,
 ];
 
 export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
@@ -53,15 +57,18 @@ export function isUnsupportedOpenAiNativeSlug(slug: string): boolean {
   return /^(?:gpt|codex)-/.test(slug);
 }
 
-export const NATIVE_GPT56_CONTEXT_WINDOW = 372_000;
+/** Measured native family contract: 922k input plus up to 128k output. */
+export const NATIVE_GPT56_CONTEXT_WINDOW = 1_050_000;
+export const NATIVE_GPT56_MAX_INPUT_TOKENS = 922_000;
 
-export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number }> = {
+export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number; maxInputTokens?: number }> = {
   "gpt-5.5": { contextWindow: 272_000, maxContextWindow: 272_000 },
   "gpt-5.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },
   "gpt-5.3-codex-spark": { contextWindow: 100_000, maxContextWindow: 100_000 },
-  "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
-  "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
-  "gpt-5.6-luna": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
+  "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
+  "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
+  "gpt-5.6-luna": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
+  [NATIVE_DAYBREAK_BLUE_MODEL]: { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
 };
 
 export function nativeOpenAiContextWindow(slug: string): number | undefined {
@@ -71,6 +78,10 @@ export function nativeOpenAiContextWindow(slug: string): number | undefined {
       : undefined);
 }
 
+export function nativeOpenAiMaxInputTokens(slug: string): number | undefined {
+  return NATIVE_OPENAI_CONTEXT_OVERRIDES[slug]?.maxInputTokens;
+}
+
 export function nativeInputModalities(slug: string): string[] {
   const upstream = UPSTREAM_NATIVE_ENTRIES.get(slug);
   if (Array.isArray(upstream?.input_modalities) && upstream!.input_modalities!.length > 0) {
@@ -144,13 +155,24 @@ export function applyNativeVisibility(entries: RawEntry[], disabledNative: Set<s
   return entries;
 }
 
-export const UPSTREAM_NATIVE_ENTRIES: Map<string, RawEntry> = new Map(
-  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
-    .filter(m => typeof m.slug === "string"
-      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string)
-      && (m.slug as string).startsWith("gpt-5.6-"))
-    .map(m => [m.slug as string, m]),
-);
+export const UPSTREAM_NATIVE_ENTRIES: Map<string, RawEntry> = (() => {
+  const entries = new Map(
+    ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
+      .filter(m => typeof m.slug === "string"
+        && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string)
+        && (m.slug as string).startsWith("gpt-5.6-"))
+      .map(m => [m.slug as string, m] as const),
+  );
+  const sol = entries.get("gpt-5.6-sol");
+  if (sol) {
+    entries.set(NATIVE_DAYBREAK_BLUE_MODEL, {
+      ...JSON.parse(JSON.stringify(sol)) as RawEntry,
+      slug: NATIVE_DAYBREAK_BLUE_MODEL,
+      display_name: "GPT Daybreak Blue",
+    });
+  }
+  return entries;
+})();
 
 export function upstreamNativeEntry(slug: string): RawEntry | null {
   const entry = UPSTREAM_NATIVE_ENTRIES.get(slug);

package/src/codex/catalog/parsing.ts

@@ -243,13 +243,20 @@ export function isNativeOpenAiEntry(entry: RawEntry): boolean {
   return typeof entry.slug === "string" && !entry.slug.includes("/");
 }
 
+function nativeAutoCompactLimit(contextWindow: number, maxInputTokens?: number): number {
+  const ninetyPercent = Math.floor(contextWindow * 0.9);
+  return typeof maxInputTokens === "number" && maxInputTokens > 0
+    ? Math.min(ninetyPercent, maxInputTokens, contextWindow)
+    : ninetyPercent;
+}
+
 export function applyNativeOpenAiContextOverride(entry: RawEntry): void {
   if (!isNativeOpenAiEntry(entry)) return;
   const override = NATIVE_OPENAI_CONTEXT_OVERRIDES[entry.slug as string];
   if (!override) return;
   if (typeof override.contextWindow === "number") {
     entry.context_window = override.contextWindow;
-    entry.auto_compact_token_limit = Math.floor(override.contextWindow * 0.9);
+    entry.auto_compact_token_limit = nativeAutoCompactLimit(override.contextWindow, override.maxInputTokens);
   }
   if (typeof override.maxContextWindow === "number") {
     entry.max_context_window = override.maxContextWindow;

package/src/codex/catalog/provider-fetch.ts

@@ -58,7 +58,7 @@ import { createAdmissionGate, ResourceAdmissionError, type AdmissionMetrics } fr
 
 import { JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
-import { disabledNativeSlugs, hasComboTargets, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
+import { disabledNativeSlugs, hasComboTargets, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 
@@ -274,10 +274,15 @@ export function warnDroppedConfiguredIdsOnce(name: string, droppedConfiguredIds:
 }
 
 export function isGlm52ModelId(id: string): boolean {
-  const normalized = id.toLowerCase();
+  const normalized = id.trim().toLowerCase();
   return normalized === "glm-5.2" || normalized === "glm-5.2[1m]";
 }
 
+export function isGlm53ModelId(id: string): boolean {
+  const normalized = id.trim().toLowerCase();
+  return normalized === "glm-5.3" || normalized === "glm-5.3[1m]";
+}
+
 function plainRecord(value: unknown): Record<string, unknown> | undefined {
   return value !== null && typeof value === "object" && !Array.isArray(value)
     ? value as Record<string, unknown>
@@ -358,6 +363,17 @@ function modelInputModalities(
     value === "text" || value === "image" || value === "audio"
   ));
   if (explicit && explicit.length > 0) return explicit;
+  const architecture = plainRecord(item.architecture);
+  const architectureModality = typeof architecture?.modality === "string"
+    ? normalizedMetadataString(architecture.modality, 64)
+    : undefined;
+  if (architectureModality?.includes("->")) {
+    const [rawInput = ""] = architectureModality.split("->");
+    const inferred = rawInput
+      .split("+")
+      .filter(value => value === "text" || value === "image" || value === "audio");
+    if (inferred.length > 0) return [...new Set(inferred)];
+  }
   if (capabilityRecord?.vision === false) return ["text"];
   if (capabilityRecord?.vision === true || capabilities?.some(value => value === "vision" || value === "image-input")) {
     return ["text", "image"];
@@ -385,9 +401,11 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
     ? sanitizeCodexReasoningEfforts(listedReasoningEfforts)
     : typeof rawReasoningEfforts === "boolean"
       ? (rawReasoningEfforts
-        ? ((providerName === "neuralwatt" || providerName === "zai") && isGlm52ModelId(item.id)
-          ? ["low", "medium", "high", "xhigh", "max"]
-          : ["low", "medium", "high", "xhigh"])
+        ? ((providerName === "neuralwatt" || providerName === "zai") && isGlm53ModelId(item.id)
+          ? ["low", "high", "max"]
+          : (providerName === "neuralwatt" || providerName === "zai") && isGlm52ModelId(item.id)
+            ? ["low", "medium", "high", "xhigh", "max"]
+            : ["low", "medium", "high", "xhigh"])
         : [])
       : undefined;
   const capabilities = modelCapabilities(item);
@@ -756,7 +774,7 @@ async function gatherRoutedModelsUncached(
         id: slug,
         owned_by: "openai",
         contextWindow,
-        maxInputTokens: contextWindow,
+        maxInputTokens: nativeOpenAiMaxInputTokens(slug) ?? contextWindow,
         inputModalities: nativeInputModalities(slug),
         reasoningEfforts: nativeReasoningEfforts(slug),
         ...(nativeParallelToolCalls(slug) ? { parallelToolCalls: true } : {}),

package/src/codex/catalog.ts

@@ -2,7 +2,7 @@
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
 export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, readCatalog, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
-export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort } from "./catalog/metadata";
+export { NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT56_CONTEXT_WINDOW, NATIVE_GPT56_MAX_INPUT_TOKENS, NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";

package/src/codex/pool-rotation.ts

@@ -19,6 +19,10 @@ const MAX_STICKY_LIMIT = 100;
 const DEFAULT_STRATEGY: OcxAccountPoolRotationStrategy = "quota";
 const VALID_STRATEGIES = new Set<OcxAccountPoolRotationStrategy>(["quota", "round-robin", "fill-first"]);
 
+export const DEFAULT_ACCOUNT_PRIORITY = 0;
+export const MIN_ACCOUNT_PRIORITY = -100;
+export const MAX_ACCOUNT_PRIORITY = 100;
+
 /** Strict parse for management APIs — returns null instead of defaulting. */
 export function parseAccountPoolStrategy(raw: unknown): OcxAccountPoolRotationStrategy | null {
   if (typeof raw === "string" && VALID_STRATEGIES.has(raw as OcxAccountPoolRotationStrategy)) {
@@ -43,6 +47,49 @@ export function normalizeAccountPoolStickyLimit(raw: unknown): number {
   return parseAccountPoolStickyLimit(raw) ?? DEFAULT_STICKY_LIMIT;
 }
 
+export function parseAccountPriority(raw: unknown): number | null {
+  return typeof raw === "number"
+    && Number.isInteger(raw)
+    && raw >= MIN_ACCOUNT_PRIORITY
+    && raw <= MAX_ACCOUNT_PRIORITY
+    ? raw
+    : null;
+}
+
+export function normalizeAccountPriority(raw: unknown): number {
+  return parseAccountPriority(raw) ?? DEFAULT_ACCOUNT_PRIORITY;
+}
+
+/**
+ * Narrow eligible ids to the highest configured tier that still has quota headroom.
+ * Equal-priority pools and fully drained pools preserve the caller's exact list/order.
+ */
+export function selectPriorityTier(
+  ids: readonly string[],
+  priorityOf: (id: string) => number,
+  hasHeadroom: (id: string) => boolean,
+  pinnedId?: string,
+): readonly string[] {
+  if (ids.length <= 1) return ids;
+  const priorities = ids.map(priorityOf);
+  const firstPriority = priorities[0]!;
+  if (priorities.every(priority => priority === firstPriority)) return ids;
+
+  let ceiling = Number.POSITIVE_INFINITY;
+  if (pinnedId !== undefined) {
+    const pinnedIndex = ids.indexOf(pinnedId);
+    if (pinnedIndex >= 0 && hasHeadroom(pinnedId)) ceiling = priorities[pinnedIndex]!;
+  }
+
+  const tiers = [...new Set(priorities)].sort((a, b) => b - a);
+  for (const tier of tiers) {
+    if (tier > ceiling) continue;
+    const members = ids.filter((_, index) => priorities[index] === tier);
+    if (members.some(hasHeadroom)) return members;
+  }
+  return ids;
+}
+
 function getOrCreateState(poolKey: string): SelectionState {
   let state = selectionState.get(poolKey);
   if (!state) {
@@ -60,7 +107,7 @@ function cloneSelectionState(state: SelectionState): SelectionState {
   };
 }
 
-function smoothWeightedIndex(ids: string[], state: SelectionState): number {
+function smoothWeightedIndex(ids: readonly string[], state: SelectionState): number {
   let best = -1;
   let bestScore = Number.NEGATIVE_INFINITY;
   let total = 0;
@@ -87,7 +134,7 @@ function smoothWeightedIndex(ids: string[], state: SelectionState): number {
  * either the live map entry or a scratch/clone for dry-run peek.
  */
 function pickRoundRobinFromState(
-  eligibleIds: string[],
+  eligibleIds: readonly string[],
   stickyLimit: number,
   state: SelectionState,
   commitSticky: boolean,
@@ -118,7 +165,7 @@ function pickRoundRobinFromState(
 
 export function pickRoundRobinAccount(
   poolKey: string,
-  eligibleIds: string[],
+  eligibleIds: readonly string[],
   stickyLimit: number,
 ): string | null {
   return pickRoundRobinFromState(eligibleIds, stickyLimit, getOrCreateState(poolKey), true);
@@ -130,7 +177,7 @@ export function pickRoundRobinAccount(
  */
 export function peekRoundRobinAccount(
   poolKey: string,
-  eligibleIds: string[],
+  eligibleIds: readonly string[],
   stickyLimit: number,
 ): string | null {
   const live = selectionState.get(poolKey);