fix: surface exhausted Kimi monthly usage automatically

[steipete]

When Kimi's monthly membership pool is exhausted but Code's shorter windows have reset, Auto currently shows unused quota. This change includes the existing known kimi-monthly window in Kimi's exhausted-window selection, fixing both the menu-bar percentage and highest-usage ranking. Partial, absent, unknown and unrelated extra windows retain their existing behavior; explicit window choices still use the standard resolver.

This extracts the display correction from #3537 and partially addresses #3536. It does not resolve the authentication portion of either report, so both remain open. Thanks @OttoPrua for identifying the monthly-pool issue.

Validation:

• Five regression assertions failed against the unchanged descriptor, across API conversion, automatic selection, the shared status resolver and highest-usage ranking.
• 189 focused tests across 22 suites passed. make check reports zero violations across 2,173 Swift files. Independent P0–P2 review is clean.
• Developer-ID-signed native tests ran the actual baseline and fixed production resolver/renderer with identical synthetic quotas. Both used the status-image path in Aqua and Dark Aqua: baseline showed 100% remaining / 0% used; fixed shows 0% remaining / 100% used. Each native run passed with zero failures. Final rebuilt captures are byte-identical to the inspected images below.
• Full make test passed all 1,061 selections across 89 groups on the first attempt, with no retries or timeouts (815.3 seconds). Exact-head CI passed every Linux x64, Linux ARM64, musl and macOS check. Merged as 9f4f544a5bf81da276fe94176aa1165c9e296b4b. The touched ranking fixture now uses in-memory settings and stubbed browser discovery.

Includes provider documentation and an Unreleased changelog entry.

Inspected synthetic native before/after proof

[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: needs maintainer review before merge. Reviewed September 10, 2026, 5:05 PM ET / 21:05 UTC (Revision 2).

ClawSweeper review

What this changes

The PR makes Kimi’s automatic usage display and highest-usage ranking consider an exhausted monthly membership pool, with regression tests, native rendering proof, and documentation.

Merge readiness

✅ Ready for maintainer review

This remains a useful, narrowly scoped fix absent from current main and v0.58.0. No actionable patch defects were found; the inspected native before/after proof supports the display correction.

Priority: P2
Reviewed head: 06ff3accab2297ed11be75e032efa61bf6f77a37

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with useful regression coverage and convincing native visual proof is ready for normal landing checks.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): The inspected native Aqua and Dark Aqua captures show the production resolver/renderer changing identical synthetic exhausted-month inputs from 100% remaining to 0% remaining, with the inverse used percentage; this supports the changed display behavior.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The inspected native Aqua and Dark Aqua captures show the production resolver/renderer changing identical synthetic exhausted-month inputs from 100% remaining to 0% remaining, with the inverse used percentage; this supports the changed display behavior.
Evidence reviewed	9 items	Repository guidance applied: Read the full root AGENTS.md. No nested AGENTS.md files were found under Sources, Tests, or docs, and .agents/maintainer-notes is absent. Applied focused scope, provider isolation, and test-isolation guidance; no builds or tests were executed during this read-only review. Current main still needs the correction: The fetched main resolver considers only primary and secondary windows before falling back to the session window; it does not consider the monthly extra window. Latest release has the same omission: The v0.58.0 descriptor also selects exhaustion from primary and secondary windows only.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar combines Kimi Code quota windows with optional monthly membership statistics. Its shared usage-window resolver selects the quota used by menu-bar rendering and highest-usage ranking.

flowchart TD
  A[Code quota windows] --> C[Combined usage snapshot]
  B[Monthly membership statistics] --> C
  C --> D{Automatic or explicit metric}
  D --> E[Automatic exhaustion selection]
  D --> F[Explicit window selection]
  E --> G[Menu-bar display and ranking]
  F --> G

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +2/-1; tests +305/-11; documentation +2/-0	Production growth is limited to selecting an existing quota window; most additions provide regression and native visual coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #3536
Summary: This PR is a candidate fix for the display portion of the broader report; authentication recovery remains separate.

Members:

