fix(grok): show validated empty usage periods

[sf-jin-ku]

A freshly reset Grok period could remain “usage unavailable” because the quota resolver discarded the billing parser's implicit zero. Accept that zero only when it comes from one complete protobuf response containing a recognized active current period, with no conflicting percentage. The resolver keeps arbitrary inferred zeros, malformed or truncated zero responses, inactive periods, and invalid percentage payloads unavailable.

The snapshot carries the parser's provenance through plan and reset overlays. The regression fixture exercises the reported payload through parsing, enrichment, and UsageSnapshot conversion, alongside rejection cases and preservation of the existing six-second enrichment timeout.

Fixes #3261. Thanks @sf-jin-ku and @olddonkey for the implementations and reproduction evidence.

Validation: 91 focused tests across four Grok suites; make check; independent Codex review. All nine checks passed on commit 24eba74, including both full macOS test shards and Linux builds (CI run). Local make test remains incomplete: shared filesystem stalls caused unrelated process-fixture and AppKit timeouts; those failures are not counted as passes.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-31T16:26:43.829280Z	046bfc2	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 1, 2026, 2:00 AM ET / 06:00 UTC.

ClawSweeper review

What this changes

This PR lets Grok’s fallback billing path adopt a parser-validated implicit 0% for a complete active weekly or monthly period while preserving unknown usage for other incomplete or inferred responses.

Regression provenance

Possible regression — probable (reproduction; reviewed change). No predecessor PR is attributed.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for maintainer confirmation of the deliberate compatibility choice: a fully valid active period with an omitted proto3 usage scalar will now display 0% rather than unavailable usage. The patch is narrowly implemented, documented, and has no discrete correctness or security finding.

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

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, well-covered provider fix with real-path evidence, pending a maintainer choice about the intentionally ambiguous protocol interpretation.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The supplied redacted terminal trace exercises the real auth-file Grok billing path and records the observed transition from unavailable usage to a 0% Grok-web result; the final commit narrows acceptance and the added captured-frame test covers that final parser-to-resolver path.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The supplied redacted terminal trace exercises the real auth-file Grok billing path and records the observed transition from unavailable usage to a 0% Grok-web result; the final commit narrows acceptance and the added captured-frame test covers that final parser-to-resolver path.
Evidence reviewed	6 items	Current-main baseline: The pinned main branch returns the proxy result unless the fallback percentage was wire-published, so an omitted scalar remains unavailable usage today. Bounded introduced gate: The introduced resolver accepts an inferred value only when it is exactly zero and carries parser provenance; the parser requires a complete single response and an active recognized period. Regression coverage: Added tests drive the captured frame through parsing, fallback resolution, and usage conversion, and cover malformed, future, incomplete, expired, and unsupported-period inputs.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar’s Grok provider reads billing data from the CLI proxy and, when usage is absent, enriches it from grok.com before producing the usage card. This change governs which fallback results may create the card’s percentage bar.

flowchart LR
A[Auth-file token] --> B[CLI proxy billing]
B --> C{Usage percent present?}
C -->|No| D[grok.com billing parser]
D --> E[Provenance gate]
E --> F[Grok usage card]

Loading

Decision needed

Question	Recommendation
Should CodexBar treat grok.com’s complete active-period omitted scalar as 0% despite the protocol’s inability to distinguish zero from a withheld value?	Adopt the bounded zero interpretation: Merge the active-period rule, accepting the small risk that an unobserved withheld value could render as 0%.

Why: The code safely narrows the heuristic and a real account exhibited the expected shape, but the wire format leaves a residual user-visible semantic ambiguity.

Before merge

• Resolve merge risk (P1) - Proto3 omission cannot distinguish an exact zero from a withheld percentage; an unobserved grok.com response that matches the active-period heuristic but withholds nonzero usage would now show 0% instead of the existing unavailable diagnostic.
• Complete next step (P2) - A maintainer must choose whether the bounded protocol inference is acceptable; no mechanical repair is indicated.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test scope	production +36/-13, tests +167/-3, docs +22/-7	The small provenance-gate change is backed by a substantially larger focused regression suite and contract documentation.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #3261
Summary: This PR is a candidate fix for the concrete Grok zero-usage report; the other open PR addresses the same symptom but is not a viable replacement because it is currently conflicted.

Members:

