cctally 1.8.2 → 1.10.0

package/bin/_cctally_setup.py

@@ -242,10 +242,22 @@ def _setup_local_bin_dir() -> pathlib.Path:
 @dataclasses.dataclass
 class _SetupSymlinkResult:
     name: str
-    status: str   # "created" | "already" | "replaced" | "failed"
+    status: str   # "created" | "already" | "replaced" | "failed" | "removed-stale"
     detail: str = ""
 
 
+# Symlink names cctally USED to install but no longer does. We keep
+# cleaning them up for one major-version's worth of upgraders so
+# `~/.local/bin/` doesn't accumulate dangling symlinks pointing at
+# scripts the current cctally checkout doesn't ship. Removal is
+# conservative: we only unlink symlinks whose `readlink()` target's
+# basename matches the stale name — a user's hand-rolled symlink with
+# the same name pointing elsewhere is left alone.
+_SETUP_STALE_SYMLINK_NAMES = (
+    "cctally-release",  # Removed in v1.9.0; release tooling went private.
+)
+
+
 def _setup_resolve_symlink_source(repo_root: pathlib.Path, name: str) -> pathlib.Path:
     """Resolve the symlink target for a given PATH-name.
 
@@ -326,6 +338,148 @@ def _setup_create_symlinks(
     return results
 
 
+def _setup_cleanup_stale_symlinks(
+    dst_dir: pathlib.Path,
+) -> list[_SetupSymlinkResult]:
+    """Unlink stale `cctally-*` symlinks left over from prior versions.
+
+    For each entry in :data:`_SETUP_STALE_SYMLINK_NAMES`, removes the
+    matching symlink in ``dst_dir`` when its readlink target basename
+    matches the stale name AND the target points at a "retired" cctally
+    install — meaning either (a) the target is *dangling* (no longer
+    resolves to a real file, e.g. an old checkout that was deleted) OR
+    (b) the target lives under a *foreign* cctally install root
+    (Homebrew keg, npm ``node_modules/cctally/``), i.e. an install root
+    other than the one currently running ``cctally setup``.
+
+    The foreign-root clause is what handles the common upgrade path:
+    after ``brew upgrade cctally`` or ``npm i -g cctally@<new>``, the
+    *prior* keg / module dir often lingers on disk until ``brew
+    cleanup`` (or the next npm install GC), so a legacy
+    ``~/.local/bin/cctally-release`` symlink from a pre-v1.9.0 ``cctally
+    setup`` still resolves to an existing file under the *old* install
+    root. The dangling-only predicate would skip it, leaving the retired
+    command on PATH; the foreign-root check retires it instead.
+
+    Both clauses still preserve the maintainer's intentional manual
+    link to the *current* checkout's still-shipped retired tooling
+    (e.g. ``~/.local/bin/cctally-release ->
+    <cctally-dev>/bin/cctally-release``) — that target is neither
+    dangling nor foreign, so it's left alone. Likewise a hand-rolled
+    link pointing somewhere unrelated (``~/scripts/...``) survives.
+
+    Returns a list of :class:`_SetupSymlinkResult` entries for the
+    actions taken (so callers can fold them into install output).
+    """
+    results: list[_SetupSymlinkResult] = []
+    repo_root = _setup_resolve_repo_root()
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if not _setup_symlink_is_retired(dst, name, repo_root):
+            continue
+        try:
+            dst.unlink()
+            results.append(
+                _SetupSymlinkResult(name, "removed-stale", "stale (from prior version)")
+            )
+        except OSError as exc:
+            results.append(
+                _SetupSymlinkResult(name, "failed", f"unlink failed: {exc}")
+            )
+    return results
+
+
+# Path tokens that identify a "foreign" cctally install root — i.e. a
+# directory tree managed by a different distribution channel (or a
+# different version of the same channel) than the one currently running
+# ``cctally setup``. A symlink whose target sits under one of these is
+# almost certainly a legacy auto-installed link from a prior version
+# whose install root the current run does NOT manage. Pre-resolved (no
+# trailing slash) so substring matching works on either UNIX or
+# resolved forms.
+_SETUP_FOREIGN_INSTALL_ROOT_TOKENS = (
+    # Homebrew keeps every installed version under
+    # ``<prefix>/Cellar/cctally/<version>/``. A target inside any of
+    # these directories points at a brew install — either the current
+    # one (when ``cctally setup`` runs from a brew install — possible
+    # but rare) or an older keg still on disk pending ``brew cleanup``.
+    "/Cellar/cctally/",
+    # npm globals land at ``<prefix>/lib/node_modules/cctally/``; npm
+    # locals at ``<project>/node_modules/cctally/``. Either way the
+    # ``/node_modules/cctally/`` segment is the discriminator. pnpm and
+    # yarn variants keep the segment, so this catches them too.
+    "/node_modules/cctally/",
+)
+
+
+def _setup_symlink_is_retired(
+    dst: pathlib.Path, name: str, repo_root: pathlib.Path,
+) -> bool:
+    """Detection predicate for retired auto-symlinks at install time.
+
+    Returns True iff ``dst`` is a symlink, its readlink target basename
+    matches ``name``, AND the target points at a "retired" cctally
+    install — i.e. one the current ``cctally setup`` run does not
+    manage. Two retirement classes:
+
+      1. **Dangling target** — readlink target does not resolve to an
+         existing filesystem entry. Covers the deleted-checkout case.
+      2. **Foreign install root** — target path contains one of
+         :data:`_SETUP_FOREIGN_INSTALL_ROOT_TOKENS` (``/Cellar/cctally/``
+         or ``/node_modules/cctally/``) AND that token does NOT also
+         appear in the current ``repo_root``. The second clause is what
+         keeps the (rare) case of running ``cctally setup`` *from* an
+         npm/brew install correctly — a symlink at the same install root
+         is NOT foreign, so it's left to the active-symlinks loop in
+         :func:`_setup_install` / :func:`_setup_uninstall`.
+
+    Targets that exist but live outside any recognized install root
+    (e.g. a maintainer's manual link to ``<checkout>/bin/cctally-release``
+    or a hand-rolled link at ``~/scripts/cctally-release``) are
+    preserved — they're either explicit operator setups or genuine
+    user-managed scripts that happen to share the name.
+
+    Shared by the cleanup site (``_setup_cleanup_stale_symlinks``) and
+    the read-only detection site (``_setup_detect_stale_symlinks``) so
+    ``--status`` and ``setup`` agree on what they call "stale".
+    """
+    if not dst.is_symlink():
+        return False
+    try:
+        target = os.readlink(dst)
+    except OSError:
+        return False
+    if pathlib.Path(target).name != name:
+        # User-managed symlink that happens to share the name; leave alone.
+        return False
+    # Resolve target relative to the symlink's parent so relative
+    # readlinks (rare for cctally setup-installed links, but possible
+    # for hand-rolled ones) classify correctly. Use lexists()-style
+    # check via Path.exists() — broken links return False, which is
+    # the "dangling, treat as stale" branch we want.
+    target_path = pathlib.Path(target)
+    if not target_path.is_absolute():
+        target_path = dst.parent / target_path
+    try:
+        target_exists = target_path.exists()
+    except OSError:
+        # Permission errors etc. — be conservative and don't remove.
+        return False
+    if not target_exists:
+        return True
+    # Target exists — retire only if it lives under a *foreign* install
+    # root (a different brew keg / npm module dir than the one running
+    # this setup). Compare against ``repo_root`` so a setup running
+    # *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)
+    repo_root_str = str(repo_root)
+    for token in _SETUP_FOREIGN_INSTALL_ROOT_TOKENS:
+        if token in target_str and token not in repo_root_str:
+            return True
+    return False
+
+
 def _setup_path_includes_local_bin() -> bool:
     local_bin = str(_setup_local_bin_dir())
     return local_bin in os.environ.get("PATH", "").split(os.pathsep)
@@ -816,12 +970,38 @@ def _setup_compute_symlink_state(
     return out
 
 
+def _setup_detect_stale_symlinks(dst_dir: pathlib.Path) -> list[str]:
+    """Return names of stale-but-still-present cctally symlinks in ``dst_dir``.
+
+    Mirrors :func:`_setup_cleanup_stale_symlinks` detection (without
+    removing): a symlink is "stale" when its name appears in
+    :data:`_SETUP_STALE_SYMLINK_NAMES`, its readlink target basename
+    matches that name, AND the target is "retired" — either dangling
+    OR pointing at a foreign cctally install root (see
+    :func:`_setup_symlink_is_retired`). Routing through the same
+    predicate keeps ``--status`` and ``setup`` in lockstep so a
+    manually-maintained link to a still-shipped retired tool
+    (``~/.local/bin/cctally-release -> <checkout>/bin/cctally-release``)
+    is neither reported as stale nor removed, while a legacy link left
+    over from a pre-v1.9.0 brew/npm install (target still resolves into
+    the old keg / ``node_modules`` tree) IS retired.
+    """
+    found: list[str] = []
+    repo_root = _setup_resolve_repo_root()
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if _setup_symlink_is_retired(dst, name, repo_root):
+            found.append(name)
+    return found
+
+
 def _setup_status(args: argparse.Namespace) -> int:
     c = _cctally()
     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)
     on_path = _setup_path_includes_local_bin()
     try:
         settings = c._load_claude_settings()
@@ -842,6 +1022,7 @@ def _setup_status(args: argparse.Namespace) -> int:
             "install": {
                 "symlinks_present": sym_ok,
                 "symlinks_total": len(c.SETUP_SYMLINK_NAMES),
+                "symlinks_stale": stale_syms,
                 "path_includes": on_path,
             },
             "hooks": {ev: hook_counts[ev] for ev in c.SETUP_HOOK_EVENTS},
@@ -869,6 +1050,11 @@ def _setup_status(args: argparse.Namespace) -> int:
     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}")
+    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 '⚠'}")
     out.append(f"Hooks ({c.CLAUDE_SETTINGS_PATH})")
@@ -950,6 +1136,50 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                     sym_removed += 1
                 except OSError as exc:
                     eprint(f"setup: failed to remove {dst}: {exc}")
+    # Also clean up legacy symlinks that older cctally versions used to
+    # install but the current version no longer manages (see
+    # :data:`_SETUP_STALE_SYMLINK_NAMES`). Without this loop, an
+    # upgrader who ran ``cctally setup`` on a prior version and now runs
+    # ``cctally setup --uninstall`` would keep e.g.
+    # ``~/.local/bin/cctally-release`` on PATH.
+    #
+    # Two removal predicates compose here:
+    #   1. ``target == _setup_resolve_symlink_source(repo_root, name)``
+    #      — the legacy auto-installed link points at *this* install
+    #      root's binary (the common case for git-checkout upgraders
+    #      who ran ``cctally setup`` on a prior version, then ``git
+    #      pull``ed; symmetric with how the active-symlink loop above
+    #      treats user-pointed `cctally` itself).
+    #   2. ``_setup_symlink_is_retired`` — target is dangling OR lives
+    #      under a *foreign* cctally install root (old brew keg /
+    #      ``node_modules/cctally/`` left behind by ``brew upgrade``
+    #      or ``npm i -g cctally@<new>``). Without this, the common
+    #      brew/npm upgrade-then-uninstall path leaves the legacy
+    #      symlink in place because the prior keg's binary still
+    #      exists on disk (``target != expected``).
+    #
+    # A maintainer's hand-rolled link pointing somewhere unrelated
+    # (``~/scripts/...``) is preserved by both predicates.
+    for name in _SETUP_STALE_SYMLINK_NAMES:
+        dst = dst_dir / name
+        if not dst.is_symlink():
+            continue
+        try:
+            target = pathlib.Path(os.readlink(dst))
+        except OSError:
+            continue
+        expected = _setup_resolve_symlink_source(repo_root, name)
+        should_remove = (
+            target == expected
+            or _setup_symlink_is_retired(dst, name, repo_root)
+        )
+        if not should_remove:
+            continue
+        try:
+            dst.unlink()
+            sym_removed += 1
+        except OSError as exc:
+            eprint(f"setup: failed to remove {dst}: {exc}")
     out.append(f"Removed {sym_removed} symlinks from {dst_dir}/")
 
     legacy = _setup_detect_legacy_snippet()
@@ -1336,6 +1566,13 @@ def _setup_install(args: argparse.Namespace) -> int:
         eprint(f"setup: {exc}")
         return 1
 
+    # Clean up symlinks left behind by prior cctally versions whose
+    # subcommand surface has changed (e.g. v1.9.0 retired
+    # `cctally-release` when release tooling went private). Only unlinks
+    # symlinks whose target's basename matches the stale name; never
+    # 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:
@@ -1354,6 +1591,16 @@ def _setup_install(args: argparse.Namespace) -> int:
         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:
+        out.append(
+            "✓ Cleaned up stale symlink(s) from prior version: "
+            + ", ".join(r.name for r in removed_stale)
+        )
+    for r in failed_stale:
+        out.append(f"⚠ Could not remove stale {r.name}: {r.detail}")
+        warnings += 1
 
     if not _setup_path_includes_local_bin():
         warnings += 1

package/bin/_cctally_tui.py

@@ -1061,6 +1061,16 @@ class DataSnapshot:
     # through ``_tui_build_snapshot``; the envelope adapter falls
     # back to the legacy inline routing in that case.
     forecast_view: Any | None = None
+    # Projects panel + modal envelope block (spec §5.2 /
+    # 2026-05-19-projects-panel-design.md). Populated on the sync
+    # thread by ``_build_projects_envelope`` (per-tick DB-touching
+    # aggregation that runs alongside the existing per-panel builds);
+    # the dashboard's pure ``snapshot_to_envelope`` reads this back
+    # unchanged and assigns it to ``envelope["projects"]``. ``None``
+    # on first tick before sync completes — the TS envelope mirror
+    # declares ``ProjectsEnvelope | null`` and the client renders the
+    # panel-empty state until the next tick replaces it.
+    projects_envelope: dict | None = None
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -1612,6 +1622,95 @@ class TuiSessionDetail:
     cost_total_usd: float
 
 
+def _tui_build_session_detail_indexed(
+    session_id: str,
+    range_start: dt.datetime,
+    range_end: dt.datetime,
+) -> Any | None:
+    """Indexed direct lookup for one session by id.
+
+    Walks ``session_files`` (indexed by ``session_id`` — migration
+    ``idx_session_files_session_id``) for the 1-3 source_paths the
+    session lives in, then fetches ONLY the entries from those paths
+    in the supplied range. Aggregates the filtered list and returns
+    the single matching ``ClaudeSessionUsage`` row.
+
+    Returns ``None`` on three indistinguishable misses (the caller's
+    fallback path handles them all):
+
+    1. session_files row hasn't been backfilled yet for this id
+       (CLAUDE.md "session_files is populated lazily" — first run
+       after deploy).
+    2. cache DB unavailable (open / lock contention).
+    3. session_id is genuinely unknown.
+
+    Falling back uniformly preserves correctness without distinguishing
+    the cases; if the slow path also misses, the modal renders 404.
+    """
+    c = _cctally()
+    open_cache_db = c.open_cache_db
+    _JoinedClaudeEntry = c._JoinedClaudeEntry
+    try:
+        conn = open_cache_db()
+    except (sqlite3.DatabaseError, OSError):
+        return None
+    try:
+        # 1) Source paths for this session id (indexed lookup).
+        rows = conn.execute(
+            "SELECT path FROM session_files WHERE session_id = ?",
+            (session_id,),
+        ).fetchall()
+        if not rows:
+            return None
+        paths = [r[0] for r in rows]
+        # 2) Entries restricted to those paths in the range. Typical
+        # path-count is 1-3 (resume across files), well below SQLite's
+        # 999 parameter cap.
+        start_iso = range_start.astimezone(dt.timezone.utc).isoformat()
+        end_iso = range_end.astimezone(dt.timezone.utc).isoformat()
+        placeholders = ",".join("?" * len(paths))
+        cur = conn.execute(
+            f"SELECT se.timestamp_utc, se.model, "
+            f"  se.input_tokens, se.output_tokens, "
+            f"  se.cache_create_tokens, se.cache_read_tokens, "
+            f"  se.source_path, sf.session_id, sf.project_path, "
+            f"  se.cost_usd_raw "
+            f"FROM session_entries se "
+            f"LEFT JOIN session_files sf ON sf.path = se.source_path "
+            f"WHERE se.timestamp_utc >= ? AND se.timestamp_utc <= ? "
+            f"  AND se.source_path IN ({placeholders}) "
+            f"ORDER BY se.timestamp_utc ASC",
+            [start_iso, end_iso, *paths],
+        )
+        entries = [
+            _JoinedClaudeEntry(
+                timestamp=dt.datetime.fromisoformat(row[0]),
+                model=row[1],
+                input_tokens=row[2],
+                output_tokens=row[3],
+                cache_creation_tokens=row[4],
+                cache_read_tokens=row[5],
+                source_path=row[6],
+                session_id=row[7],
+                project_path=row[8],
+                cost_usd=row[9],
+            )
+            for row in cur
+        ]
+        if not entries:
+            return None
+        sessions = _aggregate_claude_sessions(entries)
+        for s in sessions:
+            if s.session_id == session_id:
+                return s
+        return None
+    finally:
+        try:
+            conn.close()
+        except sqlite3.Error:
+            pass
+
+
 def _tui_build_session_detail(
     session_id: str,
     *,
@@ -1619,19 +1718,34 @@ def _tui_build_session_detail(
 ) -> TuiSessionDetail | None:
     """Look up one session by ID; return None if not found.
 