• canonical: Kimi Code shows unused weekly/5h windows after monthly membership is exhausted #3536 - Tracks both missing monthly enrichment and the automatic-display omission.
• partial_overlap: fix(kimi): recover monthly Total usage from Desktop Local Storage #3537 - Includes the same display goal plus distinct Desktop credential-discovery changes.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Keep quota selection in the existing shared resolver, preserve explicit selections, and handle Desktop credential discovery separately.

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

Yes: a known monthly window at 100% used with reset Code windows makes current main select unused session quota. Source and the supplied native baseline demonstrate the mechanism; this reviewer did not execute it.

Is this the best way to solve the issue?

Yes: extending the existing Kimi resolver is a small, maintainable correction that reaches both display and ranking while preserving explicit preferences.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: Corrects misleading exhausted-quota display and ranking for Kimi users without changing authentication or other providers.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The inspected native Aqua and Dark Aqua captures show the production resolver/renderer changing identical synthetic exhausted-month inputs from 100% remaining to 0% remaining, with the inverse used percentage; this supports the changed display behavior.
• proof: sufficient: Contributor real behavior proof is sufficient. The inspected native Aqua and Dark Aqua captures show the production resolver/renderer changing identical synthetic exhausted-month inputs from 100% remaining to 0% remaining, with the inverse used percentage; this supports the changed display behavior.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected native Aqua and Dark Aqua captures show the production resolver/renderer changing identical synthetic exhausted-month inputs from 100% remaining to 0% remaining, with the inverse used percentage; this supports the changed display behavior.

Evidence

What I checked:

• Repository guidance applied: Read the full root AGENTS.md. No nested AGENTS.md files were found under Sources, Tests, or docs, and .agents/maintainer-notes is absent. Applied focused scope, provider isolation, and test-isolation guidance; no builds or tests were executed during this read-only review. (AGENTS.md:1, 06ff3accab22)
• Current main still needs the correction: The fetched main resolver considers only primary and secondary windows before falling back to the session window; it does not consider the monthly extra window. (Sources/CodexBarCore/Providers/Kimi/KimiProviderDescriptor.swift:113, cebf9995f672)
• Latest release has the same omission: The v0.58.0 descriptor also selects exhaustion from primary and secondary windows only. (Sources/CodexBarCore/Providers/Kimi/KimiProviderDescriptor.swift:113, 88fa2f45fa1e)
• Existing monthly data and shared resolver: Snapshot conversion already emits kimi-monthly from a finite shared subscription ratio. The patch filters by that identifier and usageKnown, reuses the existing exhaustion helper, and leaves explicit metrics unhandled for standard resolution. The highest-usage owner calls the same resolver. (Sources/CodexBarCore/Providers/Kimi/KimiUsageSnapshot.swift:123, 06ff3accab22)
• Native visual proof inspected: Inspected all four downloaded attachments from the captured PR body. Aqua and Dark Aqua baseline images show 100% remaining and 0% used; fixed images show 0% remaining and 100% used with identical synthetic quotas. The native harness calls the production resolver and renderer. This demonstrates rendering, not Desktop authentication recovery. (Tests/CodexBarTests/KimiMonthlyNativeProofTests.swift:35, 06ff3accab22)
• Regression coverage and reported validation: Read coverage for exhausted, partial, absent, unknown, unrelated, and explicit-window cases, API conversion, and highest-usage ranking. The captured body reports five baseline failures, 189 focused passing tests, clean make check, and a complete make test run; these results were not rerun by this reviewer. (Tests/CodexBarTests/KimiMenuBarWindowTests.swift:6, 06ff3accab22)

Likely related people:

• steipete: 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)

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 (1 earlier review cycle)

• reviewed 2026-09-10T20:50:20.412Z sha 06ff3ac :: needs maintainer review before merge. :: none

[steipete]

Merged as 9f4f544. The automatic Kimi resolver now considers a known exhausted monthly pool before reset Code windows, fixing the status percentage and highest-usage ranking while preserving explicit choices.

The patch passed 189 focused tests, all 1,061 full-suite selections without retries/timeouts, lint, independent P0–P2 review and all Linux/musl/macOS CI checks. Signed native baseline/final proof exercises the actual status-image renderer in light and dark appearances; the final images match those in the PR body byte-for-byte. The merged tree matches the integration tree checked against main.

Docs and the Unreleased changelog are updated. #3536 and #3537 remain open for the separate authentication/data-acquisition portion. Thanks @OttoPrua!