cctally 1.6.3 → 1.7.0

package/bin/cctally

@@ -10057,7 +10057,10 @@ def _persist_install_method_to_state(method: InstallMethod) -> None:
     _save_update_state(state)
 
 
-def _stamp_install_success_to_state(installed_version: str | None) -> None:
+def _stamp_install_success_to_state(
+    installed_version: str | None,
+    method: "InstallMethod | None" = None,
+) -> None:
     """Stamp ``update-state.json`` with the just-installed version so the
     post-install banner predicate + dashboard auto-close fire immediately.
 
@@ -10070,19 +10073,84 @@ def _stamp_install_success_to_state(installed_version: str | None) -> None:
     ``refreshUpdateState`` auto-close (``current === latest``) never
     matches.
 
-    Falls back to ``state.latest_version`` when the caller didn't pass
-    an explicit ``--version`` — brew is always unpinned, and an
-    unpinned npm install resolves to whatever ``@latest`` advertised,
-    which is the value we just told the user about.
+    Resolution order:
+      1. ``installed_version`` — caller passed an explicit ``--version``.
+      2. For brew (when ``method.method == "brew"`` and no explicit
+         version), ``state.latest_version`` — the freshly-probed value
+         that drove the install. The running process's ``CHANGELOG_PATH``
+         resolved to the OLD Cellar at boot, so a CHANGELOG read here
+         returns the pre-upgrade version and would stamp the wrong
+         ``current_version`` until the next dashboard self-heal (up to
+         30 min) or the next CLI invocation. The stale-probe regression
+         that pushed CHANGELOG ahead of ``latest_version`` (1.6.0-after-
+         installing-1.6.3) does not apply on the brew path: brew's
+         install probe ran inside the user's just-issued
+         ``cctally update``, so ``latest_version`` is current.
+      3. Freshly-installed CHANGELOG (``_release_read_latest_release_version``).
+         For npm the install overwrites ``CHANGELOG.md`` in place, so
+         this read inside the same Python process returns the just-
+         installed version. Skipped on brew for the reason above.
+      4. ``state.latest_version`` — last resort, also covers the npm
+         path when CHANGELOG is unreadable.
     """
     state = _load_update_state() or {"_schema": 1}
-    cur = installed_version or state.get("latest_version")
+    cur = installed_version
+    if cur is None and method is not None and method.method == "brew":
+        # Brew: prefer the cached probe (just observed by `cctally
+        # update`) over CHANGELOG, which reads from the OLD Cellar.
+        cur = state.get("latest_version")
+    if cur is None:
+        fresh = _release_read_latest_release_version()
+        if fresh:
+            cur = fresh[0]
+    if cur is None:
+        cur = state.get("latest_version")
     if cur:
         state["current_version"] = cur
         state["last_install_success_at_utc"] = _now_utc().isoformat()
         _save_update_state(state)
 
 
+def _self_heal_current_version() -> None:
+    """Reconcile ``update-state.json``'s ``current_version`` with the
+    running binary's CHANGELOG when they disagree.
+
+    Closes the documented gap (memory:
+    ``gotcha_update_state_cache_lies_after_version_bump``) where a user
+    upgrades via ``npm install -g cctally@latest`` (or any out-of-band
+    path that bypasses ``cctally update``) and ``current_version``
+    stays frozen on the pre-upgrade value until the next TTL probe
+    fires (24h default). The dashboard's brand-version label and the
+    CLI banner predicate both read ``current_version``, so users see
+    a stale "you're on <old>" indefinitely.
+
+    Best-effort: any failure — state missing/corrupt, CHANGELOG
+    unreadable, save fails — is silently swallowed. The caller is in
+    a post-command hook and must never break the parent command.
+
+    Why not bootstrap when state is missing: a ``None`` state means no
+    update probe has ever run, so we have no ``latest_version`` /
+    ``install`` block to seed alongside ``current_version``. Writing a
+    partial state would mask the missing-probe condition that
+    ``_check_safety_update_state`` and the doctor report rely on; the
+    next ``_do_update_check`` creates the file fully.
+    """
+    try:
+        fresh = _release_read_latest_release_version()
+        if fresh is None:
+            return
+        running = fresh[0]
+        state = _load_update_state()
+        if state is None:
+            return
+        if state.get("current_version") == running:
+            return
+        state["current_version"] = running
+        _save_update_state(state)
+    except Exception:
+        pass
+
+
 # === Update subcommand: version-check pipeline (spec §3) ====================
 # Per-vector parsers, TTL gate, and the chokepoint `_do_update_check` that
 # touches the throttle marker FIRST (crash safety) before attempting any
