feat(install): prefer ~/bin when already on PATH (B2, RFC 0001)

[LukasWodka]

What (B2, cli side)

The RFC 0001 B2 fix, step 1: prefer a writable dir already on $PATH so the CLI is usable in the same terminal.

When /usr/local/bin isn't writable, the installer fell straight to ~/.local/bin — which on many setups isn't on the current shell's $PATH, so tracebloc isn't resolvable until a new terminal (or an rc reload). This adds one step before that fallback:

• If ~/bin already exists, is on $PATH, and is writable → install there. The binary is then usable in this shell and every new one, with no rc edit and no new terminal.
• Otherwise → the existing ~/.local/bin fallback + shell-rc persistence, unchanged.

Deliberately restricted to the conventional general-purpose ~/bin — never a language-specific dir (~/.cargo/bin, ~/go/bin, …) that merely happens to be on $PATH, which would be a surprising place to drop tracebloc.

Safety / tests

• POSIX sh; shellcheck --shell=sh --severity=error (CI's invocation) and--severity=warning clean; dash -n clean.
• The ~/.local/bin fallback path — what the cross-repo fresh-shell PATH guard (install-path-persist.yml → client's path-persist.sh) exercises — is untouched. Labeled e2e so that guard runs against this PR and confirms no PATH-persistence regression.

Scope

The cli half of the least-privilege install's B2. The client half (honest final CTA — never tell the user to run a command this shell can't find) is tracebloc/client#371.

Part of the least-privilege install epic — tracebloc/backend#1168, ticket tracebloc/backend#1174.

🤖 Generated with Claude Code

---

Note

Low Risk
Installer-only UX and fallback logic; the ~/.local/bin path and security-sensitive download/verify flow are unchanged.

Overview
When the chosen install prefix isn’t writable, the installer now tries writable ~/bin that’s already on $PATH before falling back to ~/.local/bin, so tracebloc can work in the current shell without an rc change or new terminal (RFC 0001 B2). That path is limited to conventional ~/bin (not tool-specific dirs like ~/.cargo/bin), with guards for empty//HOME and trailing-slash PATH entries.

PATH detection for “already on PATH” and “needs rc persistence” now treats $dir/ the same as $dir. Post-install messaging uses a new on_path flag so users see “ready to use now” when the install dir is already on the current shell’s PATH, instead of being told to open a new terminal.

^{Reviewed by Cursor Bugbot for commit d4035fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 878a7fd. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[divyasinghds]

Approve. Prefers ~/bin only when on PATH + existing + writable (conservatively excludes language-specific dirs); rc-persist is idempotent (comment-stripped, case-insensitive PATH-op match with a [^A-Za-z_] guard) and messages are honest in all three states. Well-reasoned.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit d5881bf. Configure here.}

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit d5881bf. Configure here.}

[divyasinghds]

Approve (re-review after force-push). The refinements since my first approval are all sound, no regressions:

• Trailing-slash tolerance in the ~/bin-on-PATH detection (*":$home_bin/:"*), applied consistently to the persist and on_path checks too — a $HOME/bin/ PATH entry no longer wrongly falls back to ~/.local/bin.
• HOME=""/HOME="/" guard before preferring ~/bin — prevents a root process (HOME=/ → ${HOME%/}/bin = /bin) from dropping the CLI into /bin.
• Messaging now keys off on_path across added/present/failed states, so it says "ready to use now" instead of nagging "open a new terminal" when the dir is already on PATH.

Core logic (mkdir-then-fallback, idempotent rc write) unchanged and still correct. CI green. LGTM.