fix(providers): clarify Kimi and z.ai quota availability

[steipete]

Kimi could display fresh 5-hour and weekly capacity while its known monthly membership pool was exhausted. The menu card now marks shorter windows as Blocked by monthly limit through the shared quota-binding check. Raw usage, monthly reset information, and explicit menu-bar selections are preserved. Nearby value-copy and initializer cleanup keep production code at 84 insertions / 85 deletions (net −1).

z.ai now explains empty or unsupported quota shapes and points users to Usage Dashboard. Mixed responses retain recognized quotas and identify unavailable additional quota. No confirmed V3 payload was present in #2522, so this does not claim V3 compatibility. The full quota screenshot from #2871 is now a fixture: the existing parser retains its 300-minute window and renders the exact reset as 20:09 in America/Santiago; #3416 already rejects impossible five-hour resets.

Verification

Tests ran against a complete Git tree matching the staged candidate on an isolated macOS worker, using synthetic fixtures and credential/session isolation.

CODEXBAR_KIMI_BLOCKING_PROOF_DIR=.proof-after-final ./Scripts/test_fast.sh --build-system native --jobs 2 --filter 'Kimi|Zai|MenuCard|PaceVisibility|ProviderPresentationPolicyCharacterizationTests|ProviderArchitectureGatekeeperTests|ProviderPluginDetailsParityTests'
CODEXBAR_PLUGIN_ENGINE=javascriptcore ./Scripts/test_fast.sh --build-system native --skip-build --filter ZaiPluginResetTests
make check

• Focused run: 642 Swift tests passed; native rendering: 1 passed, with 6 unrelated opt-in captures skipped.
• JavaScriptCore reset suite: 6 passed. z.ai parsing fixtures also run under both plugin engines.
• Red → green: the original implementation failed the Kimi blockers with 30 issues. The final z.ai fixture matrix failed the original plugin with 30 issues, including missing, null, numeric, and future string limit types; the patched provider passes.
• Formatting, strict lint, repository checks, and independent review passed.

Synthetic native rendering

These use the production MetricRow renderer with synthetic data.

Before	After

#3536 remains open for Desktop Local Storage token discovery, which is outside this presentation fix. Thanks @OttoPrua, @carolitascl, and @LeoLin990405 for the reports and evidence.

Closes #2871
Refs #2522
Refs #3536

