Usage limits need a stable logical account identity beyond email and plan labels

[kvnloo]

Problem

The current Usage → Limits identity layer is forced to infer subscription identity from display-ish fields:

• native providers expose auth.email + auth.label;
• hubs expose email + plan;
• Claude work for Usage → Limits merges two Codex subscriptions that share an email address #10835 is adding a human-readable organization name.

That works for some cases, but it cannot represent the actual invariant: which logical subscription/workspace/quota bucket does this snapshot belong to?

Real failures already exist:

• Usage → Limits merges two Codex subscriptions that share an email address #10835: Personal + Business Codex subscriptions on one email collapse.
• [Bug]: Codex usage limits intermittently reset to 100% in T3 Code desktop after refresh #11463: switching Personal/Business can surface the wrong quota snapshot.
• bug: /usage-limits counts the same subscription more than once #10701: the same subscription can be counted more than once.
• Usage view misreports limits with multi-account Codex routing #11515: proxy/native/hub rows can look like distinct measured accounts when attribution is weak.
• Claude can have one email in multiple orgs, including two orgs with the same plan/name.

Existing stronger identities

The provider edges already expose stronger IDs:

• Codex/CLIProxy ID tokens carry chatgpt_account_id.
• Claude keeps oauthAccount.organizationUuid in .claude.json; reset-credit redemption already reads that UUID.
• Hub auth records already have stable per-account IDs.

The shared contracts currently discard these before packages/shared/src/usageLimits.ts.

Proposed contract

Add one optional stable logical identity to both native and hub account snapshots:

ServerProviderAuth {
  ...
  accountId?: string
}

UsageLimitSourceAccount {
  ...
  accountId?: string
}

Semantics:

• accountId identifies the logical subscription/workspace/quota source for grouping.
• It is provider-scoped; collectors key on driver + accountId.
• It is not a display label and should not be rendered raw by default.
• Email, plan and organization name remain display/fallback metadata.
• Missing accountId keeps today's conservative fallback behavior.

Provider mappings:

• Codex → chatgpt_account_id when present.
• Claude → organizationUuid when present.
• Hub adapters → the same provider-native identity when available.

Grouping precedence

For account dedupe/merge:

1. driver + accountId when both observations provide it;
2. provider-specific fallback such as email + org/plan when stable identity is missing;
3. environment/source instance identity when equivalence cannot be established.

An unknown ID must never be treated as matching a known ID merely because email/plan happens to match when multiple known accounts exist.

Why this shape

This is the same separation Tokenomics now uses with measurement_source.logical_source_id: observer identity, human labels and logical quota identity are different concepts.

It also lets #10845 and #13089 remain useful incremental fixes without making plan strings or organization display names the long-term identity contract.

Acceptance

• optional stable account id added without breaking older snapshots;
• Codex native + hub map chatgpt_account_id;
• Claude maps organizationUuid;
• collectors prefer stable id and fall back safely;
• same account across environments/native+hub dedupes once;
• same email + same plan but different stable ids stays separate;
• unknown-id observations do not attach arbitrarily when multiple known ids share an email;
• reset-credit targets follow the same logical identity as the displayed quota.

Related

• Usage → Limits merges two Codex subscriptions that share an email address #10835 / fix(usage): keep same-email Codex subscriptions apart when their plans differ #10845
• fix(usage): keep one email in two Claude orgs as two accounts #13089
• fix(codex): report the stored login email when a custom provider hides the account #13114
• bug: /usage-limits counts the same subscription more than once #10701 / fix(usage): deduplicate native subscription accounts #10700
• [Bug]: Codex usage limits intermittently reset to 100% in T3 Code desktop after refresh #11463
• Usage view misreports limits with multi-account Codex routing #11515

[juliusmarminge]

Triage

This is not a separate bug. The quota mix-ups it lists already have issues, and the identity gap is already diagnosed on #10835.

On current main, accountKey in packages/shared/src/usageLimits.ts is the driver plus the lowercased email. ServerProviderAuth only carries status, type, label, and email. Hub snapshots put the auth-file id on UsageLimitSourceAccount.id, and that is what reset redemption addresses. chatgpt_account_id is decoded in apps/server/src/usage/cliproxyApi.ts, sent as Chatgpt-Account-Id, and folded into creditRedeemRequestId, then dropped before the snapshot. The native Codex probe never reads it. It only publishes planType and email. Claude's organizationUuid is read only in claudeResetCredits.ts. ClaudeProvider publishes the email, not the UUID.

#10835 is the accepted issue for two quotas that share an email. Its triage already says to split Codex when the plan label differs, and it leaves the same-plan residual. The Claude org case, and keying on organizationUuid / chatgpt_account_id, is already in #10835 (comment). #13674 was closed onto that thread. #10701 is the opposite bug, one subscription counted twice, and #10700 has to keep merging that case. #11463 is one Business account flipping to a full-looking snapshot on refresh, not this merge. #11515 stays its own accepted report.

#10845 and #13089 are the incremental fixes. #13089's org field is the display name, which is not a stable id. That correction belongs on #10835 or on those PRs, not as a new contract ticket.

Carrying a workspace id through provider auth was already opened as #10873 and #10876 and closed: provider-layer identity changes wait for the V2 rewrite. One correction if that work comes back: #10876 found different Business members can share one chatgpt_account_id and still have different quotas, so driver + accountId alone would merge them. The id has to be the quota bucket, not the workspace id by itself.

Closing as a duplicate of #10835.