Handling multi-window AI provider limits without stale state

Problem: coding-agent providers can report a five-hour window, a seven-day window, both, or—depending on account state—only a weekly primary window. Treating “primary” as always five-hour silently displays the wrong constraint and preserves stale state.

Why positional parsing fails

A naive parser maps primary → fiveHour and secondary → sevenDay. That works until the provider sends one primary window whose explicit duration is 10080 minutes. The UI then labels weekly utilization as five-hour usage. If an old five-hour value remains cached, the operator sees two misleading limits.

Boundary normalization

Exocortex receives some Codex rate-limit data as WebSocket JSON events rather than ordinary HTTP response headers. The provider adapter first normalizes the event into the same header-shaped boundary consumed by the existing parser:

primary.used_percent   → x-codex-primary-used-percent
primary.window_minutes → x-codex-primary-window-minutes
primary.reset_at       → x-codex-primary-reset-at

This keeps transport-specific decoding separate from domain-specific usage interpretation.

Classify by duration, then use position only as fallback

FIVE_HOUR_MINUTES = 5 × 60
SEVEN_DAY_MINUTES = 7 × 24 × 60

observed = [primary, secondary]
fiveHour = observed.find(window_minutes == FIVE_HOUR_MINUTES)
sevenDay = observed.find(window_minutes == SEVEN_DAY_MINUTES)

Known duration metadata wins. Positional compatibility remains only for older responses without durations or unexpected windows. When the sole primary window explicitly says seven days, the cached five-hour value is cleared rather than retained.

Important state rule

“Field absent” and “window explicitly replaced” are different events:

Without duration metadata, absence may mean the provider omitted an unchanged value, so retaining previous state can be correct.
With explicit duration metadata showing that primary is weekly, retaining an old five-hour primary is incorrect; it must become null.

Tests that matter

Both windows present with 300- and 10,080-minute durations.
A lone seven-day primary window after both values were previously cached.
WebSocket normalization preserves duration and reset metadata.
Unknown or missing durations retain backward-compatible positional behavior.
The status display renders a weekly-only account without inventing a five-hour value.

Operational consequence

Correct limit state is more than status-line polish. A scheduler can use window type + reset_at + capability to stop retry loops and select another compatible provider or account only when useful. Without that model, “fallback” frequently means repeatedly hitting routes that cannot recover yet.

Public implementation

The complete change is visible in Exocortex commit ef874ec — Handle weekly-only OpenAI usage limits. It includes transport normalization, parser behavior, display changes, and focused tests.

Have an agent workflow with ambiguous retries, limits, or recovery? Start with the free reliability checklist, or request a fixed-scope review.

This case study describes public repository behavior and does not claim client results or provider guarantees.