[rmcp-client] Serialize shared MCP OAuth stores

[stevenlee-oai]

Codex Thread 019edd6d-6f14-74e2-853c-345d1803d4a6

Important

This PR belongs to the superseded MCP OAuth stack. Please review and merge the replacement stack beginning with openai/codex#30292. This PR remains available only as historical/reference context.

Replacement review order:

1. openai/codex#30292 — shared File/Secrets store locking
2. openai/codex#30293 — authoritative serialized refresh
3. openai/codex#30294 — Codex-owned transport refresh and one-shot 401 recovery
4. openai/codex#30295 — login/logout transaction serialization
5. openai/codex#30296 — diagnostic-only Auto store drift reporting

This is part 3 of a five-PR stack that prevents concurrent MCP OAuth refreshes from replaying a rotating refresh token or overwriting newer credentials.

Review and merge as one stack. The five PRs are an atomic merge unit split only for reviewability. Each tip compiles and is testable, but implementation and regression tests are intentionally not duplicated across intermediate layers.

Review order

1. openai/codex#29017 — refresh ownership, authoritative reread, and lifecycle-local store pinning
2. openai/codex#29019 — serialize login and logout with refresh
3. openai/codex#29021 — lock aggregate stores and observe Auto resolution drift (this PR)
4. openai/codex#29018 — route all OAuth recovery through Codex
5. openai/codex#30089 — consolidated concurrency and transport regression tests

Why

The per-credential transaction lock protects one OAuth authority, but File and Secrets each store multiple server credentials in one aggregate document. Two different credential identities can still race a read-modify-write and lose each other's update.

Separately, lifecycle-local Auto resolution can choose a different store in a later process if keyring availability changes. Persisting that choice as authority would require migration and reconciliation policy that is intentionally outside this stack, but silently changing stores makes field failures hard to diagnose. This layer records only enough token-free history to surface that drift.

What changes

• Add store-scoped cross-process locks around aggregate File and Secrets reads, saves, and deletes.
• Keep aggregate-store locking independent from the per-credential refresh transaction while preserving one acquisition order.
• Hold aggregate locks only for local store work, never across a provider request.
• Add a versioned $CODEX_HOME/.mcp-oauth-store-resolutions.json diagnostic map, serialized with its own short best-effort lock and atomic writes.
• Key each observation with compute_store_key(server_name, url) and store only store_mode, keyring_backend, and resolved_store; no tokens or raw URL are added.
• When the same identity resolves Auto differently under the same keyring backend, emit a warning and increment codex.mcp.oauth.store_resolution_changed with low-cardinality previous/current/reason tags.
• Treat explicit File/Keyring configuration or a keyring-backend change as an intentional baseline reset.
• Emit a stable debug event on actual store-lock WouldBlock contention for diagnostics and deterministic regression tests.

Decisions encoded by this stack

• The per-credential lock protects OAuth authority; the aggregate-store lock protects document integrity. Neither substitutes for the other.
• Lock order is credential transaction first, aggregate store second.
• Direct keyring entries are per credential and do not use the aggregate credential-store lock.
• The resolution sidecar is diagnostic only. It is never read to select, migrate, refresh, save, or delete credentials, and its failures never fail OAuth.
• Diagnostic history is scoped to the active CODEX_HOME, matching File/Secrets state. Distinct homes do not share an authority registry.
• The last token-free observation survives logout and is replaced by the next successful resolution or save, allowing a later login to report a changed Auto choice without resurrecting credentials.
• The existing synchronous store APIs remain synchronous and bounded in this stack; an async store-I/O redesign is separate work.
• Auto never switches stores during one client lifecycle.
• openai/codex#28647 and its branch remain untouched.

Review focus

Review store scope, lock ordering, whether unrelated credential entries survive concurrent read-modify-writes, and the hard boundary between diagnostic history and credential authority.

Non-goals

• Persisting an authoritative backend selector, backend migration, or reconciliation of legacy entries.
• Redesigning the underlying synchronous file/secrets APIs.
• Cleanup of non-selected legacy credential entries.

Validation

• just test -p codex-rmcp-client: 90 passed, 2 skipped at this layer.
• Resolution-state and File/Secrets contention coverage is consolidated in part 5.