[tiagolabsit]

Summary

• /dashboard/analytics/utilization can show a provider as healthy while one of its quota windows is exhausted. Example from a Claude Team account: the weekly window sat at 0 % (exhausted) for days while the chart and the "latest snapshot" card read ~13 % / 96 %.
• Root cause: getAggregatedSnapshots() grouped by (bucket, provider, window_key) and returned one row per quota window, but ProviderUtilizationTab builds row[provider] = remainingPct per timestamp and takes the "latest" point per provider, so whichever window's row came last in a bucket won. For a provider with a 5h session window and a weekly window that is arbitrary, and it hid the exhaustion.
• Fix: collapse the windows inside the query. Each (bucket, provider-or-connection) now yields one point: the tightest window (lowest remaining percentage, named in windowKey), isExhausted when any window is. Samples of the same window inside a bucket are still averaged first, so the existing behaviour for single-window providers is unchanged.
• Side fix: windowKey was always undefined in the response because the SQL column is window_key; it is now aliased, so the field declared in ProviderUtilizationPoint is finally populated.

Related Issues

• Closes # (none filed)

Target Branch

• Base is the active release/v3.8.x branch (the highest open release/v*), not main

Proof Of Fix (required)

• TDD (preferred) — a test that fails before the fix and passes after it.
  • Test file(s): tests/unit/db-quota-snapshots.test.ts (new case: quotaSnapshots aggregation returns one row per bucket with the tightest window)
  • Failing output before the fix:

    ✖ quotaSnapshots aggregation returns one row per bucket with the tightest window
      AssertionError: one row per bucket, not one per quota window
        actual: 4, expected: 2
    

  • After the fix: the whole file passes (4/4), plus usage-utilization-connection-meta and utilization-route-import-10939 (9/9 together).

Scope

• Only the files the failing test proves need changing are touched
• No test was weakened or deleted to make the suite pass

Validation

• Change type: DB / dashboard
• Focused tests: node --import tsx/esm --test tests/unit/db-quota-snapshots.test.ts tests/unit/usage-utilization-connection-meta.test.ts tests/unit/utilization-route-import-10939.test.ts
• npm run lint on the touched files (the repo hooks passed on commit). One pre-existing no-unused-vars for the JsonRecord type in quotaSnapshots.ts is on the base branch and is untouched here.

Reviewer Notes

• Design choice worth a look: "tightest window" is the right health signal for plan-style providers (Claude/Codex: session + weekly), where the card colours at ≤ 20 % remaining. For providers that publish one window per model (e.g. Antigravity) the series now follows the most constrained model instead of an arbitrary one. If you would rather average those, the window-collapse is isolated in the outer SELECT of the CTE and is easy to special-case.
• The collapse is done in SQL (window functions, already used in this file by getLatestQuotaSnapshotsForConnection), so the route and the React tab are untouched and the response shape is unchanged.

[tiagolabsit]

Heads-up for review: the workflow runs on this PR (CI, Quality Gates, semgrep, API Route Typecheck) are sitting in action_required because this is a fork PR, so none of them have executed yet. Could a maintainer approve the runs?

Checked locally by merging this branch onto the current release/v3.8.52 (e2d5747): clean merge, tests/unit/db-quota-snapshots.test.ts passes (4/4), eslint is clean on the touched files, and check:changelog-integrity and check:test-discovery pass.

Once the checks are green, the PR still needs the queue label for the Mergify release queue to pick it up (the Mergify check is currently "waiting for queue conditions").

One unrelated note: check:file-size already fails on release/v3.8.52 itself (open-sse/services/combo/executeTargetAttempt.ts is 1288 lines vs the frozen 1284), so a red Quality Gates run may come from there rather than from this change.

[tiagolabsit]

Rebased onto the current release/v3.8.52 (88c1e33) and re-pushed, now that the earlier base-reds (#16420, #16496) have landed. On this branch check:docs-all and check:agent-skills-sync are green locally, and the new/changed tests pass. What check:file-size still flags (responseSanitizer.ts, error.ts and two test files over their frozen ceilings) comes from other merges on the release tip, not from this diff. Could a maintainer approve the workflow runs for this fork PR when convenient?

[tiagolabsit]

Added a follow-up commit (8f78863) for the multi-account case: with two accounts of one provider, the provider-level series averaged/MAX'ed across accounts per bucket, so a single exhausted account (re-snapshotted often) painted the whole provider as exhausted/0%, while a healthy account with no recent change contributed nothing (snapshots are stored only on change). Now each account is reduced to its tightest window, unchanged accounts are carried forward (seeded from before the range), and the provider point follows the best account — exhausted only when every account is. Connection aggregation is untouched. 4 new regression tests in tests/unit/db-quota-snapshots.test.ts.

[tiagolabsit]

Follow-up (5c42307): the per-account view still averaged only the windows that had a row in the bucket, so an account whose weekly window rarely changes looked nearly full while the provider view showed it much lower. Both views now share the same per-account reduction (tightest window, unchanged windows carried forward). Test added.