[BUG] npm global update leaves a stub binary and no bin/claude symlink — no rollback, and the error message is unreachable

Preflight Checklist

• [ ] 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?

Environment

• macOS (Darwin 25.5.0), Apple Silicon
• node v22.13.0 via nvm, global npm install
• @anthropic-ai/claude-code 2.1.225 (updating from 2.1.224)
• npm config: ignore-scripts=false, omit= (empty), foreground-scripts=false
• Disk: 677 GB free
• Third occurrence of this exact failure

Symptom

After an auto-update, the claude command disappears entirely:

no such file or directory: /Users/<me>/.nvm/versions/node/v22.13.0/bin/claude

State after the failed update

1. lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe is a 500-byte, non-executable shell script — the "native binary not installed" error stub, not the real binary.
2. No claude symlink exists in .nvm/versions/node/v22.13.0/bin/.
3. The previous working binary is orphaned in the npm staging directory @anthropic-ai/.claude-code-UVkpX84a/bin/claude.exe (277 MB, -rwxr-xr-x, v2.1.224, link count 2).
4. Timestamps show two update attempts an hour apart (06:24 and 07:25), both leaving artifacts behind.

Why the documented causes don't apply

The stub attributes this to --ignore-scripts or --omit=optional. Neither is set:

ignore-scripts     = false
omit               =
foreground-scripts = false

Three things that turn a transient download failure into an unrecoverable one

1. No rollback. 2.1.224 was working. The failed 2.1.225 replaced it and left nothing runnable, with the good binary stranded in a staging directory. An interrupted update should leave the previous version intact.
2. The error message is unreachable. The stub contains exactly the right guidance (run node install.cjs), but because the symlink was never created it can never execute — so the user sees no such file or directory instead. Creating the symlink before, or regardless of, the binary download would surface the actionable message.
3. No post-download verification. A 500-byte claude.exe where a ~277 MB binary is expected is trivially detectable. A size or checksum check at the end of postinstall would fail loudly rather than silently installing a stub.

Repair that worked

• Claude Code’s update had partially completed:

  1. The new Claude package and native Apple Silicon binary were downloaded.
  2. The update failed before creating the terminal command symlink.
  3. A stale backup directory from the failed update prevented npm from repairing or uninstalling the package, producing an ENOTEMPTY error.
  4. We moved that stale directory to /private/tmp so it remains recoverable.
  5. We uninstalled and reinstalled the same Claude Code version, 2.1.225.
  6. The reinstall correctly recreated:

  ~/.nvm/versions/node/v22.13.0/bin/claude

What Should Happen?

1. Verify the binary after download; fail the install if it's a stub.
2. Keep the previous version until the new one is verified.
3. Ensure the symlink exists so the stub's own error message can actually run.

Error Messages/Logs

no such file or directory: /Users/<me>/.nvm/versions/node/v22.13.0/bin/claude

Steps to Reproduce

No such steps since update happens automatically

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.225

Platform

Other

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_