@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/quota.ts

@@ -2,13 +2,37 @@ import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+import { isThirtyDayOnlyCodexPlan } from "./plan";
 
 export type StoredAccountQuota = {
   weeklyPercent?: number;
   monthlyPercent?: number;
   weeklyResetAt?: number;
   monthlyResetAt?: number;
+  /**
+   * A sub-day burst window, when upstream declares one (#1791).
+   *
+   * K12 and similar plans enforce a rolling 5-hour limit ALONGSIDE the weekly one.
+   * Not folding it into `weeklyPercent` stopped the mislabeling, but dropping it
+   * entirely hides a limit that genuinely blocks the account: a 429 at 100% here is
+   * real even while the weekly quota is untouched.
+   *
+   * `shortWindowSeconds` is retained because the duration is the only thing that makes
+   * this window self-describing; the slot it arrived in is not stable across plans.
+   */
+  shortPercent?: number;
+  shortResetAt?: number;
+  shortWindowSeconds?: number;
+  customWindows?: Array<{ label: string; percent: number; resetAt?: number }>;
   resetCredits?: number;
+  /**
+   * True when `monthlyPercent` came from an explicitly-monthly PRIMARY window —
+   * i.e. it is the account's governing quota reading, not a supplementary
+   * tertiary window. Tertiary-only monthly data lands in the same field but says
+   * nothing about the weekly quota that actually gates a non-Go/Free account,
+   * so recovery must be able to tell the two apart (#967 audit).
+   */
+  monthlyIsPrimaryWindow?: boolean;
   updatedAt: number;
 };
 
