feat(mimo): opt-in local tracker fallback for MiMo card

[LeoLin990405]

Summary

• Add an implicit opt-in local fallback so the MiMo card surfaces meaningful data (lifetime/weekly token sums + progress bar) when the platform.xiaomimimo.com SSO cookie path is unavailable, instead of stuck on Xiaomi MiMo login required.
• MiMoWebFetchStrategy.fetch() wraps existing cookie logic in try/catch and falls back to MiMoLocalUsageFallback.snapshot() only when ~/.codexbar/mimo-local-usage.json exists (zero behavior change for users who do not opt in).
• Suppress the "Balance updates in near-real time / Daily billing finalizes at 07:00 UTC" footer when sourceLabel == "local" since neither applies to local accounting.
• Ship Scripts/mimo-usage.py (Python 3, no external deps) as a sample tracker — scans ~/.claude-envs/mimo/.claude/projects/**/*.jsonl for any Claude Code wrapper pointed at MiMo (e.g. cc-mimo with ANTHROPIC_BASE_URL=https://token-plan-sgp.xiaomimimo.com/anthropic) and aggregates input_tokens / output_tokens / cache_read_input_tokens per today / week / all_time window.
• Documented under docs/mimo.md → "Local fallback (opt-in)".

Why

The MiMo provider currently only reaches platform.xiaomimimo.com via SSO cookies, which break in common macOS scenarios:

• Chrome session cookies (api-platform_serviceToken etc.) clear on Chrome relaunch (they're session-level: expires=0 in Chrome SQLite).
• Disable Keychain access / TCC blocks reading Chrome Safe Storage to decrypt the cookie value.
• The user drives MiMo inference only through a wrapper and never logs into platform from a browser.

When this happens the MiMo card shows Xiaomi MiMo login required indefinitely with no escape hatch — tp--prefixed inference API keys (token-plan-sgp.xiaomimimo.com/anthropic) cannot query platform quota; they are two independent auth systems per Xiaomi's own docs.

The local fallback is implicit opt-in: it activates only when the cache file exists. Users without a local wrapper / tracker see no change; current behavior preserved exactly.

Tests

• Added MiMoLocalUsageFallbackTests covering:
  • cache file missing → snapshot() returns nil → fallback skipped
  • cache file malformed JSON → returns nil → fallback skipped
  • normal parse with progress bar (today/week/lifetime/sessions in planCode + tokenUsed/tokenLimit/tokenPercent for the progress bar)
  • idle-week edge case (week=0, allTime>0 → progress bar empty with lifetime as baseline)

Validation

• swift build --target CodexBarCore passes locally.
• swift build --target CodexBar passes locally.
• Local swift test --filter MiMoLocalUsageFallbackTests is blocked before reaching the new tests by the local Command Line Tools environment (KeyboardShortcuts #Preview macro plugins are unavailable without full Xcode); CI should be the test signal.

Scope

No changes to OAuth/cookie paths, provider selection ordering, settings UI, Package.swift, or non-MiMo providers. Behavior is identical to current main when ~/.codexbar/mimo-local-usage.json does not exist.

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 7, 2026, 3:01 AM ET / 07:01 UTC.

Summary
This PR adds an opt-in local MiMo usage fallback backed by ~/.codexbar/mimo-local-usage.json, a no-dependency helper script, docs, tests, and a menu footer adjustment for local data.

Reproducibility: yes. from source inspection: nonzero cache_create values and stale updated_at values can be placed in the cache file, and the branch code ignores both when building the displayed snapshot. I did not run tests because this review is read-only.

Review metrics: 1 noteworthy metric.

• Changed surface: 6 files changed, +475/-1. The PR spans provider logic, UI presentation, docs, tests, and an executable helper script, so the local-accounting contract should be internally consistent before merge.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

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

Rank-up moves:

• [P2] Include cache_create/cache_creation_input_tokens in local totals and add a nonzero regression test.
• Use the cache's updated_at timestamp, with a tested fallback, so stale local data is not displayed as freshly updated.

Risk before merge

• [P2] Until fixed, the local fallback underreports cached-prompt sessions because cache-creation tokens are written by the script but omitted from the Swift fallback totals and progress denominator.
• [P2] Until fixed, stale local cache data can be shown as freshly updated because the fallback stamps snapshots with the CodexBar read time rather than the tracker cache timestamp.

Maintainer options:

1. Decide the mitigation before merge
   Keep the opt-in fallback path, but make local accounting include every emitted token bucket, preserve cache freshness metadata, and cover both cases with focused regression tests before merge.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• The remaining blockers are narrow accounting and timestamp repairs that automation can attempt on the PR branch.

Security
Cleared: No concrete security or supply-chain issue found in the provider fallback, docs, tests, or no-dependency local script.

Review findings

• [P2] Include cache-create tokens in local totals — Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:41-51
• [P2] Use the cache timestamp for local freshness — Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:76

Review details

Best possible solution:

Keep the opt-in fallback path, but make local accounting include every emitted token bucket, preserve cache freshness metadata, and cover both cases with focused regression tests before merge.

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

Yes from source inspection: nonzero cache_create values and stale updated_at values can be placed in the cache file, and the branch code ignores both when building the displayed snapshot. I did not run tests because this review is read-only.

Is this the best way to solve the issue?

No, not yet; the fallback architecture is narrow, but the shipped tracker, displayed totals, and displayed freshness need to agree before this is the best implementation.

Full review comments:

• [P2] Include cache-create tokens in local totals — Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:41-51
Scripts/mimo-usage.py records cache_creation_input_tokens into cache_create for each window, but the fallback builds today/week/all-time totals from only input/output/cache_read. Cached-prompt sessions that create cache entries are undercounted in the plan label and progress bar; include cache_create and add a nonzero regression case.
  Confidence: 0.91
• [P2] Use the cache timestamp for local freshness — Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:76
  The cache file carries updated_at from the tracker, but the fallback always sets updatedAt to now. Since the menu subtitle displays snapshot.updatedAt, an old cache can look freshly updated on every CodexBar refresh; parse updated_at or fall back to file mtime before using the read time.
  Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 574c158ce1e8.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR discussion includes after-fix terminal output showing codexbar usage --provider mimo returning a local MiMo source after the cache is populated.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR discussion includes after-fix terminal output showing codexbar usage --provider mimo returning a local MiMo source after the cache is populated.
• remove rating: 🌊 off-meta tidepool: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P2: The PR changes a user-facing provider fallback with normal-priority correctness issues in local accounting and freshness display.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR discussion includes after-fix terminal output showing codexbar usage --provider mimo returning a local MiMo source after the cache is populated.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR discussion includes after-fix terminal output showing codexbar usage --provider mimo returning a local MiMo source after the cache is populated.

Evidence reviewed

Acceptance criteria:

• [P1] swift test --filter MiMoLocalUsageFallbackTests.
• [P1] swift build --target CodexBarCore.
• [P1] make check.

What I checked:

• Repository policy read: Read all 45 lines of AGENTS.md; its provider-siloing and no-live-Keychain/browser-probe guidance applied to this review. (AGENTS.md:1, 574c158ce1e8)
• PR diff surface: The branch changes six files across provider logic, menu presentation, docs, tests, and a new executable helper script. (8fa1cbc934ba)
• Helper emits cache-create tokens: The helper reads cache_creation_input_tokens and accumulates cache_create for today, week, and all-time windows. (Scripts/mimo-usage.py:83, 8fa1cbc934ba)
• Fallback omits cache-create totals: The Swift fallback totals input, output, and cache_read but not cache_create, so displayed local totals can undercount the cache produced by the helper. (Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:41, 8fa1cbc934ba)
• Existing scanner treats cache-create as usage: The existing Claude cost scanner parses cache_creation_input_tokens as its own token bucket and carries it into usage rows, supporting that this bucket is meaningful local activity. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner+Claude.swift:139, 574c158ce1e8)
• Fallback uses read time as freshness: The fallback returns updatedAt: now instead of parsing the cache file's updated_at field produced by the helper. (Sources/CodexBarCore/Providers/MiMo/MiMoLocalUsageFallback.swift:76, 8fa1cbc934ba)

Likely related people:

• Peter Steinberger: git blame and git show attribute the current MiMo provider files to the v0.32.4 commit. (role: current MiMo provider snapshot introducer; confidence: high; commits: 723734ef3422; files: Sources/CodexBarCore/Providers/MiMo/MiMoProviderDescriptor.swift, Sources/CodexBarCore/Providers/MiMo/MiMoUsageFetcher.swift, Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift)
• Deb Pramanik: git history found earlier MiMo token-plan tracking work in commit f9a2918. (role: earlier MiMo token-plan contributor; confidence: medium; commits: f9a2918afcf1; files: Sources/CodexBarCore/Providers/MiMo, docs/mimo.md, Tests/CodexBarTests/MiMoProviderTests.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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bcd990d4c

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Let the local cache make MiMo fetching available

When MiMo is in auto mode with no cached/importable browser session, isAvailable() returns false, and ProviderFetchPipeline.fetch skips fetch() entirely before this fallback branch can run. That means the documented opt-in path for users with only ~/.codexbar/mimo-local-usage.json and no platform cookies still ends in noAvailableStrategy instead of showing local usage; the strategy needs to report available when the local cache exists or expose a separate local strategy.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include cache-creation tokens in local totals

For sessions that contain cache_creation_input_tokens, the tracker writes cache_create into each window, but the fallback snapshot only sums input/output/cache_read for today/week/all-time. Those cache-creation tokens are billable local activity and are displayed by the script summary, so omitting them here underreports the MiMo card totals and progress for any cached-prompt session that creates cache entries.

Useful? React with 👍 / 👎.

[LeoLin990405]

Pushed an amend: MiMoWebFetchStrategy.isAvailable(_:) now also returns true when MiMoLocalUsageFallback.snapshot() is non-nil. Without this, the multi-account provider switcher (the popover that lists each provider's status) reports No available fetch strategy for mimo whenever cookies are absent even though the fallback would happily serve the menu card on the next refresh. Test coverage stays the same since MiMoLocalUsageFallbackTests already pins snapshot() returning non-nil under valid cache and nil under missing/malformed cache.

[LeoLin990405]

@clawsweeper re-review

The previous review marker references commit 0bcd990d from before the amend. The branch HEAD is now f923238a which adds an isAvailable(_:) change so the provider switcher no longer reports No available fetch strategy for mimo when only the local fallback is configured.

Real-behavior proof (after installing Scripts/mimo-usage.py and running it once to populate ~/.codexbar/mimo-local-usage.json against a cc-mimo style wrapper):

$ codexbar usage --provider mimo
== Xiaomi MiMo (local) ==
Credits: 100% left [============]
Resets 0 / 20,875,221 Credits
Plan: 20.9M Total · 1296 Sessions

$ codexbar usage --provider mimo --json | jq '.[0].source'
"local"

The (local) source label, the Local Tracker (1296 Sessions) plan label in the menu loginMethod row, and the lifetime baseline as progress denominator are exactly the contract the new MiMoLocalUsageFallback.snapshot() is supposed to produce, matching the assertions in MiMoLocalUsageFallbackTests.

Menu screenshot will be attached in a follow-up comment from the PR author (gh CLI doesn't support image upload).

Zero behavior change for users without ~/.codexbar/mimo-local-usage.json — the fallback file simply does not exist, snapshot() returns nil, isAvailable falls back to the original cookie/browser-session check, and fetch() does not invoke the fallback path. Same external behavior as main.

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

Re-review progress:

• State: Failed
• Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26936029628
• Updated: 2026-06-04T07:06:29.750Z