• canonical: Grok: zero-usage weeks show a red "usage unavailable" error — the gRPC zero-usage 0% is parsed but never adopted #3261 - It documents the observed unavailable-usage behavior, source-level merge gate, and affected Grok billing shape this PR targets.
• same_root_cause: Show a 0% Grok usage bar for a period with no usage yet #3294 - It targets the same no-usage-yet Grok symptom, but remains open and non-mergeable, so it does not supersede this PR.

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

Merge-risk options

Maintainer options:

1. Accept the bounded active-period rule (recommended)
   Merge with the documented interpretation that a complete recognized current period and no percentage fields means 0% usage.
2. Preserve unknown usage semantics
   Pause this change and replace the red diagnostic with neutral period status if asserting 0% is not acceptable.

Technical review

Best possible solution:

Record acceptance of the bounded active-period interpretation, then merge this parser-provenance approach rather than widening acceptance to arbitrary inferred values.

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

Yes, source-reproducible: the pinned main guard rejects the parser’s implicit zero, while the supplied redacted real-account transcript shows the resulting unavailable state and the changed resolved output.

Is this the best way to solve the issue?

Unclear pending the stated compatibility decision: the implementation is the narrowest way to adopt the 0% interpretation, but retaining unknown usage with a neutral status is a valid safer policy alternative.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a bounded provider-usage correctness improvement affecting Grok accounts at the start of a billing period.
• merge-risk: 🚨 compatibility: The change intentionally replaces the existing unavailable-usage outcome with 0% for a protocol shape that remains semantically ambiguous.
• 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. Sufficient (terminal): The supplied redacted terminal trace exercises the real auth-file Grok billing path and records the observed transition from unavailable usage to a 0% Grok-web result; the final commit narrows acceptance and the added captured-frame test covers that final parser-to-resolver path.
• proof: sufficient: Contributor real behavior proof is sufficient. The supplied redacted terminal trace exercises the real auth-file Grok billing path and records the observed transition from unavailable usage to a 0% Grok-web result; the final commit narrows acceptance and the added captured-frame test covers that final parser-to-resolver path.

Evidence

What I checked:

• Current-main baseline: The pinned main branch returns the proxy result unless the fallback percentage was wire-published, so an omitted scalar remains unavailable usage today. (Sources/CodexBarCore/Providers/Grok/GrokProviderDescriptor.swift:318, dacbd5222bda)
• Bounded introduced gate: The introduced resolver accepts an inferred value only when it is exactly zero and carries parser provenance; the parser requires a complete single response and an active recognized period. (Sources/CodexBarCore/Providers/Grok/GrokProviderDescriptor.swift:315, 24eba74c3bd0)
• Regression coverage: Added tests drive the captured frame through parsing, fallback resolution, and usage conversion, and cover malformed, future, incomplete, expired, and unsupported-period inputs. (Tests/CodexBarTests/GrokZeroUsageTests.swift:7, 24eba74c3bd0)
• Real behavior proof: A redacted real-account terminal transcript on the immediately preceding parent reports the former unavailable state in 0.56.1 and the resolved Grok-web 0% state after the fix; the final commit tightens the accepted frame shape. (046bfc2555bb)
• Maintainer-area history: The final validation commit is authored by Peter Steinberger, and recent history includes the earlier Grok fallback work by Olddonkey. (Sources/CodexBarCore/Providers/Grok/GrokProviderDescriptor.swift:315, 24eba74c3bd0)
• Release context: The latest shipped tag is v0.56.2 at 5351013; this PR is based on a later main commit and remains unmerged, so the proposed behavior is not in that release. (5351013a211f)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• olddonkey: 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.

• Record the maintainer decision on the bounded omitted-scalar interpretation before merge.

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 (2 earlier review cycles)

• reviewed 2026-08-31T16:28:22.019Z sha 046bfc2 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T17:26:14.352Z sha 046bfc2 :: needs maintainer review before merge. :: none

[sf-jin-ku]

Post-fix proof from this exact head 046bfc255 (auth.json bearer, no cookies):

# shipped 0.56.1
source: grok-cli-proxy
primary: null
diagnostic: Grok usage is unavailable because its billing sources did not report a usage percentage.

# this head CLI
source: grok-web
primary.usedPercent: 0
primary.resetsAt: 2026-09-07T10:19:23Z
diagnostic: (absent)
loginMethod: SuperGrok Heavy

PR body updated with the redacted transcript.

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/33419718439
• Updated: 2026-08-31T17:28:32.823Z