OAuth token refresh race condition kills parent session during parallel agent spawns

Description

When spawning 3-4 parallel agents (via Agent tool with isolation: "worktree"), the parent/lead session intermittently loses authentication mid-operation with "Not logged in · Please run /login" followed by API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth authentication is currently not supported."}}.

The auth is not actually broken — opening a new terminal works immediately. The existing session has a stale token cached in memory.

Environment

• Claude Code v2.1.81
• macOS (Apple Silicon, M4 Mac Mini)
• Auth method: claude.ai (Max subscription, OAuth)
• Agent teams enabled: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Steps to Reproduce

1. Start a Claude Code session with agent teams enabled
2. Spawn 4 agents simultaneously using Agent tool with isolation: "worktree" (each gets its own git worktree)
3. Wait for agents to complete (~3-5 minutes of concurrent work)
4. As agents finish, the parent session reports "Not logged in · Please run /login"
5. Subsequent messages return API Error: 401

Expected Behavior

Parent session should remain authenticated while child agents are running. Token refresh should be coordinated across all processes sharing the same credential.

Actual Behavior

• Agents 1-2 complete successfully
• Agent 3 or 4 completion triggers "Not logged in" on the parent session
• The parent session is dead — cannot recover without /login or starting a new terminal
• New terminals work immediately (fresh token read from disk)

Root Cause (community analysis from #24317)

OAuth refresh tokens are single-use. When one agent process refreshes the token, the old token is invalidated server-side. Other processes (including the parent) still holding the old token in memory get 401 errors. The file-based lock added in v2.1.81 has only 5 retries / ~7.5s max wait, which is insufficient for 4+ concurrent processes.

Frequency

Happens multiple times per day when running 4-agent waves. Reducing to 3 agents with 30-second stagger between spawns mitigates but doesn't fully eliminate the issue.

Workaround

• Cap concurrent agents at 3 (instead of 4)
• Stagger agent spawns by 30 seconds (gives 4x margin over the 7.5s lock window)
• When it happens: /login in the dead session, or start a new terminal

Related Issues

• #37520 — v2.1.81 multiple parallel agents cause 401
• #37324 — Session token expires with concurrent subagents
• #24317 — Frequent re-authentication with concurrent sessions (detailed analysis)
• #12447 — OAuth token expiration disrupts autonomous workflows

Suggested Fix

The lock retry budget (5 attempts) needs to scale with concurrency, or a token broker/daemon should serialize refresh requests across all child processes. Per-process token isolation would be the most robust solution.