fix(xai): recover validated paid weekly zero usage

[ihonghong]

Summary

Some unified-billing SuperGrok Heavy accounts show a weekly 0% used in the official Grok Build CLI while CPAMP shows unknown usage because the REST response omits creditUsagePercent. Add a bounded, read-only gRPC-web-text check for confirmed SuperGrok/Heavy subscriptions. Accept implicit zero only from a complete successful response matching the active REST week; the existing quota UI then displays 100% remaining.

This extends #710 and #840 without treating a missing REST percentage as zero. Free and unconfirmed plans remain unknown.

Scope

• Frontend panel
• Manager Server
• CPA panel mode
• Full Docker mode
• Native packages / release
• Docs / Wiki
• CI / build / tooling

Changes

• Enrich only successful, active, unified weekly billing with absent percentage and no product usage. Confirm SuperGrok or SuperGrok Heavy through the same credential's settings endpoint before the optional gRPC read.
• Require one complete uncompressed data frame, a successful gRPC trailer, a recognized active weekly period matching REST, and no percentage field. Reject malformed/truncated/denied responses, invalid tags, overflowing varints, duplicate structural fields, mismatched periods, and explicit/invalid floats. Unknown byte fields stay opaque.
• Use gRPC-web-text because CPA's existing JSON api-call response cannot safely carry arbitrary binary. Decode independently padded base64 chunks, including trailers.
• Retain grpc-implicit-zero provenance in the billing summary and preserve REST reset metadata. Optional read failures leave REST health and existing account actions unchanged.
• Share synthetic protocol fixtures between TypeScript and Go, cover account-scoped requests and paid/free behavior, and verify 0% used maps to 100% remaining even when the credential listing omits plan metadata.

User Impact

Affected paid accounts show 100% remaining instead of unknown, consistent with the official CLI's zero-use representation. Zero may include usage rounded down to zero; this does not establish a token allowance or that no tokens were consumed. All other missing usage stays unknown.

Compatibility / Runtime Notes

• CPA panel mode: uses existing /v0/management/api-call and $TOKEN$; no new CPA core endpoint is required.
• Manager Server mode: equivalent parser and optional enrichment for server inspection.
• Full Docker / native packages: same existing proxy path; no schema/config migration or dependency added. At most six seconds of optional lookup latency; requests preserve account scope and configured request cancellation/timeouts.
• This deliberately handles validated implicit zero only. An explicit percentage appearing solely in the gRPC response is not adopted by this change.

Data / Security Notes

Tokens remain resolved by CPA; the panel never reads auth-file secrets. No inference requests, credential changes, purchases, reset redemption, or production config changes. Committed fixtures contain synthetic timestamps and no account identifiers. Optional billing errors do not become disable/recovery signals.

Risk / Rollback

Risk level: Medium — depends on an upstream internal billing protocol and a narrowly documented proto3 default-value interpretation.

On unexpected responses, usage remains unknown. Revert this PR to restore REST-only quota display. No database rollback is needed.

Verification

• Type check
• Lint
• Tests
• Build
• Manual UI check
• Docs/link check
• Not applicable, docs-only

Commands / evidence:

npm run type-check
npm run lint                    # zero errors; six pre-existing warnings
npm run test:web                 # 253 files / 4,189 tests passed
npm run test:repo                # 16 files / 258 tests passed
npm run build
cd apps/manager-server && go test ./...
cd apps/manager-server && go test -race ./internal/service/codexinspection

The first repository-test attempt lacked a merge base due to the shallow clone. After fetching the history, all repository tests passed.

Read-only live evidence (2026-09-26): same account checked with CPA v7.3.15 and Grok Build 1.0.41. Official CLI /usage showed Heavy weekly 0%; both stored OAuth tokens independently produced the same period-only REST response. Settings confirmed SuperGrok Heavy. gRPC-web-text through CPA returned HTTP 200 and gRPC status 0, and the new parser accepted the complete active period, yielding expected remaining percentage 100. No real account data is included in fixtures. The production panel was not replaced or restarted.

Screenshots / Recordings

N/A — no UI components/layout changed. An Accounts display-model regression verifies usedPercent: 0 and remainingPercent: 100; the native official CLI observation and read-only transport check are described above. No manual check of the modified panel is claimed.

Docs

• README / README_CN updated for user-visible capabilities
• Matching docs manual and navigation updated
• Demo fixtures, screenshots, and deep links reviewed
• Release notes needed
• Not needed — explanation included below

Docs decision: add bilingual provider-manual notes on the bounded zero-use interpretation. Existing pages/navigation and demo layout are unchanged. Include this fix in the next release notes; do not rewrite historical release behavior.

Related

• Refs fix(xai): preserve unknown weekly usage and separate billing reset boundaries #710, fix(xai): preserve weekly metadata and ignore zero monthly limits #840, 🐛 fix(accounts): preserve observed xAI weekly quota for unconfirmed plans #748 and [Bug]: v1.12.12 隐藏缺少套餐标识的 Grok Heavy 账号周额度，回退 v1.12.11 恢复 #744.
• Protocol/behavior reference: Grok: zero-usage weeks show a red "usage unavailable" error — the gRPC zero-usage 0% is parsed but never adopted steipete/CodexBar#3261 and fix(grok): show validated empty usage periods steipete/CodexBar#3325.
• Counterexample preserved: Grok: period-only CLI-proxy response reports 0% after Grok Build says free usage limit reached steipete/CodexBar#3157 (exhausted free account with missing REST usage).