Improve provider usage tracking across Codex, Claude, and Grok

[jetblk]

Summary

• update the pinned Codex app-server protocol and expose read-only reset-credit inventory
• classify Codex windows by duration, preserve additional limit buckets, and label model-specific limits
• make Claude usage resilient to 429s with Retry-After, credential-scoped last-good snapshots, stale-state metadata, and Max multipliers
• add Grok weekly usage, plan, and extra-usage cap through the CLI-owned x.ai/billing ACP extension
• surface freshness and reset-credit details consistently in the web and mobile clients

Deliberate boundaries

• reset credits are informational only; this does not add redemption
• Grok authentication remains owned by the CLI; T3 does not read or write its auth file
• Claude token refresh remains owned by Claude Code

Validation

• vp check (passes; existing unrelated warnings remain)
• vp run typecheck
• vp run lint:mobile (native linters are not installed in this Linux environment; the repository wrapper passed)
• focused provider/contracts/client/UI suite: 46 tests passed
• collaborative-browser inspection of the compiled provider usage presentation at 434px and 1280px

Note

Add provider usage tracking for Codex, Claude, and Grok with Usage & Limits UI

• Adds ProviderUsageService on the server that aggregates per-instance usage snapshots with a 60s cache for ok results; instances without a usage capability return an unsupported snapshot.
• Implements usage modules for Claude (ClaudeUsage.ts), Codex (CodexUsage.ts), and Grok (GrokUsage.ts) that parse provider billing/OAuth responses into a normalized ProviderUsageSnapshot shape defined in the new contracts package (providerUsage.ts).
• Exposes a new server.getProviderUsage WebSocket RPC (requiring orchestration read scope) and adds a providerUsage query atom with 30s stale time to createServerEnvironmentAtoms.
• Adds a 'Usage & Limits' settings page in both the web app (ProviderUsageSettings.tsx) and mobile app (SettingsProviderUsageRouteScreen.tsx), aggregating usage across environments with deduplication by account.
• Adds a ProviderUsageAlert popover to the chat composer footer that surfaces capacity warnings when usage meets or exceeds 75%.

^{Macroscope summarized 5af3fa8.}

Summary by CodeRabbit

• New Features

  • Added provider usage and limits reporting for Claude, Codex, and Grok.
  • Added usage alerts and detailed usage panels to chat and model selection.
  • Added a new “Usage & Limits” page in web and mobile settings.
  • Added provider-specific icons and usage meters.
  • Added nightly server artifact publishing and deployment support.

• Documentation

  • Added setup, operation, update, rollback, and provider usage documentation.

• Tests

  • Added coverage for usage aggregation, formatting, provider integrations, caching, and UI behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds provider usage contracts, Claude/Codex/Grok probes, server RPC integration, web and mobile usage interfaces, a fork nightly release workflow, node deployment service, and related tests and documentation.

Changes

Provider usage contracts and server API