@@ -10791,7 +10859,7 @@ def _do_update_install(
                 if rc != 0:
                     return 1
             _log_update_event(log_fd, "INSTALL_SUCCESS")
-            _stamp_install_success_to_state(version)
+            _stamp_install_success_to_state(version, method)
             return 0
     finally:
         _release_update_lock(lock_fd)
@@ -10966,7 +11034,7 @@ class UpdateWorker:
                     self._emit(run_id, {"type": "done", "success": False})
                     return
             _log_update_event(log_fd, "INSTALL_SUCCESS")
-            _stamp_install_success_to_state(version)
+            _stamp_install_success_to_state(version, method)
             entrypoint, exec_argv = _resolve_execvp_target()
             self._emit(run_id, {"type": "execvp", "argv": exec_argv})
             try:
@@ -11049,6 +11117,26 @@ class _DashboardUpdateCheckThread(threading.Thread):
     def run(self) -> None:
         while not self._stop.is_set():
             try:
+                # Self-heal runs every tick (every 30 min by default),
+                # NOT gated by `_is_update_check_due`'s 24h TTL. Catches
+                # the case where the user upgrades the npm package
+                # out-of-band (no `cctally update` invocation) — the
+                # dashboard's brand-version label needs to reflect the
+                # new binary without waiting up to 24h for the next
+                # TTL probe. Re-publish the snapshot after a self-heal
+                # write so live SSE subscribers pick up the corrected
+                # `current_version` on their next envelope.
+                healed_before = _load_update_state()
+                _self_heal_current_version()
+                healed_after = _load_update_state()
+                if (
+                    healed_before != healed_after
+                    and self._hub is not None
+                    and self._ref is not None
+                ):
+                    snap = self._ref.get()
+                    if snap is not None:
+                        self._hub.publish(snap)
                 config = load_config()
                 if _is_update_check_due(config):
                     _do_update_check()
@@ -15056,6 +15144,9 @@ _BANNER_SUPPRESSED_COMMANDS = frozenset({
     "tui",             # rich Live mode takes over the screen; banner would be clobbered
     "db",              # `db status` shows failure state in its own output;
                        # `db skip` / `db unskip` are mid-fix — banner would be redundant.
+    "doctor",          # consolidates migration + update banner state into its
+                       # own report; double-printing the banner would duplicate
+                       # findings doctor already surfaces structurally.
     # Note: `setup` carve-out handled separately (only suppressed w/o --status).
     # Note: `dashboard` carve-out handled separately (banner printed in cmd_dashboard).
 })
@@ -15113,6 +15204,58 @@ def _semver_gt(a: str, b: str) -> bool:
            _release_semver_sort_key(_release_parse_semver(b))
 
 
+def _compute_effective_update_available(
+    state: dict[str, Any] | None,
+    suppress: dict[str, Any] | None,
+    now_utc: "dt.datetime",
+) -> "tuple[bool, str | None]":
+    """Shared core of "is there a *real* pending update?"
+
+    Returns ``(available, reason)`` where ``reason`` is:
+      - ``"missing_state"`` — current/latest unknown (no probe yet)
+      - ``"no_newer"`` — latest is not strictly greater than current
+      - ``"skipped"`` — user has skipped the latest version
+      - ``"reminded"`` — user has deferred and the window is still active
+      - ``None`` — available (warn-worthy)
+
+    Single source of truth for both ``_should_show_update_banner`` and
+    ``cctally doctor``'s ``safety.update_available`` check. Keeping this
+    shared avoids the bug where doctor would advertise an update the
+    banner suppresses (see review finding "Respect skipped/reminded
+    updates"). Malformed ``remind_after`` fails open — matches the
+    banner's pre-extraction posture: better to show a real reminder
+    than to silently drop one because of a corrupt suppress file.
+    """
+    if state is None:
+        return False, "missing_state"
+    cur = state.get("current_version")
+    lat = state.get("latest_version")
+    if not cur or not lat:
+        return False, "missing_state"
+    try:
+        if not _semver_gt(lat, cur):
+            return False, "no_newer"
+    except ValueError:
+        return False, "no_newer"
+    sup = suppress or {}
+    if lat in sup.get("skipped_versions", []):
+        return False, "skipped"
+    remind = sup.get("remind_after")
+    if remind is not None:
+        try:
+            # Hide while the deferral is active AND the user-pinned version
+            # is still the latest. A newer drop overrides the deferral.
+            if not _semver_gt(lat, remind["version"]):
+                until = dt.datetime.fromisoformat(remind["until_utc"])
+                if now_utc < until:
+                    return False, "reminded"
+        except (KeyError, ValueError):
+            # Malformed remind_after: fail-open. Better to surface a
+            # real update than to silently drop it.
+            pass
+    return True, None
+
+
 def _should_show_update_banner(
     command: str | None,
     args: argparse.Namespace,
@@ -15130,6 +15273,10 @@ def _should_show_update_banner(
     subcommand inherits the suppression automatically. Adding a parallel
     list here would silently regress that invariant — the spec
     amendment for Codex finding #8 codifies this.
+
+    Semver + skipped + remind logic is delegated to
+    :func:`_compute_effective_update_available` so ``cctally doctor``
+    stays in lockstep with this predicate.
     """
     if command in _BANNER_SUPPRESSED_COMMANDS or command in _UPDATE_BANNER_EXTRA_SUPPRESSED:
         return False
@@ -15143,33 +15290,8 @@ def _should_show_update_banner(
         return False
     if not config.get("update", {}).get("check", {}).get("enabled", True):
         return False
-    if state is None:
-        return False
-    cur = state.get("current_version")
-    lat = state.get("latest_version")
-    if not cur or not lat:
-        return False
-    try:
-        if not _semver_gt(lat, cur):
-            return False
-    except ValueError:
-        return False
-    if lat in suppress.get("skipped_versions", []):
-        return False
-    remind = suppress.get("remind_after")
-    if remind is not None:
-        try:
-            # Hide while the deferral is active AND the user-pinned version
-            # is still the latest. A newer drop overrides the deferral.
-            if not _semver_gt(lat, remind["version"]):
-                until = dt.datetime.fromisoformat(remind["until_utc"])
-                if _now_utc() < until:
-                    return False
-        except (KeyError, ValueError):
-            # Malformed remind_after: fail-open (banner shows). Better
-            # than silently dropping a real update reminder.
-            pass
-    return True
+    available, _ = _compute_effective_update_available(state, suppress, _now_utc())
+    return available
 
 
 def _format_update_banner(state: dict[str, Any]) -> str:
@@ -24128,19 +24250,303 @@ def _setup_recent_log_stats(seconds: float = 24 * 3600) -> dict:
     return counts
 
 
-def _setup_status(args: argparse.Namespace) -> int:
+def doctor_gather_state(
+    *,
+    now_utc: "dt.datetime | None" = None,
+    runtime_bind: "str | None" = None,
+):
+    """I/O chokepoint for `cctally doctor` (spec §7.2).
+
+    H1 invariant: config.json is read RAW (NOT via load_config), since
+    load_config auto-creates the file on first run — a read-only
+    diagnostic command must never mutate user state.
+    """
+    import _lib_doctor
+
+    if now_utc is None:
+        now_utc = _now_utc()
+
+    # ── Install ──────────────────────────────────────────────────────
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
-    sym_state = []
+    try:
+        symlink_state = _setup_compute_symlink_state(repo_root, dst_dir)
+    except Exception:
+        symlink_state = None
+    try:
+        path_includes = _setup_path_includes_local_bin()
+    except Exception:
+        path_includes = None
+    try:
+        legacy_snippet = _setup_detect_legacy_snippet()
+    except Exception:
+        legacy_snippet = None
+
+    # ── Hooks ────────────────────────────────────────────────────────
+    try:
+        settings = _load_claude_settings()
+    except SetupError:
+        settings = None
+    # Below: fail-soft posture for the diagnostic — any unexpected error
+    # in a sub-probe degrades that field to None rather than aborting the
+    # whole report.
+    try:
+        hook_counts = _setup_count_hook_entries(settings or {})
+    except Exception:
+        hook_counts = None
+    try:
+        legacy_bespoke = _setup_detect_legacy_bespoke_hooks(settings or {})
+    except Exception:
+        legacy_bespoke = None
+    try:
+        activity = _setup_recent_log_stats()
+    except Exception:
+        activity = None
+
+    # ── Auth ─────────────────────────────────────────────────────────
+    try:
+        oauth_token_present = _setup_oauth_token_present()
+    except OSError:
+        oauth_token_present = None
+
+    # ── DB ───────────────────────────────────────────────────────────
+    try:
+        stats_db_status = _db_status_for(DB_PATH, _STATS_MIGRATIONS, "stats.db")
+        if not DB_PATH.exists():
+            stats_db_status["_file_exists"] = False
+    except sqlite3.Error as exc:
+        stats_db_status = {"path": str(DB_PATH), "user_version": 0,
+                           "registry_size": len(_STATS_MIGRATIONS),
+                           "migrations": [], "_open_error": str(exc)}
+    try:
+        cache_db_status = _db_status_for(CACHE_DB_PATH, _CACHE_MIGRATIONS, "cache.db")
+        if not CACHE_DB_PATH.exists():
+            cache_db_status["_file_exists"] = False
+    except sqlite3.Error as exc:
+        cache_db_status = {"path": str(CACHE_DB_PATH), "user_version": 0,
+                           "registry_size": len(_CACHE_MIGRATIONS),
+                           "migrations": [], "_open_error": str(exc)}
+
+    # ── Data freshness ───────────────────────────────────────────────
+    latest_snapshot_at = None
+    try:
+        if DB_PATH.exists():
+            conn = sqlite3.connect(str(DB_PATH))
+            try:
+                row = conn.execute(
+                    "SELECT MAX(captured_at_utc) FROM weekly_usage_snapshots"
+                ).fetchone()
+                if row and row[0]:
+                    latest_snapshot_at = parse_iso_datetime(
+                        row[0], "weekly_usage_snapshots.captured_at_utc",
+                    ).astimezone(dt.timezone.utc)
+            except sqlite3.OperationalError:
+                pass  # table missing — treat as no snapshots yet
+            finally:
+                conn.close()
+    except Exception:
+        pass
+
+    cache_entries_count = None
+    cache_last_entry_at = None
+    try:
+        if CACHE_DB_PATH.exists():
+            conn = sqlite3.connect(str(CACHE_DB_PATH))
+            try:
+                row = conn.execute(
+                    "SELECT COUNT(*), MAX(timestamp_utc) FROM session_entries"
+                ).fetchone()
+                if row:
+                    cache_entries_count = int(row[0]) if row[0] is not None else 0
+                    if row[1]:
+                        cache_last_entry_at = parse_iso_datetime(
+                            row[1], "session_entries.timestamp_utc",
+                        ).astimezone(dt.timezone.utc)
+            except sqlite3.OperationalError:
+                pass  # table missing — treat as zero
+            finally:
+                conn.close()
+    except Exception:
+        pass
+
+    claude_jsonl_present = False
+    try:
+        claude_dir = pathlib.Path.home() / ".claude" / "projects"
+        if claude_dir.exists():
+            claude_jsonl_present = next(claude_dir.glob("**/*.jsonl"), None) is not None
+    except Exception:
+        pass
+
+    codex_entries_count = None
+    codex_last_entry_at = None
+    try:
+        if CACHE_DB_PATH.exists():
+            conn = sqlite3.connect(str(CACHE_DB_PATH))
+            try:
+                row = conn.execute(
+                    "SELECT COUNT(*), MAX(timestamp_utc) FROM codex_session_entries"
+                ).fetchone()
+                if row:
+                    codex_entries_count = int(row[0]) if row[0] is not None else 0
+                    if row[1]:
+                        codex_last_entry_at = parse_iso_datetime(
+                            row[1], "codex_session_entries.timestamp_utc",
+                        ).astimezone(dt.timezone.utc)
+            except sqlite3.OperationalError:
+                pass
+            finally:
+                conn.close()
+    except Exception:
+        pass
+
+    codex_jsonl_present = False
+    try:
+        codex_dir = pathlib.Path.home() / ".codex" / "sessions"
+        if codex_dir.exists():
+            codex_jsonl_present = next(codex_dir.glob("**/*.jsonl"), None) is not None
+    except Exception:
+        pass
+
+    # ── Safety ───────────────────────────────────────────────────────
+    # `dashboard.bind` is read via the same chokepoint that powers
+    # `cctally config get dashboard.bind` — `_config_known_value`
+    # normalizes hand-edited junk back to "loopback", matching the
+    # value cmd_dashboard would actually bind to.
+    #
+    # Raw JSON read (NOT load_config or _load_config_unlocked): both
+    # call `ensure_dirs()`, which creates `~/.local/share/cctally/`
+    # and `logs/` on a fresh HOME. Doctor is a read-only diagnostic
+    # (H1 invariant) — it must never mutate user state, even by
+    # creating an empty directory tree. Corrupt JSON yields
+    # `dashboard_bind_stored = "loopback"` (the same fallback the
+    # original try/except gave); the dedicated `config_json_valid`
+    # check surfaces the corruption separately.
+    dashboard_bind_stored = "loopback"
+    try:
+        if CONFIG_PATH.exists():
+            raw_cfg = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+            if isinstance(raw_cfg, dict):
+                dashboard_bind_stored = (
+                    _config_known_value(raw_cfg, "dashboard.bind") or "loopback"
+                )
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    # config.json — RAW READ, never load_config(). load_config()
+    # auto-creates on first run AND silently falls back to defaults
+    # on corruption — both behaviors would hide diagnostic state
+    # (codex H1).
+    config_json_error = None
+    try:
+        if CONFIG_PATH.exists():
+            json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        config_json_error = f"{type(exc).__name__}: {exc}"
+    except OSError as exc:
+        config_json_error = f"OSError: {exc}"
+
+    update_state = None
+    update_state_error = None
+    try:
+        update_state = _load_update_state()
+    except Exception as exc:
+        update_state_error = f"{type(exc).__name__}: {exc}"
+
+    update_suppress = None
+    update_suppress_error = None
+    try:
+        update_suppress = _load_update_suppress()
+    except Exception as exc:
+        update_suppress_error = f"{type(exc).__name__}: {exc}"
+
+    # Same predicate the update banner uses; doctor must not warn about
+    # updates the user has already skipped or deferred.
+    effective_update_available, effective_update_reason = (
+        _compute_effective_update_available(update_state, update_suppress, now_utc)
+    )
+
+    # ── Meta ─────────────────────────────────────────────────────────
+    cctally_version_tuple = _release_read_latest_release_version()
+    cctally_version = (
+        cctally_version_tuple[0] if cctally_version_tuple else "unknown"
+    )
+
+    return _lib_doctor.DoctorState(
+        symlink_state=symlink_state,
+        path_includes_local_bin=path_includes,
+        legacy_snippet=legacy_snippet,
+        legacy_bespoke=legacy_bespoke,
+        claude_settings=settings,
+        hook_counts=hook_counts,
+        log_activity_24h=activity,
+        oauth_token_present=oauth_token_present,
+        stats_db_status=stats_db_status,
+        cache_db_status=cache_db_status,
+        latest_snapshot_at=latest_snapshot_at,
+        cache_entries_count=cache_entries_count,
+        cache_last_entry_at=cache_last_entry_at,
+        claude_jsonl_present=claude_jsonl_present,
+        codex_entries_count=codex_entries_count,
+        codex_last_entry_at=codex_last_entry_at,
+        codex_jsonl_present=codex_jsonl_present,
+        dashboard_bind_stored=dashboard_bind_stored,
+        runtime_bind=runtime_bind,
+        config_json_error=config_json_error,
+        update_state=update_state,
+        update_state_error=update_state_error,
+        update_suppress=update_suppress,
+        update_suppress_error=update_suppress_error,
+        effective_update_available=effective_update_available,
+        effective_update_reason=effective_update_reason,
+        now_utc=now_utc,
+        cctally_version=cctally_version,
+    )
+
+
+def _setup_compute_symlink_state(
+    repo_root: pathlib.Path, dst_dir: pathlib.Path,
+) -> "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`.
+    """
+    del repo_root  # unused; see docstring
+    out: list[tuple[str, str]] = []
     for name in SETUP_SYMLINK_NAMES:
         dst = dst_dir / name
-        src = _setup_resolve_symlink_source(repo_root, name)
-        if dst.is_symlink() and pathlib.Path(os.readlink(dst)) == src:
-            sym_state.append((name, "ok"))
+        if dst.is_symlink():
+            try:
+                dst.resolve(strict=True)
+                out.append((name, "ok"))
+            except (FileNotFoundError, OSError):
+                out.append((name, "wrong"))
         elif dst.exists():
-            sym_state.append((name, "wrong"))
+            out.append((name, "wrong"))
         else:
-            sym_state.append((name, "missing"))
+            out.append((name, "missing"))
+    return out
+
+
+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")
     on_path = _setup_path_includes_local_bin()
     try:
@@ -25255,6 +25661,39 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
     return 3
 
 
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Run all doctor checks and emit the report. Spec §4, §7.3.
+
+    Calls the I/O chokepoint (doctor_gather_state) → pure kernel
+    (_lib_doctor.run_checks) → renderer (render_text or
+    serialize_json). The argparse `add_mutually_exclusive_group`
+    handles the --quiet/--verbose collision at parse time; the
+    defense-in-depth check here covers programmatic invocation that
+    bypasses argparse.
+
+    Exit code follows the loose mapping in spec §4.5: 0 unless
+    overall_severity == "fail", then 2. Note that warn → 0; doctor
+    is read-only and warn-class findings are advisories, not errors.
+    """
+    import _lib_doctor
+    quiet = bool(getattr(args, "quiet", False))
+    verbose = bool(getattr(args, "verbose", False))
+    if quiet and verbose:
+        eprint("doctor: --quiet and --verbose are mutually exclusive")
+        return 2
+    state = doctor_gather_state()
+    report = _lib_doctor.run_checks(state)
+    if getattr(args, "json", False):
+        print(json.dumps(
+            _lib_doctor.serialize_json(report), indent=2, sort_keys=True,
+        ))
+    else:
+        sys.stdout.write(_lib_doctor.render_text(
+            report, quiet=quiet, verbose=verbose,
+        ))
+    return 2 if report.overall_severity == "fail" else 0
+
+
 def cmd_setup(args: argparse.Namespace) -> int:
     # Migration flags are install-mode-only. Reject combinations with
     # --status or --uninstall (per spec Section 2 mode×flag matrix). The
@@ -27236,6 +27675,43 @@ def build_parser() -> argparse.ArgumentParser:
     )
     db_unskip.set_defaults(func=cmd_db_unskip)
 
+    # ─── doctor (Diagnostics) ───────────────────────────────────────────
+    doctor_p = sub.add_parser(
+        "doctor",
+        help="Diagnose data freshness and install state",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Run all read-only diagnostic checks and emit a report.
+
+            Categories: install, hooks, auth, db, data, safety. Each
+            category renders a severity (✓ ok / ⚠ warn / ✗ fail) and
+            actionable remediation guidance for non-OK rows.
+
+            Exit code: 0 unless any check is FAIL (then exit 2). WARN
+            rows do not change the exit code — doctor is a read-only
+            diagnostic and warn-class findings are advisories.
+
+            See docs/commands/doctor.md for the full check inventory
+            and JSON schema reference.
+            """
+        ),
+    )
+    doctor_p.add_argument(
+        "--json", action="store_true",
+        help="Emit machine-readable JSON to stdout (schema_version: 1)",
+    )
+    doctor_mutex = doctor_p.add_mutually_exclusive_group()
+    doctor_mutex.add_argument(
+        "--quiet", "-q", action="store_true",
+        help="Hide OK rows (human mode only)",
+    )
+    doctor_mutex.add_argument(
+        "--verbose", "-v", action="store_true",
+        help="Include each check's details block (human mode only)",
+    )
+    doctor_p.set_defaults(func=cmd_doctor)
+
     # ---- release (issue #24 release automation) ----
     p_release = sub.add_parser(
         "release",
@@ -29335,6 +29811,147 @@ def _share_top_projects_for_range(
     return [(path, cost) for path, cost in ranked[:_SHARE_TOP_PROJECTS_BUILDER_CAP]]
 
 
+def _share_all_projects_for_range(
+    range_start: "dt.datetime",
+    range_end: "dt.datetime",
+    *,
+    skip_sync: bool = True,
+) -> dict[str, float]:
+    """Like `_share_top_projects_for_range` but uncapped and unsorted.
+
+    Returns {project_path_or_'(unknown)': cost_usd} for every project
+    active in the range. Caller orders or caps as needed. Used by
+    `_share_per_block_per_project`'s fallback path so the fallback's
+    accuracy matches the canonical rollup-table path (spec §7.2.1,
+    issue #33).
+    """
+    bucket: dict[str, float] = {}
+    try:
+        entries = get_claude_session_entries(
+            range_start, range_end, skip_sync=skip_sync,
+        )
+    except Exception:
+        return bucket
+    for entry in entries:
+        usage = {
+            "input_tokens":                entry.input_tokens,
+            "output_tokens":               entry.output_tokens,
+            "cache_creation_input_tokens": entry.cache_creation_tokens,
+            "cache_read_input_tokens":     entry.cache_read_tokens,
+        }
+        cost = _calculate_entry_cost(
+            entry.model, usage, mode="auto", cost_usd=entry.cost_usd,
+        )
+        key = entry.project_path or "(unknown)"
+        bucket[key] = bucket.get(key, 0.0) + cost
+    return bucket
+
+
+def _share_per_day_per_project_for_range(
+    range_start: "dt.datetime",
+    range_end: "dt.datetime",
+    *,
+    display_tz: str,
+    skip_sync: bool = True,
+) -> dict[str, dict[str, float]]:
+    """Aggregate session_entries in [range_start, range_end] by
+    (day-in-display_tz, project_path).
+
+    Returns {date_str: {project_path_or_'(unknown)': cost_usd}}. Same
+    cache-first/lock-contention/direct-JSONL fallback chain as
+    `_share_top_projects_for_range`. Day bucket computed in display_tz
+    so the rendered row label matches. Issue #33.
+    """
+    try:
+        tz = ZoneInfo(display_tz) if display_tz else dt.timezone.utc
+    except Exception:
+        tz = dt.timezone.utc
+    out: dict[str, dict[str, float]] = {}
+    try:
+        entries = get_claude_session_entries(
+            range_start, range_end, skip_sync=skip_sync,
+        )
+    except Exception:
+        return out
+    for entry in entries:
+        usage = {
+            "input_tokens":                entry.input_tokens,
+            "output_tokens":               entry.output_tokens,
+            "cache_creation_input_tokens": entry.cache_creation_tokens,
+            "cache_read_input_tokens":     entry.cache_read_tokens,
+        }
+        cost = _calculate_entry_cost(
+            entry.model, usage, mode="auto", cost_usd=entry.cost_usd,
+        )
+        day = entry.timestamp.astimezone(tz).strftime("%Y-%m-%d")
+        proj = entry.project_path or "(unknown)"
+        out.setdefault(day, {})
+        out[day][proj] = out[day].get(proj, 0.0) + cost
+    return out
+
+
+def _share_per_block_per_project(
+    recent_blocks: list[dict],
+) -> dict[str, dict[str, float]]:
+    """Aggregate per-block per-project costs from `five_hour_block_projects`.
+
+    Returns {block_start_at_iso: {project_path_or_'(unknown)': cost_usd}}.
+    Block.start_at → five_hour_window_key via `_canonical_5h_window_key`
+    (10-min floor; same chokepoint as `maybe_update_five_hour_block`,
+    per CLAUDE.md "5-hour windows" gotcha — never derive a third key shape).
+
+    Fallback (rollup empty/unreadable): per-block sweep over
+    `_share_all_projects_for_range` — uncapped, accuracy parity with the
+    canonical path. Fires only during the first tick after fresh install
+    or before stats-migration `002_five_hour_block_projects_backfill_v1`
+    completes. Issue #33.
+    """
+    if not recent_blocks:
+        return {}
+    out: dict[str, dict[str, float]] = {}
+    keys: list[int] = []
+    iso_by_key: dict[int, str] = {}
+    for b in recent_blocks:
+        try:
+            ts = parse_iso_datetime(b["start_at"], "share.block.start_at")
+        except (ValueError, KeyError):
+            continue
+        wk = _canonical_5h_window_key(int(ts.timestamp()))
+        keys.append(wk)
+        iso_by_key[wk] = b["start_at"]
+    if not keys:
+        return out
+    try:
+        conn = open_db()
+        placeholders = ",".join("?" for _ in keys)
+        rows = conn.execute(
+            f"SELECT five_hour_window_key, project_path, cost_usd "
+            f"FROM five_hour_block_projects "
+            f"WHERE five_hour_window_key IN ({placeholders})",
+            keys,
+        ).fetchall()
+        for wk, project_path, cost in rows:
+            block_iso = iso_by_key.get(wk)
+            if block_iso is None:
+                continue
+            proj = project_path or "(unknown)"
+            out.setdefault(block_iso, {})
+            out[block_iso][proj] = out[block_iso].get(proj, 0.0) + float(cost)
+        if out:
+            return out
+    except (sqlite3.DatabaseError, OSError):
+        pass
+    # Fallback: per-block uncapped session_entries sweep.
+    for b in recent_blocks:
+        try:
+            ts = parse_iso_datetime(b["start_at"], "share.block.start_at")
+        except (ValueError, KeyError):
+            continue
+        end = ts + dt.timedelta(hours=5)
+        out[b["start_at"]] = _share_all_projects_for_range(ts, end)
+    return out
+
+
 def _build_share_panel_data(panel: str, options: dict,
                             snap: "DataSnapshot | None") -> dict:
     """Dispatch to the per-panel builder; reuses the dashboard DataSnapshot.
@@ -29414,12 +30031,19 @@ def _build_weekly_share_panel_data(options: dict,
             ws_dt = we_dt = None
         if ws_dt is not None and we_dt is not None:
             top_projects = _share_top_projects_for_range(ws_dt, we_dt)
+        # Per-week × per-model breakdown (issue #33 cross-tab Detail).
+        models_list = getattr(r, "models", None) or []
+        models = {
+            (m.get("model") or "(unknown)"): float(m.get("cost_usd", 0.0) or 0.0)
+            for m in models_list
+        }
         weeks.append({
             "start_date":     start_date,
             "cost_usd":       cost,
             "pct_used":       used_pct,
             "dollar_per_pct": dpp,
             "top_projects":   top_projects,
+            "models":         models,
         })
     if not weeks:
         weeks = [_share_empty_week_stub()]
@@ -29556,6 +30180,16 @@ def _build_daily_share_panel_data(options: dict,
             "pct_of_period": cost / total,
             "top_model":     top_model,
         })
+    # `days[*].date` is bucketed in display_tz by `_dashboard_build_daily_panel`,
+    # so the query window must use display-tz midnights too — otherwise entries
+    # near midnight (up to ±UTC-offset hours) get queried under the wrong UTC
+    # day and either spill into Other or vanish from cross-tab cells while
+    # still counted in the row total.
+    display_tz_name = options.get("display_tz", "Etc/UTC")
+    try:
+        _range_tz = ZoneInfo(display_tz_name) if display_tz_name else dt.timezone.utc
+    except Exception:
+        _range_tz = dt.timezone.utc
     # Daily top_projects: aggregate over the 7-day window. Derive the
     # range from the dates rendered above so the rollup covers exactly
     # what the panel shows (rather than re-deriving "7 days ago" from
@@ -29563,19 +30197,43 @@ def _build_daily_share_panel_data(options: dict,
     top_projects: list[tuple[str, float]] = []
     if days:
         try:
-            range_start = dt.datetime.fromisoformat(
-                f"{days[0]['date']}T00:00:00+00:00"
+            first_date = dt.date.fromisoformat(days[0]["date"])
+            last_date = dt.date.fromisoformat(days[-1]["date"])
+            range_start = dt.datetime(
+                first_date.year, first_date.month, first_date.day,
+                tzinfo=_range_tz,
             )
             # Include the last day in full — end-exclusive boundary at
-            # the start of the next UTC day.
-            last_date = dt.date.fromisoformat(days[-1]["date"])
+            # the start of the next display-tz day.
             range_end = dt.datetime(
                 last_date.year, last_date.month, last_date.day,
-                tzinfo=dt.timezone.utc,
+                tzinfo=_range_tz,
             ) + dt.timedelta(days=1)
             top_projects = _share_top_projects_for_range(range_start, range_end)
         except (ValueError, KeyError):
             top_projects = []
+    # Per-day × per-project breakdown (issue #33 cross-tab Detail).
+    per_day_per_project: dict[str, dict[str, float]] = {}
+    if days:
+        try:
+            first_date = dt.date.fromisoformat(days[0]["date"])
+            last_date = dt.date.fromisoformat(days[-1]["date"])
+            pdpp_range_start = dt.datetime(
+                first_date.year, first_date.month, first_date.day,
+                tzinfo=_range_tz,
+            )
+            pdpp_range_end = dt.datetime(
+                last_date.year, last_date.month, last_date.day,
+                tzinfo=_range_tz,
+            ) + dt.timedelta(days=1)
+            per_day_per_project = _share_per_day_per_project_for_range(
+                pdpp_range_start, pdpp_range_end,
+                display_tz=display_tz_name,
+            )
+        except (ValueError, KeyError):
+            per_day_per_project = {}
+    for d in days:
+        d["projects"] = per_day_per_project.get(d["date"], {})
     return {"days": days, "top_projects": top_projects}
 
 
@@ -29594,13 +30252,19 @@ def _build_monthly_share_panel_data(options: dict,
     rows = list(reversed(rows))
     months: list[dict] = []
     for r in rows:
-        models = getattr(r, "models", None) or []
-        top_model = (models[0].get("model") if models else None) or "—"
+        models_list = getattr(r, "models", None) or []
+        top_model = (models_list[0].get("model") if models_list else None) or "—"
+        # Per-month × per-model breakdown (issue #33 cross-tab Detail).
+        models = {
+            (m.get("model") or "(unknown)"): float(m.get("cost_usd", 0.0) or 0.0)
+            for m in models_list
+        }
         months.append({
             "month":     getattr(r, "label", "") or "",  # "YYYY-MM"
             "cost_usd":  float(getattr(r, "cost_usd", 0.0) or 0.0),
             "pct_used":  0.0,
             "top_model": top_model,
+            "models":    models,
         })
     # Monthly top_projects: aggregate across the entire 12-month window.
     # Range = [first day of oldest month, last day of newest month + 1].
@@ -29755,6 +30419,10 @@ def _build_blocks_share_panel_data(options: dict,
             top_projects = _share_top_projects_for_range(range_start, range_end)
         except (ValueError, KeyError):
             top_projects = []
+    # Per-block × per-project breakdown (issue #33 cross-tab Detail).
+    per_block_per_project = _share_per_block_per_project(recent)
+    for r in recent:
+        r["projects"] = per_block_per_project.get(r["start_at"], {})
     return {
         "current_block": cb,
         "recent_blocks": recent,
@@ -32471,7 +33139,8 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                          now_utc: "dt.datetime",
                          monotonic_now: "float | None" = None,
                          oauth_usage_cfg: "dict | None" = None,
-                         display_tz_pref_override: "str | None" = None) -> dict:
+                         display_tz_pref_override: "str | None" = None,
+                         runtime_bind: "str | None" = None) -> dict:
     """Serialize a DataSnapshot into the JSON envelope consumed by the
     browser (design spec §2.2).
 
@@ -32803,6 +33472,32 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "suppress": _update_suppress_envelope,
     }
 
+    # Doctor aggregate block (spec §5.5). Only the small severity tree
+    # rides on every SSE tick (~120 bytes); the full per-check payload
+    # is fetched lazily via `GET /api/doctor`. `runtime_bind` is the
+    # actual host the dashboard process is bound to (Codex H4) so
+    # `safety.dashboard_bind` reflects the running state, not just
+    # `config.json`. Defensive: never crash the snapshot pipeline on
+    # a doctor failure — surface a synthetic FAIL block with `_error`.
+    try:
+        import _lib_doctor as _ld
+        _doc_state = doctor_gather_state(now_utc=now_utc, runtime_bind=runtime_bind)
+        _doc_report = _ld.run_checks(_doc_state)
+        doctor_envelope: "dict" = {
+            "severity":     _doc_report.overall_severity,
+            "counts":       dict(_doc_report.counts),
+            "generated_at": _ld._iso_z(_doc_report.generated_at),
+            "fingerprint":  _ld.fingerprint(_doc_report),
+        }
+    except Exception as exc:  # noqa: BLE001 — never crash SSE on doctor failure
+        doctor_envelope = {
+            "severity":     "fail",
+            "counts":       {"ok": 0, "warn": 0, "fail": 1},
+            "generated_at": _iso_z(now_utc),
+            "fingerprint":  "sha1:" + ("0" * 40),
+            "_error":       f"{type(exc).__name__}: {exc}",
+        }
+
     return {
         "envelope_version": 2,
         "generated_at":     _iso_z(snap.generated_at),
@@ -32939,6 +33634,10 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # dashboard client's existing coerceUpdateState/Suppress logic
         # consumes both surfaces uniformly.
         "update":           update_envelope,
+
+        # Doctor aggregate-only block (spec §5.5). Full per-check
+        # report fetched lazily via GET /api/doctor.
+        "doctor":           doctor_envelope,
     }
 
 
@@ -33000,6 +33699,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         GET /api/events             → SSE stream                (Task 5)
         GET /api/session/:id        → per-session detail JSON   (v2)
         GET /api/block/:start_at    → per-block detail JSON     (v3)
+        GET /api/doctor             → full doctor report JSON   (spec §5.6)
         POST /api/sync              → trigger a sync tick       (v2)
     Anything else → 404.
 
@@ -33025,6 +33725,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     # routes through `_apply_display_tz_override` so the override wins
     # over `config.display.tz`. Set by cmd_dashboard before serve_forever.
     display_tz_pref_override: "str | None" = None
+    # Doctor (spec §5.5, §7.4): the host the dashboard process is
+    # ACTUALLY bound to (`args.host`). Threaded into `doctor_gather_state`
+    # so `safety.dashboard_bind` reflects the running state — the CLI
+    # path leaves this None and only sees the `config.json` view, which
+    # is the Codex H4 finding. Set by cmd_dashboard before serve_forever.
+    cctally_host: "str | None" = None
 
     # Silence the default per-request access log — noisy in the parent
     # terminal, and we pipe it through our own logger in cmd_dashboard.
@@ -33093,6 +33799,8 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_share_presets_get()
         elif path == "/api/share/history":
             self._handle_share_history_get()
+        elif path == "/api/doctor":
+            self._handle_get_doctor()
         else:
             self.send_error(404, "not found")
 
@@ -33776,6 +34484,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "field": "options",
             })
             return
