[BUG] AutoUpdater race condition corrupts npm global installation with concurrent long-running sessions

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The Claude Code AutoUpdater has a race condition that corrupts the npm global installation when multiple long-running sessions attempt to auto-update simultaneously. The corruption leaves the CLI completely unusable, requiring manual reinstallation.

Root Cause Analysis

The Race Condition

The AutoUpdater runs on a fixed schedule (every 30 minutes at :24 and :54 past the hour) in every active Claude Code session. When multiple sessions are running concurrently, they all attempt to check for/install updates at the exact same moment.

Evidence from debug logs showing 7 concurrent auto-update triggers within 70ms:

2026-01-18T00:18:41.627Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.633Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.634Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.639Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.653Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.683Z [DEBUG] AutoUpdater: Detected installation type: npm-global
2026-01-18T00:18:41.694Z [DEBUG] AutoUpdater: Detected installation type: npm-global

Multiple Concurrent Terminal Sessions

The root cause is that each Claude Code process runs its own AutoUpdater independently. When running Claude Code in multiple terminal windows (a common workflow for power users), each terminal session has its own auto-update timer.

At the time of corruption, I had multiple terminal sessions open:

| Session ID | Started | Duration | User Prompts |
|------------|---------|----------|--------------|
| 1cf3b56a | Jan 15, 4:00 PM | 3+ days | 190 |
| 407b45d0 | Jan 16, 4:35 PM | 2+ days | 13 |
| 3abd847f | Jan 17, 3:33 AM | 1.5+ days | 29 |
| + 9 more sessions | Various | Hours to days | Various |

12 concurrent Claude Code processes were all triggering the auto-updater at the exact same scheduled times.

The Lock Mechanism Failure

The AutoUpdater uses a lock to prevent concurrent updates, but:

1. The lock persisted indefinitely after an update was interrupted
2. No timeout mechanism exists to clear stale locks
3. No PID verification to check if the locking process still exists
4. The error "Another process is currently installing an update" repeated every 30 minutes for 17+ hours without self-recovery

The Corruption Event

At 10:54 AM (17:54 UTC), another batch of concurrent auto-update attempts occurred and left only partial installation artifacts - empty dependency directories with no actual code:

/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/
├── node_modules/
│   └── @img/
│       ├── sharp-darwin-arm64/  (empty)
│       └── ... (14 more empty directories)

Missing files: cli.js, package.json, all source code, vendor/ripgrep/

What Should Happen?

1. Auto-updates should be coordinated across sessions (only one update at a time, globally)
2. Lock files should include PID and timestamp, with automatic expiration
3. Failed/interrupted updates should roll back cleanly
4. Corrupted installations should be detected and trigger auto-repair or user notification
5. The CLI should remain functional even if an update fails

Error Messages/Logs

Lock error timeline (partial):
2026-01-18T00:54:00.062Z [ERROR] Another process is currently installing an update
2026-01-18T02:54:00.091Z [ERROR] Another process is currently installing an update
2026-01-18T03:24:00.351Z [ERROR] Another process is currently installing an update
... (continued every 30 min)
2026-01-18T17:54:00.554Z [ERROR] Another process is currently installing an update

Corruption event logs:
2026-01-18T17:54:00.550Z [DEBUG] AutoUpdater: Using global update method
2026-01-18T17:54:00.551Z [DEBUG] AutoUpdater: Using global update method (3 sessions)
2026-01-18T17:54:00.554Z [DEBUG] AutoUpdater: Using global update method

Filesystem state after corruption:
$ ls -la /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/
drwxr-xr-x  3 user  admin  96 Jan 18 10:54 .

$ /opt/homebrew/bin/claude --version
zsh: no such file or directory: /opt/homebrew/bin/claude

Steps to Reproduce

1. Install Claude Code globally via npm: npm install -g @anthropic-ai/claude-code
2. Start 5+ Claude Code sessions in separate terminal windows
3. Leave sessions running for extended periods (hours to days)
4. Wait for the scheduled auto-update time (:24 or :54 past the hour)
5. If multiple sessions race to update simultaneously, the installation may become corrupted

Factors that increase likelihood:

• More concurrent sessions = higher chance of race condition
• Longer-running sessions = more opportunities for the race
• Network latency during npm install = wider window for race
• Existing stale lock = guaranteed failure for all subsequent attempts

Workaround: Manually reinstall with npm install -g @anthropic-ai/claude-code

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.x (corrupted; reinstalled to 2.1.12)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

This is a normal usage pattern: Power users often have multiple Claude Code terminal sessions open for different projects or tasks. This is not an edge case.

• I typically have 3-5 terminal windows with Claude Code sessions running simultaneously
• Sessions often stay open for days as I context-switch between projects
• The corruption occurred overnight when no user interaction could intervene
• The issue has been present since at least Jan 11 (first occurrence of lock error in logs), but only caused corruption on Jan 18
• Any user who runs multiple Claude Code sessions in parallel is at risk of hitting this bug