OAuth token refresh race condition with multiple concurrent sessions on same machine

Environment

• Claude Code version: 2.1.39 / 2.1.41
• OS: Ubuntu 22.04 (Hetzner VPS)
• Auth method: claudeAiOauth (Max plan)

Description

When running multiple Claude Code sessions concurrently on the same machine (e.g., in separate tmux panes or terminal tabs), OAuth tokens are frequently revoked mid-session, requiring manual re-authentication and interrupting work.

All sessions share the same credential file (~/.claude/.credentials.json), but there is no coordination (file lock, mutex, or leader election) during token refresh. This causes a classic refresh token rotation race condition.

Steps to Reproduce

1. Open 2+ terminal sessions on the same machine
2. Start claude in each (all authenticate via the same OAuth credentials)
3. Use them concurrently over several hours
4. Eventually the OAuth access token expires and multiple sessions attempt to refresh simultaneously

What happens

1. Session A detects token expiry → sends refresh request to Anthropic
2. Session B also detects token expiry → sends refresh request with the same (now-stale) refresh token
3. Anthropic issues a new token for A, invalidating the old refresh token
4. Session B's refresh request fails because it used the now-invalid refresh token
5. All sessions lose authentication; manual claude re-login required

Evidence

At the time of diagnosis, 4 Claude Code processes were running concurrently on a single machine:

camillo  1002351  pts/14 Sl+ Feb11   7:57 claude --dangerously-skip-permissions
camillo  1015377  pts/17 Sl+ Feb11  91:44 claude --dangerously-skip-permissions
camillo  1211561  pts/19 Sl+ Feb12  29:25 claude --dangerously-skip-permissions
camillo  1575480  pts/15 Rl+ 18:22   5:06 claude --dangerously-skip-permissions

This issue does not occur on a single-session setup (e.g., MacBook with one terminal). It only manifests on environments where sessions accumulate across tmux panes or terminal tabs.

Expected Behavior

Multiple Claude Code processes on the same machine should coordinate token refresh. Possible approaches:

• File-based lock around token refresh (only one process refreshes at a time, others wait and re-read the updated credential file)
• Local token refresh daemon/socket that serializes refresh requests
• Retry with re-read from credential file before failing (at minimum)

Impact

• Authentication loss mid-session, losing work context
• Happens approximately 3x per week with normal multi-session VPS usage
• No user-side workaround other than running a single session at a time (which limits productivity)
• Particularly painful for users running agent swarms or parallel workflows that naturally create multiple sessions