Add recorded quota burndown alongside plan usage history

[callmejustdodo]

Maintainer review

This proposes a menu burndown view and requests feature sign-off under VISION.md. It reuses account-scoped quota history and adds no dependencies or authentication changes.

Summary

• Show recorded remaining-quota samples against an even-use guide for active saved windows in Codex and Claude's Plan Usage menu.
• Keep the original utilization chart below the burndown, including its existing refresh behavior.
• Explicitly show the last-known capture age for the selected series; a future reset alone is not evidence of fresh live usage.
• Show localized weekday, month, date, and time at weekly and other multi-day endpoints. Session endpoints remain compact.

Review follow-up

• Preserved utilization history and added a regression test covering native lazy hydration and refresh after the active window expires.
• Added capture-age tests for independent Weekly/Opus series and older saved samples.
• Added a DEBUG-only, isolated synthetic fixture for the production native submenu, before normal provider startup. It disables Keychain access and provider polling.
• Native-menu accessibility verification confirmed both charts and the updated weekly calendar endpoints.

Verification

• Fresh focused build/test: 69 tests in 5 suites passed, including the model, chart, hosted-submenu refresh, provider architecture gate, and rendering fixture.
• make check: passed.
• make test: run; stopped in group 10/130 on two AdaptiveRefreshTimerTests cancellation errors, reproduced on the runner's retry. Those timer files are unchanged by this PR. Earlier initial implementation verification passed all 1,438 selected tests; that result is not claimed for this follow-up.
• Local installation uses the verified development executable with the existing app resources and widget; binary hash, signature, and running process checked. Release packaging was interrupted when the local Xcode beta toolchain disappeared during compilation.

Native menu proof

Synthetic data from the freshly built running DEBUG fixture, captured before the calendar-label follow-up. It demonstrates the last-known label and the preserved original utilization chart.

Updated weekly labels

Hosted-view rendering of the final weekly view. The updated endpoint strings were also verified in the running native submenu's accessibility tree.

Reproduction instructions

Limits

This plots provider-reported quota percentages, not exact token totals. The observed line gains detail as CodexBar records more snapshots. Saved samples remain explicitly last-known; feature sign-off is still a maintainer decision.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 27, 2026, 11:46 PM ET / September 28, 2026, 03:46 UTC (Revision 4).

ClawSweeper review

What this changes

Adds a recorded remaining-quota chart with an even-use guide and capture-age label above the existing Codex and Claude Plan Usage history, with tests, documentation, and synthetic menu proof.

Merge readiness

⛔ Blocked before merge - 4 items remain

The feature remains useful and is absent from current main, but a saved-history compatibility defect remains at the reviewed head. VISION.md also requires maintainer sign-off for this new menu feature.

Priority: P2
Reviewed head: 32119dae74814f53437959a88c7646c4d0fe7b2d
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The native UI proof is strong, but saved-history naming remains incorrect and the new feature still needs direction sign-off.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): A freshly built DEBUG fixture exercises the production native Plan Usage submenu with synthetic saved Codex captures; the matching native screenshot shows the burndown, capture-age text, and retained utilization chart. A separate final hosted-view image shows the updated weekly endpoints, with native accessibility verification reported in the PR. No stored-data contract changes.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): A freshly built DEBUG fixture exercises the production native Plan Usage submenu with synthetic saved Codex captures; the matching native screenshot shows the burndown, capture-age text, and retained utilization chart. A separate final hosted-view image shows the updated weekly endpoints, with native accessibility verification reported in the PR. No stored-data contract changes.
Evidence reviewed	8 items	Introduced menu behavior: The branch adds the burndown above the retained utilization chart for Codex and Claude. Unresolved legacy naming: The new picker titles and identifies series from the stored name. A legacy 43,200-minute Codex series stored as Session or Weekly is therefore presented under that name. Existing classification contract: The existing utilization chart explicitly normalizes pre-classification 43,200-minute Codex history through the provider presentation policy, so the two charts can disagree after upgrade.
Findings	1 actionable finding	[P2] Classify saved 30-day Codex windows before naming burndown tabs
Security	None	None.

How this fits together

CodexBar records provider quota samples by account and reset window. The Plan Usage submenu reads those samples and presents utilization history; this PR adds a remaining-quota view to that submenu.

flowchart LR
  A[Codex and Claude quota samples] --> B[Account-scoped saved history]
  B --> C[Plan Usage submenu]
  C --> D[Choose active window]
  D --> E[Remaining-quota chart]
  D --> F[Existing utilization chart]

Loading

Decision needed

Question	Recommendation
Should CodexBar add a second quota-history chart to the Codex and Claude Plan Usage submenu once the saved 30-day naming defect is repaired?	Sponsor the feature after repair: Accept the additional menu chart after saved-history classification is made consistent and its upgrade case is covered.

Why: VISION.md requires sign-off for new features, and the available discussion contains no maintainer approval of this menu surface.

Before merge

