Fix z.ai BigModel CN quota parsing

[joeVenner]

Summary

• accept successful BigModel CN quota responses that omit the optional msg field
• keep existing API error details when the field is present and use a safe fallback otherwise
• cover the exact payload from z.ai (BigModel CN) usage bars are wrong: MCP shows 100%, token windows show 0% #1855, including weekly, 5-hour, and MCP usage mapping

Closes #1855.

Runtime proof

Ran the freshly built CLI through the full API request and rendering path against the exact redacted issue payload served by an HTTPS fixture endpoint. The request used a dummy token; no real account, browser data, or Keychain entry was accessed.

$ Z_AI_API_KEY=<dummy> Z_AI_QUOTA_URL=<https-fixture> .build/debug/CodexBarCLI usage --provider zai --source api --format json --pretty
[
  {
    "provider" : "zai",
    "source" : "api",
    "usage" : {
      "primary" : {
        "resetDescription" : "1 week window",
        "usedPercent" : 7,
        "windowMinutes" : 10080
      },
      "secondary" : {
        "resetDescription" : "Monthly",
        "usedPercent" : 14.7
      },
      "tertiary" : {
        "resetDescription" : "5 hours window",
        "usedPercent" : 8,
        "windowMinutes" : 300
      }
    }
  }
]

This verifies the successful response without msg reaches the CLI and preserves all three reported usage lanes.

Testing

• swift test --disable-sandbox --filter ZaiProviderTests (39 tests passed)
• make check completed all repository checks and reported 0 SwiftFormat/SwiftLint violations; the managed sandbox denied SwiftLint's final cache write
• full sharded make test was attempted with writable test caches; it reached unrelated baseline failures in KeychainNoUIQueryTests where LAContext.interactionNotAllowed remains false on this host

No real provider account, browser-cookie, or Keychain probe was run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 3, 2026, 6:14 PM ET / 22:14 UTC.

Summary
The branch makes the z.ai quota response msg optional, adds fallback API error text, adds BigModel CN parser coverage, and updates the unreleased changelog.

Reproducibility: yes. Current main requires msg in the quota envelope while the payload in #1855 omits it, so source inspection shows decoding fails before the existing mapping runs.

Review metrics: 2 noteworthy metrics.

• Changed surface: 3 files changed, +74/-2. The diff is small and concentrated in one provider parser, its tests, and an unreleased changelog note.
• Runtime source delta: 1 provider source file changed, +8/-2. Runtime behavior is limited to quota envelope decoding and fallback API error text.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #1855
Summary: This PR is the candidate fix for the open Z.ai BigModel CN parser issue whose exact no-msg payload it covers.

Members:

• canonical: z.ai (BigModel CN) usage bars are wrong: MCP shows 100%, token windows show 0% #1855 - The issue contains the exact BigModel CN quota payload and this PR explicitly closes it.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] The PR body reports full sharded make test reached unrelated local KeychainNoUIQueryTests baseline failures, and GitHub CI was still queued/in progress during review, so maintainers should rely on final CI before merge.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow optional-msg parser fix with the added BigModel CN fixture once maintainers are satisfied with CI.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No automated repair is needed; the remaining action is maintainer review, final CI, and merge handling for the linked fix candidate.

Security
Cleared: The diff only changes JSON decoding, parser tests, and an unreleased changelog entry; it does not touch dependencies, scripts, secrets, permissions, or code execution paths.

Review details

Best possible solution:

Land the narrow optional-msg parser fix with the added BigModel CN fixture once maintainers are satisfied with CI.

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

Yes. Current main requires msg in the quota envelope while the payload in #1855 omits it, so source inspection shows decoding fails before the existing mapping runs.

Is this the best way to solve the issue?

Yes. The PR fixes the narrow decoding gap, preserves API error details when available, and pins the exact BigModel CN response shape in parser coverage.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This fixes a concrete provider usage parsing bug with limited blast radius to Z.ai BigModel CN quota display.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal output from a freshly built CLI against an HTTPS fixture with the exact redacted payload and a dummy token, showing all three quota lanes after the fix.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal output from a freshly built CLI against an HTTPS fixture with the exact redacted payload and a dummy token, showing all three quota lanes after the fix.

Evidence reviewed

Acceptance criteria:

• [P1] swift test --disable-sandbox --filter ZaiProviderTests.
• [P1] make check.
• [P1] make test.

What I checked:

• Repository policy read: AGENTS.md was read fully; its guidance favored focused parser/CLI validation and avoiding live provider, browser-cookie, or Keychain probes for this provider parsing review. (AGENTS.md:1, a310c42774ce)
• Current main still requires msg: Current main decodes ZaiQuotaLimitResponse.msg as a required String, so the linked successful BigModel CN payload that omits msg fails before quota mapping can run. (Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift:247, a310c42774ce)
• Existing usage mapping is already in place: Current main already falls back to the decoded percentage field and maps token windows into primary/tertiary usage lanes, so the remaining bug is the quota envelope decode gap. (Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift:83, a310c42774ce)
• PR diff is narrow: The PR changes the quota envelope to String?, routes failures through a fallback errorMessage, and adds the exact no-msg BigModel CN fixture plus a no-message error case. (Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift:249, 52f523a61552)
• Linked issue and proof: The PR explicitly closes z.ai (BigModel CN) usage bars are wrong: MCP shows 100%, token windows show 0% #1855, whose raw payload omits msg; the PR body includes terminal output from CodexBarCLI usage --provider zai --source api --format json --pretty against a redacted HTTPS fixture showing primary 7%, secondary 14.7%, and tertiary 8%. (52f523a61552)
• Feature history: History around the parser points to prior work on the used-percent fallback, token-window mapping, and original Z.ai provider support as the relevant ownership trail. (Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift:83, b4b92279ec94)

Likely related people:

• ratulsarna: Authored the Z.ai used-percent fallback change that handles missing quota fields in the affected parser path. (role: used-percent fallback contributor; confidence: high; commits: b4b92279ec94; files: Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift, Tests/CodexBarTests/ZaiProviderTests.swift)
• takumi3488: Authored the Z.ai multi-window token quota mapping that places weekly and 5-hour token limits into the rows implicated by the linked report. (role: quota-window mapping contributor; confidence: high; commits: 67e937dcb0d5; files: Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift, Tests/CodexBarTests/ZaiProviderTests.swift)
• steipete: Introduced Z.ai provider support and authored recent commits touching this provider and this PR branch. (role: provider introducer and recent area contributor; confidence: medium; commits: bbfe9c4617d1, 52f523a61552; files: Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift, Tests/CodexBarTests/ZaiProviderTests.swift, docs/zai.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

[joeVenner]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[steipete]

Landed as 408af89f. Thanks @joeVenner!

Maintainer proof on exact head 52f523a6:

• swift test --filter ZaiUsageParsingTests — 9 passed
• swift test --filter Zai — 52 passed across 11 suites
• make check — passed
• make test — all 45 shards passed
• autoreview — no accepted/actionable findings
• GitHub CI — all 10 checks green at exact head

The successful BigModel CN payload is covered by a deterministic fixture matching the reported response shape; no live credentials or Keychain access were needed.