# Rate-limit Freshness Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use /ship (recommended) or /executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make periodic and icon-triggered probes authoritative while rendering only real Codex quota windows.

**Architecture:** Normalize provider response at health-client boundary. Preserve stale quotas only for failed probes; successful absence clears cache and both UI surfaces. Reuse existing GTK account-card quota rows.

**Tech Stack:** Python 3, pytest, GTK 3.

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|------|-------|---------------|----------------------|
| 1 | Task 1, Task 2, Task 3, Task 4 | `health_client.py`, `tests/test_health_client.py`; `indicator.py`, `tests/test_indicator.py`; `ui/view_model.py`, `tray_model.py`, `tests/test_ui_view_model.py`, `tests/test_tray_model.py`; `ui/account_card.py`, `tests/test_ui_account_card.py` | Yes — disjoint files |

### Task 1: Codex Window Normalization

**Wave:** 1  
**Blocks:** —  
**Blocked by:** —

**Files:**
- Modify: `health_client.py` — classify rate-limit windows from duration metadata.
- Test: `tests/test_health_client.py`

**Contract:**
- Preserve `AccountHealthClient.fetch(codex_home: Path, timeout_secs: float = 10.0) -> AccountSnapshot`.
- `windowDurationMins == 300` maps to primary/5h fields.
- `windowDurationMins == 10080` maps to secondary/7d fields.
- Missing duration uses legacy positional mapping; explicit unsupported duration maps to neither semantic slot.

**Acceptance:**
- Run: `pytest -q tests/test_health_client.py`
- Expected: PASS; duration-aware single weekly window never populates 5h fields.

- [ ] Write failing parser tests.
- [ ] Run tests and confirm expected failure.
- [ ] Implement minimal normalization.
- [ ] Run acceptance check.

### Task 2: Authoritative Refresh Semantics

**Wave:** 1  
**Blocks:** —  
**Blocked by:** —

**Files:**
- Modify: `indicator.py` — force popup probe and clear successful absent windows.
- Test: `tests/test_indicator.py`

**Contract:**
- `_open_popup()` invokes `_refresh_all(force=True)` once per open.
- Tray menu `show` invokes `_refresh_all(force=True)` once; no duplicate `popped-up` handler.
- `_merge_snapshot()` preserves cached quotas for non-OK results only.
- `_merge_snapshot()` preserves cached quota `checked_at` for non-OK results.
- Successful missing fields clear cached percentages/reset times and existing UI update path hides rows.

**Acceptance:**
- Run: `pytest -q tests/test_indicator.py tests/test_ui_view_model.py tests/test_ui_account_card.py tests/test_ui_provider_tab.py`
- Expected: PASS; fresh popup probes execute and successful absent windows disappear.

- [ ] Write failing refresh/merge tests.
- [ ] Run tests and confirm expected failures.
- [ ] Implement minimal refresh changes.
- [ ] Run acceptance check.

### Task 3: Reset Countdown Validity

**Wave:** 1  
**Blocks:** —  
**Blocked by:** —

**Files:**
- Modify: `ui/view_model.py`, `tray_model.py` — omit invalid reset countdowns.
- Test: `tests/test_ui_view_model.py`, `tests/test_tray_model.py`

**Contract:**
- Future reset timestamps render provider-native countdown text.
- Missing or expired reset timestamps render no countdown in dashboard or tray menu.

**Acceptance:**
- Run: `pytest -q tests/test_ui_view_model.py tests/test_tray_model.py`
- Expected: PASS; expired timestamps never render `0m`.

- [ ] Write failing expired-reset tests.
- [ ] Run tests and confirm expected failures.
- [ ] Implement minimal reset validity guard.
- [ ] Run acceptance check.

### Task 4: Native GTK Quota Row Visibility

**Wave:** 1  
**Blocks:** —  
**Blocked by:** —

**Files:**
- Modify: `ui/account_card.py` — map present quota-row children under GTK `no-show-all` semantics.
- Test: `tests/test_ui_account_card.py`

**Contract:**
- Present quota rows temporarily disable `no-show-all`, map row children, then restore suppression.
- Missing quota rows remain hidden through parent `show_all()` calls.

**Acceptance:**
- Run: `pytest -q tests/test_ui_account_card.py`
- Expected: PASS; strict visibility fake records unsuppressed `show_all()` for present rows.

- [ ] Write failing strict GTK visibility test.
- [ ] Run test and confirm expected failure.
- [ ] Implement minimal visibility sequencing fix.
- [ ] Run acceptance check.

## Decision Enumeration

No human gate. Changes are reversible, local, and preserve existing data contracts.