• Classify saved 30-day Codex windows before naming burndown tabs (P2) - Saved Codex history can retain a Session or Weekly name for a 43,200-minute window. This new switch uses that stored name, while the existing utilization chart normalizes the same history to Monthly, so upgraded users can see contradictory tabs for one window. Reuse the provider classification and cover a saved-history case.
• Resolve merge risk (P1) - An upgraded user with saved 30-day Codex history can see that burndown labeled Session or Weekly beside an existing chart that correctly calls the same window Monthly.
• Complete next step (P2) - Normalize the saved 30-day Codex series, add upgrade coverage, and obtain maintainer feature sign-off before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P2] Classify saved 30-day Codex windows before naming burndown tabs — Sources/CodexBar/QuotaBurndownChartMenuView.swift:40-44

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Source and test growth	production +512 lines, tests +360 lines	The production total includes a 235-line DEBUG-only native proof fixture; feature sign-off should account for that maintenance footprint.

Merge-risk options

Maintainer options:

1. Normalize saved Codex windows (recommended)
   Apply the existing provider classification to burndown series and verify a saved 43,200-minute Session or Weekly series displays as Monthly.
2. Pause the menu addition
   Defer the feature if the extra chart and its compatibility handling are not worth the menu complexity.

Technical review

Best possible solution:

Use the existing provider series classification when building burndown tabs, add a saved 30-day history regression case, and keep the visualization only if its added menu complexity receives feature sign-off.

Do we have a high-confidence way to reproduce the issue?

Yes for the review finding: supply saved Codex history named Session or Weekly with a 43,200-minute window and an active reset. Source inspection shows the new picker keeps that name while the existing chart normalizes it to Monthly; the case was not executed here.

Is this the best way to solve the issue?

Yes, subject to feature sign-off and the compatibility repair. Reusing account-scoped saved samples and retaining the original chart is a coherent path; the new picker should reuse the existing classification policy.

Full review comments:

• [P2] Classify saved 30-day Codex windows before naming burndown tabs — Sources/CodexBar/QuotaBurndownChartMenuView.swift:40-44
  Saved Codex history can retain a Session or Weekly name for a 43,200-minute window. This new switch uses that stored name, while the existing utilization chart normalizes the same history to Monthly, so upgraded users can see contradictory tabs for one window. Reuse the provider classification and cover a saved-history case.
  Confidence: 0.96

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 579f68406855.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This is a bounded menu improvement with one saved-history compatibility defect.
• merge-risk: 🚨 compatibility: The new chart can misname existing saved 30-day Codex windows after upgrade.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): A freshly built DEBUG fixture exercises the production native Plan Usage submenu with synthetic saved Codex captures; the matching native screenshot shows the burndown, capture-age text, and retained utilization chart. A separate final hosted-view image shows the updated weekly endpoints, with native accessibility verification reported in the PR. No stored-data contract changes.
• proof: sufficient: Contributor real behavior proof is sufficient. A freshly built DEBUG fixture exercises the production native Plan Usage submenu with synthetic saved Codex captures; the matching native screenshot shows the burndown, capture-age text, and retained utilization chart. A separate final hosted-view image shows the updated weekly endpoints, with native accessibility verification reported in the PR. No stored-data contract changes.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. A freshly built DEBUG fixture exercises the production native Plan Usage submenu with synthetic saved Codex captures; the matching native screenshot shows the burndown, capture-age text, and retained utilization chart. A separate final hosted-view image shows the updated weekly endpoints, with native accessibility verification reported in the PR. No stored-data contract changes.

Evidence

What I checked:

• Introduced menu behavior: The branch adds the burndown above the retained utilization chart for Codex and Claude. (Sources/CodexBar/StatusItemController+UsageHistoryMenu.swift:52, 32119dae7481)
• Unresolved legacy naming: The new picker titles and identifies series from the stored name. A legacy 43,200-minute Codex series stored as Session or Weekly is therefore presented under that name. (Sources/CodexBar/QuotaBurndownChartMenuView.swift:40, 32119dae7481)
• Existing classification contract: The existing utilization chart explicitly normalizes pre-classification 43,200-minute Codex history through the provider presentation policy, so the two charts can disagree after upgrade. (Sources/CodexBar/PlanUtilizationHistoryChartMenuView.swift:237, 579f68406855)
• Saved format: Saved series retain a name and duration, and decoding does not reclassify the name. (Sources/CodexBar/PlanUtilizationHistoryStore.swift:56, 579f68406855)
• Real menu proof: The downloaded native submenu screenshot matches the committed image and visibly shows both charts and the last-known capture-age label. The separate final weekly render matches its committed image and shows calendar endpoints; the PR body reports final-label verification in the native accessibility tree. (docs/widgets/burndown-native-synthetic.png, 32119dae7481)
• Feature scope: VISION.md places new features under Needs Sign-Off; this is a new menu visualization rather than a repair to a defined existing behavior. (VISION.md:13, 579f68406855)

Likely related people:

• Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Yuxin Qiao: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Normalize saved 30-day Codex series and test the upgrade case.
• Obtain maintainer sign-off for the additional Plan Usage chart.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-28T02:34:09.542Z sha 7a279fa :: needs real behavior proof before merge. :: [P1] Keep the existing utilization history accessible | [P2] Check the live window before presenting history as current
• reviewed 2026-09-28T02:38:47.098Z sha 7a279fa :: needs real behavior proof before merge. :: [P1] Keep the existing utilization history accessible | [P2] Check the live window before presenting history as current
• reviewed 2026-09-28T03:38:41.437Z sha 32119da :: blocked before merge. :: [P2] Classify legacy 30-day Codex history before naming burndown tabs