-    Reuses the same `get_claude_session_entries` + `_aggregate_claude_sessions`
-    pipeline as `_tui_build_sessions` but filters down to the matching ID.
-    Bounded scan window matches the panel builder (365 days).
+    Fast path: ``_tui_build_session_detail_indexed`` reads
+    ``session_files`` by id, scopes the entries SELECT to the matching
+    source_paths, and aggregates only those rows — turning the lookup
+    from "build every session in 365 days" into an indexed direct
+    fetch (~3000× fewer rows on real DBs).
+
+    Slow-path fallback: when the indexed lookup misses (session_files
+    not yet backfilled, cache unavailable, or genuinely unknown), the
+    legacy bulk-fetch + linear scan still runs so the modal renders
+    consistently with the panel's session list during the lazy-
+    backfill window.
     """
     now_utc = now_utc or dt.datetime.now(dt.timezone.utc)
     range_start = now_utc - dt.timedelta(days=365)
-    entries = get_claude_session_entries(range_start, now_utc, skip_sync=True)
-    sessions = _aggregate_claude_sessions(entries)
-    match: Any | None = None
-    for s in sessions:
-        if s.session_id == session_id:
-            match = s
-            break
+    match: Any | None = _tui_build_session_detail_indexed(
+        session_id, range_start, now_utc,
+    )
+    if match is None:
+        # Fall back to the bulk-aggregate path. Same shape as before,
+        # used only when the index lookup couldn't conclude.
+        entries = get_claude_session_entries(
+            range_start, now_utc, skip_sync=True,
+        )
+        sessions = _aggregate_claude_sessions(entries)
+        for s in sessions:
+            if s.session_id == session_id:
+                match = s
+                break
     if match is None:
         return None
     duration_min = (match.last_activity - match.first_activity).total_seconds() / 60.0
@@ -1896,6 +2010,109 @@ def _tui_build_snapshot(
             fh_milestones = _tui_build_five_hour_milestones(conn, win_key)
         except Exception as exc:
             errors.append(f"five-hour-milestones: {exc}")
+        # ---- Projects panel + modal envelope (spec §5.2, plan Task 1) -----
+        # Per-tick aggregation lives on the sync thread; the dashboard's
+        # pure ``snapshot_to_envelope`` reads ``snap.projects_envelope``
+        # back unchanged. Errors are recorded on ``last_sync_error`` —
+        # the client renders the panel-empty state when the field is
+        # None (first tick, or sub-build failure).
+        #
+        # ATTACH cache.db onto the open stats conn so
+        # ``_build_projects_envelope`` (which reads ``session_entries`` +
+        # ``session_files`` + ``weekly_usage_snapshots`` off one conn —
+        # the test contract per tests/test_projects_envelope.py) sees
+        # all three tables. ATTACH/DETACH is cheap and scoped to this
+        # sub-build; no schema migration / lock acquisition is needed.
+        projects_envelope_block: dict | None = None
+        try:
+            c = _cctally()
+            cache_db_path = c.CACHE_DB_PATH
+            conn.execute(
+                "ATTACH DATABASE ? AS cache_db",
+                (str(cache_db_path),),
+            )
+            # session_entries / session_files live in cache.db; the
+            # builder reads them via raw SQL keyed by the unqualified
+            # table names. SQLite's name resolution prefers the `main`
+            # schema, so create temporary views in `main` that point
+            # at the attached schema's tables. Aliasing via VIEWs keeps
+            # the builder portable: unit tests pass one conn carrying
+            # both schemas; production wiring uses an attached cache.
+            conn.execute(
+                "CREATE TEMP VIEW IF NOT EXISTS session_entries AS "
+                "SELECT * FROM cache_db.session_entries"
+            )
+            conn.execute(
+                "CREATE TEMP VIEW IF NOT EXISTS session_files AS "
+                "SELECT * FROM cache_db.session_files"
+            )
+            projects_envelope_block = c._build_projects_envelope(
+                conn,
+                now_utc=now_utc,
+                current_week=cw,
+                weeks_back=12,
+            )
+        except Exception as exc:
+            errors.append(f"projects-envelope: {exc}")
+        finally:
+            try:
+                conn.execute("DROP VIEW IF EXISTS session_entries")
+                conn.execute("DROP VIEW IF EXISTS session_files")
+            except Exception:
+                pass
+            try:
+                conn.execute("DETACH DATABASE cache_db")
+            except Exception:
+                pass
+        # Late-bind disambiguated `project_key` onto each SessionsPanel
+        # row so the SessionsPanel → ProjectsModal cross-nav (spec §4.1)
+        # routes by the same identity the Projects envelope emits.
+        # Cheap dict-lookup per row; no second aggregation pass.
+        #
+        # `key_by_bucket_path` is indexed by git-root bucket_path (the
+        # envelope builder calls `_resolve_project_key(..., "git-root")`
+        # in `_build_projects_envelope`), but `srow.project_path` is the
+        # raw cwd from `_aggregate_claude_sessions` — typically a
+        # subdirectory of the repo root for monorepo sessions. We must
+        # resolve each cwd through the same production resolver so the
+        # lookup hits; otherwise `project_key` stays None and the
+        # cross-nav button degrades to plain text.
+        if projects_envelope_block is not None:
+            try:
+                key_by_bucket_path: dict[str, str] = {}
+                for r in projects_envelope_block.get(
+                    "current_week", {}
+                ).get("rows", []):
+                    bp = r.get("bucket_path")
+                    k = r.get("key")
+                    if bp and k:
+                        key_by_bucket_path[bp] = k
+                for r in projects_envelope_block.get(
+                    "trend", {}
+                ).get("projects", []):
+                    bp = r.get("bucket_path")
+                    k = r.get("key")
+                    if bp and k and bp not in key_by_bucket_path:
+                        key_by_bucket_path[bp] = k
+                _resolve = _cctally()._resolve_project_key
+                resolver_cache: dict = {}
+                annotated: list[TuiSessionRow] = []
+                for srow in sessions:
+                    pkey = None
+                    if srow.project_path:
+                        bp = _resolve(
+                            srow.project_path, "git-root", resolver_cache,
+                        ).bucket_path
+                        pkey = key_by_bucket_path.get(bp)
+                    if pkey is None:
+                        annotated.append(srow)
+                    else:
+                        annotated.append(
+                            dataclasses.replace(srow, project_key=pkey)
+                        )
+                sessions = annotated
+            except Exception as exc:
+                errors.append(f"projects-cross-nav-bind: {exc}")
         return DataSnapshot(
             current_week=cw,
             forecast=fc,
@@ -1923,6 +2140,7 @@ def _tui_build_snapshot(
             trend_avg_dollars_per_pct=trend_avg_dpp,
             trend_history_median_dpp=history_median_dpp,
             forecast_view=fc_view,
+            projects_envelope=projects_envelope_block,
         )
     finally:
         conn.close()

package/bin/_cctally_update.py

@@ -116,10 +116,16 @@ What stays in bin/cctally:
   write surface in cmd_dashboard works unchanged; moved code
   reads via ``c.X``.
 - ``eprint``, ``_now_utc`` (used by moved code via shim/accessor),
-  ``_release_read_latest_release_version`` (stays in cctally per
-  spec §6.7 — 6+ external callers, file I/O over CHANGELOG.md),
+  ``_release_read_latest_release_version`` (impl moved to
+  ``_lib_changelog._read_latest_changelog_version``; cctally
+  re-exports the historical name. The shim below routes through
+  ``sys.modules['cctally']`` so test ``monkeypatch.setitem(ns, ...)``
+  on the historical name still overrides the 5 internal callers
+  here),
   ``_release_parse_semver`` / ``_release_semver_sort_key`` (lives
-  in ``_lib_semver`` and re-exported by cctally),
+  in ``_lib_semver``; shims below route directly to that module —
+  the cctally re-exports were removed in the release-command split
+  privatization),
   ``load_config`` (lives in ``_cctally_config``; re-exported),
   ``_BANNER_SUPPRESSED_COMMANDS`` (lives in ``_cctally_db``;
   re-exported by cctally — composed with the update-only
@@ -210,17 +216,35 @@ def load_config(*args, **kwargs):
 
 
 def _release_read_latest_release_version(*args, **kwargs):
+    """Back-compat shim. The implementation now lives in
+    ``bin/_lib_changelog._read_latest_changelog_version``; ``bin/cctally``
+    re-exports it under the historical name. This shim routes through
+    the ``cctally`` namespace (not directly to ``_lib_changelog``) so
+    that ``monkeypatch.setitem(ns, "_release_read_latest_release_version", ...)``
+    in tests/test_update.py + tests/test_release_internals.py overrides
+    the 5+ internal callers in this module. New code should call
+    ``_lib_changelog._read_latest_changelog_version`` directly.
+    """
     return sys.modules["cctally"]._release_read_latest_release_version(
         *args, **kwargs
     )
 
 
+# The semver shims now resolve via ``_lib_semver`` directly — the
+# cctally re-exports (``_release_parse_semver`` / ``_release_semver_sort_key``)
+# were removed in the release-command split privatization. Kept as
+# call-time shims (vs. module-top ``from _lib_semver import ...``) so
+# tests can still ``monkeypatch.setitem(ns, "_release_parse_semver", ...)``
+# on this module's namespace if needed; the bare-name lookup inside this
+# module resolves here, not at the import site.
 def _release_parse_semver(*args, **kwargs):
-    return sys.modules["cctally"]._release_parse_semver(*args, **kwargs)
+    import _lib_semver
+    return _lib_semver._release_parse_semver(*args, **kwargs)
 
 
 def _release_semver_sort_key(*args, **kwargs):
-    return sys.modules["cctally"]._release_semver_sort_key(*args, **kwargs)
+    import _lib_semver
+    return _lib_semver._release_semver_sort_key(*args, **kwargs)
 
 
 def _normalize_alerts_enabled_value(*args, **kwargs):