fix(codex): lift nested child cooldowns on parent clear and on snapshot headroom

[HouMinXi]

Bug Description

Two ways a Codex account stays skipped after its quota is actually back.

#12817 — Clearing a Codex cooldown from the dashboard (or the CAS recovery path) only nulls rate_limited_until. Dispatch still reads providerSpecificData.codexScopeRateLimitedUntil, so the account stays skipped.

#12860 — Quota preflight parks a cooldown at the reported next_reset_at. When a later snapshot shows the window recovered early, nothing removes that timestamp, so the account keeps getting skipped until the original deadline passes.

Fixes #12817
Fixes #12860

Root Cause

Codex writes per-scope timestamps into JSON (codex / spark) without always mirroring them onto the parent column. Every "clear cooldown" path only touched that column, and no path ran in the other direction: a fresh snapshot proving headroom had no way to retire a cooldown the preflight had written.

Fix

Parent column → nested maps (#12817):

• PUT rateLimitedUntil: null or "" also drops the nested Codex maps
• clearConnectionRateLimit nulls the parent column and the nested maps in one transaction
• CAS recovery (clearConnectionErrorIfUnchanged) uses json_remove in the same UPDATE
• A 200 quota observation drops that child's leftover only; Spark stays

Snapshot → nested maps (#12860):

• liftCodexScopeCooldownOnHeadroom(id, scope) retires a scope cooldown when a snapshot proves headroom, inside one transaction
• saveQuotaSnapshot calls it after persisting a Codex row with remaining_percentage > 0 and is_exhausted !== 1
• Only fallback-sourced cooldowns are eligible. A cooldown sourced from an upstream 429 quota_reset is authoritative and is held until it expires, with a 30s grace window so local clock skew cannot release it early
• Every window in the scope must report headroom: one exhausted window still justifies the cooldown even when a sibling reports full
• hasCodexScopeCooldown short-circuits before the scope-wide snapshot read, so the common (clean) connection pays one indexed lookup and no backup

Non-Codex connections are unchanged. Crash recovery still keeps future nested timestamps (they are live quota windows).

How to Verify

Parent column path:

1. Persist Codex + Spark child cooldowns on one connection.
2. PUT { "rateLimitedUntil": null } (or click Clear cooldown).
3. getCodexChildCooldown for both models returns null; unrelated JSON is still there.
4. A 200 quota observation for gpt-5.5 clears only the Codex child; Spark remains limited.

Snapshot path:

5. Park a fallback cooldown on the codex scope with a reset an hour out.
6. Save a snapshot for that connection with remaining_percentage: 100, is_exhausted: 0.
7. The codex entry is gone; a Spark cooldown on the same connection is untouched.
8. Repeat with the cooldown sourced from quota_reset — it survives.

Test Plan

• tests/unit/codex-scope-cooldown-clear-12817.test.ts — 14 tests covering both issues (PUT null, PUT empty string, clearConnectionRateLimit, CAS, 200 observation, non-Codex, snapshot lift, quota_reset protection, skew grace boundary on both sides, partial-window hold, Spark isolation, short-circuit probe)
• Existing codex-account-cooldown-write, codex-account-helpers, quota-connection-recovery still pass (40/40 combined)
• Injection, each behavior separately: drop the PUT strip → red; drop the snapshot call → red; remove the skew grace → red; make the short-circuit probe ignore scope → red. Restore → green.
• typecheck:core, check:cycles (427 files), check-docs-sync clean

Risk Assessment

Low. Nested maps are Codex-only, and the snapshot lift is gated on provider codex plus a fallback source. Spark sibling state is preserved on a Codex-only 200 and on a Codex-only snapshot. The write runs in one transaction that re-reads the row under lock, so a concurrent cooldown write cannot be lost. providers.ts shrank 1186 → 1137 (CAS moved to rateLimit.ts).

[xiaoyaner0201]

Thanks for addressing both the manual-clear and restored-quota paths. I added an independent affected-instance observation to #12860: fresh weekly usage showed 100% remaining while a legacy fallback Codex child cooldown kept the account excluded; removing only the stale child-map entries restored real traffic without a restart.

Could the regression coverage also exercise the reset-credit button's actual service path, rather than only the generic parent clear and direct snapshot writes?

At consumeCodexResetCredit on the current release, a recognized consume outcome invalidates the quota cache and calls fetchAndPersistProviderLimits. It does not directly invoke the parent clear path. The snapshot reconciliation in this patch looks relevant, but I have not run this PR and cannot claim that the whole button path passes.

A useful regression would seed a future legacy fallback child cooldown, mock a successful reset redemption plus fresh healthy weekly usage, invoke consumeCodexResetCredit, then assert the persisted Codex child is eligible without another manual clear or restart. It should preserve an unrelated Spark cooldown and retain protection on failed redemption, incomplete refresh, or a newer concurrent cooldown. An alreadyRedeemed retry should likewise rely on verified fresh quota evidence rather than unconditionally clearing current limits.

That would directly cover the operator-visible symptom: “reset succeeded and the quota bar refilled, but requests still cannot use the account.” Related alternative reconciliation work: #13073.

[HouMinXi]

Thanks — that was the operator-visible hole.

consumeCodexResetCredit already invalidated the quota cache and called fetchAndPersistProviderLimits after a recognized redeem. That live-fetch writes setQuotaCache, which persists snapshots and is the same headroom lift as a dashboard usage refresh. The missing piece was a regression that actually invoked the button function instead of writing a snapshot by hand.

Added four cases on that path:

• leftover fallback Codex child + successful redeem + healthy weekly usage → Codex child eligible, Spark child still parked
• alreadyRedeemed without headroom (used_percent: 100) → nested maps stay
• failed consume (HTTP 409 noCredit) → nested maps stay
• incomplete usage refresh (usage endpoint 500; getCodexUsage swallows that into {message} and still returns from consume) → nested maps stay

No extra production branch: the button already rode the snapshot path. Coverage now pins it so a filled quota bar after reset cannot leave the leftover fallback child parked.

Pushed on this PR (af2ed0194). Related: #12860, #13073.