+        # Client `ShareOptions` (dashboard/web/src/share/types.ts) does
+        # not carry `display_tz`; server-side config is the source of
+        # truth. Inject before `_share_apply_period_override` so the
+        # daily panel rebuild and per-day cross-tab bucketing both see
+        # the user's display tz instead of falling back to UTC.
+        if "display_tz" not in options:
+            options["display_tz"] = get_display_tz_pref(load_config())
         if not isinstance(panel, str) or not panel:
             self._respond_json(400, {
                 "error": "missing or non-string panel",
@@ -33984,6 +34699,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         ls = _share_load_lib()
         snap_ref = type(self).snapshot_ref
         data_snap = snap_ref.get() if snap_ref is not None else None
+        # Resolve display_tz from config once (client `ShareOptions`
+        # does not carry it); applied to every section's options below
+        # so daily panel rebuilds and per-day cross-tab cells bucket in
+        # the user's display tz, not UTC.
+        composite_display_tz = get_display_tz_pref(load_config())
 
         composed_sections: list = []
         section_results: list[dict] = []
@@ -34037,6 +34757,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             composite_opts = {**sec_opts, "reveal_projects": reveal_projects,
                               "theme": theme, "format": fmt,
                               "no_branding": no_branding}
+            composite_opts.setdefault("display_tz", composite_display_tz)
             # Per-section period override — each basket item carries its
             # own period recipe, independent of the composite anon flag.
             sec_snap, period_err = _share_apply_period_override(
@@ -34473,10 +35194,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             cfg_oauth = dict(_OAUTH_USAGE_DEFAULTS)
         env = snapshot_to_envelope(
             snap,
-            now_utc=dt.datetime.now(dt.timezone.utc),
+            # `_now_utc()` honors CCTALLY_AS_OF for harness determinism;
+            # zero production impact (the env var is never set outside
+            # fixture tests). Without this, the doctor block's now_utc
+            # flows from wall clock and severity flips on borderline-age
+            # checks between parallel test runs, churning goldens.
+            now_utc=_now_utc(),
             monotonic_now=time.monotonic(),
             oauth_usage_cfg=cfg_oauth,
             display_tz_pref_override=type(self).display_tz_pref_override,
+            runtime_bind=type(self).cctally_host,
         )
         body = json.dumps(env, ensure_ascii=False).encode("utf-8")
         self.send_response(200)
@@ -34486,6 +35213,40 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
+    def _handle_get_doctor(self) -> None:
+        """`GET /api/doctor` — full kernel-serialized doctor report (spec §5.6).
+
+        Lazy companion to the aggregate-only `doctor` block on the SSE
+        envelope. Re-runs the gather + checks fresh on every call (cheap;
+        no per-tick cache needed — the kernel's identity-slice fingerprint
+        carries the dedup story for the SSE channel, not this endpoint).
+        Passes `runtime_bind = cctally_host` so `safety.dashboard_bind`
+        sees the bind the dashboard is ACTUALLY serving (Codex H4 — CLI
+        path stays config-only).
+
+        GET endpoints are read-only and loopback-protected by the
+        dashboard's default bind; no CSRF gating here (mirrors
+        `/api/data`, `/api/session/:id`, `/api/block/:start_at`).
+        """
+        try:
+            import _lib_doctor as _ld
+            state = doctor_gather_state(
+                runtime_bind=type(self).cctally_host,
+            )
+            report = _ld.run_checks(state)
+            body = json.dumps(
+                _ld.serialize_json(report), ensure_ascii=False,
+            ).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-cache")
+            self.end_headers()
+            self.wfile.write(body)
+        except Exception as exc:  # noqa: BLE001
+            self.log_error("/api/doctor failed: %r", exc)
+            self._respond_json(500, {"error": f"{type(exc).__name__}: {exc}"})
+
     def _handle_get_session_detail(self, path: str) -> None:
         """Return TuiSessionDetail JSON for the given session id (spec §3.2).
 
@@ -34666,6 +35427,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     monotonic_now=time.monotonic(),
                     oauth_usage_cfg=cfg_oauth,
                     display_tz_pref_override=type(self).display_tz_pref_override,
+                    runtime_bind=type(self).cctally_host,
                 )
                 msg = (
                     "event: update\n"
@@ -36834,6 +37596,10 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     DashboardHTTPHandler.sync_lock = sync_lock
     DashboardHTTPHandler.no_sync = bool(args.no_sync)
     DashboardHTTPHandler.display_tz_pref_override = display_tz_pref_override
+    # Doctor (spec §7.4 / Codex H4): runtime bind, so safety.dashboard_bind
+    # in the doctor SSE block + /api/doctor reflects the actual --host
+    # the process is serving, not just the config-only view the CLI sees.
+    DashboardHTTPHandler.cctally_host = args.host
     DashboardHTTPHandler.run_sync_now = staticmethod(
         lambda: _run_sync_now(skip_sync=args.no_sync)
     )
@@ -37391,9 +38157,26 @@ def _post_command_update_hooks(command: str | None, args) -> None:
     ``ensure_dirs()`` first-run path, leaving a stub config.json behind
     and breaking the post-purge "data dir gone" invariant. Skip the
     hook entirely for that command — the banner is moot post-uninstall
-    anyway."""
+    anyway.
+
+    Skip-for-doctor: ``doctor`` is a read-only diagnostic by contract.
+    ``load_config()`` would call ``ensure_dirs()`` and write a stub
+    ``config.json`` on a fresh HOME; ``_spawn_background_update_check``
+    would write ``update-state.json`` and ``update.log``. Adding doctor
+    to ``_BANNER_SUPPRESSED_COMMANDS`` only silences the banner — it
+    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``."""
     if command == "setup" and getattr(args, "uninstall", False):
         return
+    if command == "doctor":
+        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
+    # bumped version is visible to the banner predicate immediately.
+    _self_heal_current_version()
     config = load_config()
     state = _load_update_state()
     suppress = _load_update_suppress()