@bitkyc08/opencodex 2.52.0-preview.20260912 → 2.53.0-preview.20260913

package/src/codex/quota-capacity.ts

@@ -0,0 +1,98 @@
+import type { QuotaHistorySample, QuotaHistoryWindow } from "./quota-history";
+import type { PersistedUsageAttempt, PersistedUsageEntry } from "../usage/log";
+
+export const CAPACITY_ASSUMPTIONS = [
+  "Quota percentages can be rounded or delayed.",
+  "Only retained valid proxy usage rows are observed; external usage is unknown.",
+  "Account log labels are assumed stable within each observation interval.",
+  "This low-confidence effective-token estimate is not a provider token limit or lower bound.",
+] as const;
+export const CAPACITY_REASONS = ["insufficient_intervals", "ledger_unavailable", "ledger_truncated", "identity_unavailable", "identity_changed", "ambiguous_usage"] as const;
+export type CapacityReason = typeof CAPACITY_REASONS[number];
+export function parseCapacityReason(value: unknown): CapacityReason | undefined {
+  return CAPACITY_REASONS.find(reason => reason === value);
+}
+export interface CodexCapacityResult {
+  status: "estimated" | "insufficient-evidence";
+  estimates: Array<{ window: QuotaHistoryWindow["window"]; estimatedTokens: number; sampleCount: number; confidence: "low" }>;
+  reason?: CapacityReason;
+  assumptions: readonly string[];
+}
+export function insufficientCodexCapacity(reason: CapacityReason): CodexCapacityResult {
+  return { status: "insufficient-evidence", estimates: [], reason, assumptions: [...CAPACITY_ASSUMPTIONS] };
+}
+const nonnegative = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+function reportedTokens(attempt: PersistedUsageAttempt): number | undefined {
+  if (attempt.sendCount !== 1 || attempt.usageStatus !== "reported" || attempt.locallyAnswered === true
+    || !attempt.usage || attempt.usage.estimated === true
+    || !nonnegative(attempt.usage.inputTokens) || !nonnegative(attempt.usage.outputTokens)) return undefined;
+  const total = attempt.usage.totalTokens ?? attempt.usage.inputTokens + attempt.usage.outputTokens;
+  return nonnegative(total) ? total : undefined;
+}
+
+/** Informational inference over raw same-window observations, never an account-selection input. */
+export function estimateCodexQuotaCapacity(
+  observations: ReadonlyArray<Omit<QuotaHistorySample, "credentialGeneration">>,
+  entries: readonly PersistedUsageEntry[],
+  label: string,
+  sharedQuotaModel: (model: string) => boolean,
+): CodexCapacityResult {
+  if (entries.length > 10_000) return insufficientCodexCapacity("ledger_truncated");
+  const requests = new Map<string, PersistedUsageEntry>();
+  for (const entry of entries) {
+    const previous = requests.get(entry.requestId);
+    if (previous && JSON.stringify(previous) !== JSON.stringify(entry)) return insufficientCodexCapacity("ambiguous_usage");
+    requests.set(entry.requestId, entry);
+  }
+  const sorted = [...observations].sort((a, b) => a.observedAt - b.observedAt);
+  const estimates: CodexCapacityResult["estimates"] = [];
+  for (const windowName of ["short", "weekly", "monthly"] as const) {
+    const points = sorted.flatMap(row => {
+      const window = row.windows.find(candidate => candidate.family === "account" && candidate.window === windowName);
+      return window ? [{ ...window, at: row.observedAt, source: row.source }] : [];
+    });
+    const samples: number[] = [];
+    for (let index = 1; index < points.length; index++) {
+      const left = points[index - 1], right = points[index];
+      const delta = right.usedPercent - left.usedPercent;
+      if (left.source !== right.source || !nonnegative(left.resetAtMs) || left.resetAtMs !== right.resetAtMs
+        || left.resetAtMs <= right.at || left.windowSeconds !== right.windowSeconds
+        || left.monthlyIsPrimaryWindow !== right.monthlyIsPrimaryWindow
+        || right.at <= left.at || delta < 1 || delta > 100 || !Number.isFinite(delta)) continue;
+      let tokens = 0;
+      let valid = true;
+      for (const entry of requests.values()) {
+        if (!nonnegative(entry.timestamp) || !nonnegative(entry.durationMs)) continue;
+        const end = entry.timestamp + entry.durationMs;
+        if (!Number.isFinite(end) || entry.timestamp <= left.at || end > right.at) continue;
+        // Untimed or absent physical-attempt evidence cannot be reconstructed from parent totals.
+        if (!entry.attempts?.length) continue;
+        const attempts = new Map<number, PersistedUsageAttempt>();
+        for (const attempt of entry.attempts) {
+          const prior = attempts.get(attempt.ordinal);
+          if (prior && JSON.stringify(prior) !== JSON.stringify(attempt)) { valid = false; break; }
+          attempts.set(attempt.ordinal, attempt);
+        }
+        if (!valid) break;
+        for (const attempt of attempts.values()) {
+          if (attempt.accountLogLabel !== label || attempt.adapter !== "openai-responses" || !sharedQuotaModel(attempt.model)) continue;
+          const reported = reportedTokens(attempt);
+          if (reported === undefined) continue;
+          tokens += reported;
+        }
+      }
+      const inferred = tokens * 100 / delta;
+      if (valid && tokens > 0 && Number.isFinite(inferred) && inferred > 0) samples.push(inferred);
+    }
+    if (samples.length) {
+      samples.sort((a, b) => a - b);
+      const middle = Math.floor(samples.length / 2);
+      const median = samples.length % 2 ? samples[middle] : samples[middle - 1] / 2 + samples[middle] / 2;
+      const estimatedTokens = Math.round(median);
+      if (estimatedTokens > 0) estimates.push({ window: windowName, estimatedTokens, sampleCount: samples.length, confidence: "low" });
+    }
+  }
+  return estimates.length ? { status: "estimated", estimates, assumptions: [...CAPACITY_ASSUMPTIONS] }
+    : insufficientCodexCapacity("insufficient_intervals");
+}

