claude update shows false PATH warning on macOS when $HOME/.local/bin is in PATH

Summary

On macOS, claude update prints

Warning: Native installation exists but ~/.local/bin is not in your PATH Fix: Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc …

even when $HOME/.local/bin is unambiguously present in $PATH. The advised fix is a no-op — the export is already in the user's shell config.

Reproducer (minimal)

$ PATH="$HOME/.local/bin:/usr/bin:/bin" claude update
Current version: 2.1.112
Checking for updates to latest version...

Warning: Native installation exists but ~/.local/bin is not in your PATH
Fix: Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc
Claude Code is up to date (2.1.112)

$HOME/.local/bin is the very first PATH entry, yet the check fails.

Environment

• claude 2.1.112 (native install, ~/.local/share/claude/versions/2.1.112)
• macOS 26.4.1 (Darwin 25.4.0, arm64)
• zsh (.zshenv, .zprofile, .zshrc all export $HOME/.local/bin to PATH)

Hypothesis

From strings on the 2.1.112 binary, the macOS/Linux branch of the check is roughly:

process.env.PATH
  .split(path.delimiter)
  .some(f => {
    const j = path.resolve(f);
    return j === A;   // A = resolved target path
  });

Given that path.resolve('/Users/me/.local/bin') returns itself, a literal string mismatch is the likely cause — target A is probably computed via fs.realpathSync or contains a different form of $HOME (e.g. with trailing slash, or symlink-resolved) while the PATH entry is not normalized the same way.

Impact

Cosmetic — update still completes. But the suggested fix is misleading (users add the export repeatedly with no effect) and clutters claude update output.

Related

• #48068 — same behavior on Windows (has repro)
• #24397, #22110 — Linux startup variants (marked stale)