@@ -28,7 +52,7 @@ let persistTimer: ReturnType<typeof setTimeout> | null = null;
 
 export type WhamUsageResponse = {
   email?: string | null;
-  plan_type?: string | null;
+  plan_type?: unknown;
   rate_limit?: {
     // Live WHAM payloads send explicit nulls for absent windows (issue #315 repro).
     primary_window?: WhamUsageWindow | null;
@@ -38,6 +62,16 @@ export type WhamUsageResponse = {
   rate_limit_reset_credits?: {
     available_count: number;
   } | null;
+  additional_rate_limits?: WhamAdditionalRateLimit[] | null;
+};
+
+type WhamAdditionalRateLimit = {
+  limit_name?: unknown;
+  metered_feature?: unknown;
+  rate_limit?: {
+    primary_window?: WhamUsageWindow | null;
+    secondary_window?: WhamUsageWindow | null;
+  } | null;
 };
 
 type WhamUsageWindow = {
@@ -47,7 +81,23 @@ type WhamUsageWindow = {
 };
 
 const MONTHLY_WINDOW_MIN_SECONDS = 28 * 24 * 60 * 60;
+/**
+ * Shortest window still plausibly the WEEKLY quota (#1791).
+ *
+ * K12 and similar plans send a 5-hour primary window plus a 7-day secondary. Folding the
+ * primary into `weeklyPercent` reported the 5-hour bar as the weekly one and discarded the
+ * real weekly reading entirely, so the dashboard showed a window that reset every few hours
+ * and routing never saw the limit that actually gates the account.
+ *
+ * 24h is the discriminator: anything shorter is a burst window, not a weekly one. A window
+ * with no declared duration is unchanged, because older payloads omit `limit_window_seconds`
+ * and guessing there would break every legacy account.
+ */
+const WEEKLY_WINDOW_MIN_SECONDS = 24 * 60 * 60;
 const MONTHLY_WINDOW_MIN_MINUTES = MONTHLY_WINDOW_MIN_SECONDS / 60;
+// Derived, never written as a literal: the header parser and the WHAM parser must not be able
+// to drift to different thresholds, which is the class of defect this pair exists to prevent.
+const WEEKLY_WINDOW_MIN_MINUTES = WEEKLY_WINDOW_MIN_SECONDS / 60;
 
 const accountQuota = new Map<string, StoredAccountQuota>();
 let lastReconciledGeneration = 0;
@@ -63,19 +113,72 @@ export const CODEX_UNKNOWN_USAGE_SCORE = 101;
 export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
 export function isCodexQuotaExhausted(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent"> | null,
-  plan?: string | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent"> | null,
+  plan?: unknown,
 ): boolean {
   if (!quota) return false;
-  const normalizedPlan = plan?.trim().toLowerCase();
-  const values = normalizedPlan === "go" || normalizedPlan === "free"
-    ? [quota.monthlyPercent]
-    : [quota.weeklyPercent, quota.monthlyPercent];
+  // The burst window counts on EVERY plan. It is upstream-enforced independently, so an
+  // account at 100% there is blocked regardless of which longer window governs its plan;
+  // omitting it would route traffic straight into a 429 (#1791).
+  const values = codexQuotaWindowForPlan(plan) === "monthly"
+    ? [quota.monthlyPercent, quota.shortPercent]
+    : [quota.weeklyPercent, quota.monthlyPercent, quota.shortPercent];
   return values.some(value => typeof value === "number"
     && Number.isFinite(value)
     && value >= CODEX_EXHAUSTED_USAGE_PERCENT);
 }
 
+/**
+ * Which usage window a plan reports in. This is the SINGLE rule shared by quota
+ * parsing, exhaustion, and recovery — they must not diverge.
+ *
+ * An allowlist of "known" plans was tried here and was wrong: the upstream model
+ * snapshot alone carries 21 distinct plan strings (`edu_plus`, `finserv`, `k12`,
+ * `quorum`, `self_serve_business_usage_based`, ...), and `CodexAccount.plan` is an
+ * unrestricted string, so any list is a list of the plans someone remembered.
+ * Twelve real plans would have been refused recovery and stayed cooled forever —
+ * the very defect this unit exists to fix, reintroduced as a typo-shaped hole.
+ *
+ * The honest rule is the parser's own: Go and Free report a 30-day window,
+ * everything else (including an absent plan) reports weekly. Recovery reads the
+ * window the parser actually wrote rather than second-guessing it.
+ */
+export function codexQuotaWindowForPlan(plan?: unknown): "monthly" | "weekly" {
+  return isThirtyDayOnlyCodexPlan(plan) ? "monthly" : "weekly";
+}
+
+export function isCompleteCodexQuotaRecoverySnapshot(
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent"> | null,
+  plan?: unknown,
+): boolean {
+  if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
+  // Recovery still fails closed on MISSING EVIDENCE — a credits-only or windowless payload
+  // carries no usage reading at all and must never clear a cooldown. What it does not do is
+  // fail closed on an unfamiliar plan NAME, which only ever meant "cooled forever".
+  //
+  // The parser classifies windows by DURATION, not by plan name: a Team response whose
+  // primary window is explicitly monthly parses to monthlyPercent only (no secondary
+  // window exists), so requiring weeklyPercent because the plan is not go/free would
+  // strand exactly those accounts until their predicted expiry. Accept whichever window(s)
+  // the parser actually wrote; Go/Free never carry a weekly value, so monthly-only is
+  // required there.
+  //
+  // Audit correction: "the parser wrote monthlyPercent" is NOT by itself evidence for a
+  // weekly-quota plan. A tertiary-only response also writes monthlyPercent, and it says
+  // nothing about the weekly quota that actually gates a Team/Plus account — accepting it
+  // would clear the cooldown on a reading of a different window. Only an explicitly-monthly
+  // PRIMARY window is the governing reading, which is what `monthlyIsPrimaryWindow` records.
+  if (codexQuotaWindowForPlan(plan) === "monthly") {
+    return finitePercent(quota.monthlyPercent);
+  }
+  if (finitePercent(quota.weeklyPercent)) return true;
+  return quota.monthlyIsPrimaryWindow === true && finitePercent(quota.monthlyPercent);
+}
+
+function finitePercent(value: number | undefined): boolean {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
 export function normalizeUsagePercent(value: unknown): number | undefined {
   const numeric = typeof value === "number"
     ? value
@@ -97,8 +200,18 @@ function normalizeResetAt(value: unknown): number | undefined {
 }
 
 function hasKnownQuotaValue(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
-  return [quota.weeklyPercent, quota.monthlyPercent]
-    .some(value => typeof value === "number" && Number.isFinite(value));
+  return [quota.weeklyPercent, quota.monthlyPercent, quota.shortPercent]
+    .some(value => typeof value === "number" && Number.isFinite(value))
+    || !!quota.customWindows?.some(window => Number.isFinite(window.percent));
+}
+
+/** True only for a window that DECLARES a duration shorter than a day. */
+function isExplicitShortWindow(window: WhamUsageWindow | null | undefined): boolean {
+  const seconds = window?.limit_window_seconds;
+  return typeof seconds === "number"
+    && Number.isFinite(seconds)
+    && seconds > 0
+    && seconds < WEEKLY_WINDOW_MIN_SECONDS;
 }
 
 function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): boolean {
@@ -109,14 +222,24 @@ function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): bo
 }
 
 function isExplicitMonthlyWindowMinutes(windowMinutes: unknown): boolean {
-  const minutes = typeof windowMinutes === "number"
-    ? windowMinutes
-    : typeof windowMinutes === "string" && windowMinutes.trim() !== ""
-      ? Number(windowMinutes)
+  const minutes = windowMinutes_(windowMinutes);
+  return minutes !== undefined && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
+}
+
+/** The header wire reports a window duration in MINUTES; WHAM reports it in seconds. */
+function windowMinutes_(value: unknown): number | undefined {
+  const minutes = typeof value === "number"
+    ? value
+    : typeof value === "string" && value.trim() !== ""
+      ? Number(value)
       : undefined;
-  return typeof minutes === "number"
-    && Number.isFinite(minutes)
-    && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
+  return typeof minutes === "number" && Number.isFinite(minutes) ? minutes : undefined;
+}
+
+/** Minutes-domain twin of isExplicitShortWindow. Same strict `<`, same 24h discriminator. */
+function isExplicitShortWindowMinutes(value: unknown): boolean {
+  const minutes = windowMinutes_(value);
+  return minutes !== undefined && minutes > 0 && minutes < WEEKLY_WINDOW_MIN_MINUTES;
 }
 
 
@@ -128,8 +251,18 @@ function snapshotHasMonthly(quota: Omit<StoredAccountQuota, "updatedAt">): boole
   return quota.monthlyPercent !== undefined || quota.monthlyResetAt !== undefined;
 }
 
+function snapshotHasShort(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.shortPercent !== undefined
+    || quota.shortResetAt !== undefined
+    || quota.shortWindowSeconds !== undefined;
+}
+
+function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.customWindows !== undefined;
+}
+
 function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
-  return snapshotHasWeekly(quota) || snapshotHasMonthly(quota);
+  return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota);
 }
 export function setAccountQuotaFromParsed(
   accountId: string,
@@ -147,6 +280,11 @@ export function setAccountQuotaFromParsed(
     if (existing?.weeklyResetAt !== undefined) next.weeklyResetAt = existing.weeklyResetAt;
     if (existing?.monthlyPercent !== undefined) next.monthlyPercent = existing.monthlyPercent;
     if (existing?.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+    if (existing?.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
+    if (existing?.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
+    if (existing?.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
+    if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
+    if (existing?.customWindows !== undefined) next.customWindows = existing.customWindows;
     next.resetCredits = quota.resetCredits;
     accountQuota.set(accountId, next);
     schedulePersistAccountQuotas();
@@ -166,11 +304,32 @@ export function setAccountQuotaFromParsed(
   if (snapshotHasMonthly(quota)) {
     if (quota.monthlyPercent !== undefined) next.monthlyPercent = quota.monthlyPercent;
     if (quota.monthlyResetAt !== undefined) next.monthlyResetAt = quota.monthlyResetAt;
-  } else if (snapshotHasWeekly(quota) && existing?.monthlyPercent !== undefined) {
+    // Carry the provenance with the value it describes. Recovery reads `freshQuota` directly,
+    // so this is not on its path today — but a cached snapshot that kept `monthlyPercent`
+    // while silently dropping `monthlyIsPrimaryWindow` would look like tertiary-only data to
+    // any future reader, and that failure would be invisible.
+    if (quota.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
+  } else if ((snapshotHasWeekly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota))
+      && existing?.monthlyPercent !== undefined) {
     next.monthlyPercent = existing.monthlyPercent;
     if (existing.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+    if (existing.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
+  }
+
+  if (snapshotHasShort(quota)) {
+    if (quota.shortPercent !== undefined) next.shortPercent = quota.shortPercent;
+    if (quota.shortResetAt !== undefined) next.shortResetAt = quota.shortResetAt;
+    if (quota.shortWindowSeconds !== undefined) next.shortWindowSeconds = quota.shortWindowSeconds;
+  } else {
+    // Header and reset-credit updates are partial snapshots. Preserve the last full WHAM
+    // burst tuple when those updates do not carry enough window metadata to replace it.
+    if (existing?.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
+    if (existing?.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
+    if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
   }
 
+  if (snapshotHasCustom(quota)) next.customWindows = quota.customWindows;
+
   if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
   else if (existing?.resetCredits !== undefined) next.resetCredits = existing.resetCredits;
 
@@ -196,16 +355,39 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
   const secondaryResetAt = normalizeResetAt(secondaryResetRaw);
   const tertiaryResetAt = normalizeResetAt(tertiaryResetRaw);
   const primaryIsMonthly = primaryRaw !== null && isExplicitMonthlyWindowMinutes(primaryWindowMinutes);
+  // Codex removed the 5-hour window and has now restored it for Plus and Team (Pro stays
+  // weekly-only). A primary window that DECLARES a sub-day duration is a burst window: folding
+  // it into weeklyPercent both discards the real weekly reading and leaves the account looking
+  // exhausted long after the burst window resets. Duration decides, exactly as parseUsageQuota
+  // already does for the WHAM payload — the two parsers must not disagree about the same data.
+  const primaryIsShort = primaryRaw !== null && isExplicitShortWindowMinutes(primaryWindowMinutes);
 
   if (primaryIsMonthly) {
     if (primaryPercent !== undefined) {
       quota.monthlyPercent = primaryPercent;
       if (primaryResetAt !== undefined) quota.monthlyResetAt = primaryResetAt;
+      // Same provenance rule as parseUsageQuota(): this monthly value is the governing
+      // primary window, not a supplementary tertiary one. Not on the recovery path today,
+      // but the two parsers must agree on what a bare monthlyPercent means.
+      quota.monthlyIsPrimaryWindow = true;
     }
     if (secondaryPercent !== undefined) {
       quota.weeklyPercent = secondaryPercent;
       if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
     }
+  } else if (primaryIsShort) {
+    if (primaryPercent !== undefined) {
+      quota.shortPercent = primaryPercent;
+      if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
+      const minutes = windowMinutes_(primaryWindowMinutes);
+      if (minutes !== undefined) quota.shortWindowSeconds = Math.round(minutes * 60);
+    }
+    // The burst window vacates the primary slot, so the weekly reading is the secondary — which
+    // is where it was all along. Without this the true weekly value is silently dropped.
+    if (secondaryPercent !== undefined) {
+      quota.weeklyPercent = secondaryPercent;
+      if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
+    }
   } else {
     const weeklyPercent = primaryPercent ?? secondaryPercent;
     const weeklyResetAt = primaryPercent !== undefined
@@ -253,8 +435,17 @@ export function updateAccountQuota(
   const quota: StoredAccountQuota = {
     ...(existing?.weeklyPercent !== undefined ? { weeklyPercent: existing.weeklyPercent } : {}),
     ...(existing?.monthlyPercent !== undefined ? { monthlyPercent: existing.monthlyPercent } : {}),
+    // Carry provenance with the value it describes. Dropping it here would downgrade a proven
+    // explicit-primary reading to "unproven" on the next unrelated weekly update.
+    ...(existing?.monthlyPercent !== undefined && existing.monthlyIsPrimaryWindow === true
+      ? { monthlyIsPrimaryWindow: true }
+      : {}),
     ...(existing?.weeklyResetAt !== undefined ? { weeklyResetAt: existing.weeklyResetAt } : {}),
     ...(existing?.monthlyResetAt !== undefined ? { monthlyResetAt: existing.monthlyResetAt } : {}),
+    ...(existing?.shortPercent !== undefined ? { shortPercent: existing.shortPercent } : {}),
+    ...(existing?.shortResetAt !== undefined ? { shortResetAt: existing.shortResetAt } : {}),
+    ...(existing?.shortWindowSeconds !== undefined ? { shortWindowSeconds: existing.shortWindowSeconds } : {}),
+    ...(existing?.customWindows !== undefined ? { customWindows: existing.customWindows } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
     updatedAt: Date.now(),
   };
@@ -268,6 +459,10 @@ export function updateAccountQuota(
   if (nextMonthly !== undefined) {
     quota.monthlyPercent = nextMonthly;
     if (nextMonthlyResetAt !== undefined) quota.monthlyResetAt = nextMonthlyResetAt;
+    // A caller-supplied monthly value arrives without window provenance, so it REPLACES the
+    // proven reading and must not inherit its flag — otherwise an unproven number would be
+    // treated as governing evidence.
+    delete quota.monthlyIsPrimaryWindow;
   }
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
@@ -363,11 +558,14 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
     : undefined;
 
   if (!data.rate_limit) {
+    if (data.additional_rate_limits?.length) {
+      return parseUsageQuota({ ...data, rate_limit: {} });
+    }
     return resetCredits !== undefined ? { resetCredits } : null;
   }
 
   const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
-  const thirtyDayOnly = data.plan_type?.trim().toLowerCase() === "go" || data.plan_type?.trim().toLowerCase() === "free";
+  const thirtyDayOnly = codexQuotaWindowForPlan(data.plan_type) === "monthly";
   const primaryWindow = data.rate_limit.primary_window;
   const secondaryWindow = data.rate_limit.secondary_window;
   const tertiaryWindow = data.rate_limit.tertiary_window;
@@ -386,10 +584,25 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   // - 선택한 방식: only an explicit primary duration of at least 28 days changes it to monthly.
   // - 다른 대안 대신 이 방식을 선택한 이유: it accepts calendar-month variance and preserves legacy payloads.
   // - 장점, 단점 및 영향: Team monthly quotas classify correctly; unknown durations remain weekly by design.
-  const weeklyPercent = primaryIsMonthly ? secondaryPercent : primaryPercent ?? secondaryPercent;
+  // #1791: a primary window that declares a sub-day duration is a burst window, not the
+  // weekly one. Skip it so the secondary (the real 7-day window) is what lands in
+  // `weeklyPercent`; without this the 5-hour bar was reported as weekly and the actual
+  // weekly reading was dropped on the floor.
+  const primaryIsShort = isExplicitShortWindow(primaryWindow);
+  const weeklyCandidatePercent = primaryIsShort ? undefined : primaryPercent;
+  const weeklyCandidateResetAt = primaryIsShort ? undefined : primaryResetAt;
+  // Keep the burst reading instead of dropping it on the floor: it is a real limit, and
+  // the account is blocked when it fills even though the weekly window is fine (#1791).
+  if (primaryIsShort && primaryPercent !== undefined) {
+    quota.shortPercent = primaryPercent;
+    if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
+    const seconds = primaryWindow?.limit_window_seconds;
+    if (typeof seconds === "number" && Number.isFinite(seconds)) quota.shortWindowSeconds = seconds;
+  }
+  const weeklyPercent = primaryIsMonthly ? secondaryPercent : weeklyCandidatePercent ?? secondaryPercent;
   const weeklyResetAt = primaryIsMonthly
     ? secondaryResetAt
-    : primaryPercent !== undefined ? primaryResetAt : secondaryResetAt;
+    : weeklyCandidatePercent !== undefined ? weeklyCandidateResetAt : secondaryResetAt;
   const monthlyPercent = primaryIsMonthly ? primaryPercent ?? tertiaryPercent : tertiaryPercent;
   const monthlyResetAt = primaryIsMonthly && primaryPercent !== undefined ? primaryResetAt : tertiaryResetAt;
   if (thirtyDayOnly) {
@@ -404,6 +617,36 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   if (!thirtyDayOnly && monthlyPercent !== undefined) {
     quota.monthlyPercent = monthlyPercent;
     if (monthlyResetAt !== undefined) quota.monthlyResetAt = monthlyResetAt;
+    // Record WHERE this reading came from. Only an explicitly-monthly primary window is the
+    // account's governing quota; a tertiary window lands in the same field but describes a
+    // different period, so recovery must not treat the two as interchangeable.
+    if (primaryIsMonthly && primaryPercent !== undefined) quota.monthlyIsPrimaryWindow = true;
+  }
+
+  const spark = data.additional_rate_limits?.find(additional => {
+    const name = String(additional.limit_name ?? "").toLowerCase();
+    const feature = String(additional.metered_feature ?? "").toLowerCase();
+    return feature === "codex_bengalfox" || name.includes("gpt-5.3-codex-spark");
+  });
+  const sparkWindows = [spark?.rate_limit?.primary_window, spark?.rate_limit?.secondary_window]
+    .filter((window): window is WhamUsageWindow => !!window);
+  const sparkWeekly = sparkWindows.find(window => {
+    const percent = normalizeUsagePercent(window.used_percent);
+    const seconds = window.limit_window_seconds;
+    return percent !== undefined
+      && !isExplicitShortWindow(window)
+      && !isExplicitMonthlyWindow(window)
+      && (seconds === undefined || seconds >= WEEKLY_WINDOW_MIN_SECONDS);
+  });
+  const sparkPercent = normalizeUsagePercent(sparkWeekly?.used_percent);
+  if (sparkPercent !== undefined) {
+    const sparkWindow: { label: string; percent: number; resetAt?: number } = {
+      label: "GPT-5.3-Codex-Spark Weekly",
+      percent: sparkPercent,
+    };
+    const resetAt = normalizeResetAt(sparkWeekly?.reset_at);
+    if (resetAt !== undefined) sparkWindow.resetAt = resetAt;
+    quota.customWindows = [sparkWindow];
   }
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 

package/src/codex/refresh.ts

@@ -4,6 +4,7 @@ import type { ComboCatalogOmission } from "./catalog/aggregation";
 import { CODEX_MODELS_CACHE_PATH } from "./paths";
 import { atomicWriteFile } from "../config";
 import type { OcxConfig } from "../types";
+import type { CodexCatalogSyncOptions } from "./catalog/sync";
 
 export interface CodexCatalogRefreshResult {
   added: number;
@@ -12,6 +13,8 @@ export interface CodexCatalogRefreshResult {
   catalogWritten: boolean;
   cacheSynced: boolean;
   comboOmissions: ComboCatalogOmission[];
+  /** Desired OFF observed under K during the catalog commit; no cache write either. */
+  skippedReason?: "desired_disabled";
 }
 
 interface RefreshDeps {
@@ -40,14 +43,20 @@ export function syncCodexModelsCacheFromCatalog(catalogPath: string): void {
 export async function refreshCodexModelCatalog(
   config: OcxConfig,
   deps: RefreshDeps = defaultDeps,
+  options?: CodexCatalogSyncOptions,
 ): Promise<CodexCatalogRefreshResult> {
-  const result = await deps.syncCatalogModels(config);
+  const result = await deps.syncCatalogModels(config, options);
   const catalogExists = deps.existsSync(result.path);
   const catalogWritten = result.catalogWritten === true;
   const comboOmissions = result.comboOmissions ?? [];
+  if (result.skippedReason === "desired_disabled") {
+    // The commit path observed OFF under K. Invalidate nothing: rewriting the
+    // models cache here would be exactly the routed-cache write the skip refused.
+    return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
+  }
   if (!catalogExists) {
     return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
   }
-  const cacheSynced = deps.invalidateCodexModelsCache();
+  const cacheSynced = deps.invalidateCodexModelsCache(options);
   return { ...result, catalogExists, catalogWritten, cacheSynced, comboOmissions };
 }