feat(usage): include MCode activity

[Hylouis233]

Problem

T3 Code's Usage page does not include activity from MCode. MCode's terminal UI and desktop app share the same local runtime, so both surfaces are missing from provider totals, charts, and model breakdowns.

What changed

• read MCode's indexed local_runtime_token_usage rows from its shared runtime SQLite store
• cover both MCode TUI and Desktop without double counting their shared physical source
• support MINIMAX_DATA_DIR and the legacy MAVIS_DATA_DIR override
• include the SQLite WAL in fingerprints and cache the earliest covered instant
• preserve uncached input, cache reads/writes, output, reasoning, sessions, models, and positive reported cost
• surface missing, partial, and failed provider coverage on web and mobile
• negotiate v4/v5 responses so rolling client and server upgrades remain decodable
• add the official MCode presentation on web and mobile, plus user documentation

Verification

• 10 focused usage test files: 95 tests passed
• targeted server, contracts, shared, web, and mobile typechecks passed
• focused lint, formatting, and git diff --check passed
• compared the parser against the live shared MCode accounting database: row count and input/output/cache-read/cache-write totals matched the indexed SQL source

Merge order

This PR and #7877 independently target the current v4 usage contract and therefore both introduce v5. Whichever merges second must be rebased and advance the combined contract version before it is ready to merge.

The available before/after usage captures contain private local totals, so they are not attached to this PR.

Built with Codex (GPT-5).

Note

Add mcode usage provider with SQLite store reading and contract version 5 negotiation

• Introduces mcode as a new UsageProviderKind. The server reads token usage from the MCode SQLite store (local_runtime_token_usage table) via an inline worker thread with bounded timeouts, probes primary/alternate DB paths, and parses rows through parseMcodeUsageRow.
• Bumps USAGE_CONTRACT_VERSION from 4 to 5. Adds contractVersion to UsageSummaryInput and makeWindow output. Legacy clients receive version 4 responses via negotiateUsageContractVersion, which excludes mcode data entirely.
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3; adds completeFromMs to CachedFile for window-bounded MCode cache reuse via isReusableCachedFile.
• Updates mergeUsage to prefer ok sources over partial duplicates, exclude failed/missing sources from ownership, and surface partial/failed provider sources in a new incompleteSources array on MergedUsage.
• Adds MCode icon, label, color (--usage-provider-mcode), and provider ordering across web and mobile UIs; UsageCoverageNotice now displays incomplete or failed source messages.
• Risk: Existing on-disk scan caches (USAGE_SCAN_CACHE_VERSION != 3) in usageScanCache.ts are invalidated and treated as empty. listTranscriptFiles return type changed to TranscriptListing (adds failedEntries) — callers in UsageService.ts are updated.

^{Macroscope summarized dec5c52.}

---

Note

Medium Risk
Touches the usage RPC contract, scan cache format, and merge ownership, plus worker-thread SQLite reads. Rolling upgrades are negotiated, but a second v5 PR would need a further bump, and v2 caches are discarded.

Overview
Adds MCode as a third usage provider so the Usage page includes MiniMax TUI and desktop activity from the shared local SQLite runtime (~/.minimax, with MINIMAX_DATA_DIR / MAVIS_DATA_DIR overrides).

The server reads local_runtime_token_usage off the event loop via an embedded worker (busy + 30s wall timeouts), probes primary vs alternate DB paths, and fingerprints the SQLite file plus WAL. Scan cache is bumped to v3 with a completeFromMs bound so windowed MCode scans are not reused for a wider request. Failed reads stay uncached instead of looking like empty usage.

The usage contract is v5. Clients advertise contractVersion; older clients still get a v4 response with MCode omitted. Merge logic prefers a complete duplicate over a partial one, drops fully failed sources from totals, and surfaces incompleteSources on web and mobile. Charts, tables, and docs pick up MCode branding.

^{Reviewed by Cursor Bugbot for commit dec5c52. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 204553f8-8220-4e79-a2f1-bd326eea7d89

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

One finding on the new MCode provider presentation: the series color is a single static value that is barely legible on the light canvas. Everything else in scope (provider order derivation, colSpan={PROVIDER_ORDER.length + 3} fix, the coverage-notice row, the generic chart/tooltip/skeleton loops) stays consistent with the existing usage UI contract.

^{Posted via Macroscope — UI Consistency}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[macroscopeapp]

Approvability

Verdict: Skipped

Macroscope did not run approvability analysis for this PR. Macroscope could not determine whether this PR modifies its approvability configuration, so the PR was not approved automatically. A PR that may change the rules that govern approval is never approved automatically.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9e0fe073a

ℹ️ 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b4f0106f90

ℹ️ 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dafb96fd03

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 709b341. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 709b341385

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