Document MiMo reserve evidence contract

[steipete]

Summary

• records the missing MiMo period contract that blocks Implement reserve for Xiaomi MiMo plan #1205
• rejects 30/31-day inference from reset proximity and plan validity
• recommends keeping windowMinutes and reserve text nil until cadence or start time is authoritative
• defines monthly/annual proof requirements and fail-closed acceptance tests

Evidence

• Xiaomi publicly offers monthly and annual token plans: https://platform.xiaomimimo.com/token-plan
• the redacted live response already documented on Implement reserve for Xiaomi MiMo plan #1205 has usage percent and period end, but no start, duration, or cadence discriminator
• closed PR feat: Add reserve/pace indicator for Xiaomi MiMo token plan #1310 demonstrated why period-end proximity misclassifies annual plans
• active PR [codex] Add Codex pace headroom hint #1789 owns shared pace presentation; active PR Fix MiMo Firefox session cookie import #1565 changes MiMo cookie import, not cadence data

Recommendation requested

Approve the fail-closed contract, or explicitly authorize a labeled heuristic and its acceptable error cases. The next evidence needed is an annual-plan payload plus an authoritative token-credit reset source. This draft should not merge as a product decision without maintainer sign-off.

Verification

• make check
• make test — all 44 shards passed on exact head 5cd26231a
• autoreview — clean, no accepted/actionable findings

No UI behavior changed, so there is no implementation screenshot. The brief specifies the redacted monthly/annual proof and packaged screenshots required for an eventual implementation.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 4:25 AM ET / 08:25 UTC.

Summary
The PR adds a MiMo reserve decision brief documenting why reserve/deficit text should stay disabled until MiMo exposes authoritative cadence or period-start evidence.

Reproducibility: not applicable. this is a docs-only decision brief, not a runtime bug report. Source inspection confirms the documented current behavior without needing a live MiMo account probe.

Review metrics: 1 noteworthy metric.

• Changed Surface: 1 docs file added, +97/-0. The patch records product guidance without changing runtime behavior, so review should focus on correctness and sign-off rather than code execution.

Root-cause cluster
Relationship: partial_overlap
Canonical: #1205
Summary: This PR is a decision brief for the open MiMo reserve feature request, while related PRs cover either a rejected heuristic, shared pace presentation, or adjacent MiMo auth work.

Members:

• canonical: Implement reserve for Xiaomi MiMo plan #1205 - The issue remains the canonical open request for MiMo reserve/deficit display.
• superseded: feat: Add reserve/pace indicator for Xiaomi MiMo token plan #1310 - The closed unmerged PR attempted the reserve UI with a rejected period-end inference heuristic.
• partial_overlap: [codex] Add Codex pace headroom hint #1789 - The open draft overlaps shared pace presentation but does not provide MiMo cadence evidence.
• adjacent_distinct: Fix MiMo Firefox session cookie import #1565 - The open PR changes MiMo Firefox cookie import and does not affect reserve cadence or pace evidence.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
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:

• Record maintainer approval or revise the brief before undrafting and merging.

Risk before merge

• [P1] The PR is still draft and explicitly asks for product sign-off; merging it before that decision would turn the fail-closed MiMo reserve contract into repository guidance without the requested approval.

Maintainer options:

1. Decide Contract Before Undrafting (recommended)
   Approve the fail-closed contract or revise the brief to the authorized heuristic before merging it as repository guidance.
2. Merge As Explicit Owner Guidance
   Maintainers can merge the brief if they intentionally accept that MiMo reserve UI stays blocked until authoritative cadence evidence exists.
3. Pause For Annual Proof
   Keep the draft open if maintainers want annual-plan payloads and an authoritative reset source before accepting the contract.

Next step before merge

• [P2] This owner-authored draft needs maintainer product approval of the MiMo reserve contract, not an automated repair.

Security
Cleared: The diff is docs-only and introduces no code execution, dependency, secret-handling, or supply-chain surface.

Review details

Best possible solution:

Keep the draft open until maintainers approve the fail-closed contract or revise it to an explicitly authorized heuristic, then use the brief as the basis for any later MiMo reserve implementation.

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

Not applicable; this is a docs-only decision brief, not a runtime bug report. Source inspection confirms the documented current behavior without needing a live MiMo account probe.

Is this the best way to solve the issue?

Yes for the current draft: documenting the fail-closed evidence contract is the narrow maintainable path while MiMo cadence data is missing. It should merge only after the requested product decision is made.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P3: This is a low-risk docs/product-decision PR for a provider parity feature, not an urgent runtime regression.
• add merge-risk: 🚨 other: The only meaningful merge risk is accepting a product evidence contract before the draft’s requested maintainer decision is made.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is a low-risk docs/product-decision PR for a provider parity feature, not an urgent runtime regression.
• merge-risk: 🚨 other: The only meaningful merge risk is accepting a product evidence contract before the draft’s requested maintainer decision is made.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• PR metadata and diff: GitHub reports this as an open draft PR by repository owner steipete, with one added docs file and no runtime files changed. (docs/superpowers/specs/2026-07-01-mimo-reserve-decision.md:1, 5cd26231aa39)
• MiMo keeps unknown duration nil: Current main maps MiMo token-plan usage to a primary RateWindow with windowMinutes: nil and resetsAt from planPeriodEnd, matching the proposed fail-closed contract. (Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift:55, 46b493fc45bd)
• Generic pace requires duration: Current main returns nil for non-Codex pace when window.windowMinutes is absent, so MiMo does not fabricate weekly reserve text from a reset timestamp alone. (Sources/CodexBar/UsageStore+HistoricalPace.swift:29, 46b493fc45bd)
• Related issue evidence: The open MiMo reserve issue includes live API discussion saying MiMo exposes usage percent and period end but not period start, duration, billing cycle, reset cycle, or cadence discriminator.
• Rejected heuristic provenance: The closed unmerged MiMo reserve PR was closed by the owner after review because period-end inference can misclassify annual plans in their final month.
• MiMo feature history: Commit f9a2918 introduced Xiaomi MiMo token-plan usage tracking, including the usage fetcher, snapshot mapping, docs, and tests. (Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, f9a2918afcf1)

Likely related people:

• steipete: Authored this draft PR, posted the related owner comment keeping the MiMo reserve issue open for sign-off, and appears in current-main MiMo/pace file history through the release snapshot and co-authorship. (role: owner-decision holder and recent area contributor; confidence: high; commits: 5cd26231aa39, f380287041b8, f9a2918afcf1; files: docs/superpowers/specs/2026-07-01-mimo-reserve-decision.md, Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, Sources/CodexBar/UsageStore+HistoricalPace.swift)
• Deb Pramanik: Authored the merged commit that added Xiaomi MiMo token-plan tracking, including the fetcher, snapshot, docs, and tests now referenced by the decision brief. (role: introduced MiMo token-plan behavior; confidence: high; commits: f9a2918afcf1; files: Sources/CodexBarCore/Providers/MiMo/MiMoUsageFetcher.swift, Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, Tests/CodexBarTests/MiMoProviderTests.swift)
• ViperThanks: Authored the commit that generalized quota pace display around explicit reset windows, adjacent to the fail-closed duration behavior used here. (role: pace behavior contributor; confidence: medium; commits: 0d60c9067352; files: Sources/CodexBar/UsageStore+HistoricalPace.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.