feat(account-pool): show what the usage threshold means per strategy

gui/src/codex-quota-utils.ts

@@ -1,3 +1,5 @@
+import { CODEX_EXHAUSTED_USAGE_PERCENT, TERMINAL_SHORT_WINDOW_FRESHNESS_MS } from "../../src/codex/quota-types";
+
 export interface AccountQuota {
   weeklyPercent?: number;
   fiveHourPercent?: number;
@@ -7,6 +9,8 @@ export interface AccountQuota {
   weeklyResetAt?: number;
   fiveHourResetAt?: number;
   shortResetAt?: number;
+  /** Local observation time for the short-window percentage. */
+  shortObservedAt?: number;
   shortWindowSeconds?: number;
   monthlyResetAt?: number;
   customWindows?: { label: string; percent: number; resetAt?: number }[];
@@ -53,3 +57,44 @@ export function normalizeQuotaForPlan(quota: AccountQuota | null, plan: string |
     updatedAt: normalized.updatedAt,
   };
 }
+
+/**
+ * Compute the governing Codex usage score matching the server's auto-switch threshold evaluation.
+ *
+ * Evaluates governing quota windows based on the account's plan:
+ * - For 30-day only plans (e.g. Free/Go), only the monthly window governs.
+ * - For standard plans, weekly and monthly windows govern.
+ * - A known five-hour / short window refines a known governing long-window score.
+ * - If no long window has been observed, an active terminal short burst (at 100%) acts as exhausted (100).
+ * - Unknown or unprimed quota returns `null` so callers do not spuriously trigger threshold actions.
+ */
+export function computeCodexUsageScore(
+  quota: AccountQuota | null | undefined,
+  plan?: string | null,
+  now: number = Date.now(),
+): number | null {
+  if (!quota) return null;
+  const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+  const shortPercent = finite(quota.fiveHourPercent)
+    ? quota.fiveHourPercent
+    : (finite(quota.shortPercent) ? quota.shortPercent : undefined);
+  const longWindows = isThirtyDayOnlyPlan(plan)
+    ? [quota.monthlyPercent]
+    : [quota.weeklyPercent, quota.monthlyPercent];
+  const knownLong = longWindows.filter(finite);
+  if (knownLong.length === 0) {
+    const shortReset = quota.fiveHourResetAt ?? quota.shortResetAt;
+    const shortObservationAge = typeof quota.shortObservedAt === "number"
+      ? now - quota.shortObservedAt
+      : undefined;
+    const isExhausted = finite(shortPercent) && shortPercent >= CODEX_EXHAUSTED_USAGE_PERCENT && (
+      (typeof shortReset === "number" && shortReset > now) ||
+      (typeof shortObservationAge === "number"
+        && shortObservationAge >= 0
+        && shortObservationAge <= TERMINAL_SHORT_WINDOW_FRESHNESS_MS)
+    );
+    return isExhausted ? 100 : null;
+  }
+  const values = finite(shortPercent) ? [...knownLong, shortPercent] : knownLong;
+  return values.length ? Math.max(...values) : null;
+}

gui/src/components/AccountPoolStrategyControls.tsx

@@ -24,6 +24,7 @@ const STRATEGY_HINT_KEYS = {
 export interface AccountPoolStrategyControlsProps {
   strategy: AccountPoolStrategy;
   codex?: boolean;
+  threshold?: number;
   stickyDraft: string;
   disabled?: boolean;
   strategySelectId?: string;
@@ -45,6 +46,7 @@ export interface AccountPoolStrategyControlsProps {
 export default function AccountPoolStrategyControls({
   strategy,
   codex = false,
+  threshold,
   stickyDraft,
   disabled = false,
   strategySelectId = "account-pool-strategy",
@@ -59,6 +61,23 @@ export default function AccountPoolStrategyControls({
     label: t(STRATEGY_LABEL_KEYS[value]),
   }));
 
+  const thresholdSummary = (() => {
+    if (threshold === undefined) return null;
+    if (strategy === "round-robin") {
+      return t("accountPool.thresholdNotUsed");
+    }
+    if (threshold > 0) {
+      if (strategy === "fill-first") {
+        return t("accountPool.drainAtThreshold", { threshold: String(threshold) });
+      }
+      if (strategy === "reset-first") {
+        return t("accountPool.resetBelowThreshold", { threshold: String(threshold) });
+      }
+      return t("accountPool.switchAtThreshold", { threshold: String(threshold) });
+    }
+    return t("accountPool.proactiveSwitchingOff");
+  })();
+
   return (
     <div className="account-pool-strategy-controls">
       {/*
@@ -86,6 +105,11 @@ export default function AccountPoolStrategyControls({
             label={t("accountPool.strategy")}
             onChange={(next) => onStrategyChange(next as AccountPoolStrategy)}
           />
+          {thresholdSummary && (
+            <span className="badge badge-muted account-pool-threshold-badge" data-testid="account-pool-threshold-summary">
+              {thresholdSummary}
+            </span>
+          )}
         </div>
       </div>
       {strategy === "round-robin" && (

gui/src/components/CodexAccountPool.tsx

@@ -546,6 +546,7 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
         subscribeLoadObserver={controller.subscribeLoadObserver}
         readLastActive={controller.readLastActive}
         onStrategyResolved={setPoolStrategy}
+        threshold={autoSwitch.threshold}
       />
 
       <CodexAuthAdvancedSettings
@@ -599,6 +600,7 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
           accountModeState={accountModeState}
           switchingId={switchingId}
           orderBusy={priorityUpdatingId !== null}
+          threshold={poolStrategy && poolStrategy !== "round-robin" ? autoSwitchThreshold : undefined}
           onCancel={() => setConfirm(null)}
           onConfirm={() => { void setActive(confirm.id === "__main__" ? "__main__" : confirm.id); }}
         />

gui/src/components/CodexPoolStrategySetting.tsx

@@ -13,16 +13,22 @@ import {
 import AccountPoolStrategyControls from "./AccountPoolStrategyControls";
 import type { CodexAccountLoadObserver } from "../hooks/useCodexAccountPool";
 
+/**
+ * Extract normalized strategy, sticky limit, and optional autoSwitchThreshold from an active-response payload.
+ */
 function strategyFieldsFromActive(value: unknown): {
   strategy: AccountPoolStrategy;
   stickyLimit: number;
+  threshold?: number;
 } | null {
   if (!value || typeof value !== "object") return null;
   const row = value as Record<string, unknown>;
-  if (!("accountPoolStrategy" in row) && !("accountPoolStickyLimit" in row)) return null;
+  if (!("accountPoolStrategy" in row) && !("accountPoolStickyLimit" in row) && !("autoSwitchThreshold" in row)) return null;
+  const threshold = typeof row.autoSwitchThreshold === "number" ? row.autoSwitchThreshold : undefined;
   return {
     strategy: normalizeAccountPoolStrategy(row.accountPoolStrategy),
     stickyLimit: normalizeAccountPoolStickyLimit(row.accountPoolStickyLimit),
+    threshold,
   };
 }
 
@@ -36,17 +42,20 @@ export default function CodexPoolStrategySetting({
   subscribeLoadObserver,
   readLastActive,
   onStrategyResolved,
+  threshold: propThreshold,
 }: {
   apiBase: string;
   subscribeLoadObserver?: (observer: CodexAccountLoadObserver) => () => void;
   readLastActive?: () => unknown;
   onStrategyResolved?: (strategy: AccountPoolStrategy) => void;
+  threshold?: number;
 }) {
   const t = useT();
   // Seed defaults immediately — never gate the control chrome on a network round-trip.
   const [strategy, setStrategy] = useState<AccountPoolStrategy>(DEFAULT_ACCOUNT_POOL_STRATEGY);
   const [stickyLimit, setStickyLimit] = useState(DEFAULT_ACCOUNT_POOL_STICKY_LIMIT);
   const [stickyDraft, setStickyDraft] = useState(String(DEFAULT_ACCOUNT_POOL_STICKY_LIMIT));
+  const [serverThreshold, setServerThreshold] = useState<number | undefined>(undefined);
   const [hydrated, setHydrated] = useState(false);
   const hydratedRef = useRef(false);
   const [saving, setSaving] = useState(false);
@@ -60,9 +69,13 @@ export default function CodexPoolStrategySetting({
   const applyServer = useCallback((json: {
     accountPoolStrategy?: unknown;
     accountPoolStickyLimit?: unknown;
+    autoSwitchThreshold?: unknown;
   }) => {
     const nextStrategy = normalizeAccountPoolStrategy(json.accountPoolStrategy);
     const nextSticky = normalizeAccountPoolStickyLimit(json.accountPoolStickyLimit);
+    if (typeof json.autoSwitchThreshold === "number") {
+      setServerThreshold(json.autoSwitchThreshold);
+    }
     setStrategy(nextStrategy);
     onStrategyResolved?.(nextStrategy);
     setStickyLimit(nextSticky);
@@ -79,6 +92,7 @@ export default function CodexPoolStrategySetting({
     applyServer({
       accountPoolStrategy: fields.strategy,
       accountPoolStickyLimit: fields.stickyLimit,
+      autoSwitchThreshold: fields.threshold,
     });
   }, [applyServer]);
 
@@ -89,6 +103,7 @@ export default function CodexPoolStrategySetting({
       const payload = await res.json() as {
         accountPoolStrategy?: unknown;
         accountPoolStickyLimit?: unknown;
+        autoSwitchThreshold?: unknown;
       };
       // A save started while this GET was in flight — retry once after it settles.
       if (savingRef.current) {
@@ -215,6 +230,7 @@ export default function CodexPoolStrategySetting({
         <AccountPoolStrategyControls
           codex
           strategy={strategy}
+          threshold={propThreshold !== undefined ? propThreshold : serverThreshold}
           stickyDraft={stickyDraft}
           disabled={controlsDisabled}
           strategySelectId="codex-pool-strategy"

gui/src/components/codex-account-switch-modal.tsx

@@ -3,13 +3,19 @@ import { useT } from "../i18n/shared";
 import { IconAlert } from "../icons";
 import type { CodexAccountEntry } from "./codex-account-pool-types";
 import type { CodexAccountModeState } from "../codex-multi-state";
+import { computeCodexUsageScore } from "../codex-quota-utils";
 
+/**
+ * Modal dialog confirming manual switch to a specific Codex pool account.
+ * Displays a warning when the target account meets or exceeds the auto-switch threshold.
+ */
 export function CodexAccountSwitchModal({
   confirm,
   mainEmail,
   accountModeState,
   switchingId,
   orderBusy = false,
+  threshold,
   onCancel,
   onConfirm,
 }: {
@@ -23,6 +29,7 @@ export function CodexAccountSwitchModal({
    * the button has to be unavailable rather than silently ineffective.
    */
   orderBusy?: boolean;
+  threshold?: number;
   onCancel: () => void;
   onConfirm: () => void;
 }) {
@@ -39,6 +46,9 @@ export function CodexAccountSwitchModal({
     onCancel();
   }, [onCancel]);
 
+  const usageScore = computeCodexUsageScore(confirm.quota, confirm.plan);
+  const exceedsThreshold = threshold !== undefined && threshold > 0 && usageScore !== null && usageScore >= threshold;
+
   return (
     <dialog
       ref={dialogRef}
@@ -64,6 +74,11 @@ export function CodexAccountSwitchModal({
         {confirm.id !== "__main__" && (
           <div className="notice-warn"><IconAlert width={14} /> {t("codexAuth.cacheWarning")}</div>
         )}
+        {exceedsThreshold && (
+          <div className="notice-warn" data-testid="codex-switch-threshold-warning">
+            <IconAlert width={14} /> {t("codexAuth.switchExceedsThresholdWarning", { threshold })}
+          </div>
+        )}
         <div className="modal-actions">
           <button type="button" className="btn btn-ghost" onClick={onCancel}>{t("codexAuth.cancel")}</button>
           <button type="button" className="btn btn-primary" disabled={Boolean(switchingId) || orderBusy} onClick={onConfirm}>

gui/src/i18n/de.ts

@@ -1397,6 +1397,7 @@ export const de: Record<TKey, string> = {
   "codexAuth.switchTitle": "Aktives Konto wechseln?",
   "codexAuth.switchDesc": "Wird sofort wirksam. Bereits laufende Anfragen behalten ihr Konto; alles andere wechselt zu diesem Konto, wobei Konten mit derselben Auswahlreihenfolge sich weiterhin abwechseln.",
   "codexAuth.cacheWarning": "Prompt-Cache wird beim Kontowechsel zurückgesetzt. Neue Sitzung startet mit leerem Cache.",
+  "codexAuth.switchExceedsThresholdWarning": "Dieses Konto hat die Wechselschwelle ({threshold}%) erreicht oder überschritten. Die Fixierung wird freigegeben, wenn kein Kontingent-Puffer verfügbar ist.",
   "codexAuth.setAsNext": "Dieses Konto als Nächstes verwenden",
   "codexAuth.cancel": "Abbrechen",
   "codexAuth.switchBack": "Zurück zum Hauptkonto?",
@@ -1468,6 +1469,11 @@ export const de: Record<TKey, string> = {
   "accountPool.stickyLimitInvalid": "Gib eine ganze Zahl von 1 bis 100 ein",
   "accountPool.strategyLoadFailed": "Rotationsstrategie konnte nicht geladen werden.",
   "accountPool.strategyUpdateFailed": "Rotationsstrategie konnte nicht gespeichert werden.",
+  "accountPool.switchAtThreshold": "Wechsel bei {threshold}%",
+  "accountPool.drainAtThreshold": "Entleeren bei {threshold}%",
+  "accountPool.resetBelowThreshold": "nächster Reset unter {threshold}%",
+  "accountPool.thresholdNotUsed": "Schwelle nicht verwendet",
+  "accountPool.proactiveSwitchingOff": "Proaktiver Wechsel aus",
 
   "accountPool.quotaWindow": "Kontingentfenster",
   "accountPool.quotaWindowDesc": "Welcher zwischengespeicherte Nutzungsbalken die kontingentbasierte Auswahl neuer Sitzungen, Fill-first-Schwellenprüfungen und geeignete 429-Ersatzkonten steuert.",

gui/src/i18n/en.ts

@@ -1985,6 +1985,7 @@ export const en = {
   "codexAuth.switchTitle": "Switch active account?",
   "codexAuth.switchDesc": "Takes effect immediately. Existing account-affine threads and requests already in flight keep their captured account; new or unbound requests use the selected account's order tier, and accounts at the same selection order still take turns.",
   "codexAuth.cacheWarning": "Prompt cache resets on account switch. New session starts with empty cache.",
+  "codexAuth.switchExceedsThresholdWarning": "This account's usage meets or exceeds the switch threshold ({threshold}%). The pinned selection will be released if no quota headroom is available.",
   "codexAuth.setAsNext": "Use this account next",
   "codexAuth.cancel": "Cancel",
   "codexAuth.switchBack": "Switch back to Main?",
@@ -2056,6 +2057,11 @@ export const en = {
   "accountPool.stickyLimitInvalid": "Enter a whole number from 1 to 100",
   "accountPool.strategyLoadFailed": "Rotation strategy could not be loaded.",
   "accountPool.strategyUpdateFailed": "Rotation strategy could not be saved.",
+  "accountPool.switchAtThreshold": "switch at {threshold}%",
+  "accountPool.drainAtThreshold": "drain at {threshold}%",
+  "accountPool.resetBelowThreshold": "nearest reset below {threshold}%",
+  "accountPool.thresholdNotUsed": "threshold not used",
+  "accountPool.proactiveSwitchingOff": "proactive switching off",
 
   // The three window labels double as the {window} name inlined into
   // anthropicPool.enabledDesc, so each locale owns its own inline casing instead of the

gui/src/i18n/fr.ts

@@ -1917,6 +1917,7 @@ export const fr: Record<TKey, string> = {
   "codexAuth.switchTitle": "Changer de compte actif ?",
   "codexAuth.switchDesc": "Prend effet immédiatement. Les fils liés à un compte et les requêtes déjà en cours conservent le compte capturé ; les requêtes nouvelles ou non liées utilisent le niveau d’ordre du compte sélectionné, et les comptes de même ordre continuent d’alterner.",
   "codexAuth.cacheWarning": "Le cache des prompts est réinitialisé lors d’un changement de compte. La nouvelle session démarre avec un cache vide.",
+  "codexAuth.switchExceedsThresholdWarning": "Ce compte a atteint ou dépassé le seuil de basculement ({threshold} %). La sélection épinglée sera libérée si la marge de quota est insuffisante.",
   "codexAuth.setAsNext": "Utiliser ensuite ce compte",
   "codexAuth.cancel": "Annuler",
   "codexAuth.switchBack": "Revenir au compte principal ?",
@@ -1986,6 +1987,11 @@ export const fr: Record<TKey, string> = {
   "accountPool.stickyLimitInvalid": "Saisissez un nombre entier compris entre 1 et 100",
   "accountPool.strategyLoadFailed": "Impossible de charger la stratégie de rotation.",
   "accountPool.strategyUpdateFailed": "Impossible d’enregistrer la stratégie de rotation.",
+  "accountPool.switchAtThreshold": "bascule à {threshold} %",
+  "accountPool.drainAtThreshold": "épuisement à {threshold} %",
+  "accountPool.resetBelowThreshold": "prochaine réinitialisation sous {threshold} %",
+  "accountPool.thresholdNotUsed": "seuil non utilisé",
+  "accountPool.proactiveSwitchingOff": "bascule proactive désactivée",
   "accountPool.quotaWindow": "Fenêtre de quota",
   "accountPool.quotaWindowDesc": "Barre d’utilisation en cache qui régit la sélection des nouvelles sessions par quota, les seuils de remplissage prioritaire et les remplacements 429 admissibles.",
   "accountPool.quotaWindowFiveHour": "Barre de 5 heures",

gui/src/i18n/ja.ts

@@ -1842,6 +1842,7 @@ export const ja: Record<TKey, string> = {
   "codexAuth.switchTitle": "アクティブアカウントを切り替えますか?",
   "codexAuth.switchDesc": "すぐに反映されます。アカウントに紐付いた既存スレッドと処理中のリクエストは現在のアカウントを維持し、新規または未紐付けのリクエストは選択したアカウントの順序ティアを使います。同じ選択順序のアカウントは引き続き交代で使われます。",
   "codexAuth.cacheWarning": "アカウント切り替えでプロンプトキャッシュはリセットされます。新規セッションは空のキャッシュで開始します。",
+  "codexAuth.switchExceedsThresholdWarning": "このアカウントは切り替えしきい値（{threshold}%）に達しているか超えています。クォータの余白がない場合、ピン留めは解除されます。",
   "codexAuth.setAsNext": "このアカウントを次に使う",
   "codexAuth.cancel": "キャンセル",
   "codexAuth.switchBack": "メインに戻しますか?",
@@ -1913,6 +1914,11 @@ export const ja: Record<TKey, string> = {
   "accountPool.stickyLimitInvalid": "1 から 100 までの整数を入力してください",
   "accountPool.strategyLoadFailed": "ローテーション戦略を読み込めませんでした。",
   "accountPool.strategyUpdateFailed": "ローテーション戦略を保存できませんでした。",
+  "accountPool.switchAtThreshold": "{threshold}% で切り替え",
+  "accountPool.drainAtThreshold": "{threshold}% で新規割り当て停止",
+  "accountPool.resetBelowThreshold": "{threshold}% 未満で次回リセットが最速のアカウントを選択",
+  "accountPool.thresholdNotUsed": "しきい値は未使用",
+  "accountPool.proactiveSwitchingOff": "事前切り替えオフ",
 
   "accountPool.quotaWindow": "クォータ集計ウィンドウ",
   "accountPool.quotaWindowDesc": "クォータに基づく新規セッション選択、フィルファーストのしきい値判定、対象となる 429 代替先で使うキャッシュ済み使用量バーを指定します。",

gui/src/i18n/ko.ts

@@ -1433,6 +1433,7 @@ export const ko: Record<TKey, string> = {
   "codexAuth.switchTitle": "활성 계정을 변경하시겠습니까?",
   "codexAuth.switchDesc": "즉시 적용됩니다. 계정에 바인딩된 기존 스레드와 이미 진행 중인 요청은 기존 계정을 유지하고, 새 요청이나 바인딩 없는 요청은 선택한 계정의 순서 티어를 사용합니다. 같은 선택 순서의 계정은 계속 번갈아 사용됩니다.",
   "codexAuth.cacheWarning": "계정 전환 시 프롬프트 캐시가 초기화됩니다.",
+  "codexAuth.switchExceedsThresholdWarning": "이 계정의 사용량이 전환 임계값({threshold}%)에 도달했거나 초과했습니다. 할당량 여유가 없으면 고정 선택이 해제됩니다.",
   "codexAuth.setAsNext": "이 계정을 다음에 사용",
   "codexAuth.cancel": "취소",
   "codexAuth.switchBack": "메인 계정으로 돌아가시겠습니까?",
@@ -1504,6 +1505,11 @@ export const ko: Record<TKey, string> = {
   "accountPool.stickyLimitInvalid": "1에서 100 사이의 정수를 입력하세요",
   "accountPool.strategyLoadFailed": "로테이션 전략을 불러오지 못했습니다.",
   "accountPool.strategyUpdateFailed": "로테이션 전략을 저장하지 못했습니다.",
+  "accountPool.switchAtThreshold": "{threshold}%에서 전환",
+  "accountPool.drainAtThreshold": "{threshold}%에서 소진",
+  "accountPool.resetBelowThreshold": "{threshold}% 미만에서 가장 빠른 초기화 선택",
+  "accountPool.thresholdNotUsed": "임계값 미사용",
+  "accountPool.proactiveSwitchingOff": "사전 전환 꺼짐",
 
   "accountPool.quotaWindow": "할당량 기준 구간",
   "accountPool.quotaWindowDesc": "할당량 기반 새 세션 선택, 필 퍼스트 임계값 판정, 가능한 429 대체 계정에 사용할 캐시 사용량 기준을 정합니다.",