Copilot: drop zero-entitlement quotas instead of showing "0% used" (#1258)

[devYRPauli]

Fixes #1258.

Problem. GitHub Copilot Business token-based billing returns every quota as entitlement: 0, remaining: 0, percent_remaining: 100. CodexBar computes used percent as 100 - percent_remaining, so these accounts showed a misleading "0% used" instead of recognizing the endpoint exposes no usable quota. The placeholder guard only caught the all-zero shape with an empty quota_id, so the percent_remaining: 100 variant slipped through as a real window.

Fix. A zero-entitlement / zero-remaining snapshot carries no usage signal, so treat it as a placeholder (entitlement == 0 && remaining == 0). These now drop out the same way other empty/placeholder Copilot responses already do, so the account no longer shows a fake "0% used". Quotas with a positive entitlement are unchanged, including the genuine "100% used" case (guarded by a test).

Tests. Added parser + fetcher regression tests for the reported payload. The three new assertions fail on main (the fetcher test shows RateWindow(usedPercent: 0.0)) and pass after the change.

Real-behavior proof. Running the production decode + rate-window path (CopilotUsageResponse decode → CopilotUsageFetcher.makeRateWindow) on the exact token-billing payload reported in #1258:

Before (main):

premium -> RateWindow(usedPercent: 0.0)  -> shown as "0% used"
chat    -> RateWindow(usedPercent: 0.0)  -> shown as "0% used"

After (this PR):

premium -> no window (unavailable)
chat    -> no window (unavailable)

I don't have a live Copilot Business account, so this drives the real parsing/window code with the issue's verbatim payload rather than a live credentialed probe.

Verification. swift test --filter CopilotUsageModelsTests and CopilotUsageFetcherTests pass; make check clean (parser hash current); full swift test (3219 tests) passes.

Used the Claude CLI while working on this.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 1, 2026, 6:03 PM ET / 22:03 UTC.

Summary
The PR updates Copilot quota decoding/fetching so explicit zero-entitlement and zero-remaining token-billing snapshots are dropped as unavailable, with parser and fetcher regression tests.

Reproducibility: yes. there is a high-confidence source reproduction path: decode the linked Copilot Business token-billing payload on current main and pass its snapshots through makeRateWindow, which yields 0% windows instead of an unavailable state. I did not run live account probes because the repo policy says not to do credentialed provider validation unless explicitly requested.

Review metrics: 2 noteworthy metrics.

• Changed surface: 4 files: 2 source, 2 tests. The behavioral change is confined to Copilot quota decoding/fetching plus focused regression coverage.
• Regression coverage: 7 tests added. The tests cover the reported Business token-billing payload and guard the important positive-entitlement and percent-only quota cases.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
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.

Risk before merge

• [P1] The PR deliberately does not discover actual token-billing usage from another GitHub endpoint; it makes the current endpoint's zero-entitlement shape unavailable instead of showing fabricated 0% usage.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow parser/fetcher fix, then track any future actual-usage endpoint for Copilot Business token billing as a separate enhancement if GitHub exposes one.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] No repair lane is needed; the remaining action is normal maintainer merge/check review for the existing PR.

Security
Cleared: The diff only changes Copilot response parsing, fetcher transport injection for tests, and focused tests; I found no concrete security or supply-chain concern.

Review details

Best possible solution:

Land the narrow parser/fetcher fix, then track any future actual-usage endpoint for Copilot Business token billing as a separate enhancement if GitHub exposes one.

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

Yes, there is a high-confidence source reproduction path: decode the linked Copilot Business token-billing payload on current main and pass its snapshots through makeRateWindow, which yields 0% windows instead of an unavailable state. I did not run live account probes because the repo policy says not to do credentialed provider validation unless explicitly requested.

Is this the best way to solve the issue?

Yes. The PR is the narrowest maintainable fix for the current endpoint: drop explicit zero-entitlement snapshots, preserve real positive-entitlement and percent-only quotas, and return a plan-only unavailable state for token-based billing.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4756ba06bf42.

Label changes

Label justifications:

• P2: This is a normal-priority provider correctness fix for misleading Copilot Business usage display with limited blast radius.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes before/after copied output from the production decode-to-rate-window path on the exact linked payload, which is sufficient for this parser/fetcher fix under the repo's no-unrequested-live-probe policy.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes before/after copied output from the production decode-to-rate-window path on the exact linked payload, which is sufficient for this parser/fetcher fix under the repo's no-unrequested-live-probe policy.

Evidence reviewed

What I checked:

• Repository policy read: The full target AGENTS.md was read; its guidance favors focused parser/provider tests and warns not to run live provider probes or Keychain-triggering validation unless explicitly requested. (AGENTS.md:26, 4756ba06bf42)
• Current main still treats the reported payload as a real quota window: On current main, Copilot placeholders only match entitlement=0, remaining=0, percent_remaining=0, and an empty quota id, so the issue payload with percent_remaining=100 and non-empty quota ids is not dropped by this guard. (Sources/CodexBarCore/CopilotUsageModels.swift:33, 4756ba06bf42)
• Current main errors when no usable Copilot windows remain: Current main throws cannotDecodeRawData when neither premium nor chat produces a rate window, so a plan-only unavailable state for token-billing accounts is not currently represented by the fetcher. (Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift:76, 4756ba06bf42)
• PR parser change: The PR records whether entitlement and remaining were explicitly decoded, treats explicit zero-entitlement/zero-remaining snapshots as placeholders, and decodes token_based_billing for the fetcher decision. (Sources/CodexBarCore/CopilotUsageModels.swift:35, 22668160a55c)
• PR fetcher change: The PR returns a UsageSnapshot with nil primary/secondary windows but preserved Business identity when token_based_billing is true and all quota windows are unavailable. (Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift:82, 22668160a55c)
• Regression tests: The PR adds model tests for the reported zero-entitlement Business token-billing payload, positive-entitlement 100%-used preservation, percent-only preservation, and fetcher behavior for a plan-only unavailable snapshot. (Tests/CodexBarTests/CopilotUsageModelsTests.swift:440, 22668160a55c)

Likely related people:

• steipete: Recent current-main history and PR-branch commits touch the Copilot provider display/fetch path, including the final PR head commit that returns the token-billing unavailable state. (role: recent area contributor; confidence: high; commits: 3f419060f875, 4c9e6a8, 9d64126; files: Sources/CodexBarCore/CopilotUsageModels.swift, Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift)
• Ratul Sarna: Introduced and refined the Copilot quota fallback and placeholder handling that this PR adjusts for token-billing zero-entitlement snapshots. (role: fallback and placeholder behavior contributor; confidence: high; commits: 1a793120f3ad, 174811212356, 90c096d; files: Sources/CodexBarCore/CopilotUsageModels.swift)
• Emanuel Stadler: The current Copilot free-plan usage parsing and fetcher metric behavior traces back to this area work, making it useful context for parser regressions. (role: original parser/fetcher behavior contributor; confidence: medium; commits: 249bcf1d6630; files: Sources/CodexBarCore/CopilotUsageModels.swift, Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift)

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.