package/src/codex/quota-history.ts

@@ -0,0 +1,160 @@
+import { isValidCodexAccountId } from "./account-id";
+import type { PoolQuotaWriter } from "./quota-types";
+
+export const QUOTA_HISTORY_LIMITS = { perAccount: 200, accounts: 64, samples: 4096, bytes: 2 * 1024 * 1024, ageMs: 30 * 86400_000 } as const;
+export interface QuotaHistoryWindow {
+  family: "account" | "spark";
+  window: "short" | "weekly" | "monthly";
+  usedPercent: number;
+  resetAtMs?: number;
+  windowSeconds?: number;
+  monthlyIsPrimaryWindow?: boolean;
+}
+export interface QuotaHistorySample {
+  observedAt: number;
+  source: "wham" | "response-header";
+  credentialGeneration: number;
+  windows: QuotaHistoryWindow[];
+}
+type Envelope = { identity: string; samples: QuotaHistorySample[] };
+type Bucket = Envelope & { costs: number[]; overhead: number };
+const encoder = new TextEncoder();
+const byteSize = (value: unknown) => encoder.encode(JSON.stringify(value)).byteLength;
+const identityPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+/** Reconstruct allowlisted data at the disk boundary; malformed windows cannot be partial evidence. */
+function parseSample(value: unknown, now: number): QuotaHistorySample | undefined {
+  if (!record(value) || !finite(value.observedAt) || value.observedAt > now
+    || value.observedAt < now - QUOTA_HISTORY_LIMITS.ageMs
+    || !Number.isSafeInteger(value.credentialGeneration) || (value.credentialGeneration as number) < 0
+    || (value.source !== "wham" && value.source !== "response-header")
+    || !Array.isArray(value.windows) || !value.windows.length || value.windows.length > 5) return undefined;
+  const windows: QuotaHistoryWindow[] = [];
+  const seen = new Set<string>();
+  for (const item of value.windows) {
+    if (!record(item) || (item.family !== "account" && item.family !== "spark")
+      || (item.window !== "short" && item.window !== "weekly" && item.window !== "monthly")
+      || (item.family === "spark" && item.window === "monthly")
+      || !finite(item.usedPercent) || item.usedPercent > 100) return undefined;
+    const key = `${item.family}:${item.window}`;
+    if (seen.has(key)) return undefined;
+    seen.add(key);
+    if ((item.resetAtMs !== undefined && !finite(item.resetAtMs))
+      || (item.windowSeconds !== undefined && (!finite(item.windowSeconds) || item.windowSeconds === 0))
+      || (item.monthlyIsPrimaryWindow !== undefined && typeof item.monthlyIsPrimaryWindow !== "boolean")) return undefined;
+    windows.push({ family: item.family, window: item.window, usedPercent: item.usedPercent,
+      ...(item.resetAtMs !== undefined ? { resetAtMs: item.resetAtMs as number } : {}),
+      ...(item.windowSeconds !== undefined ? { windowSeconds: item.windowSeconds as number } : {}),
+      ...(item.monthlyIsPrimaryWindow === true && item.family === "account" && item.window === "monthly" ? { monthlyIsPrimaryWindow: true } : {}),
+    });
+  }
+  return { observedAt: value.observedAt, source: value.source, credentialGeneration: value.credentialGeneration as number, windows };
+}
+
+/** Bounded in-process observations. The quota cache owns persistence and credential admission. */
+export class CodexQuotaHistory {
+  private accounts = new Map<string, Bucket>();
+  private bytes = 32;
+  private count = 0;
+
+  append(writer: PoolQuotaWriter, sample: QuotaHistorySample, now = Date.now()): void {
+    if (!isValidCodexAccountId(writer.accountId) || !identityPattern.test(writer.historyIdentity)
+      || sample.credentialGeneration !== writer.credentialGeneration) return;
+    const parsed = parseSample(sample, now);
+    if (!parsed) return;
+    let bucket = this.accounts.get(writer.accountId);
+    if (bucket && bucket.identity !== writer.historyIdentity) { this.clear(writer.accountId); bucket = undefined; }
+    if (!bucket) {
+      const overhead = byteSize(writer.accountId) + byteSize({ identity: writer.historyIdentity, samples: [] }) + 8;
+      bucket = { identity: writer.historyIdentity, samples: [], costs: [], overhead };
+      this.accounts.set(writer.accountId, bucket);
+      this.bytes += overhead;
+    }
+    const index = bucket.samples.findIndex(row => row.observedAt > parsed.observedAt);
+    const position = index < 0 ? bucket.samples.length : index;
+    const cost = byteSize(parsed) + 1;
+    bucket.samples.splice(position, 0, parsed);
+    bucket.costs.splice(position, 0, cost);
+    this.bytes += cost;
+    this.count++;
+    while (bucket.samples.length > QUOTA_HISTORY_LIMITS.perAccount) this.dropFirst(writer.accountId);
+    this.prune(now);
+  }
+
+  read(accountId: string, identity: string | undefined, now = Date.now(), limit: number = QUOTA_HISTORY_LIMITS.perAccount): { samples: QuotaHistorySample[]; truncated: boolean } {
+    this.prune(now);
+    const bucket = this.accounts.get(accountId);
+    if (!identity || !bucket) return { samples: [], truncated: false };
+    if (bucket.identity !== identity) { this.clear(accountId); return { samples: [], truncated: false }; }
+    const capped = Math.max(1, Math.min(QUOTA_HISTORY_LIMITS.perAccount, Math.trunc(limit)));
+    return { samples: structuredClone(bucket.samples.slice(-capped)), truncated: bucket.samples.length > capped };
+  }
+
+  clear(accountId?: string): number {
+    if (accountId === undefined) {
+      const count = this.accounts.size;
+      this.accounts.clear(); this.count = 0; this.bytes = 32;
+      return count;
+    }
+    const bucket = this.accounts.get(accountId);
+    if (!bucket) return 0;
+    this.bytes -= bucket.overhead + bucket.costs.reduce((a, b) => a + b, 0);
+    this.count -= bucket.samples.length;
+    this.accounts.delete(accountId);
+    return 1;
+  }
+
+  reconcile(ids: ReadonlySet<string>): number {
+    let removed = 0;
+    for (const id of this.accounts.keys()) if (!ids.has(id)) removed += this.clear(id);
+    return removed;
+  }
+
+  serialize(now = Date.now()): { version: 1; accounts: Record<string, Envelope> } {
+    this.prune(now);
+    return { version: 1, accounts: Object.fromEntries([...this.accounts].map(([id, bucket]) => [id,
+      { identity: bucket.identity, samples: structuredClone(bucket.samples) }])) };
+  }
+
+  hydrate(value: unknown, now = Date.now()): void {
+    this.clear();
+    if (!record(value) || value.version !== 1 || !record(value.accounts) || byteSize(value) > QUOTA_HISTORY_LIMITS.bytes) return;
+    const entries = Object.entries(value.accounts);
+    if (entries.length > QUOTA_HISTORY_LIMITS.accounts) return;
+    let count = 0;
+    for (const [id, envelope] of entries) {
+      if (!isValidCodexAccountId(id) || !record(envelope) || typeof envelope.identity !== "string"
+        || !identityPattern.test(envelope.identity) || !Array.isArray(envelope.samples)
+        || envelope.samples.length > QUOTA_HISTORY_LIMITS.perAccount) return;
+      count += envelope.samples.length;
+      if (count > QUOTA_HISTORY_LIMITS.samples) return;
+    }
+    for (const [accountId, raw] of entries) {
+      const envelope = raw as Envelope;
+      for (const sample of envelope.samples) {
+        const parsed = parseSample(sample, now);
+        if (parsed) this.append({ accountId, historyIdentity: envelope.identity, credentialGeneration: parsed.credentialGeneration }, parsed, now);
+      }
+    }
+  }
+
+  private dropFirst(id: string): void {
+    const bucket = this.accounts.get(id)!;
+    this.bytes -= bucket.costs.shift()!;
+    bucket.samples.shift(); this.count--;
+    if (!bucket.samples.length) { this.bytes -= bucket.overhead; this.accounts.delete(id); }
+  }
+
+  private prune(now: number): void {
+    for (const [id, bucket] of this.accounts) {
+      while (bucket.samples.length && bucket.samples[0].observedAt < now - QUOTA_HISTORY_LIMITS.ageMs) this.dropFirst(id);
+    }
+    while (this.accounts.size > QUOTA_HISTORY_LIMITS.accounts || this.count > QUOTA_HISTORY_LIMITS.samples || this.bytes > QUOTA_HISTORY_LIMITS.bytes) {
+      const first = [...this.accounts].sort(([a, x], [b, y]) => x.samples[0].observedAt - y.samples[0].observedAt || a.localeCompare(b))[0];
+      if (!first) break;
+      this.dropFirst(first[0]);
+    }
+  }
+}

