fix(install): PATH-aware final CTA (B2, #1174 client half) by LukasWodka · Pull Request #371 · tracebloc/client

LukasWodka · 2026-07-22T15:47:56Z

What (B2, client side)

Least-privilege means the CLI lands in ~/.local/bin (no sudo to write /usr/local/bin). A child-process installer can't change the launching shell's PATH, so tracebloc isn't resolvable in the current shell right after install. install-cli.sh already prints honest guidance for that case — but the final summary still said "Run tracebloc to get started" unconditionally, contradicting it (hit live by mprendke @ [redacted]).

This makes the summary CTA honest:

install-cli.sh records TB_CLI_USABLE_NOW — set to 1 only in the branch where the CLI resolves in this shell (not just a fresh terminal); left 0/unset on any ~/.local/bin, download, install, or verify miss.
summary.sh gains _cli_runnable_now (reads TB_CLI_USABLE_NOW, with a live has tracebloc fallback) and branches the CTA:
- usable now → Run tracebloc to get started.
- not yet on PATH → Open a new terminal, then run tracebloc to get started.

The detailed shell-correct activation (source ~/.zshrc, etc.) still lives in install-cli.sh's step output — this PR only stops the final line from pointing at a command the shell can't find.

Tests

2 new summary.bats cases (grep-based, robust on bash 3.2): CTA is "Run" when usable-now, "Open a new terminal" when not.
install-cli.bats suite green; shellcheck --severity=warning clean; R8 manifest regenerated.
Note: 3 failures exist in common.bats / install-bootstrap.bats / install-client-helm.batson clean develop too (macOS bash-3.2 blindspot + locally-unstamped DEFAULT_REF) — pre-existing, unrelated to this change, and green on Linux CI.

Scope

This is the client half of #1174. The complementary cli-repo change — the CLI installer preferring a writable dir already on $PATH so the same-terminal case happens more often — is a separate PR.

Part of the least-privilege install epic (#1168), Wave 0 (independent).

Part of tracebloc/backend#1174 (client half — leave the issue open until the cli-repo half also lands).

🤖 Generated with Claude Code

Note

Low Risk
User-facing installer copy and flags only; no cluster, auth, or data-path changes. Regression risk is covered by expanded bats and golden catalog pinning.

Overview
Fixes the connected install summary telling users to Run tracebloc when the CLI only resolves in the installer process (e.g. ~/.local/bin prepended for this run), which contradicted step output and caused command-not-found in the user’s shell.

install-cli.sh adds _cli_at_system_dir and drives TB_CLI_USABLE_NOW / TB_CLI_ON_FRESH_PATH: “run it now” and step success copy apply only when the binary is on a system PATH dir in this shell; ~/.local/bin / fresh-shell-only cases get “open a new terminal” or PATH-fix messaging. Pre-install state seeds TB_CLI_USABLE_NOW so an existing system tracebloc still gets “Run” if the CLI step fails before verify.

summary.sh branches the final CTA on those flags via _cli_runnable_now (no live has tracebloc, which would false-positive): Run → Open a new terminal (case A / unset) → Add to PATH (see above) when even a new shell won’t find it (case B).

Tests and golden copy catalog pin the happy-path CTA; manifest hashes updated.

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

LukasWodka · 2026-07-22T15:48:02Z

bugbot run

LukasWodka · 2026-07-23T06:39:22Z

bugbot run

… mutated process PATH (Bugbot #371) _cli_runnable_now dropped its `has tracebloc` fallback: install.sh + provision.sh prepend ~/.local/bin to THIS process PATH, so `has tracebloc` was true even when the user's launching shell could not resolve it — so the CTA wrongly said "Run tracebloc" on the common curl|bash path. Now it trusts only TB_CLI_USABLE_NOW (set from install-cli.sh's FRESH-shell probe); unset/0 → the honest "open a new terminal" branch. Also fixed a pre-existing summary.bats test that assumed the unconditional CTA (pinned TB_CLI_USABLE_NOW=1) — it was RED on Linux CI (masked locally by my having the CLI installed) — and tightened the new B2 test to assert the "Run …" branch specifically. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

LukasWodka · 2026-07-23T07:07:33Z

bugbot run

…cess PATH (Bugbot #371 r2) TB_CLI_USABLE_NOW was still set from `has tracebloc` in the installer process, whose PATH install.sh prepended with ~/.local/bin — so it was true even when the users returning shell cannot resolve the CLI. New _cli_at_system_dir keys the flag on WHERE the CLI landed: a system dir (unconditionally on PATH) => usable now => "Run tracebloc"; a $HOME bin (~/.local/bin, ~/bin) or unresolved => conservative => "open a new terminal". Unit test for the gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… mutated process PATH (Bugbot #371) _cli_runnable_now dropped its `has tracebloc` fallback: install.sh + provision.sh prepend ~/.local/bin to THIS process PATH, so `has tracebloc` was true even when the user's launching shell could not resolve it — so the CTA wrongly said "Run tracebloc" on the common curl|bash path. Now it trusts only TB_CLI_USABLE_NOW (set from install-cli.sh's FRESH-shell probe); unset/0 → the honest "open a new terminal" branch. Also fixed a pre-existing summary.bats test that assumed the unconditional CTA (pinned TB_CLI_USABLE_NOW=1) — it was RED on Linux CI (masked locally by my having the CLI installed) — and tightened the new B2 test to assert the "Run …" branch specifically. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

LukasWodka · 2026-07-23T09:26:37Z

bugbot run

…cess PATH (Bugbot #371 r2) TB_CLI_USABLE_NOW was still set from `has tracebloc` in the installer process, whose PATH install.sh prepended with ~/.local/bin — so it was true even when the users returning shell cannot resolve the CLI. New _cli_at_system_dir keys the flag on WHERE the CLI landed: a system dir (unconditionally on PATH) => usable now => "Run tracebloc"; a $HOME bin (~/.local/bin, ~/bin) or unresolved => conservative => "open a new terminal". Unit test for the gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

_verify_tracebloc_cli set TB_CLI_USABLE_NOW=0 for a ~/.local/bin install but then printed the usable-now verdict ("... ready — run tracebloc to use it") and returned, because `has tracebloc` is always true (install.sh prepends ~/.local/bin to the process PATH). The summary CTA, keyed on TB_CLI_USABLE_NOW=0, said "open a new terminal" — a direct contradiction on the least-privilege path, and following the step fails command-not-found. Gate the usable-now verdict on `has tracebloc && _cli_at_system_dir`; otherwise fall through to the honest "installed — open a new terminal" guidance and keep TB_CLI_USABLE_NOW=0 so the summary agrees. Add a regression test; the two existing usable-now tests now force _cli_at_system_dir (they mocked tracebloc as a function, so command -v never returned a system path). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…inal (Bugbot #371) TB_CLI_USABLE_NOW=0 covered two different states, and the summary always said "open a new terminal" for both: - case A: installed to ~/.local/bin, persisted — a NEW terminal resolves it (only this login shell does not). "Open a new terminal" is correct. - case B: _cli_on_fresh_path failed — a new terminal will NOT find it either; install-cli.sh prints the exact PATH fix and deliberately avoids "open a new terminal". The summary contradicted that, pointing users at a useless step. Add a second signal TB_CLI_ON_FRESH_PATH (set 1 on the fresh-path branch, 0 in the case-B fall-through) and a third summary CTA branch: case B now says "Add tracebloc to your PATH (see above)", matching install-cli.sh. Update the case-A test to set the flag; add a case-B CTA test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

LukasWodka · 2026-07-23T09:50:28Z

bugbot run

… see-above PATH fix (Bugbot #371) The case-B CTA branch fired on `else`, catching BOTH TB_CLI_ON_FRESH_PATH=0 (install-cli.sh ran and printed the exact PATH fix) AND the flag being UNSET (CLI step skipped/failed, so nothing was printed above). In the unset case the "Add tracebloc to your PATH (see above)" message pointed at guidance that never appeared. Gate case B on the explicit "0"; fold unset + case A into the safe "open a new terminal" default (matching _cli_runnable_now's documented default). Add an unset-flag test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

LukasWodka · 2026-07-23T10:00:38Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

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

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

…this shell cannot find (B2, #1174) install-cli.sh records TB_CLI_USABLE_NOW (1 only when the CLI resolves in THIS shell, not just a fresh terminal). summary.sh reads it via _cli_runnable_now (with a live has-tracebloc fallback) so the final CTA says "Run tracebloc" only when that is true, and "Open a new terminal, then run tracebloc" otherwise — matching the honest guidance install-cli already prints for the ~/.local/bin case. 2 new summary bats; install-cli suite green; shellcheck + manifest clean. The complementary cli-repo change (installer prefers a writable dir already on PATH so the same-terminal case happens more often) is a separate PR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… mutated process PATH (Bugbot #371) _cli_runnable_now dropped its `has tracebloc` fallback: install.sh + provision.sh prepend ~/.local/bin to THIS process PATH, so `has tracebloc` was true even when the user's launching shell could not resolve it — so the CTA wrongly said "Run tracebloc" on the common curl|bash path. Now it trusts only TB_CLI_USABLE_NOW (set from install-cli.sh's FRESH-shell probe); unset/0 → the honest "open a new terminal" branch. Also fixed a pre-existing summary.bats test that assumed the unconditional CTA (pinned TB_CLI_USABLE_NOW=1) — it was RED on Linux CI (masked locally by my having the CLI installed) — and tightened the new B2 test to assert the "Run …" branch specifically. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…cess PATH (Bugbot #371 r2) TB_CLI_USABLE_NOW was still set from `has tracebloc` in the installer process, whose PATH install.sh prepended with ~/.local/bin — so it was true even when the users returning shell cannot resolve the CLI. New _cli_at_system_dir keys the flag on WHERE the CLI landed: a system dir (unconditionally on PATH) => usable now => "Run tracebloc"; a $HOME bin (~/.local/bin, ~/bin) or unresolved => conservative => "open a new terminal". Unit test for the gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

_verify_tracebloc_cli set TB_CLI_USABLE_NOW=0 for a ~/.local/bin install but then printed the usable-now verdict ("... ready — run tracebloc to use it") and returned, because `has tracebloc` is always true (install.sh prepends ~/.local/bin to the process PATH). The summary CTA, keyed on TB_CLI_USABLE_NOW=0, said "open a new terminal" — a direct contradiction on the least-privilege path, and following the step fails command-not-found. Gate the usable-now verdict on `has tracebloc && _cli_at_system_dir`; otherwise fall through to the honest "installed — open a new terminal" guidance and keep TB_CLI_USABLE_NOW=0 so the summary agrees. Add a regression test; the two existing usable-now tests now force _cli_at_system_dir (they mocked tracebloc as a function, so command -v never returned a system path). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…inal (Bugbot #371) TB_CLI_USABLE_NOW=0 covered two different states, and the summary always said "open a new terminal" for both: - case A: installed to ~/.local/bin, persisted — a NEW terminal resolves it (only this login shell does not). "Open a new terminal" is correct. - case B: _cli_on_fresh_path failed — a new terminal will NOT find it either; install-cli.sh prints the exact PATH fix and deliberately avoids "open a new terminal". The summary contradicted that, pointing users at a useless step. Add a second signal TB_CLI_ON_FRESH_PATH (set 1 on the fresh-path branch, 0 in the case-B fall-through) and a third summary CTA branch: case B now says "Add tracebloc to your PATH (see above)", matching install-cli.sh. Update the case-A test to set the flag; add a case-B CTA test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… see-above PATH fix (Bugbot #371) The case-B CTA branch fired on `else`, catching BOTH TB_CLI_ON_FRESH_PATH=0 (install-cli.sh ran and printed the exact PATH fix) AND the flag being UNSET (CLI step skipped/failed, so nothing was printed above). In the unset case the "Add tracebloc to your PATH (see above)" message pointed at guidance that never appeared. Gate case B on the explicit "0"; fold unset + case A into the safe "open a new terminal" default (matching _cli_runnable_now's documented default). Add an unset-flag test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

LukasWodka · 2026-07-23T16:18:39Z

bugbot run

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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

shujaatTracebloc

Review — PATH-aware final CTA (B2, #1174 client half)

Solid, low-risk fix — it makes the final "Connected" CTA honest for least-privilege (~/.local/bin) installs, and the state machine is correct. Verified the load-bearing parts:

Verified ✅

Signed manifest is correct — recomputed sha256 for all 18 entries against the committed files; every hash matches, including both changed scripts (install-cli.sh, summary.sh). Clean.
The CTA state machine is right, and tested for every branch._cli_runnable_now gates on TB_CLI_USABLE_NOW only (correctly — install.sh/provision.sh prepend ~/.local/bin to this process's PATH, so a has tracebloc fallback would false-positive; the code comment nails the reasoning). All four cases pass:
- USABLE_NOW=1 → Run tracebloc
- 0 + ON_FRESH_PATH=1 (case A) → Open a new terminal
- 0 + ON_FRESH_PATH=0 (case B) → Add tracebloc to your PATH (see above)
- unset → Open a new terminal (safe default; the explicit == "0" test is what keeps an unset flag out of the "see above" branch — nicely covered by a dedicated test)
_cli_at_system_dir is the right discriminator (""/$HOME/* → conservative, else system) — verified by its unit test.
All new bats green (summary.bats 4 CTA cases + install-cli.bats ~/.local/bin verdict + the _cli_at_system_dir unit). Pre-existing bash-3.2/DEFAULT_REF failures you flagged are indeed unrelated (same ones I saw on #368/#371-adjacent, green on Linux CI).

Non-blocking notes

PR description contradicts the code. The "## What" section says _cli_runnable_now reads TB_CLI_USABLE_NOW"with a live has tracebloc fallback" — but the code is [[ "${TB_CLI_USABLE_NOW:-0}" == "1" ]] with no fallback, and the comment explains a fallback would be wrong. The code is right; the description is stale (the Cursor summary has it correct). Worth fixing the body so a future reader isn't misled.
Install-failed edge (pre-existing, out of scope). If the CLI install fails entirely, TB_CLI_USABLE_NOW=0 + ON_FRESH_PATH unset → the CTA still says "Open a new terminal, then run tracebloc" for a command that was never installed — the same dishonest-CTA class this PR fixes, on a different path. Not introduced here (the old code said "Run tracebloc" unconditionally, equally wrong on install-fail), and CLI-install failure is separately warned + non-fatal. Possible follow-up: suppress the tracebloc CTA entirely when the CLI wasn't installed.

LGTM to merge. 🚀

shujaatTracebloc

Approving — signed manifest verified (all 18 hashes match), the CTA state machine is correct with every branch tested (Run / open-a-new-terminal / add-to-PATH / unset safe-default), and _cli_runnable_now correctly avoids a has tracebloc fallback. Details in my review comment above.

Non-blocking follow-ups: (1) the PR description says _cli_runnable_now has a has tracebloc fallback, but the code deliberately doesn't — worth correcting the body; (2) pre-existing install-failed edge where the CTA still nudges tracebloc when the CLI never installed (out of scope). Neither blocks. 🚀

🤖 Reviewed with Claude Code

…LI step is skipped (Bugbot #371) Bugbot (Medium): install_tracebloc_cli hard-defaulted TB_CLI_USABLE_NOW=0, so if the CLI step is skipped or fails (download/installer/temp-dir miss → early return, _verify_tracebloc_cli never runs) the connected summary said 'open a new terminal' even when tracebloc was ALREADY on a system PATH dir and works in the user's current shell. Seed the default from the PRE-install state instead: usable-now iff a tracebloc is already resolvable AND at a system dir. Gate on _cli_at_system_dir, NOT bare 'has tracebloc' — install.sh prepends ~/.local/bin to THIS process, which would false-positive a ~/.local/bin install the returning shell can't yet see (the exact trap the earlier #371 findings closed). _verify_tracebloc_cli still overrides per this run's outcome; summary.sh's _cli_runnable_now is unchanged. Tests: pre-existing system tracebloc + failed install → stays 1; ~/.local/bin + failed install → 0. install-cli.bats green; manifest regenerated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

# Conflicts: # scripts/manifest.sha256

…den is stable (#371) Merging #371's PATH-aware connected-state CTA into a develop that has the #366 copy catalog broke copy-catalog.bats: emit_outcomes renders print_summary, and with TB_CLI_USABLE_NOW unset the new CTA branch prints 'Open a new terminal…' while 01-outcomes.golden still has the happy-path 'Run tracebloc to get started.'. Pin TB_CLI_USABLE_NOW=1 in setup() (mirrors #371's summary.bats) so the catalog deterministically renders the 'Run' line the golden captures — no golden regen needed, and it's robust to an inherited flag (same env-stability class as the TRACEBLOC_BANNER_SHOWN unset). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

shujaatTracebloc

Reviewed the code + logic: the PATH-aware final CTA correctly seeds TB_CLI_USABLE_NOW from the pre-install system-dir state (_cli_at_system_dir), so a skipped/failed CLI step with an already-installed system tracebloc now shows the "Run" CTA instead of "open a new terminal" — that was the Bugbot finding, and it's fixed. _cli_at_system_dir correctly rejects "" and $HOME/* so the install.sh PATH-prepend of ~/.local/bin can't false-positive.

Also fixed the copy-catalog golden drift the CTA change introduced against the merged #366 catalog by pinning TB_CLI_USABLE_NOW=1 in copy-catalog.bats setup() (no golden regen). manifest.sha256 verified consistent after the develop merge.

CI fully green (bats, Unit tests, Cursor Bugbot, all PATH/Prereqs/E2E), Bugbot clean. LGTM 🚀

LukasWodka requested a review from saadqbal as a code owner July 22, 2026 15:47

LukasWodka assigned saadqbal Jul 22, 2026

cursorBot reviewed Jul 22, 2026
View reviewed changes

Comment threadscripts/lib/summary.sh

LukasWodka mentioned this pull request Jul 22, 2026
feat(install): prefer ~/bin when already on PATH (B2, RFC 0001) tracebloc/cli#392
Merged

LukasWodka requested a review from divyasinghds July 23, 2026 06:28