Account-first Phase 1: account registry, default identity, cache stamp, plain-matching CLI/API

[robinebers]

TL;DR

The account-first structural core (Phase 1 of docs/research/account-first-plan.md), invisible to every existing user: each Claude/Codex login becomes an account record with a stable id, cached snapshots remember which account produced them, and the CLI/API answer ids by plain string matching — no alias resolution.

What was happening

• Nothing modeled which account a Claude/Codex card shows. Swapping the login at ~/.claude/~/.codex between launches painted the previous account's cached limits and plan under the new login until the first refresh.
• The CLI and local HTTP API treated claude/codex as plain provider ids, with no defined behavior for the multi-account phases to build on.

What this changes

• ProviderAccountsStore (openusage.providerAccounts.v1): every account is a record with an opaque identity key and a stable id minted at creation. The first account observed at a family's default home keeps the bare id — existing installs migrate by doing nothing. "Default" is an exclusive per-family badge on a source, never a key.
• DefaultAccountObserver reads which account is signed in at each default home only (no candidate scanning): Claude's state file (org-scoped identity), Codex's auth.json under the strict rule — tokens.account_id or the id_token's ChatGPT account claim. An account that can't name itself is reported unresolved, never guessed by path. While a Codex keychain item exists (in-process attributes-only probe; the secret is never read at launch), the family stays unresolved — a later phase binds keyring identities.
• ProviderAccountAssembly runs the pass at launch off the main thread's critical path. ProcessEnvironmentReader pins identity-relevant shell facts (CLAUDE_CONFIG_DIR, CODEX_HOME, …) to Phase 0's persisted snapshot for the whole session, so the identity pass and every provider read resolve the same homes by construction; the pass skips per family only on a genuinely first launch where that family's override could be invisible. Soak trail documented in docs/debugging.md.
• Snapshot cache v9: entries carry a producedByIdentityKeys sidecar. One shared predicate (hasStaleAccountStamp) guards all three read paths — launch paint, the refresh cache-hit gate, and the CLI's persisted-freshness reads — so a swap discards the stale entry instead of serving it. Unresolved identity = today's behavior exactly.
• CLI + local HTTP API: plain matching, no aliasing (breaking /v1 change). A requested id names an exact card, or, as a family id, every card of that family; every match is returned and an id naming nothing is 404. The answer never depends on runtime state. Both surfaces always return the multi-provider shape: the limits envelope (already keyed by card id), and /v1/usage/:id now returns an array (was a single object; the 204 no-snapshot answers became 200 with an empty shape). ProviderCardResolver and its alias rules are deleted.

Heads-up

• Deliberate /v1 breaking change (owner decision): /v1/usage/:id single-object → array, 204s → 200 + empty shape. Made now, before multi-account ships, so the shape never forks on how many cards an id names.
• The CLI's exit code 3 ("no cached snapshot") is gone — that state can no longer occur (a known id always yields an envelope, empty or not); unknown ids exit 2 as before.
• Zero visible change in the app while each family has one account — that's the point of the phase; the flip ships before any multi-account discovery exists.
• The v8→v9 cache key bump refetches once on upgrade (established pattern), so every retained entry is stamped from its first write.
• Signed-out rendering + "Remove Account…" slid to Phase 2 per the plan (meaningless while a family can only have one card).

Tests

• New suites: ProviderAccountsStoreTests, DefaultAccountObserverTests, ProviderAccountAssemblyTests, WidgetDataStoreAccountCacheTests; plus family-matching and status-code coverage in the LocalUsageAPI/LocalLimitsAPI tests and environment-layering tests. Full suite: 1249 green.
• Multiple local + remote Bugbot rounds; all findings fixed (CLI stale-cache gap, refresh cache-hit gap, Codex keychain-fallback stamping, main-thread launch stalls, identity/provider environment splits, per-family first-launch skip).
• Live run: both identities resolve on this machine, correct stamps; curl verified the new array/404 shapes and the family-matching envelope.

Made with Cursor

[cursor]

Cursor Bugbot has reviewed your changes using default 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 aeb0938. Configure here.}