Layer / File(s)	Summary
Contracts, service, and RPC wiring packages/contracts/src/*, apps/server/src/provider/Services/*, apps/server/src/ws.ts, packages/client-runtime/src/state/server.ts	Defines provider usage schemas, server service interfaces, the server.getProviderUsage WebSocket RPC, live service wiring, authorization, and cached environment queries.
Provider probes and driver integration apps/server/src/provider/Layers/*Usage*, apps/server/src/provider/Drivers/*, apps/server/src/provider/ProviderDriver.ts	Adds Claude, Codex, and Grok usage probes, normalized snapshots, provider capability wiring, cache behavior, authentication/error handling, and focused tests.

Web and mobile usage interfaces

Layer / File(s)	Summary
Web aggregation and presentation packages/client-runtime/src/providerUsage.ts, apps/web/src/components/provider-usage/*, apps/web/src/components/chat/*	Aggregates usage across environments, deduplicates accounts, formats limits and credits, renders usage details/meters, and adds chat alerts and selector panels.
Web settings route apps/web/src/components/settings/*, apps/web/src/routes/settings.usage.tsx, apps/web/src/routeTree.gen.ts	Adds the Usage & Limits settings page, environment status rows, navigation entry, and generated route wiring.
Mobile usage settings apps/mobile/src/features/settings/*, apps/mobile/src/Stack.tsx, apps/mobile/src/state/providerUsage.ts	Adds the mobile Usage & Limits screen, multi-environment aggregation, provider cards, refresh behavior, node statuses, settings navigation, and provider-specific icons.

Fork delivery and supporting updates

Layer / File(s)	Summary
Nightly artifact and node service .github/workflows/nightly-fork.yml, docs/t3code.service, docs/nodes.md	Builds and publishes versioned and rolling self-contained server releases, and documents systemd-based node installation, updates, rollback, and operations.
Fork configuration and implementation plan apps/mobile/app.config.ts, apps/mobile/global.css, docs/provider-usage-plan.md	Adds configurable fork identity values, warning theme tokens, and documentation for the provider usage architecture and rollout.
Codex protocol generator packages/effect-codex-app-server/scripts/generate.ts	Updates the upstream protocol reference and adds a workspace-message response mapping.

Estimated code review effort: 5 (Critical) | ~120 minutes

Suggested reviewers: juliusmarminge

Poem

I’m a rabbit with usage in view,
Hopping through limits and releases anew.
Claude, Codex, and Grok share the way,
While nightly builds burrow out every day.
Web and mobile meters now glow—
Tiny paws ship a status row!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.23% which is insufficient. The required threshold is 80.00%.	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 summarizes the main change: provider usage tracking across Codex, Claude, and Grok.
Description check	✅ Passed	The description covers the main changes, boundaries, and validation, though it doesn't follow the template headings exactly.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[jetblk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (1)

docs/nodes.md (1)

7-7: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Specify a language for fenced code blocks.

To improve syntax highlighting and resolve markdownlint warnings, consider specifying a language identifier (such as text or log) for these code blocks.

• docs/nodes.md#L7-L7: Change to ````text`
• docs/nodes.md#L104-L104: Change to ````text`

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/nodes.md` at line 7, Specify the text language identifier on the fenced
code blocks at docs/nodes.md lines 7-7 and 104-104 by changing each opening
fence to use text.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/nightly-fork.yml:
- Around line 139-150: Update the date calculation in the workflow step using
RUN_STARTED_AT so it passes a fallback of “now” when the variable is empty or
unset, while preserving the existing run-start timestamp behavior when
available. Keep the change scoped to the day assignment near the base-version
logic.

In `@apps/mobile/src/features/settings/SettingsProviderUsageRouteScreen.tsx`:
- Line 94: Update the SettingsProviderUsageRouteScreen logic around nowMs to
refresh the current timestamp on a timer, matching the web usage view’s periodic
update behavior. Ensure the timer is cleaned up when the screen unmounts, and
use the refreshed value for reset, retry, and expiry labels.

In `@apps/server/src/provider/Layers/ClaudeUsage.ts`:
- Around line 162-169: Validate the `resetsAt` value derived from
`stringField(input.raw, "resets_at")` before adding it to the
`ProviderUsageWindow` result, including the separate `limits[]` mapping. Only
include `resetsAt` when the string is a valid `IsoDateTime`; omit it for
malformed or empty values while preserving the remaining normalized fields.

In `@apps/server/src/provider/Layers/GrokUsage.ts`:
- Around line 115-116: Update the usage parsing around percentValue and the
related fields at the additionally referenced section so missing billing values
remain undefined instead of being converted to zero. Only call numberValue when
the source field is present, and preserve the existing numeric conversion for
supplied values so the UI does not fabricate usage or extra-usage limits.

In `@apps/server/src/provider/Layers/ProviderUsageService.ts`:
- Around line 26-29: Update CacheEntry and the cache lookup/store logic in
ProviderUsageService to retain the originating ProviderInstance identity
alongside each snapshot. When reading an entry, accept it only if it is
unexpired and belongs to the exact current provider instance; otherwise discard
it and fetch fresh usage, while preserving the existing instanceId keying and
TTL behavior.
- Around line 74-89: Update the cache-miss flow in the service containing the
Ref-based cache to maintain an in-flight effect keyed by instance.instanceId.
Before calling instance.usage.fetchUsage, reuse the existing effect for that
key; otherwise register the fetch-and-identity effect, share it with concurrent
callers, and remove the entry when it completes. Preserve the existing
successful snapshot cache update and ensure failures also clear the in-flight
entry.

In `@apps/web/src/components/chat/ProviderUsageControl.tsx`:
- Around line 193-195: Update the early-return logic in ProviderUsageControl so
status "ok" snapshots are not hidden solely when headline is null. Use the
snapshot’s available displayable details—the same criteria supported by
ProviderUsageExpandedContent—to decide whether content exists, preserving the
existing null and unsupported checks.

In `@packages/contracts/src/providerUsage.ts`:
- Around line 104-109: The provider usage schema currently uses the
human-readable account label as the deduplication input. Update the provider
usage contract around account to add a canonical provider-issued accountKey,
while retaining account for display/auth labels; update the client-runtime
deduplication logic to use accountKey exclusively and avoid lowercasing or
merging based on account.

---

Nitpick comments:
In `@docs/nodes.md`:
- Line 7: Specify the text language identifier on the fenced code blocks at
docs/nodes.md lines 7-7 and 104-104 by changing each opening fence to use text.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c58de088-4c1d-4307-9f29-dd2fdbf43cbc

📥 Commits

Reviewing files that changed from the base of the PR and between ebe8afb and 5af3fa8.

⛔ Files ignored due to path filters (3)

• packages/effect-codex-app-server/src/_generated/meta.gen.ts is excluded by !**/_generated/**
• packages/effect-codex-app-server/src/_generated/namespaces.gen.ts is excluded by !**/_generated/**
• packages/effect-codex-app-server/src/_generated/schema.gen.ts is excluded by !**/_generated/**

📒 Files selected for processing (52)

• .github/workflows/nightly-fork.yml
• apps/mobile/app.config.ts
• apps/mobile/global.css
• apps/mobile/src/Stack.tsx
• apps/mobile/src/components/ProviderIcon.tsx
• apps/mobile/src/features/settings/SettingsProviderUsageRouteScreen.tsx
• apps/mobile/src/features/settings/SettingsRouteScreen.tsx
• apps/mobile/src/features/settings/components/settings-sheet-targets.ts
• apps/mobile/src/state/providerUsage.test.ts
• apps/mobile/src/state/providerUsage.ts
• apps/server/src/provider/Drivers/ClaudeDriver.ts
• apps/server/src/provider/Drivers/ClaudeHome.test.ts
• apps/server/src/provider/Drivers/ClaudeHome.ts
• apps/server/src/provider/Drivers/CodexDriver.ts
• apps/server/src/provider/Drivers/GrokDriver.ts
• apps/server/src/provider/Layers/ClaudeProvider.ts
• apps/server/src/provider/Layers/ClaudeUsage.test.ts
• apps/server/src/provider/Layers/ClaudeUsage.ts
• apps/server/src/provider/Layers/CodexUsage.test.ts
• apps/server/src/provider/Layers/CodexUsage.ts
• apps/server/src/provider/Layers/GrokUsage.test.ts
• apps/server/src/provider/Layers/GrokUsage.ts
• apps/server/src/provider/Layers/ProviderUsageService.test.ts
• apps/server/src/provider/Layers/ProviderUsageService.ts
• apps/server/src/provider/ProviderDriver.ts
• apps/server/src/provider/Services/ProviderUsage.ts
• apps/server/src/server.test.ts
• apps/server/src/server.ts
• apps/server/src/ws.ts
• apps/web/src/components/chat/ChatComposer.tsx
• apps/web/src/components/chat/ModelPickerContent.tsx
• apps/web/src/components/chat/ProviderModelPicker.tsx
• apps/web/src/components/chat/ProviderUsageControl.test.ts
• apps/web/src/components/chat/ProviderUsageControl.tsx
• apps/web/src/components/provider-usage/ProviderUsagePresentation.test.tsx
• apps/web/src/components/provider-usage/ProviderUsagePresentation.tsx
• apps/web/src/components/settings/ProviderUsageSettings.tsx
• apps/web/src/components/settings/SettingsSidebarNav.tsx
• apps/web/src/routeTree.gen.ts
• apps/web/src/routes/settings.usage.tsx
• docs/nodes.md
• docs/provider-usage-plan.md
• docs/t3code.service
• packages/client-runtime/package.json
• packages/client-runtime/src/providerUsage.test.ts
• packages/client-runtime/src/providerUsage.ts
• packages/client-runtime/src/state/server.ts
• packages/contracts/src/index.ts
• packages/contracts/src/providerUsage.test.ts
• packages/contracts/src/providerUsage.ts
• packages/contracts/src/rpc.ts
• packages/effect-codex-app-server/scripts/generate.ts

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Provide a fallback for RUN_STARTED_AT to prevent script failure.

The static analysis tool actionlint reports that run_started_at is not a defined property on the github context object. If this property evaluates to an empty string, the date -u -d "" command will fail with an invalid date error, breaking the workflow due to set -euo pipefail.

Add a fallback to "now" (${RUN_STARTED_AT:-now}) to ensure the script always succeeds, even if the context property is missing.

🛡️ Proposed fix

       env:
         RUN_STARTED_AT: ${{ github.run_started_at }}
       run: |
         set -euo pipefail
         # Track upstream's stable base from package.json (nightly versions are
         # never committed upstream, so main always carries the last stable),
         # then mark it as ours so it is obvious which build a node is running.
         base="$(node -p "require('./apps/server/package.json').version")"
         # Date the run, not the clock: bare `date -u` reads whenever this step
         # happens to run, so a build starting at 23:59 UTC would stamp
         # tomorrow. Mirrors upstream's NIGHTLY_DATE: github.run_started_at.
-        day="$(date -u -d "$RUN_STARTED_AT" +%Y%m%d)"
+        day="$(date -u -d "${RUN_STARTED_AT:-now}" +%Y%m%d)"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	env:
	RUN_STARTED_AT: ${{ github.run_started_at }}
	run: |
	set -euo pipefail
	# Track upstream's stable base from package.json (nightly versions are
	# never committed upstream, so main always carries the last stable),
	# then mark it as ours so it is obvious which build a node is running.
	base="$(node -p "require('./apps/server/package.json').version")"
	# Date the run, not the clock: bare `date -u` reads whenever this step
	# happens to run, so a build starting at 23:59 UTC would stamp
	# tomorrow. Mirrors upstream's NIGHTLY_DATE: github.run_started_at.
	day="$(date -u -d "$RUN_STARTED_AT" +%Y%m%d)"
	env:
	RUN_STARTED_AT: ${{ github.run_started_at }}
	run: |
	set -euo pipefail
	# Track upstream's stable base from package.json (nightly versions are
	# never committed upstream, so main always carries the last stable),
	# then mark it as ours so it is obvious which build a node is running.
	base="$(node -p "require('./apps/server/package.json').version")"
	# Date the run, not the clock: bare `date -u` reads whenever this step
	# happens to run, so a build starting at 23:59 UTC would stamp
	# tomorrow. Mirrors upstream's NIGHTLY_DATE: github.run_started_at.
	day="$(date -u -d "${RUN_STARTED_AT:-now}" +%Y%m%d)"

🧰 Tools

🪛 actionlint (1.7.12)

[error] 140-140: property "run_started_at" is not defined in object type {action: string; action_path: string; action_ref: string; action_repository: string; action_status: string; actor: string; actor_id: string; api_url: string; artifact_cache_size_limit: number; base_ref: string; env: string; event: object; event_name: string; event_path: string; graphql_url: string; head_ref: string; job: string; output: string; path: string; ref: string; ref_name: string; ref_protected: bool; ref_type: string; repository: string; repository_id: string; repository_owner: string; repository_owner_id: string; repository_visibility: string; repositoryurl: string; retention_days: number; run_attempt: string; run_id: string; run_number: string; secret_source: string; server_url: string; sha: string; state: string; step_summary: string; token: string; triggering_actor: string; workflow: string; workflow_ref: string; workflow_sha: string; workspace: string}

(expression)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/nightly-fork.yml around lines 139 - 150, Update the date
calculation in the workflow step using RUN_STARTED_AT so it passes a fallback of
“now” when the variable is empty or unset, while preserving the existing
run-start timestamp behavior when available. Keep the change scoped to the day
assignment near the base-version logic.

Source: Linters/SAST tools

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Periodically refresh relative reset and expiry labels.

nowMs changes only when another state update rerenders the screen, so “resets in,” retry, and expiry text can remain stale indefinitely. Update it on a timer as the web usage view does.

Proposed fix

-  const nowMs = Date.now();
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  useEffect(() => {
+    const interval = setInterval(() => setNowMs(Date.now()), 30_000);
+    return () => clearInterval(interval);
+  }, []);

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const nowMs = Date.now();
	const [nowMs, setNowMs] = useState(() => Date.now());
	useEffect(() => {
	const interval = setInterval(() => setNowMs(Date.now()), 30_000);
	return () => clearInterval(interval);
	}, []);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/mobile/src/features/settings/SettingsProviderUsageRouteScreen.tsx` at
line 94, Update the SettingsProviderUsageRouteScreen logic around nowMs to
refresh the current timestamp on a timer, matching the web usage view’s periodic
update behavior. Ensure the timer is cleaned up when the screen unmounts, and
use the refreshed value for reset, retry, and expiry labels.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Validate reset timestamps before adding them to usage windows.

Both paths copy any non-empty resets_at string into ProviderUsageWindow.resetsAt, although the upstream contract requires IsoDateTime. A malformed response can therefore invalidate the normalized snapshot instead of degrading to fewer fields as intended.

Proposed normalization

-  const resetsAt = stringField(input.raw, "resets_at");
+  const rawResetsAt = stringField(input.raw, "resets_at");
+  const resetMillis = rawResetsAt ? Date.parse(rawResetsAt) : Number.NaN;
+  const resetsAt = Number.isFinite(resetMillis)
+    ? new Date(resetMillis).toISOString()
+    : undefined;

Apply the same validation to the limits[] mapping.

Also applies to: 236-243

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/provider/Layers/ClaudeUsage.ts` around lines 162 - 169,
Validate the `resetsAt` value derived from `stringField(input.raw, "resets_at")`
before adding it to the `ProviderUsageWindow` result, including the separate
`limits[]` mapping. Only include `resetsAt` when the string is a valid
`IsoDateTime`; omit it for malformed or empty values while preserving the
remaining normalized fields.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not interpret missing billing fields as zero.

A partial response containing only currentPeriod reports 0% usage and “Extra usage: Disabled,” even though neither value was supplied. Preserve undefined so the UI does not present fabricated limits.

Proposed fix

   const percentValue = config["creditUsagePercent"] ?? config["credit_usage_percent"];
-  const usedPercent = percentValue === undefined ? 0 : numberValue(percentValue);
+  const usedPercent = numberValue(percentValue);
...
-  const cap = numberValue(config["onDemandCap"] ?? config["on_demand_cap"]) ?? 0;
-  const credits: ProviderUsageCredits = {
-    label: "Extra usage",
-    balance: cap > 0 ? `${formatOpaqueNumber(cap)} cap` : "Disabled",
-  };
+  const cap = numberValue(config["onDemandCap"] ?? config["on_demand_cap"]);
+  const credits: ProviderUsageCredits | undefined =
+    cap === undefined
+      ? undefined
+      : {
+          label: "Extra usage",
+          balance: cap > 0 ? `${formatOpaqueNumber(cap)} cap` : "Disabled",
+        };

Also applies to: 134-138

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/provider/Layers/GrokUsage.ts` around lines 115 - 116, Update
the usage parsing around percentValue and the related fields at the additionally
referenced section so missing billing values remain undefined instead of being
converted to zero. Only call numberValue when the source field is present, and
preserve the existing numeric conversion for supplied values so the UI does not
fabricate usage or extra-usage limits.

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Invalidate cached usage when the provider instance is replaced.

The cache is keyed only by instanceId. Reconfiguring credentials under the same ID can therefore expose the previous account’s usage and email for up to 60 seconds. Store the originating ProviderInstance identity and accept the entry only when it still matches.

Proposed fix

 interface CacheEntry {
+  readonly instance: ProviderInstance;
   readonly snapshot: ProviderUsageSnapshot;
   readonly expiresAtMillis: number;
 }

-        if (cached && cached.expiresAtMillis > nowMillis) {
+        if (cached && cached.instance === instance && cached.expiresAtMillis > nowMillis) {
           return cached.snapshot;
         }
...
             next.set(instance.instanceId, {
+              instance,
               snapshot,
               expiresAtMillis: nowMillis + Duration.toMillis(USAGE_CACHE_TTL),
             });

Also applies to: 65-65, 74-89

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/provider/Layers/ProviderUsageService.ts` around lines 26 -
29, Update CacheEntry and the cache lookup/store logic in ProviderUsageService
to retain the originating ProviderInstance identity alongside each snapshot.
When reading an entry, accept it only if it is unexpired and belongs to the
exact current provider instance; otherwise discard it and fetch fresh usage,
while preserving the existing instanceId keying and TTL behavior.

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift

Coalesce concurrent cache misses per instance.

The read-fetch-write sequence is not atomic. Simultaneous RPC requests all miss and independently invoke the upstream probe, defeating the traffic-bound cache and potentially spawning duplicate Codex processes. Track an in-flight effect per instance and share it until completion.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/provider/Layers/ProviderUsageService.ts` around lines 74 -
89, Update the cache-miss flow in the service containing the Ref-based cache to
maintain an in-flight effect keyed by instance.instanceId. Before calling
instance.usage.fetchUsage, reuse the existing effect for that key; otherwise
register the fetch-and-identity effect, share it with concurrent callers, and
remove the entry when it completes. Preserve the existing successful snapshot
cache update and ensure failures also clear the in-flight entry.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not hide valid usage details merely because there is no headline.

Reset-credit-only, stale-without-meter, and nonnumeric-window snapshots can have headline === null, yet ProviderUsageExpandedContent can render them. Base this check on whether the snapshot has any displayable details.

Proposed fix

   if (!usage || usage.status === "unsupported") return null;
-  if (usage.status === "ok" && headline === null) return null;
+  const hasDetails =
+    usage.windows.length > 0 ||
+    usage.credits !== undefined ||
+    (usage.resetCredits?.availableCount ?? 0) > 0 ||
+    usage.freshness?.state === "stale";
+  if (usage.status === "ok" && headline === null && !hasDetails) return null;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (!usage || usage.status === "unsupported") return null;
	if (usage.status === "ok" && headline === null) return null;
	if (!usage || usage.status === "unsupported") return null;
	const hasDetails =
	usage.windows.length > 0 ||
	usage.credits !== undefined ||
	(usage.resetCredits?.availableCount ?? 0) > 0 ||
	usage.freshness?.state === "stale";
	if (usage.status === "ok" && headline === null && !hasDetails) return null;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/web/src/components/chat/ProviderUsageControl.tsx` around lines 193 -
195, Update the early-return logic in ProviderUsageControl so status "ok"
snapshots are not hidden solely when headline is null. Use the snapshot’s
available displayable details—the same criteria supported by
ProviderUsageExpandedContent—to decide whether content exists, preserving the
existing null and unsupported checks.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Separate the canonical deduplication key from the account label.

This field permits arbitrary auth labels, while packages/client-runtime/src/providerUsage.ts lowercases it for deduplication. Case-sensitive labels can therefore merge unrelated accounts. Add a canonical provider-issued accountKey and keep the human-readable account label separate.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/contracts/src/providerUsage.ts` around lines 104 - 109, The provider
usage schema currently uses the human-readable account label as the
deduplication input. Update the provider usage contract around account to add a
canonical provider-issued accountKey, while retaining account for display/auth
labels; update the client-runtime deduplication logic to use accountKey
exclusively and avoid lowercasing or merging based on account.

[jetblk]

Closing because this branch builds on provider-usage work that lives on the fork main, so the correct review target is jetblk#5: jetblk#5