package/src/codex/quota-types.ts

@@ -49,3 +49,11 @@ export type WhamUsageResponse = {
   rate_limit_reset_credits?: { available_count: number } | null;
   additional_rate_limits?: WhamAdditionalRateLimit[] | null;
 };
+
+
+/** Captured from the exact dispatched pool credential; never a management API field. */
+export interface PoolQuotaWriter {
+  accountId: string;
+  credentialGeneration: number;
+  historyIdentity: string;
+}

package/src/codex/quota.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, openSync, readSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
@@ -6,10 +6,12 @@ import { isThirtyDayOnlyCodexPlan } from "./plan";
 import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaWriter } from "./main-account-cache";
 
-import type { StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
+import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
+import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
+import type { PoolQuotaWriter, StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
 export type { StoredAccountQuota, WhamUsageResponse } from "./quota-types";
 
-/** Disk snapshot under OPENCODEX_HOME — quota and policy identity only, never credential tags. */
+/** Disk snapshot: quota, private non-secret publication UUIDs and policy identity; never token-derived fingerprints. */
 const QUOTA_CACHE_FILENAME = "codex-quota-cache.json";
 /** Keep last-known bars across restarts; WHAM still refreshes on TTL in live/prime paths. */
 const QUOTA_DISK_MAX_AGE_MS = 6 * 60 * 60_000;
@@ -19,6 +21,7 @@ type QuotaDiskFile = {
   version: 1;
   quotas: Record<string, StoredAccountQuota>;
   mainPolicyQuota?: MainPolicyQuota;
+  history?: ReturnType<CodexQuotaHistory["serialize"]>;
 };
 
 type MainPolicyQuota = { identityKey: string; quota: StoredAccountQuota };
@@ -61,6 +64,7 @@ export function resetAtToMs(resetAt: number): number {
 }
 
 const accountQuota = new Map<string, StoredAccountQuota>();
+const quotaHistory = new CodexQuotaHistory();
 let lastReconciledGeneration = 0;
 let liveAccountIds = new Set<string>();
 
@@ -268,14 +272,22 @@ export function setAccountQuotaFromParsed(
   writerGeneration = captureConfigGeneration(),
   mainWriter?: MainQuotaWriter,
   policyQuota: Omit<StoredAccountQuota, "updatedAt"> | null = quota,
+  historyEvidence?: QuotaObservationEvidence,
 ): void {
-  if (!quota) return;
+  quota = withoutRetiredCodexQuota(quota);
+  policyQuota = withoutRetiredCodexQuota(policyQuota);
+  if (!quota || (!snapshotHasUsage(quota) && quota.resetCredits === undefined)) return;
   if (!mayCommitAccountQuota(accountId, writerGeneration)) return;
   const isMain = accountId === MAIN_CODEX_ACCOUNT_ID;
   if (isMain && mainWriter && !isMainQuotaWriterLive(mainWriter)) return;
   hydrateAccountQuotasFromDisk();
   const legacyExisting = accountQuota.get(accountId);
   const updatedAt = Date.now();
+  if (historyEvidence && historyEvidence.writer.accountId === accountId && isPoolQuotaWriterLive(historyEvidence.writer)) {
+    quotaHistory.append(historyEvidence.writer, { observedAt: historyEvidence.observedAt, source: historyEvidence.source,
+      credentialGeneration: historyEvidence.writer.credentialGeneration, windows: historyWindows(historyEvidence.raw),
+    }, updatedAt);
+  }
   // Legacy rotation keeps its existing carry behavior, but never inherits policy-only
   // evidence that outlived its disk TTL. Policy has a separate, identity-checked base.
   const next = mergeAccountQuota(quota, legacyExisting, updatedAt);
@@ -307,6 +319,8 @@ function mergeAccountQuota(
   updatedAt: number,
   policyEvidence = false,
 ): StoredAccountQuota {
+  quota = withoutRetiredCodexQuota(quota) ?? {};
+  existing = withoutRetiredCodexQuota(existing ?? null) ?? undefined;
   const next: StoredAccountQuota = { updatedAt };
   const creditsOnly = quota.resetCredits !== undefined && !snapshotHasUsage(quota);
 
@@ -415,7 +429,9 @@ function notifyCodexQuotaSnapshot(accountId: string, next: StoredAccountQuota):
   // Copy before the boundary: `next` is the live map value and the following write mutates
   // it, so an observation that read it after awaiting could see a later snapshot than the
   // one it was called for.
-  const snapshot = { ...next };
+  const retained = withoutRetiredCodexQuota(next);
+  if (!retained) return;
+  const snapshot = { ...retained };
   pendingObservation = pendingObservation
     .then(async () => {
       const observer = await import("../quota/reset-observer");
@@ -439,20 +455,25 @@ export function flushQuotaObservationsForTests(): Promise<void> {
   return pendingObservation;
 }
 
-/** Wire marker shared by Spark-family models, whose upstream limit family is model-specific. */
-const SPARK_MODEL_MARKER = "codex-spark";
-/**
- * Custom-window label for the Spark 5h window. The WHAM parser and the response-header path
- * must write the SAME label so a header refresh replaces the WHAM reading instead of doubling it.
- */
-const SPARK_SHORT_WINDOW_LABEL = "GPT-5.3-Codex-Spark 5h";
+/** Exact retired model evidence, including account/provider-qualified selectors. */
+export function isRetiredCodexSparkModel(modelId: string | undefined): boolean {
+  return modelId?.trim().toLowerCase().split("/").at(-1) === "gpt-5.3-codex-spark";
+}
 
-/** True when the routed model belongs to the Spark family, which carries its own rate limit. */
-function isCodexSparkModel(modelId: string | undefined): boolean {
-  return typeof modelId === "string" && modelId.includes(SPARK_MODEL_MARKER);
+/** Tombstone old cache/DTO labels without changing unrelated custom windows or stores. */
+export function withoutRetiredCodexQuota<T extends Omit<StoredAccountQuota, "updatedAt"> | null>(quota: T): T | null {
+  if (!quota?.customWindows?.length) return quota;
+  const kept = quota.customWindows.filter(window =>
+    window.label !== "GPT-5.3-Codex-Spark 5h" && window.label !== "GPT-5.3-Codex-Spark Weekly");
+  if (kept.length === quota.customWindows.length) return quota;
+  const next = { ...quota };
+  if (kept.length > 0) next.customWindows = kept;
+  else delete next.customWindows;
+  return snapshotHasUsage(next) || next.resetCredits !== undefined ? next as T : null;
 }
 
 export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?: string }): Omit<StoredAccountQuota, "updatedAt"> | null {
+  if (isRetiredCodexSparkModel(options?.modelId)) return null;
   const primaryRaw = headers.get("x-codex-primary-used-percent");
   const secondaryRaw = headers.get("x-codex-secondary-used-percent");
   const tertiaryRaw = headers.get("x-codex-tertiary-used-percent");
@@ -475,10 +496,6 @@ export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?
   // 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.
-  // One more attribution layer (#4122): on a Spark-family model response the sub-day primary is
-  // the MODEL-SPECIFIC limit, not an account window. Filing it as the account short tuple made
-  // one pool account display a 5h bar its identically-limited peers did not have, and fed a
-  // model limit to the account-policy readers (main-account hard lock, five-hour auto-refresh).
   const primaryIsShort = isExplicitShortWindowMinutes(primaryWindowMinutes);
 
   if (primaryIsMonthly) {
@@ -495,21 +512,10 @@ export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?
       if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
     }
   } else if (primaryIsShort) {
-    if (isCodexSparkModel(options?.modelId)) {
-      if (primaryPercent !== undefined) {
-        const sparkWindow: { label: string; percent: number; resetAt?: number } = {
-          label: SPARK_SHORT_WINDOW_LABEL,
-          percent: primaryPercent,
-        };
-        if (primaryResetAt !== undefined) sparkWindow.resetAt = primaryResetAt;
-        quota.customWindows = [sparkWindow];
-      }
-    } else {
-      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);
-    }
+    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) {
@@ -540,31 +546,17 @@ export function applyAccountQuotaFromUpstreamHeaders(
   headers: Headers,
   writerGeneration = captureConfigGeneration(),
   mainWriter?: MainQuotaWriter,
-  options?: { modelId?: string },
+  options?: { modelId?: string; poolWriter?: PoolQuotaWriter },
 ): void {
   const quota = parseUpstreamQuotaHeaders(headers, options);
   if (!quota) return;
   const policyQuota = [
     "x-codex-primary-used-percent", "x-codex-secondary-used-percent", "x-codex-tertiary-used-percent",
   ].some(name => isInvalidPolicyUsagePercent(headers.get(name))) ? null : filterMainPolicyMonthlyQuota(quota);
-  // A header-observed Spark window is a partial update against the WHAM-recorded custom windows:
-  // merge by label so the weekly Spark entry survives, and hydrate first so the first call in a
-  // process does not merge against an empty map. The merged list goes only to the legacy
-  // snapshot — the identity-bound policy evidence keeps exactly what this response said.
-  let legacyQuota = quota;
-  if (quota.customWindows !== undefined) {
-    hydrateAccountQuotasFromDisk();
-    const existing = accountQuota.get(accountId)?.customWindows;
-    if (existing !== undefined) {
-      const incoming = new Map(quota.customWindows.map(window => [window.label, window]));
-      const merged = existing.map(window => incoming.get(window.label) ?? window);
-      for (const window of quota.customWindows) {
-        if (!existing.some(entry => entry.label === window.label)) merged.push(window);
-      }
-      legacyQuota = { ...quota, customWindows: merged };
-    }
-  }
-  setAccountQuotaFromParsed(accountId, legacyQuota, writerGeneration, mainWriter, policyQuota);
+  const validHistory = !["x-codex-primary-used-percent", "x-codex-secondary-used-percent", "x-codex-tertiary-used-percent"]
+    .some(name => isInvalidPolicyUsagePercent(headers.get(name)));
+  setAccountQuotaFromParsed(accountId, quota, writerGeneration, mainWriter, policyQuota,
+    options?.poolWriter && validHistory ? { writer: options.poolWriter, observedAt: Date.now(), source: "response-header", raw: quota } : undefined);
 }
 
 export function updateAccountQuota(
@@ -658,16 +650,19 @@ function hydrateAccountQuotasFromDisk(): void {
   try {
     const path = join(getConfigDir(), QUOTA_CACHE_FILENAME);
     if (!existsSync(path)) return;
-    const raw = readFileSync(path, "utf8");
+    const raw = readQuotaCacheBounded(path);
     const parsed = JSON.parse(raw) as QuotaDiskFile;
     if (!parsed || parsed.version !== 1 || !parsed.quotas || typeof parsed.quotas !== "object") return;
+    quotaHistory.hydrate(parsed.history);
     // Policy evidence deliberately outlives the legacy six-hour rotation-cache TTL.
     mainPolicyQuota = readMainPolicyQuota(parsed.mainPolicyQuota);
     const now = Date.now();
     for (const [accountId, quota] of Object.entries(parsed.quotas)) {
       if (!quota || typeof quota !== "object" || typeof quota.updatedAt !== "number") continue;
       if (now - quota.updatedAt > QUOTA_DISK_MAX_AGE_MS) continue;
-      if (!accountQuota.has(accountId)) accountQuota.set(accountId, quota);
+      const retained = withoutRetiredCodexQuota(quota);
+      if (!retained) continue;
+      if (!accountQuota.has(accountId)) accountQuota.set(accountId, retained);
     }
   } catch {
     // Corrupt/missing cache must never block routing or the dashboard.
@@ -687,6 +682,7 @@ function schedulePersistAccountQuotas(): void {
         version: 1,
         quotas,
         ...(mainPolicyQuota ? { mainPolicyQuota } : {}),
+        history: quotaHistory.serialize(),
       };
       atomicWriteFile(join(getConfigDir(), QUOTA_CACHE_FILENAME), `${JSON.stringify(body)}\n`);
     } catch {
@@ -735,6 +731,8 @@ function forgetCodexQuotaBaseline(accountId?: string): void {
 }
 
 export function clearAccountQuota(accountId?: string): void {
+  if (accountId) hydrateAccountQuotasFromDisk();
+  quotaHistory.clear(accountId);
   if (accountId) {
     hydrateAccountQuotasFromDisk();
     accountQuota.delete(accountId);
@@ -762,7 +760,7 @@ export function clearAccountQuota(accountId?: string): void {
 export function reconcileCodexQuotaAccounts(context: GenerationContext): number {
   if (context.generation <= lastReconciledGeneration) return 0;
   hydrateAccountQuotasFromDisk();
-  let removed = 0;
+  let removed = quotaHistory.reconcile(context.codexAccountIds);
   for (const accountId of accountQuota.keys()) {
     if (context.codexAccountIds.has(accountId)) continue;
     accountQuota.delete(accountId);
@@ -801,9 +799,6 @@ 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;
   }
 
@@ -866,39 +861,71 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   // A supplementary value (including fallback from an unreadable primary) is not proof.
   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 sparkShort = sparkWindows.find(window => {
-    const percent = normalizeUsagePercent(window.used_percent);
-    return percent !== undefined && isExplicitShortWindow(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 sparkCustomWindows: Array<{ label: string; percent: number; resetAt?: number }> = [];
-  for (const [label, window] of [
-    [SPARK_SHORT_WINDOW_LABEL, sparkShort],
-    ["GPT-5.3-Codex-Spark Weekly", sparkWeekly],
-  ] as const) {
-    const percent = normalizeUsagePercent(window?.used_percent);
-    if (percent === undefined) continue;
-    const sparkWindow: { label: string; percent: number; resetAt?: number } = { label, percent };
-    const resetAt = normalizeResetAt(window?.reset_at);
-    if (resetAt !== undefined) sparkWindow.resetAt = resetAt;
-    sparkCustomWindows.push(sparkWindow);
-  }
-  if (sparkCustomWindows.length > 0) quota.customWindows = sparkCustomWindows;
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
   return hasKnownQuotaValue(quota) || resetCredits !== undefined ? quota : null;
 }
+
+
+export interface QuotaObservationEvidence {
+  writer: PoolQuotaWriter;
+  observedAt: number;
+  source: "wham" | "response-header";
+  raw: Omit<StoredAccountQuota, "updatedAt">;
+}
+
+/** Reject raw invalid readings before the compatibility parser clamps them into valid-looking bars. */
+export function isValidWhamHistoryObservation(data: WhamUsageResponse): boolean {
+  const windows = [data.rate_limit?.primary_window, data.rate_limit?.secondary_window, data.rate_limit?.tertiary_window];
+  for (const limit of Array.isArray(data.additional_rate_limits) ? data.additional_rate_limits : []) {
+    if (limit && typeof limit === "object") windows.push(limit.rate_limit?.primary_window, limit.rate_limit?.secondary_window);
+  }
+  return !windows.some(window => isInvalidPolicyUsagePercent(window?.used_percent));
+}
+
+function historyWindows(quota: Omit<StoredAccountQuota, "updatedAt">): QuotaHistoryWindow[] {
+  const windows: QuotaHistoryWindow[] = [];
+  for (const window of ["short", "weekly", "monthly"] as const) {
+    const percent = quota[`${window}Percent`];
+    const reset = quota[`${window}ResetAt`];
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) continue;
+    windows.push({ family: "account", window, usedPercent: percent,
+      ...(typeof reset === "number" && Number.isFinite(reset) && reset >= 0 ? { resetAtMs: resetAtToMs(reset) } : {}),
+      ...(window === "short" && quota.shortWindowSeconds ? { windowSeconds: quota.shortWindowSeconds } : {}),
+      ...(window === "monthly" && quota.monthlyIsPrimaryWindow ? { monthlyIsPrimaryWindow: true } : {}),
+    });
+  }
+  // No observation path emits retired Spark custom windows any more: the header parser refuses the
+  // retired model and the WHAM parser no longer derives its family, so recording one here could only
+  // resurrect evidence `withoutRetiredCodexQuota` tombstones on the way in. The `spark` family stays
+  // in the history schema so samples already persisted by older builds still parse.
+  return windows;
+}
+
+/** A cache read is bounded even if a file grows between stat and read. */
+function readQuotaCacheBounded(path: string): string {
+  const limit = 4 * 1024 * 1024;
+  const flags = fsConstants.O_RDONLY | (process.platform === "win32" ? 0 : fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW);
+  const fd = openSync(path, flags);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > limit) throw new Error("quota cache exceeds bounds");
+    const chunks: Buffer[] = [];
+    let total = 0;
+    while (total <= limit) {
+      const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, limit + 1 - total));
+      const size = readSync(fd, chunk, 0, chunk.length, null);
+      if (!size) return Buffer.concat(chunks, total).toString("utf8");
+      chunks.push(chunk.subarray(0, size)); total += size;
+    }
+    throw new Error("quota cache exceeds bounds");
+  } finally { closeSync(fd); }
+}
+
+/** Cached pool observations only. An unavailable identity never authorizes publication or deletion. */
+export function getAccountQuotaHistory(accountId: string, limit: number = QUOTA_HISTORY_LIMITS.perAccount) {
+  hydrateAccountQuotasFromDisk();
+  const result = quotaHistory.read(accountId, poolQuotaHistoryIdentity(accountId), Date.now(), limit);
+  return { observations: result.samples.map(({ credentialGeneration: _generation, ...sample }) => sample),
+    truncated: result.truncated, retention: { maxObservations: QUOTA_HISTORY_LIMITS.perAccount, maxAgeDays: 30 } };
+}

package/src/codex/refresh.ts

@@ -13,6 +13,7 @@ export interface CodexCatalogRefreshResult {
   catalogWritten: boolean;
   cacheSynced: boolean;
   comboOmissions: ComboCatalogOmission[];
+  refreshOutcome?: "committed" | "refused";
   /** Desired OFF observed under K during the catalog commit; no cache write either. */
   skippedReason?: "desired_disabled";
 }
@@ -49,7 +50,7 @@ export async function refreshCodexModelCatalog(
   const catalogExists = deps.existsSync(result.path);
   const catalogWritten = result.catalogWritten === true;
   const comboOmissions = result.comboOmissions ?? [];
-  if (result.skippedReason === "desired_disabled") {
+  if (result.skippedReason === "desired_disabled" || result.refreshOutcome === "refused") {
     // 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 };