[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 28, 2026, 1:05 AM ET / 05:05 UTC (Revision 2).

ClawSweeper review

What this changes

The branch makes CodexBar’s Kimi menu card show when an exhausted monthly quota blocks shorter windows, adds z.ai guidance for unavailable quota responses, and updates tests and documentation.

Merge readiness

⛔ Blocked before merge - 4 items remain

Keep this PR open. Current main still lacks the proposed Kimi menu-card behavior and z.ai unavailable-state guidance. The scoped patch has focused coverage, but its closing reference would close a reset report that the new fixture does not resolve, and the repository-required full test run is not recorded.

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

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Focused coverage and visible Kimi renderer evidence support a sound scoped patch, with linked-report resolution and the repository’s full-suite gate still outstanding.
Proof confidence	🐚 platinum hermit (4/6)	Not applicable: The owner-authored PR is exempt from the external-contributor proof gate. Prepared synthetic before and after images exercise the production Kimi MetricRow renderer and show the blocked rows; bundled z.ai parser fixtures cover unavailable shapes but do not prove the separate live reset mismatch. No stored-data contract changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The owner-authored PR is exempt from the external-contributor proof gate. Prepared synthetic before and after images exercise the production Kimi MetricRow renderer and show the blocked rows; bundled z.ai parser fixtures cover unavailable shapes but do not prove the separate live reset mismatch. No stored-data contract changes.
Evidence reviewed	10 items	Introduced Kimi presentation: The introduced helper projects an actively exhausted known monthly window onto shorter Kimi menu-card metrics and removes their misleading reset and pace text. Current-main gap: The pinned main revision returns menu-card metrics without the introduced monthly blocking pass. Distinct existing Kimi behavior: Current main already prioritizes a known exhausted monthly window for automatic menu-bar selection; this PR addresses the separate menu-card rows.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar turns provider quota responses into usage snapshots and displays them in its menu card and usage details. Kimi’s Swift provider supplies monthly and shorter windows; the bundled z.ai JavaScript provider parses its quota response.

flowchart LR
A[Kimi quota responses] --> B[Kimi usage snapshot]
C[z.ai quota response] --> D[z.ai plugin parser]
B --> E[Quota presentation]
D --> E
E --> F[Menu card and usage details]

Loading

Decision needed

Question	Recommendation
Does the screenshot-derived fixture justify closing #2871 when this PR merges?	Keep the reset report open: Use a non-closing reference in the PR body and merge commit message, and assess the reset discrepancy when a complete same-refresh trace is available.

Why: The fixture verifies the parser’s existing conversion, while the prior owner discussion requires evidence of the reported display mismatch at the same refresh.

Before merge

• Resolve merge risk (P1) - Merging with the closing reference in the PR body or commit message could close bug(z.ai) Reset time shows 10 hrs window instead of 5 hours (again in 0.49.2) #2871 although this branch does not establish that its reported same-refresh reset mismatch is resolved.
• Resolve merge risk (P1) - The PR records focused tests and make check, but not the full make test run required by this repository’s handoff policy.
• Complete next step (P2) - Resolve the linked reset report’s closing syntax in the PR body and merge commit message, then record a safe full make test result before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test lines	production +84/−85; tests +238/−1	The production change is net small and has substantial focused regression coverage.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Land the scoped quota presentation changes with the reset report still open for a complete same-refresh response and display trace, after a safe full-suite run.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Land the scoped quota presentation changes with the reset report still open for a complete same-refresh response and display trace, after a safe full-suite run.

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

Yes for the Kimi display defect: the supplied synthetic before and after renderer images and source path show an exhausted month beside fresh shorter windows. The historical z.ai same-refresh display mismatch is not reproduced by the new fixture.

Is this the best way to solve the issue?

Yes for the scoped Kimi presentation and z.ai unavailable-state guidance. The reset fixture is useful characterization, but it does not establish closure of the separate display report.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

No label changes.

Label justifications:

• P2: This is a bounded provider-usage presentation repair with limited user impact.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The owner-authored PR is exempt from the external-contributor proof gate. Prepared synthetic before and after images exercise the production Kimi MetricRow renderer and show the blocked rows; bundled z.ai parser fixtures cover unavailable shapes but do not prove the separate live reset mismatch. No stored-data contract changes.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The owner-authored PR is exempt from the external-contributor proof gate. Prepared synthetic before and after images exercise the production Kimi MetricRow renderer and show the blocked rows; bundled z.ai parser fixtures cover unavailable shapes but do not prove the separate live reset mismatch. No stored-data contract changes.

Evidence

What I checked:

• Introduced Kimi presentation: The introduced helper projects an actively exhausted known monthly window onto shorter Kimi menu-card metrics and removes their misleading reset and pace text. (Sources/CodexBar/MenuCardView+ModelHelpers.swift:232, d5e0d0f3dab4)
• Current-main gap: The pinned main revision returns menu-card metrics without the introduced monthly blocking pass. (Sources/CodexBar/MenuCardView.swift:1247, 579f68406855)
• Distinct existing Kimi behavior: Current main already prioritizes a known exhausted monthly window for automatic menu-bar selection; this PR addresses the separate menu-card rows. (Sources/CodexBarCore/Providers/Kimi/KimiProviderDescriptor.swift:140, d5e0d0f3dab4)
• z.ai parser change: Unknown string limit types are skipped, while empty or partly unrecognized responses gain an unavailable-state detail row; recognized limits remain available. (Sources/CodexBarCore/Resources/Plugins/zai.js:180, d5e0d0f3dab4)
• Kimi visual proof: The prepared before and after images show synthetic data through the production MetricRow renderer: fresh-looking shorter windows become rows labeled “Blocked by monthly limit.”. (Tests/CodexBarTests/KimiMonthlyBlockingTests.swift:129, d5e0d0f3dab4)
• Reset fixture scope: The added screenshot-derived fixture checks five-hour selection and epoch conversion to 20:09 in Santiago; it does not reproduce the reported same-refresh CodexBar-versus-ZCode display discrepancy. (TestsPlugin/ZaiPluginResetTests.swift:12, d5e0d0f3dab4)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• xirong: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• kiranmagic7: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• zhiyue: 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.

• Resolve the closing reference to bug(z.ai) Reset time shows 10 hrs window instead of 5 hours (again in 0.49.2) #2871 against the available evidence.
• Record a safe full make test run before handoff.

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-28T04:12:25.060Z sha d5e0d0f :: blocked before merge. :: none