Windows PATH shadowing can leave multiple specsmith installs active after pipx install/upgrade

[tbitcs]

Summary

On Windows, specsmith can be installed or exposed from more than one location (pipx, Python Scripts, symlink shims, Scoop-managed Python paths). That leaves users in a confusing state where specsmith appears upgraded, but a different launcher may still be found on PATH or be shadowing the intended one.

What happened on this machine

Date: 2026-07-10
Host: Windows

Tool discovery showed:

python.exe    C:\Users\trist\scoop\apps\python312\current\python.exe
specsmith.exe C:\Users\trist\.local\bin\specsmith.exe

Then I ran:

pipx install --force specsmith==0.21.0.dev787

pipx reported:

Installing to existing venv 'specsmith'
  installed package specsmith 0.21.0.dev787, installed using Python 3.12.10
  These apps are now globally available
    - specsmith.exe
⚠️  Note: specsmith.exe was already on your PATH at
    C:\Users\trist\scoop\apps\python312\current\Scripts\specsmith.exe

That warning is easy to miss, and it indicates the system may now have more than one live specsmith.exe path.

Why this is a problem

This makes governance failures harder to diagnose because users can end up with:

• pipx believing it upgraded specsmith
• a different specsmith.exe already on PATH
• unclear which launcher a shell or app is actually invoking
• repeated version mismatch / downgrade errors with no obvious remediation

Expected behavior

Specsmith should provide a safer Windows story for launcher resolution, for example one or more of:

• a specsmith doctor or specsmith self-check that detects multiple installations on PATH
• an explicit warning when the active executable is not the one pipx just updated
• documented/supported cleanup steps for duplicate launchers
• a preferred launcher strategy that avoids ambiguous shims on Windows

Actual behavior

The install succeeded, but the environment still had multiple candidate specsmith.exe locations and no built-in guidance for normalizing them.

Suggested fix

• Add PATH-shadowing detection to startup or doctor
• Print the actual executable path and package version in error output
• Add Windows cleanup guidance for duplicate specsmith.exe launchers (pipx, Python Scripts, Scoop shims, symlinks)
• Consider failing harder or prompting when a new install detects a preexisting specsmith.exe earlier on PATH

This one is worth tightening because it compounds every other specsmith support issue on Windows.