fix(upgrade): stop npm installs self-shadowing on upgrade; verify the resolved version after every upgrade

[colbymchenry]

Companion to #1239 / #1238. Together they make three guarantees hold after codegraph upgrade: hooks refreshed, agent instruction files refreshed (#1239), and — this PR — codegraph -v in the same terminal provably serving the new version.

Problem 1 — npm installs self-shadow on upgrade (found while validating #1239)

Reproduced live in a sandboxed $HOME: install 1.3.1 via npm i -g, run codegraph upgrade — and codegraph --version reports 1.3.1 forever, in that terminal and every future one.

Root cause: the npm thin-installer's per-platform package (@colbymchenry/codegraph-<platform>-<arch>) is itself a complete bundle — vendored node + bin/ launcher — living inside node_modules. detectInstallMethod checked the bundle layout before the node_modules path, so every npm install misdetected as a standalone bundle and upgrade curled install.sh into ~/.codegraph: a second install that never wins the PATH race against npm's shim. The #1071 shadow pile-up, manufactured by upgrade itself.

This also silently broke #1239 for npm users (the issue author's own environment): its post-upgrade codegraph install --refresh spawn resolves the stale npm shim, which doesn't know --refresh.

Fix: path-based checks (/_npx/, /node_modules/) now run before the layout sniff — where the file lives is authoritative about how the user installed, whatever the artifact inside looks like. npm installs upgrade through npm install -g …@latest again: same shim path, so the same terminal picks up the new version immediately. The shim's GitHub-download self-heal cache (~/.codegraph, issue #303) is outside node_modules and still detects as a bundle.

Problem 2 — nothing ever verified the upgrade took

The unix-bundle path ended with "✓ Upgrade complete. Open a new terminal if the version looks unchanged (PATH cache)" — an unconditional hedge for a failure mode we can detect. After a successful swap, runUpgrade now probes the PATH-resolved codegraph --version (through cmd.exe on Windows for the .cmd launcher) and reports the real outcome:

• match → ✓ codegraph on your PATH now reports v1.4.0 — this terminal is already using it.
• mismatch → a loud warning that a stale install is shadowing the upgraded one, with which -a codegraph / where codegraph to find it. Warn-only; the upgrade itself still exits 0.
• inconclusive (no codegraph on PATH, probe fails or output unparsable) → the old soft new-terminal hint, never a scare.

Skipped for npm-local installs, whose binary PATH never serves. New capture dep on UpgradeDeps (piped stdio, 30s timeout) keeps it unit-testable; probe parsing takes the last non-empty stdout line so a stray runtime warning can't spoil it.

Validation

• 3 detection regression tests (thin-installer platform package → npm global / npm local / npx-cached) — verified to fail against the pre-fix code and pass now.
• 8 probe orchestration tests: match / mismatch / both inconclusive shapes / last-line parsing / Windows cmd.exe routing / npm-local skip / no probe after a failed upgrade.
• Full suite: 2290 passed, 4 skipped (platform-gated).
• Live e2e against real binaries in a sandboxed $HOME: bundle 1.3.1 → upgrade → same-shell -v = 1.4.0 with the green confirmation; simulated shadow prints the warning. (The npm misdetection itself was reproduced live pre-fix: upgrade curled install.sh and left the shim at 1.3.1.)

Interaction with #1239

Independent — either can merge first; whichever lands second has a trivial conflict in runUpgrade's post-success block and the CHANGELOG. Ordering note for the rebase: the version probe should run (and ideally gate) before the install --refresh spawn, so the refresh never executes through a shadowed stale binary.

🤖 Generated with Claude Code

[colbymchenry]

Cross-platform validation

Linux (Docker, node:22-bookworm, --rm --init)

• Targeted suites: 194/194. Full suite: 2290 passed, 4 skipped (platform-gated), 0 failed.
• Live e2e in the container: real install.sh bundle 1.3.1 → codegraph upgrade → same-shell codegraph --version = 1.4.0.
• Probe harness with the real defaultCapture/hasCommand against the PATH-resolved binary: match prints the green confirmation; a forced mismatch prints the shadow warning.

Windows (Parallels VM, win32-arm64, Node 24, fresh npm ci at C:\dev\codegraph on b108500)

• Targeted suites: 194/194 (upgrade 43, installer-targets 151).
• Live probe against a naturally occurring The version and the “--version” display are inconsistent #1071 shadow found on the VM: a stale 0.9.6 bundle launcher (AppData\Local\codegraph\current\bin\codegraph.cmd) sits earlier on PATH than a fresh 1.4.0 npm install, so codegraph --version genuinely reports 0.9.6.
  • Target v1.4.0 → mismatch: the shadow warning fired on a real-world true positive.
  • Target v0.9.6 → match: green "this terminal is already using it."
  • This exercised the cmd.exe /d /s /c routing, the PATHEXT hasCommand scan, and CRLF stdout parsing against a real .cmd launcher.

🤖 Generated with Claude Code