fix(codex): retire the main account's carried monthly window when WHAM shows none - #8698

Summary

The main account kept a stored monthlyPercent: 100 (with monthlyIsPrimaryWindow: true) forever once a later WHAM read stopped reporting any monthly window. #8120 retired that carried tuple for pool accounts only; parseMainPolicyUsageQuota never derived monthlyWindowAbsent, so mergeAccountQuota carried the tuple into both the main display cache and the identity-bound mainPolicyQuota. isCodexQuotaExhausted() then refused every main request locally with the usage-limit message.

This takes Option A from the issue and applies the #8120 proof to the main path:

• The monthly-absence derivation moves from poolWhamPolicyObservation into a shared withWhamMonthlyWindowAbsence. It marks absence only when the topology already proves short-window absence, no window declares a monthly duration and no tertiary window is present. It never marks absence on an explicit allowed: false, an invalid percentage or an unparseable reading (additional windows included, via the extracted hasMalformedWhamReading).
• parseMainPolicyUsageQuota applies it, so a complete main read retires the tuple in both quotas.__main__ and mainPolicyQuota. Retirement still goes through the existing main gate in setAccountQuotaFromParsed: a live, identity-current main writer. A missing or stale writer, partial WHAM and response headers keep the tuple. The marker is consumed by the merge and never persisted.
• Pool behavior is unchanged (same checks, now through the shared helper). Real monthly-primary plans (Free, Team) and a present tertiary window still replace the reading instead of retiring it.
• structure/providers/openai-tiers.md now states the main-account rule next to the [Bug]: prolite account with secondary_window: null is cached as monthlyPercent: 100 and is never selected #8067 pool rule.

The refusal wording from Option B is not changed. With the phantom tuple retired, that refusal no longer fires for this case.

Covering the points from the maintainer follow-up in tests/codex-integration/pool-monthly-window-retirement.test.ts:

• complete allowed weekly-only main read (the issue's exact payload, with and without an explicit null tertiary) retires both caches;
• denied, malformed additional window, partial, invalid/unparseable percentage, header-only and writerless reads keep both;
• A to B to A identity change: the stale writer can neither retire the tuple nor, after a live retirement, restore it with a delayed commit;
• persistence: the saved file holds no monthly fields in either cache, and a restart that hydrates exactly those bytes keeps the account usable;
• later partial, header-only and credits-only saves do not reintroduce the tuple;
• Free monthly primary, Team monthly primary plus weekly secondary, and a tertiary monthly window keep or replace the reading; the existing pool cases stay as they were.

Closes #8596

Verification

On dev 8f6d9b64e, Linux, Bun 1.4.4:

• bun test --timeout 30000 tests/codex-integration/pool-monthly-window-retirement.test.ts: 12 pass, 0 fail. With src/codex/quota.ts from dev, the 4 new retirement, persistence, save and stale-writer cases fail.
• bun run typecheck: no type errors. bun run structure:check: passed. bun run privacy:scan: passed.
• OCX_TEST_MAIN_TIMEOUT_MS=3600000 bun run test --parallel=3 --timeout 30000 over every test file that imports src/codex/quota (101 files): 3742 pass, 3 skip, 0 fail.

Full-suite exception: the shared machine this ran on was heavily loaded (load average 15 to 59 on 16 CPUs). Two bun run test runs hit the one-hour cap; the next two finished with 24 and 17 failures; two bun run test:changed runs finished with 3 and 8 failures. Every one of those was a timeout or timing assertion outside the quota code, the set differed each run, and each failing file passed when rerun alone on this branch. Rerun alone: server-auth, server-key-failover-e2e, server-xai-chat-reasoning-streaming, model-costs-pricing-cache, sse-untyped-credential-mask, request-history-index, the messages-overflow-* files, claude-messages-endpoint, claude-config-root-stale-updates, cli-message-mcp, cli-codex-cli-update, command-code-project-context, codex-composed-acceptance, update-orchestrated-pnpm-global-store-entry and the test-runner fixtures. tests/clients/link-supervisor.test.ts fails here on unmodified dev too (its fixed /tmp/opencodex-link-supervisor-test directory belongs to another user on this machine) and was excluded. The full suite is left to CI.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Screenshots

The issue's sequence through the real quota code: a stored monthly-primary 100% reading for main, then the issue's WHAM payload (Plus, weekly 1%, secondary_window: null).

Before	After

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes
  • Monthly quota details are now cleared from quota displays when a complete, valid account update confirms that no monthly quota window applies.
  • Incomplete or invalid updates, explicit denials, and header-only or credits-only updates continue to preserve existing monthly quota details.
• Documentation
  • Clarified when monthly quota details are cleared or retained.