cctally 1.21.1 → 1.21.3

package/CHANGELOG.md

@@ -5,6 +5,21 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.21.3] - 2026-05-29
+
+### Fixed
+- `cctally doctor` no longer warns about a "legacy status-line snippet" when your `~/.claude/statusline-command.sh` merely *mentions* `cctally record-usage` inside a shell comment — e.g. a trailing `# NOTE:` documenting that the old background invocation was removed. The detector (`_setup_detect_legacy_snippet`) tested only `"cctally record-usage" in line` with no comment-stripping, so a `#`-prefixed prose reference was reported identically to a line that actually executes it, and the WARN surfaced in terminal `doctor` output, the dashboard freshness chip + doctor modal, and the TUI hero card — nudging users to delete a harmless comment of their own. It now skips any line whose first non-whitespace character is `#` (POSIX shell only treats `#` as a comment marker at start-of-token, so natural-language comments are excluded without trying to parse the shell); actually-executing legacy lines like `exec cctally record-usage "$@"` still fire exactly as before. Regression: new `tests/test_setup_legacy_snippet.py` unit coverage (comment-only / indented-comment / real-line / mixed cases) plus a new `bin/cctally-doctor-test` scenario `14-legacy-snippet-in-comment-ignored` that asserts a clean install carrying the needle only in comments stays fully OK. (#115)
+- Homebrew installs no longer create dangling `~/.local/bin/` symlinks, and Claude Code hooks now point at the version-stable `<prefix>/bin/cctally` so they survive `brew cleanup`; `cctally setup` from a brew install relies on the formula's `<prefix>/bin/` and cleans up legacy keg/npm leftover links. (#119)
+- `cctally doctor` `install.path` is now availability-aware (passes whenever cctally is genuinely reachable on `$PATH` via any channel — Homebrew `<prefix>/bin/`, an npm prefix, or source `~/.local/bin` — rather than merely because `~/.local/bin` is on `$PATH`), and when it does warn the remediation is tailored to how cctally was installed (Homebrew → `eval "$(brew shellenv)"`; source/npm → `export PATH="$HOME/.local/bin:$PATH"` + `cctally setup`); `install.symlinks` reports leftover keg links as a cleanable "stale" state instead of a generic failure. (#119)
+
+## [1.21.2] - 2026-05-28
+
+### Fixed
+- npm upgrades now self-heal `~/.local/bin/` symlinks for newly added subcommands: the postinstall best-effort runs an internal additive `repair-symlinks` pass (gated to existing installs), so a new `cctally-*` binary is reachable immediately after `npm install -g cctally@<newer>` without re-running `cctally setup` (#114).
+
+### Changed
+- `cctally doctor` / `cctally setup --status` now report subcommand symlinks as "available" and treat a command reachable on `$PATH` via another install channel (e.g. Homebrew) as present, instead of warning only because `~/.local/bin/` lacks the link (#114).
+
 ## [1.21.1] - 2026-05-28
 
 ### Fixed

package/bin/_cctally_db.py

@@ -1023,6 +1023,7 @@ _BANNER_SUPPRESSED_COMMANDS = frozenset({
     "doctor",          # consolidates migration + update banner state into its
                        # own report; double-printing the banner would duplicate
                        # findings doctor already surfaces structurally.
+    "repair-symlinks", # invoked by npm postinstall; no banner during install
     "blocks",          # stdout-formatted table replacing `ccusage blocks`;
                        # stderr noise pollutes the visually-aligned report and
                        # confuses scripted pipelines piping via `2>&1`.

package/bin/_cctally_setup.py

@@ -293,6 +293,12 @@ _SETUP_STALE_SYMLINK_NAMES = (
 )
 
 
+# The npm package ships a Node shim as the `cctally` entry point. Its
+# basename differs from the command name, so any code matching a
+# symlink's readlink target by basename must special-case it.
+_CCTALLY_NPM_SHIM_BASENAME = "cctally-npm-shim.js"
+
+
 def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib.Path:
     """Resolve the symlink target for a given PATH-name.
 
@@ -310,27 +316,27 @@ def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib
     documented. All other names map directly to ``bin/<name>``.
     """
     if name == "cctally" and "node_modules" in repo_root.parts:
-        shim = repo_root / "bin" / "cctally-npm-shim.js"
+        shim = repo_root / "bin" / _CCTALLY_NPM_SHIM_BASENAME
         if shim.exists():
             return shim
     return repo_root / "bin" / name
 
 
 def _setup_resolve_hook_target(repo_root: pathlib.Path) -> pathlib.Path:
-    """Resolve the absolute path that goes into Claude Code hook entries.
-
-    Single chokepoint shared by ``_setup_install``, ``_setup_dry_run``
-    (text + JSON envelopes), and any other site that emits a hook
-    command. Routes through :func:`_setup_resolve_symlink_source` so
-    npm-layout installs point hooks at the Node shim instead of the
-    Python script directly — without this, the shim's
-    ``CCTALLY_PYTHON`` honoring works for interactive ``cctally`` calls
-    but every hook fire bypasses it via ``/usr/bin/env python3`` and
-    silently fails when the user's ``python3`` doesn't meet the version
-    floor. The returned path is fully resolved (symlinks followed) so
-    the recorded hook entry survives later filesystem rearrangements
-    of the source clone or the npm install root.
+    """Absolute path recorded in Claude Code hook entries.
+
+    Brew installs: return the version-stable `<prefix>/bin/cctally` (the
+    formula's symlink, which self-heals on `brew upgrade`) WITHOUT
+    `.resolve()` — resolving would pin the hook to the versioned keg and
+    dangle after `brew cleanup` (issue #119). Source/npm: keep the
+    `.resolve()` semantics (survives clone/node_modules rearrangement and
+    the npm-shim branch in `_setup_resolve_symlink_source`).
     """
+    if _setup_is_brew_install(repo_root):
+        prefix = _setup_brew_prefix(repo_root)
+        stable = pathlib.Path(prefix) / "bin" / "cctally"
+        if stable.exists():
+            return stable
     return _setup_resolve_symlink_source(repo_root, "cctally").resolve()
 
 
@@ -373,6 +379,44 @@ def _setup_create_symlinks(
     return results
 
 
+@dataclasses.dataclass
+class _RepairResult:
+    gated: bool
+    created: list[str]
+    failed: list[tuple[str, str]]  # (name, detail)
+
+
+def _setup_repair_symlinks(
+    repo_root: pathlib.Path, dst_dir: pathlib.Path,
+) -> _RepairResult:
+    """Additively reconcile ``dst_dir`` to ``SETUP_SYMLINK_NAMES`` (issue #114).
+
+    Existing-install gate: acts only when at least one
+    ``SETUP_SYMLINK_NAMES`` symlink is already present in ``dst_dir`` — a
+    fresh install (zero links) is left untouched so onboarding stays
+    opt-in. Strictly additive: creates only *genuinely empty* slots and
+    leaves present / wrong-target / dangling / non-symlink slots alone.
+    Touches nothing but ``~/.local/bin/`` symlinks (no hooks /
+    settings.json / cache). Filesystem-only — deliberately NOT PATH-aware
+    (unlike :func:`_setup_compute_symlink_state`), so it stays
+    deterministic regardless of the live ``PATH``.
+    """
+    names = _cctally().SETUP_SYMLINK_NAMES
+    present = [n for n in names if (dst_dir / n).is_symlink()]
+    if not present:
+        return _RepairResult(gated=True, created=[], failed=[])
+    missing = [
+        n for n in names
+        if not (dst_dir / n).is_symlink() and not (dst_dir / n).exists()
+    ]
+    if not missing:
+        return _RepairResult(gated=False, created=[], failed=[])
+    results = _setup_create_symlinks(repo_root, dst_dir, names=tuple(missing))
+    created = [r.name for r in results if r.status == "created"]
+    failed = [(r.name, r.detail) for r in results if r.status == "failed"]
+    return _RepairResult(gated=False, created=created, failed=failed)
+
+
 def _setup_cleanup_stale_symlinks(
     dst_dir: pathlib.Path,
 ) -> list[_SetupSymlinkResult]:
@@ -408,19 +452,23 @@ def _setup_cleanup_stale_symlinks(
     """
     results: list[_SetupSymlinkResult] = []
     repo_root = _setup_resolve_repo_root()
-    for name in _SETUP_STALE_SYMLINK_NAMES:
+    retired_names = set(_SETUP_STALE_SYMLINK_NAMES)
+    for name in dict.fromkeys(_SETUP_STALE_SYMLINK_NAMES + tuple(_cctally().SETUP_SYMLINK_NAMES)):
         dst = dst_dir / name
         if not _setup_symlink_is_retired(dst, name, repo_root):
             continue
+        if name in retired_names:
+            should_remove = True                       # retired command: unconditional
+        else:                                           # active name: reachability-gated
+            is_dangling = not dst.resolve(strict=False).exists() if dst.is_symlink() else False
+            should_remove = is_dangling or _reachable_elsewhere(name)
+        if not should_remove:
+            continue
         try:
             dst.unlink()
-            results.append(
-                _SetupSymlinkResult(name, "removed-stale", "stale (from prior version)")
-            )
+            results.append(_SetupSymlinkResult(name, "removed-stale", "stale (issue #119 cleanup)"))
         except OSError as exc:
-            results.append(
-                _SetupSymlinkResult(name, "failed", f"unlink failed: {exc}")
-            )
+            results.append(_SetupSymlinkResult(name, "failed", f"unlink failed: {exc}"))
     return results
 
 
@@ -484,7 +532,11 @@ def _setup_symlink_is_retired(
         target = os.readlink(dst)
     except OSError:
         return False
-    if pathlib.Path(target).name != name:
+    target_basename = pathlib.Path(target).name
+    accepted = {name}
+    if name == "cctally":
+        accepted.add(_CCTALLY_NPM_SHIM_BASENAME)
+    if target_basename not in accepted:
         # User-managed symlink that happens to share the name; leave alone.
         return False
     # Resolve target relative to the symlink's parent so relative
@@ -508,9 +560,30 @@ def _setup_symlink_is_retired(
     # *from* an npm/brew install doesn't classify its own siblings as
     # foreign — that's the active-symlinks loop's job.
     target_str = str(target_path)
+    # "Same install root" means the target lives UNDER the current
+    # ``repo_root`` tree. Use a separator-anchored prefix check rather
+    # than a bare substring of the token: a same-``repo_root`` npm install
+    # has ``repo_root == <…>/node_modules/cctally`` (no trailing slash),
+    # so the raw ``"/node_modules/cctally/" in repo_root_str`` test would
+    # spuriously miss and classify the live channel's own link as foreign
+    # (issue #119 finding #7 — the npm `cctally` shim under its own
+    # ``node_modules/cctally`` must be preserved, not retired).
     repo_root_str = str(repo_root)
+    repo_root_prefix = repo_root_str.rstrip(os.sep) + os.sep
+    target_under_repo_root = (
+        target_str == repo_root_str or target_str.startswith(repo_root_prefix)
+    )
     for token in _SETUP_FOREIGN_INSTALL_ROOT_TOKENS:
-        if token in target_str and token not in repo_root_str:
+        if token not in target_str:
+            continue
+        # Homebrew keg links are NEVER owned by ~/.local/bin under the
+        # issue-#119 policy, so retire them regardless of which keg /
+        # whether repo_root is itself a keg. Other foreign roots
+        # (node_modules) retire only when the target is NOT under the
+        # current install root.
+        if token == _SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0]:   # "/Cellar/cctally/"
+            return True
+        if not target_under_repo_root:
             return True
     return False
 
@@ -520,6 +593,44 @@ def _setup_path_includes_local_bin() -> bool:
     return local_bin in os.environ.get("PATH", "").split(os.pathsep)
 
 
+def _setup_is_brew_install(repo_root: pathlib.Path) -> bool:
+    """True when this cctally runs from a Homebrew keg.
+
+    `_setup_resolve_repo_root()` `.resolve()`s `__file__`, so a brew
+    install reliably carries the `/Cellar/cctally/` token (Apple Silicon,
+    Intel, Linuxbrew all funnel through it). Reuses the single token
+    source in `_SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0]`. Cheap — no
+    `npm prefix` subprocess; we only need the brew yes/no.
+    """
+    return _SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0] in str(repo_root)
+
+
+def _setup_brew_prefix(repo_root: pathlib.Path) -> str:
+    """The Homebrew `<prefix>` (e.g. `/opt/homebrew`) for a brew keg
+    `repo_root`. Splits on the single-source brew token so we never spell
+    the Cellar path a third way. Callers must guard with
+    `_setup_is_brew_install(repo_root)` first; off a keg this returns the
+    unchanged string."""
+    return str(repo_root).split(_SETUP_FOREIGN_INSTALL_ROOT_TOKENS[0])[0]
+
+
+def _reachable_elsewhere(name: str) -> bool:
+    """Would `<name>` still be found on PATH if the ~/.local/bin slot
+    didn't exist? Excludes the ~/.local/bin directory (realpath-compared)
+    so a stale link can't satisfy its own reachability check (issue #119
+    finding #6)."""
+    local_bin = _setup_local_bin_dir()
+    try:
+        local_real = os.path.realpath(local_bin)
+    except OSError:
+        local_real = str(local_bin)
+    dirs = [
+        d for d in os.environ.get("PATH", "").split(os.pathsep)
+        if d and os.path.realpath(d) != local_real
+    ]
+    return shutil.which(name, path=os.pathsep.join(dirs)) is not None
+
+
 def _setup_shell_rc_hint() -> str:
     shell = os.environ.get("SHELL", "")
     if "zsh" in shell:
@@ -542,7 +653,16 @@ def _setup_detect_legacy_snippet() -> tuple[pathlib.Path, list[int]] | None:
             text = path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             continue
-        hits = [i + 1 for i, ln in enumerate(text.splitlines()) if c.LEGACY_STATUSLINE_NEEDLE in ln]
+        # Skip lines whose first non-whitespace char is `#`: a shell comment
+        # that merely references the legacy command in prose (e.g. a NOTE
+        # documenting its removal) is not an executing snippet (issue #115).
+        # POSIX shell only treats `#` as a comment marker at start-of-token,
+        # so this covers natural-language comments without parsing the shell.
+        hits = [
+            i + 1
+            for i, ln in enumerate(text.splitlines())
+            if c.LEGACY_STATUSLINE_NEEDLE in ln and not ln.lstrip().startswith("#")
+        ]
         if hits:
             return (path, hits)
     return None
@@ -970,29 +1090,25 @@ def _setup_compute_symlink_state(
 ) -> "list[tuple[str, str]]":
     """Per-symlink (name, state) for `_setup_status` + `doctor_gather_state`.
 
-    state ∈ {"ok", "wrong", "missing"}:
-      - "ok": ``dst_dir/name`` is a symlink whose target is reachable.
-        The target is NOT required to match ``repo_root/bin/<name>`` —
-        power users routinely have the symlinks installed by one
-        cctally channel (npm/brew) while running ``doctor`` from a
-        parallel source clone, which would otherwise produce a 0/N
-        false negative on a perfectly healthy install. The diagnostic
-        question is "is `cctally-X` invokable from PATH?", not "did
-        THIS checkout install the symlink?". ``_setup_create_symlinks``
-        keeps its own strict equality check for install-management
-        (replace-vs-already).
-      - "wrong": a non-symlink file occupies the slot, or the symlink
-        target is dangling.
-      - "missing": nothing at ``dst_dir/name``.
-
-    ``repo_root`` is unused here — retained on the signature for
-    call-site stability across `_setup_status` and `doctor_gather_state`.
+    state ∈ {"ok", "stale", "wrong", "missing"}.
+      - ok:      resolvable non-retired link, OR empty slot reachable elsewhere.
+      - stale:   retired link (Cellar/foreign/dangling) AND command reachable
+                 via a non-~/.local/bin dir (safely cleanable). Issue #119.
+      - wrong:   non-symlink file in slot; dangling non-retired link; OR a
+                 retired link with no reachable_elsewhere fallback (broken, or
+                 the pathological only-path-live-Cellar case).
+      - missing: empty slot, not reachable elsewhere.
+    Retired check precedes the resolve()->ok branch so a LIVE Cellar link is
+    classed stale, not masked as ok.
     """
-    del repo_root  # unused; see docstring
     out: list[tuple[str, str]] = []
     for name in _cctally().SETUP_SYMLINK_NAMES:
         dst = dst_dir / name
+        reachable = _reachable_elsewhere(name)
         if dst.is_symlink():
+            if _setup_symlink_is_retired(dst, name, repo_root):
+                out.append((name, "stale" if reachable else "wrong"))
+                continue
             try:
                 dst.resolve(strict=True)
                 out.append((name, "ok"))
@@ -1000,6 +1116,8 @@ def _setup_compute_symlink_state(
                 out.append((name, "wrong"))
         elif dst.exists():
             out.append((name, "wrong"))
+        elif reachable:
+            out.append((name, "ok"))
         else:
             out.append((name, "missing"))
     return out
@@ -1035,8 +1153,11 @@ def _setup_status(args: argparse.Namespace) -> int:
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
     sym_state = _setup_compute_symlink_state(repo_root, dst_dir)
-    sym_ok = sum(1 for _, s in sym_state if s == "ok")
-    stale_syms = _setup_detect_stale_symlinks(dst_dir)
+    sym_ok = sum(1 for _, s in sym_state if s in ("ok", "stale"))     # available = ok + stale
+    active_stale = [n for n, s in sym_state if s == "stale"]
+    retired_stale = _setup_detect_stale_symlinks(dst_dir)
+    stale_syms = list(dict.fromkeys(active_stale + retired_stale))    # union, order-stable
+    is_brew = _setup_is_brew_install(repo_root)
     on_path = _setup_path_includes_local_bin()
     try:
         settings = c._load_claude_settings()
@@ -1084,14 +1205,18 @@ def _setup_status(args: argparse.Namespace) -> int:
     out: list[str] = []
     out.append("Install")
     sym_marker = "✓" if sym_ok == len(c.SETUP_SYMLINK_NAMES) else "✗"
-    out.append(f"  Symlinks       {sym_ok}/{len(c.SETUP_SYMLINK_NAMES)} present at {dst_dir}/  {sym_marker}")
+    out.append(f"  Symlinks       {sym_ok}/{len(c.SETUP_SYMLINK_NAMES)} available at {dst_dir}/  {sym_marker}")
     if stale_syms:
         out.append(
             f"  Stale symlinks {len(stale_syms)} from prior version: {', '.join(stale_syms)}  ⚠"
         )
         out.append("                 run `cctally setup` to remove")
-    out.append(f"  PATH includes  {'yes' if on_path else 'no'}                                   "
-               f"{'✓' if on_path else '⚠'}")
+    if is_brew and (on_path or any(s in ("ok", "stale") for _, s in sym_state)):
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(f"  PATH           brew: commands via {prefix}/bin                 ✓")
+    else:
+        out.append(f"  PATH includes  {'yes' if on_path else 'no'}                                   "
+                   f"{'✓' if on_path else '⚠'}")
     out.append(f"Hooks ({_cctally_core.CLAUDE_SETTINGS_PATH})")
     for ev in c.SETUP_HOOK_EVENTS:
         marker = "✓" if hook_counts[ev] >= 1 else "✗"
@@ -1331,14 +1456,20 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
     new = sum(1 for _, s in sym_results if s == "would-create")
     same = sum(1 for _, s in sym_results if s == "already")
     blocked = [name for name, s in sym_results if s == "blocked"]
+    is_brew = _setup_is_brew_install(repo_root)
     out: list[str] = []
-    out.append(
-        f"Would symlink {len(c.SETUP_SYMLINK_NAMES)} files to {dst_dir}/ "
-        f"({same} already correct, {new} new)"
-    )
-    if blocked:
-        out.append(f"⚠ Blocked (non-symlink files exist): {', '.join(blocked)}")
-        out.append("  Remove them manually then re-run.")
+    if is_brew:
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(f"Brew install — would skip ~/.local/bin/ symlinks "
+                   f"(commands on PATH via {prefix}/bin/)")
+    else:
+        out.append(
+            f"Would symlink {len(c.SETUP_SYMLINK_NAMES)} files to {dst_dir}/ "
+            f"({same} already correct, {new} new)"
+        )
+        if blocked:
+            out.append(f"⚠ Blocked (non-symlink files exist): {', '.join(blocked)}")
+            out.append("  Remove them manually then re-run.")
 
     out.append(f"Would add {len(c.SETUP_HOOK_EVENTS)} hook entries to {_cctally_core.CLAUDE_SETTINGS_PATH}:")
     abs_path = str(_setup_resolve_hook_target(repo_root))
@@ -1410,13 +1541,18 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
         envelope = {
             "schema_version": 1,
             "mode": "dry-run",
-            "symlinks": {
-                "would_create": new,
-                "already": same,
-                "blocked": blocked,
-                "destination": str(dst_dir),
-                "total": len(c.SETUP_SYMLINK_NAMES),
-            },
+            "symlinks": (
+                {"skipped": True, "reason": "brew", "would_create": 0,
+                 "already": 0, "blocked": [], "destination": str(dst_dir),
+                 "total": 0,
+                 "would_remove_stale": [
+                     n for n, s in _setup_compute_symlink_state(repo_root, dst_dir)
+                     if s == "stale"
+                 ]}
+                if is_brew else
+                {"would_create": new, "already": same, "blocked": blocked,
+                 "destination": str(dst_dir), "total": len(c.SETUP_SYMLINK_NAMES)}
+            ),
             "hooks": {
                 "would_add": [
                     {
@@ -1608,24 +1744,40 @@ def _setup_install(args: argparse.Namespace) -> int:
     # disturbs a user's hand-rolled symlink sharing the name.
     stale_results = _setup_cleanup_stale_symlinks(dst_dir)
 
-    sym_results = _setup_create_symlinks(repo_root, dst_dir)
-    failed = [r for r in sym_results if r.status == "failed"]
-    if failed:
-        for r in failed:
-            eprint(f"setup: symlink {r.name} failed: {r.detail}")
-        return 1
-    new_count = sum(1 for r in sym_results if r.status == "created")
-    same_count = sum(1 for r in sym_results if r.status == "already")
-    repl_count = sum(1 for r in sym_results if r.status == "replaced")
-    detail_parts = []
-    if new_count:
-        detail_parts.append(f"{new_count} newly created")
-    if same_count:
-        detail_parts.append(f"{same_count} already correct")
-    if repl_count:
-        detail_parts.append(f"{repl_count} re-pointed")
-    detail = ", ".join(detail_parts) or "no changes"
-    out.append(f"✓ Symlinks at {dst_dir}/: {len(sym_results)}/{len(sym_results)} ({detail})")
+    # Issue #119: brew owns <prefix>/bin/, never ~/.local/bin/. On a brew
+    # install, skip symlink CREATION entirely (commands reach PATH via the
+    # formula's <prefix>/bin/) but keep everything else — cleanup, hook
+    # wiring, cache bootstrap. The new/same/repl counts are initialized to
+    # 0 here so the install JSON envelope references are always bound on
+    # the brew branch (sym_results stays empty).
+    is_brew = _setup_is_brew_install(repo_root)
+    new_count = same_count = repl_count = 0
+    if is_brew:
+        prefix = _setup_brew_prefix(repo_root)
+        out.append(
+            f"✓ Brew install detected — commands are on PATH via {prefix}/bin/; "
+            f"skipping ~/.local/bin/ symlinks"
+        )
+        sym_results = []
+    else:
+        sym_results = _setup_create_symlinks(repo_root, dst_dir)
+        failed = [r for r in sym_results if r.status == "failed"]
+        if failed:
+            for r in failed:
+                eprint(f"setup: symlink {r.name} failed: {r.detail}")
+            return 1
+        new_count = sum(1 for r in sym_results if r.status == "created")
+        same_count = sum(1 for r in sym_results if r.status == "already")
+        repl_count = sum(1 for r in sym_results if r.status == "replaced")
+        detail_parts = []
+        if new_count:
+            detail_parts.append(f"{new_count} newly created")
+        if same_count:
+            detail_parts.append(f"{same_count} already correct")
+        if repl_count:
+            detail_parts.append(f"{repl_count} re-pointed")
+        detail = ", ".join(detail_parts) or "no changes"
+        out.append(f"✓ Symlinks at {dst_dir}/: {len(sym_results)}/{len(sym_results)} ({detail})")
     removed_stale = [r for r in stale_results if r.status == "removed-stale"]
     failed_stale = [r for r in stale_results if r.status == "failed"]
     if removed_stale:
@@ -1637,7 +1789,7 @@ def _setup_install(args: argparse.Namespace) -> int:
         out.append(f"⚠ Could not remove stale {r.name}: {r.detail}")
         warnings += 1
 
-    if not _setup_path_includes_local_bin():
+    if not is_brew and not _setup_path_includes_local_bin():
         warnings += 1
         rc = _setup_shell_rc_hint()
         out.append(f"⚠ {dst_dir} is not on your PATH. Add to {rc}:")
@@ -1645,6 +1797,25 @@ def _setup_install(args: argparse.Namespace) -> int:
         out.append("  Then reload (`source ...`) or open a new terminal.")
         out.append("  (Hooks still work — we used absolute paths in settings.json.)")
 
+    # Pinned-only-path guidance (issue #119 finding #10): if any active
+    # name's slot is a live retired link with no reachable_elsewhere
+    # fallback, setup deliberately won't remove it (would break the only
+    # reachable copy) — surface the actionable PATH fix instead of silence.
+    pinned = [
+        n for n, s in _setup_compute_symlink_state(repo_root, dst_dir)
+        if s == "wrong" and (dst_dir / n).is_symlink()
+        and _setup_symlink_is_retired(dst_dir / n, n, repo_root)
+        and (dst_dir / n).resolve(strict=False).exists()
+    ]
+    if pinned:
+        prefix = _setup_brew_prefix(repo_root) if is_brew else "<prefix>"
+        out.append(
+            f"⚠ cctally is reachable only via a legacy ~/.local/bin link. "
+            f"Put {prefix}/bin on your PATH (eval \"$(brew shellenv)\"), then "
+            f"re-run cctally setup to clean it."
+        )
+        warnings += 1
+
     c._backup_claude_settings()
     try:
         c._write_claude_settings_atomic(settings)
@@ -1813,8 +1984,11 @@ def _setup_install(args: argparse.Namespace) -> int:
                 "created": new_count,
                 "already": same_count,
                 "replaced": repl_count,
-                "total": len(sym_results),
+                "total": len(sym_results),          # 0 on brew (sym_results == [])
                 "destination": str(dst_dir),
+                **({"skipped": True, "reason": "brew",
+                    "stale_removed": [r.name for r in stale_results if r.status == "removed-stale"]}
+                   if is_brew else {}),
             },
             "hooks": {
                 "events_added": list(c.SETUP_HOOK_EVENTS),

package/bin/_lib_doctor.py

@@ -103,6 +103,33 @@ class DoctorState:
     dev_mode: bool
     app_dir: str
     is_dev_checkout: bool = False
+    # Issue #119: availability-aware install checks. Both precomputed by
+    # `doctor_gather_state` (the I/O layer) so the kernel stays pure —
+    # `shutil.which` and the on-disk legacy-link probe never run here.
+    # Defaulted (and placed last, after `is_dev_checkout`) so existing
+    # constructors that don't pass them still work and the dataclass's
+    # non-default-then-default field ordering stays valid.
+    #   * cctally_reachable_on_path — `shutil.which("cctally") is not None`;
+    #     channel-agnostic (brew `<prefix>/bin`, npm prefix, source
+    #     `~/.local/bin` all satisfy it). Lets `_check_install_path` pass
+    #     whenever the command is reachable, not only when `~/.local/bin`
+    #     is on PATH.
+    #   * symlinks_path_pinned — true iff cctally is reachable ONLY through
+    #     a legacy `~/.local/bin` link to a retired/foreign (e.g. Homebrew
+    #     keg) install (a live retired link with no `reachable_elsewhere`
+    #     fallback). The kernel can't tell this `wrong`-mode apart from an
+    #     ordinary occupied slot from `(name, state)` alone, so it's
+    #     precomputed; drives the PATH-fix remediation in
+    #     `_check_install_symlinks`.
+    #   * install_is_brew — true iff this cctally runs from a Homebrew keg
+    #     (`_setup_is_brew_install(repo_root)`). Channel knowledge the
+    #     kernel can't derive from `repo_root` (it does no I/O); drives the
+    #     channel-aware `_check_install_path` WARN remediation so a brew
+    #     install isn't told to fix a `~/.local/bin` it deliberately
+    #     doesn't use (#119 made brew `~/.local/bin`-free).
+    cctally_reachable_on_path: Optional[bool] = None
+    symlinks_path_pinned: bool = False
+    install_is_brew: bool = False
 
 
 @dataclasses.dataclass(frozen=True)
@@ -145,6 +172,11 @@ def _max_severity(severities: list[str]) -> str:
 
 
 def _check_install_symlinks(s: DoctorState) -> CheckResult:
+    # Issue #119: the symlink state grew a fourth value, `stale` — a
+    # retired/foreign (e.g. Homebrew keg) link whose command IS still
+    # reachable elsewhere, so the link is safely-cleanable cruft, not a
+    # broken slot. Count `available = ok + stale` (both ⟹ reachable);
+    # `bad = wrong + missing` is what is genuinely actionable.
     if s.symlink_state is None:
         return CheckResult(
             id="install.symlinks", title="Symlinks",
@@ -152,35 +184,89 @@ def _check_install_symlinks(s: DoctorState) -> CheckResult:
             remediation="See logs", details={"reason": "gather returned None"},
         )
     total = len(s.symlink_state)
-    missing = [n for n, st in s.symlink_state if st != "ok"]
-    ok_count = total - len(missing)
-    if not missing:
+    stale = [n for n, st in s.symlink_state if st == "stale"]
+    bad = [n for n, st in s.symlink_state if st in ("wrong", "missing")]
+    available = total - len(bad)            # available = ok + stale
+    # "missing" carries the full `bad` list (wrong + missing); the key name is
+    # kept for JSON-schema stability even though it now spans both states.
+    details = {"present": available, "total": total,
+               "missing": bad, "stale": stale}
+    if not bad and not stale:
         return CheckResult(
             id="install.symlinks", title="Symlinks",
-            severity="ok", summary=f"{ok_count}/{total} present",
-            remediation=None,
-            details={"present": ok_count, "total": total, "missing": []},
+            severity="ok", summary=f"{available}/{total} available",
+            remediation=None, details=details,
+        )
+    if not bad:   # stale only
+        return CheckResult(
+            id="install.symlinks", title="Symlinks",
+            severity="warn",
+            summary=f"{available}/{total} available; {len(stale)} stale link(s) to clean",
+            remediation="Run `cctally setup` to clean stale links",
+            details=details,
         )
+    # bad present
+    if s.symlinks_path_pinned:
+        # Pinned-only-path (finding #2/#10): cctally runs ONLY through a
+        # legacy ~/.local/bin link to a keg, so its slot classes `wrong`
+        # but the command works. `cctally setup` deliberately won't remove
+        # the only reachable copy — the actionable fix is a PATH change.
+        # Keep this message in sync with the pinned guidance in _setup_install
+        # (bin/_cctally_setup.py).
+        remediation = (
+            "cctally is reachable only through a legacy ~/.local/bin link to a "
+            "Homebrew keg. Put <prefix>/bin on your PATH (e.g. `eval \"$(brew shellenv)\"`), "
+            "then run `cctally setup` to remove the legacy link."
+        )
+    else:
+        remediation = "Run `cctally setup`"
+    summary = f"{available}/{total} available; missing/broken {', '.join(bad)}"
+    if stale:
+        summary += f"; {len(stale)} stale"
     return CheckResult(
         id="install.symlinks", title="Symlinks",
-        severity="warn",
-        summary=f"{ok_count}/{total} present; missing {', '.join(missing)}",
-        remediation="Run `cctally setup`",
-        details={"present": ok_count, "total": total, "missing": missing},
+        severity="warn", summary=summary, remediation=remediation, details=details,
     )
 
 
 def _check_install_path(s: DoctorState) -> CheckResult:
-    if s.path_includes_local_bin:
+    # Issue #119: availability-aware. OK iff cctally is ACTUALLY reachable
+    # on $PATH via ANY channel — brew `<prefix>/bin`, npm prefix, or source
+    # `~/.local/bin` (`shutil.which`, precomputed in the I/O layer). Mere
+    # `~/.local/bin` membership is NOT sufficient: doctor can be launched by
+    # absolute path or from another UI with `~/.local/bin` on $PATH yet no
+    # `cctally` installed there (the brew-only #119 case), which must WARN.
+    # `path_includes_local_bin` is only a fail-soft fallback for when the
+    # reachability probe could not run (None), so a gather failure never
+    # hard-WARNs an otherwise-working install.
+    reachable = s.cctally_reachable_on_path
+    if reachable is None:
+        reachable = bool(s.path_includes_local_bin)
+    if reachable:
         return CheckResult(
             id="install.path", title="PATH",
-            severity="ok", summary="~/.local/bin on $PATH",
+            severity="ok", summary="cctally reachable on $PATH",
             remediation=None, details={},
         )
+    # Channel-aware remediation: a Homebrew keg keeps cctally on
+    # `<prefix>/bin` and deliberately owns no `~/.local/bin` symlinks
+    # (#119), so the `~/.local/bin` / `cctally setup` hint would be wrong
+    # for it — point brew users at `brew shellenv` instead (matching the
+    # pinned-only-path remediation in `_check_install_symlinks`). Source /
+    # npm installs keep the `~/.local/bin` + `cctally setup` guidance.
+    if s.install_is_brew:
+        remediation = (
+            "Put `<prefix>/bin` on your PATH (e.g. `eval \"$(brew shellenv)\"`)"
+        )
+    else:
+        remediation = (
+            "Append `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell rc, "
+            "or run `cctally setup`"
+        )
     return CheckResult(
         id="install.path", title="PATH",
-        severity="warn", summary="~/.local/bin not on $PATH",
-        remediation="Append `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell rc",
+        severity="warn", summary="cctally not reachable on $PATH",
+        remediation=remediation,
         details={},
     )
 

package/bin/cctally

@@ -479,7 +479,10 @@ _SetupSymlinkResult = _cctally_setup._SetupSymlinkResult
 _setup_resolve_symlink_source = _cctally_setup._setup_resolve_symlink_source
 _setup_resolve_hook_target = _cctally_setup._setup_resolve_hook_target
 _setup_create_symlinks = _cctally_setup._setup_create_symlinks
+_setup_repair_symlinks = _cctally_setup._setup_repair_symlinks
 _setup_path_includes_local_bin = _cctally_setup._setup_path_includes_local_bin
+_setup_symlink_is_retired = _cctally_setup._setup_symlink_is_retired
+_setup_is_brew_install = _cctally_setup._setup_is_brew_install
 _setup_shell_rc_hint = _cctally_setup._setup_shell_rc_hint
 _setup_detect_legacy_snippet = _cctally_setup._setup_detect_legacy_snippet
 _setup_detect_legacy_bespoke_hooks = _cctally_setup._setup_detect_legacy_bespoke_hooks
@@ -10405,6 +10408,39 @@ def doctor_gather_state(
         path_includes = _setup_path_includes_local_bin()
     except Exception:
         path_includes = None
+    # Issue #119: availability-aware install checks. Precomputed here (the
+    # I/O layer) so the kernel stays pure — `shutil.which` and the on-disk
+    # legacy-link probe never run in _lib_doctor.
+    #   * cctally_reachable_on_path — channel-agnostic "is the command on
+    #     $PATH at all?" (brew <prefix>/bin, npm prefix, source ~/.local/bin
+    #     all satisfy it). Lets install.path pass without a ~/.local/bin
+    #     membership check.
+    #   * symlinks_path_pinned — true iff cctally runs ONLY through a legacy
+    #     ~/.local/bin link to a retired/foreign install (live retired link
+    #     with no reachable_elsewhere fallback). Mirrors the pinned-only-path
+    #     predicate in _setup_install so doctor + setup agree on the fix.
+    try:
+        cctally_reachable_on_path = shutil.which("cctally") is not None
+    except Exception:
+        cctally_reachable_on_path = None
+    try:
+        symlinks_path_pinned = any(
+            s == "wrong"
+            and (dst_dir / n).is_symlink()
+            and _setup_symlink_is_retired(dst_dir / n, n, repo_root)
+            and (dst_dir / n).resolve(strict=False).exists()
+            for n, s in (symlink_state or [])
+        )
+    except Exception:
+        symlinks_path_pinned = False
+    # install_is_brew — channel knowledge for the install.path WARN
+    # remediation. Brew kegs own no ~/.local/bin symlinks (#119), so the
+    # ~/.local/bin / `cctally setup` hint is wrong for them; the kernel
+    # can't derive this from repo_root (no I/O), so precompute it here.
+    try:
+        install_is_brew = _setup_is_brew_install(repo_root)
+    except Exception:
+        install_is_brew = False
     try:
         legacy_snippet = _setup_detect_legacy_snippet()
     except Exception:
@@ -10687,6 +10723,10 @@ def doctor_gather_state(
     return _lib_doctor.DoctorState(
         symlink_state=symlink_state,
         path_includes_local_bin=path_includes,
+        # Issue #119: availability-aware install checks (precomputed above).
+        cctally_reachable_on_path=cctally_reachable_on_path,
+        symlinks_path_pinned=symlinks_path_pinned,
+        install_is_brew=install_is_brew,
         legacy_snippet=legacy_snippet,
         legacy_bespoke=legacy_bespoke,
         claude_settings=settings,
@@ -13108,6 +13148,27 @@ def build_parser() -> argparse.ArgumentParser:
     )
     uc.set_defaults(func=cmd_update_check_internal)
 
+    # ---- repair-symlinks (internal — hidden; npm-postinstall self-heal, issue #114) ----
+    rs = sub.add_parser(
+        "repair-symlinks",
+        help=argparse.SUPPRESS,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Internal subcommand: additively create any missing
+            ~/.local/bin/ symlinks for cctally subcommands (issue #114).
+
+            Invoked best-effort by the npm postinstall on upgrade so new
+            cctally-* binaries become reachable without re-running
+            `cctally setup`. Gated to existing installs (>=1 symlink
+            already present); a fresh install is a silent no-op. Touches
+            only symlinks — no hooks, settings.json, or cache. Refuses
+            from a dev checkout.
+            """
+        ),
+    )
+    rs.set_defaults(func=cmd_repair_symlinks)
+
     # Python 3.14 leaks `==SUPPRESS==` for hidden subparsers in --help; strip
     # the pseudo-action so the row disappears entirely. (The choice still
     # appears in the `{...}` choices header — there's no clean way to hide
@@ -14921,6 +14982,33 @@ cmd_tui = _cctally_tui.cmd_tui
 _tui_render_once = _cctally_tui._tui_render_once
 
 
+def cmd_repair_symlinks(args: argparse.Namespace) -> int:
+    """Hidden: additively create missing ~/.local/bin/ symlinks on upgrade.
+
+    Invoked best-effort by the npm postinstall (issue #114). Refuses from
+    a dev checkout (would point ~/.local/bin at the dev tree). Touches
+    only symlinks — see _setup_repair_symlinks. Exempted from main()'s
+    post-command update hooks (see _post_command_update_hooks).
+    """
+    if _cctally_core._is_dev_checkout():
+        eprint(
+            "repair-symlinks: refusing to run from a dev checkout "
+            "(would point ~/.local/bin at the dev tree)"
+        )
+        return 2
+    repo_root = _setup_resolve_repo_root()
+    dst_dir = _setup_local_bin_dir()
+    result = _setup_repair_symlinks(repo_root, dst_dir)
+    if result.created:
+        print(
+            f"cctally: linked {len(result.created)} new command symlink(s): "
+            + ", ".join(result.created)
+        )
+    for name, detail in result.failed:
+        eprint(f"repair-symlinks: {name}: {detail}")
+    return 1 if result.failed else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     _migrate_legacy_data_dir()
     parser = build_parser()
@@ -14994,11 +15082,21 @@ def _post_command_update_hooks(command: str | None, args) -> None:
     does not stop these side effects. Doctor reads update state for
     its report via the gather layer; it must not refresh that state
     opportunistically. Users who want a fresh check have
-    ``cctally update --check``."""
+    ``cctally update --check``.
+
+    Skip-for-repair-symlinks: ``repair-symlinks`` is spawned by the npm
+    postinstall on every install (issue #114). It must touch nothing but
+    ~/.local/bin/ symlinks — running ``load_config()`` /
+    ``_spawn_background_update_check`` here would create ``config.json``,
+    ``update-state.json``, and ``update.log`` on a fresh install where
+    the existing-install gate already makes the symlink work a no-op.
+    Same rationale as doctor."""
     if command == "setup" and getattr(args, "uninstall", False):
         return
     if command == "doctor":
         return
+    if command == "repair-symlinks":
+        return
     # Self-heal: reconcile current_version with the running binary's
     # CHANGELOG. Cheap (one CHANGELOG read, write only on the first
     # command after a manual upgrade). Runs before load_config so a

package/bin/cctally-npm-postinstall.js

@@ -16,6 +16,20 @@ if (process.env.CCTALLY_NPM_POSTINSTALL_QUIET === '1') {
   process.exit(0);
 }
 
+// Best-effort symlink self-heal on upgrade (issue #114): additively
+// create ~/.local/bin/ symlinks for any new cctally-* subcommands so an
+// upgrade doesn't strand them until the user re-runs `cctally setup`.
+// MUST NOT fail the npm install — swallow every error, ignore exit code.
+try {
+  const { spawnSync } = require('child_process');
+  const path = require('path');
+  const python = process.env.CCTALLY_PYTHON || 'python3';
+  const scriptPath = path.join(__dirname, 'cctally');
+  spawnSync(python, [scriptPath, 'repair-symlinks'], { stdio: 'inherit' });
+} catch (_) {
+  // best-effort only
+}
+
 process.stdout.write(
   '\ncctally installed.\n' +
   '\nTo finish setup, run:\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.21.1",
+  "version": "1.21.3",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {