fix(usage): identify client version mismatches

[tris203]

Fixes #8145

Problem

When a connected environment reports a newer usage contract than the client expects, the usage page excludes its data but incorrectly says that the environment runs an older server version.

Changes

• Record whether each usage contract mismatch means the server or client is behind.
• Format the version-specific notice in shared usage formatting code.
• Use the same notice on web and mobile.

Screenshots

Before:

After:

Verification

• pnpm exec vp test run packages/shared/src/usageMerge.test.ts
• pnpm exec vp lint apps/mobile/src/features/usage/UsageRouteScreen.tsx apps/web/src/components/usage/UsagePage.tsx packages/shared/src/usageFormat.ts packages/shared/src/usageMerge.test.ts packages/shared/src/usageMerge.ts
• pnpm --filter @t3tools/shared typecheck
• pnpm --filter @t3tools/web typecheck
• pnpm --filter @t3tools/mobile typecheck

Built with GPT-5.6 using the Codex harness in T3 Code.

---

Note

Low Risk
Localized usage merge/UI messaging change with tests; breaking rename of staleEnvironments is fully updated in-repo.

Overview
Fixes incorrect usage coverage copy when a server reports a newer usage contract than the client expects: those environments were still excluded from totals, but the UI always blamed an older server.

mergeUsage now emits contractMismatches (replacing staleEnvironments) with serverBehind vs clientBehind and the reported contract version. Incompatible environments are still dropped from aggregation.

Shared formatUsageContractMismatch centralizes the two user-facing messages. Web and mobile coverage notices and the web environment filter consume contractMismatches and show the direction-specific text. Tests cover both mismatch directions.

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

Note

Replace stale environment IDs with UsageContractMismatch records in mergeUsage

• The mergeUsage function now records server-behind or client-behind direction and the reported version for incompatible environments instead of just listing stale environment IDs.
• Web and mobile usage components consume these structured mismatch records to display accurate exclusion messages via the new formatUsageContractMismatch formatter.
• Behavioral Change: MergedUsage replaces the stale environment ID collection with contractMismatches; consumers must handle the new UsageContractMismatch type instead of string IDs.

^{Macroscope summarized 4ec785b.}

Summary by CodeRabbit

• Bug Fixes
  • Usage status messages now specify whether the server or client has an incompatible contract version.
  • Usage from incompatible environments remains excluded from totals, with the affected environment identified in the coverage notice.
  • Compatible environments continue to be included in usage totals.
• User Experience
  • Mobile and web usage screens provide direction-specific explanations instead of generic “Older server” messaging.
  • Notices for failed environments and duplicate sources remain unchanged.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: b09665c4-bf20-4047-8bc3-9c3531512b5f

📥 Commits

Reviewing files that changed from the base of the PR and between 1c6518b404fe2a0ee034dc2fe66273ab241adda3 and 6ef11c7.

📒 Files selected for processing (1)

• apps/web/src/components/usage/UsagePage.tsx

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Usage merging now records structured contract mismatches with direction and contract version. Web and mobile usage views use these records to report whether the server or client is behind.

Changes

Usage contract mismatch reporting

Layer / File(s)	Summary
Structured mismatch data packages/shared/src/usageMerge.ts, packages/shared/src/usageMerge.test.ts	mergeUsage replaces stale environment IDs with structured mismatch records. It records whether the server or client is behind and excludes incompatible data from totals. Tests cover older, newer, and compatible contract versions.
Direction-specific message formatting packages/shared/src/usageFormat.ts	Adds formatUsageContractMismatch for server-behind and client-behind messages.
Usage view integration apps/web/src/components/usage/UsagePage.tsx, apps/mobile/src/features/usage/UsageRouteScreen.tsx	The usage views pass contract mismatch records to filters and notices, mark affected environments, and display direction-specific messages.

Priority: ⬆️ High

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: High

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 6ef11

The web and mobile views consistently identify which side has the incompatible usage contract, while incompatible environments remain excluded from totals. No merge-blocking behavior is established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 6ef11

Incompatible usage data remains excluded from totals. The change improves the explanation shown to users without showing a new path to change settings or access data. Review of broader access controls remains outside the available evidence.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The changed mismatch value affects usage coverage and status presentation for connected environments, not the environment-scoped settings command; broader route exposure was not established.

Trust Boundaries and Controls

• observed — The reported server contract version is compared with the expected version to classify a mismatch; incompatible usage is not passed into source claiming and totals aggregation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main fix: usage now reports client version mismatches. It is concise and relevant to the changes.
Description check	✅ Passed	The description explains the problem, changes, UI impact with before-and-after screenshots, and verification steps. It does not use the exact template headings or checklist, but it provides the requir…
Linked Issues check	✅ Passed	Issue #8145 requires correct direction reporting for usage contract mismatches and correct handling of incompatible usage. mergeUsage records serverBehind for lower reported versions and `clientBe…
Out of Scope Changes check	✅ Passed	The changes remain within Issue #8145. They structure contract mismatch data, centralize mismatch notices, update web and mobile display logic, and update merge tests. These changes directly support a…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[macroscopeapp]

Approvability

Verdict: Approved at 1c6518b

Macroscope's review found this PR approvable — This is a focused usage bug fix that preserves existing totals and compatibility behavior while distinguishing older servers from older clients in web and mobile messaging. The shared metadata change is localized and covered by tests, with no deployment, security, billing, default, or static-analysis changes.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate 213e2bd

Dismissing prior approval to re-evaluate 4ec785b

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

Dismissing prior approval to re-evaluate 3b86bd7