cctally 1.10.3 → 1.11.1

package/bin/_cctally_db.py

@@ -34,15 +34,22 @@ Holds:
   ``_db_path_for_label``).
 
 What stays in bin/cctally (reached via the ``_cctally()`` accessor):
-- Path constants ``STATS_DB_PATH``, ``CACHE_DB_PATH``,
-  ``MIGRATION_ERROR_LOG_PATH``, ``LOG_DIR`` (spec §86–92 — every
-  path constant stays so monkeypatched HOME redirects propagate).
 - ``open_db`` / ``open_cache_db`` — DB-open primitives that CALL
   the dispatcher; they're the boundary owners, not internal to the
   migration system.
-- ``now_utc_iso``, ``parse_iso_datetime``, ``_compute_block_totals``,
-  ``eprint``, ``format_local_iso`` — tiny helpers / hot-path entry
-  points consumed by migration handlers + cmd_db_status renderers.
+- ``_compute_block_totals`` — Z-high callable consumed by migration
+  handlers; reached via the back-ref shim at the top of this module.
+
+Path constants reached via ``_cctally_core.X`` at call time:
+``DB_PATH`` / ``CACHE_DB_PATH`` / ``LOG_DIR`` /
+``MIGRATION_ERROR_LOG_PATH``. After the data-globals promotion
+(2026-05-22, issue #84) ``_cctally_core`` is the single source of
+truth and the only legal monkeypatch target; tests redirecting
+``HOME`` via ``redirect_paths`` propagate without a sibling-side
+seed block in ``bin/cctally``.
+
+Kernel helpers (``now_utc_iso``, ``parse_iso_datetime``, ``eprint``)
+are direct-imported from ``_cctally_core`` per spec §3.3.
 
 §5.6 audit: zero monkeypatch sites on any moved symbol — the
 extraction is pure-mechanical. No Option C call-site rewrites
@@ -75,6 +82,7 @@ def _cctally():
 # Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
 # import from _cctally_core. The legacy shim functions for these names
 # are deleted.
+import _cctally_core
 from _cctally_core import (
     eprint,
     now_utc_iso,
@@ -89,10 +97,12 @@ from _cctally_core import (
 # _cctally_cache via get_claude_session_entries) and is explicitly listed
 # in spec §3.7's stays-on-shim allowlist.
 #
-# Path constants and rarer helpers (`MIGRATION_ERROR_LOG_PATH`,
-# `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`, `format_local_iso`) are
-# accessed via the standard `c = _cctally()` + `c.X` pattern instead
-# (call-time lookup so fixture-HOME redirects propagate).
+# Path constants (`MIGRATION_ERROR_LOG_PATH`, `LOG_DIR`, `DB_PATH`,
+# `CACHE_DB_PATH`) are accessed via `_cctally_core.X` at call time —
+# the canonical sibling pattern after the data-globals promotion
+# (2026-05-22, issue #84). `_cctally_core` is the single source of
+# truth and the only legal monkeypatch target; bin/cctally no longer
+# seeds duplicates into this module's namespace.
 def _compute_block_totals(*args, **kwargs):
     return sys.modules["cctally"]._compute_block_totals(*args, **kwargs)
 
@@ -101,9 +111,11 @@ def _compute_block_totals(*args, **kwargs):
 # Regions below are inserted verbatim from bin/cctally. Bare-name
 # references to `now_utc_iso(...)`, `parse_iso_datetime(...)`,
 # `_compute_block_totals(...)`, and `eprint(...)` resolve to the shims
-# above. Path-constant references (`MIGRATION_ERROR_LOG_PATH`,
-# `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`) get rewritten to `c.X` form
-# with a top-of-function `c = _cctally()` binding inserted.
+# / direct imports above. Path-constant references
+# (`MIGRATION_ERROR_LOG_PATH`, `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`)
+# are read as `_cctally_core.X` at call time (post-#84 canonical
+# sibling pattern; no `c = _cctally()` binding required for path
+# reads, since `_cctally_core` is direct-imported above).
 
 # === Region 1: add_column_if_missing (was bin/cctally:8584-8621) ===
 
@@ -697,12 +709,12 @@ def _log_migration_error(*, name: str, exc: BaseException, tb: str) -> None:
     # crash). Acceptable per "best effort" design — concurrent migration
     # failures are vanishingly rare since open_db() serializes via WAL.
     try:
-        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        _cctally_core.LOG_DIR.mkdir(parents=True, exist_ok=True)
         ts = now_utc_iso()
         one_line_err = str(exc).replace("\n", " ").strip() or exc.__class__.__name__
         indented_tb = "\n".join("  " + line for line in tb.rstrip().splitlines())
         block = f"[{ts}] {name}\n  {one_line_err}\n{indented_tb}\n\n"
-        with open(MIGRATION_ERROR_LOG_PATH, "a") as fh:
+        with open(_cctally_core.MIGRATION_ERROR_LOG_PATH, "a") as fh:
             fh.write(block)
     except Exception as log_exc:
         eprint(f"[migration-error-log] failed to write: {log_exc}")
@@ -723,9 +735,9 @@ def _clear_migration_error_log_entries(name: str) -> None:
     # extra banner cycle. Not worth fcntl.flock complexity for failure-rare
     # code path.
     try:
-        if not MIGRATION_ERROR_LOG_PATH.exists():
+        if not _cctally_core.MIGRATION_ERROR_LOG_PATH.exists():
             return
-        content = MIGRATION_ERROR_LOG_PATH.read_text()
+        content = _cctally_core.MIGRATION_ERROR_LOG_PATH.read_text()
         # Entries are separated by "\n\n". Each entry's first line is
         # "[ts] <name>".
         blocks = [b for b in content.split("\n\n") if b.strip()]
@@ -737,9 +749,9 @@ def _clear_migration_error_log_entries(name: str) -> None:
                 continue
             kept.append(block)
         if not kept:
-            MIGRATION_ERROR_LOG_PATH.unlink()
+            _cctally_core.MIGRATION_ERROR_LOG_PATH.unlink()
             return
-        MIGRATION_ERROR_LOG_PATH.write_text("\n\n".join(kept) + "\n\n")
+        _cctally_core.MIGRATION_ERROR_LOG_PATH.write_text("\n\n".join(kept) + "\n\n")
     except Exception as exc:
         eprint(
             f"[migration-error-log] failed to clear entries for {name}: {exc}"
@@ -753,10 +765,10 @@ def _render_migration_error_banner() -> str | None:
     Parses the most recent entry's first line for the migration name and
     timestamp. Falls back to a generic message on parse failure.
     """
-    if not MIGRATION_ERROR_LOG_PATH.exists():
+    if not _cctally_core.MIGRATION_ERROR_LOG_PATH.exists():
         return None
     try:
-        content = MIGRATION_ERROR_LOG_PATH.read_text()
+        content = _cctally_core.MIGRATION_ERROR_LOG_PATH.read_text()
     except Exception:
         return None
     if not content.strip():
@@ -774,13 +786,13 @@ def _render_migration_error_banner() -> str | None:
             if ts and name:
                 return (
                     f"⚠ cctally: migration `{name}` failed at {ts}. "
-                    f"See {MIGRATION_ERROR_LOG_PATH}"
+                    f"See {_cctally_core.MIGRATION_ERROR_LOG_PATH}"
                 )
         except Exception:
             pass
     return (
         f"⚠ cctally: migration error logged. "
-        f"See {MIGRATION_ERROR_LOG_PATH}"
+        f"See {_cctally_core.MIGRATION_ERROR_LOG_PATH}"
     )
 
 
@@ -1737,8 +1749,8 @@ def cmd_db_status(args: argparse.Namespace) -> int:
     payload = {
         "schema_version": 1,
         "databases": {
-            "stats.db": _db_status_for(DB_PATH, _STATS_MIGRATIONS, "stats.db"),
-            "cache.db": _db_status_for(CACHE_DB_PATH, _CACHE_MIGRATIONS, "cache.db"),
+            "stats.db": _db_status_for(_cctally_core.DB_PATH, _STATS_MIGRATIONS, "stats.db"),
+            "cache.db": _db_status_for(_cctally_core.CACHE_DB_PATH, _CACHE_MIGRATIONS, "cache.db"),
         },
     }
     if getattr(args, "json", False):
@@ -1828,7 +1840,7 @@ def _db_status_for(
                 "seq": m.seq, "name": m.name,
                 "status": "failed",
                 "last_failure_at": failed_names[m.name],
-                "log_path": str(MIGRATION_ERROR_LOG_PATH),
+                "log_path": str(_cctally_core.MIGRATION_ERROR_LOG_PATH),
             })
         else:
             migrations_out.append({
@@ -1852,11 +1864,11 @@ def _db_status_failed_names_from_log(db_label: str) -> dict[str, str]:
     `merge_5h_block_duplicates_v1` are bootstrap-renamed at next open
     (via Task 4) so they don't accumulate post-PR.
     """
-    if not MIGRATION_ERROR_LOG_PATH.exists():
+    if not _cctally_core.MIGRATION_ERROR_LOG_PATH.exists():
         return {}
     out: dict[str, str] = {}
     try:
-        content = MIGRATION_ERROR_LOG_PATH.read_text()
+        content = _cctally_core.MIGRATION_ERROR_LOG_PATH.read_text()
     except Exception:
         return {}
     blocks = [b for b in content.split("\n\n") if b.strip()]
@@ -1929,9 +1941,9 @@ def _db_resolve_migration_name(name_arg: str) -> tuple[str, str, list[Migration]
 
 def _db_path_for_label(db_label: str) -> pathlib.Path:
     if db_label == "stats.db":
-        return DB_PATH
+        return _cctally_core.DB_PATH
     if db_label == "cache.db":
-        return CACHE_DB_PATH
+        return _cctally_core.CACHE_DB_PATH
     raise ValueError(f"unknown db_label: {db_label}")
 
 

package/bin/_cctally_record.py

@@ -158,6 +158,7 @@ def _cctally():
 
 # === Honest imports from extracted homes ===================================
 # Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3.
+import _cctally_core
 from _cctally_core import (
     eprint,
     now_utc_iso,
@@ -312,18 +313,17 @@ _logged_window_key_coerce_failure = False
 
 
 # === BEGIN MOVED REGIONS ===
-# Path constants (APP_DIR, HOOK_TICK_*) are accessed via the
-# `c = _cctally()` call-time accessor inside each function that needs
-# them — so ``monkeypatch.setitem(ns, "APP_DIR", tmp)`` in tests
-# resolves on every read (no stale module-level binding).
+# Path constants (APP_DIR, HOOK_TICK_*) moved to _cctally_core
+# 2026-05-22 (#84). Reads use call-time ``_cctally_core.X``; tests
+# patch via ``monkeypatch.setattr(_cctally_core, "X", v)``.
 #
-# Constants pulled from cctally at call time:
+# Constants pulled at call time:
+#   _cctally_core.APP_DIR
+#   _cctally_core.HOOK_TICK_LOG_DIR / _PATH / _ROTATED_PATH / _ROTATE_BYTES
+#   _cctally_core.HOOK_TICK_THROTTLE_PATH / _LOCK_PATH
 #   c._FIVE_HOUR_JITTER_FLOOR_SECONDS — _lib_five_hour.* re-export
 #   c._RESET_PCT_DROP_THRESHOLD       — bin/cctally module-level constant
-#   c.HOOK_TICK_LOG_DIR / _PATH / _ROTATED_PATH / _ROTATE_BYTES
-#   c.HOOK_TICK_THROTTLE_PATH / _LOCK_PATH
 #   c.HOOK_TICK_DEFAULT_THROTTLE_SECONDS
-#   c.APP_DIR
 
 
 def _normalize_percent(value: "float | int | None") -> "float | None":
@@ -1521,7 +1521,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         # record-usage reader doesn't see the new HWM
                         # before the event row is durable.
                         try:
-                            (c.APP_DIR / "hwm-7d").write_text(
+                            (_cctally_core.APP_DIR / "hwm-7d").write_text(
                                 f"{week_start_date} {weekly_percent}\n"
                             )
                         except OSError:
@@ -1731,7 +1731,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                             # matches the canonical writer:
                             # ``<key> <percent>\n``.
                             try:
-                                (c.APP_DIR / "hwm-5h").write_text(
+                                (_cctally_core.APP_DIR / "hwm-5h").write_text(
                                     f"{int(five_hour_window_key)} "
                                     f"{float(five_hour_percent)}\n"
                                 )
@@ -2096,7 +2096,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     # Write high-water mark so the status line never displays a regression.
     # The file contains "week_start_date weekly_percent" on one line.
     try:
-        hwm_path = c.APP_DIR / "hwm-7d"
+        hwm_path = _cctally_core.APP_DIR / "hwm-7d"
         existing_hwm = 0.0
         try:
             parts = hwm_path.read_text().strip().split()
@@ -2119,7 +2119,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     ):
         try:
             five_resets_key = five_hour_window_key
-            hwm5_path = c.APP_DIR / "hwm-5h"
+            hwm5_path = _cctally_core.APP_DIR / "hwm-5h"
             existing_hwm5 = 0.0
             try:
                 parts5 = hwm5_path.read_text().strip().split()
@@ -2143,8 +2143,8 @@ def _hook_tick_log_line(line: str) -> None:
     """
     c = _cctally()
     try:
-        c.HOOK_TICK_LOG_DIR.mkdir(parents=True, exist_ok=True)
-        fd = os.open(c.HOOK_TICK_LOG_PATH, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+        _cctally_core.HOOK_TICK_LOG_DIR.mkdir(parents=True, exist_ok=True)
+        fd = os.open(_cctally_core.HOOK_TICK_LOG_PATH, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
         try:
             os.write(fd, (line.rstrip("\n") + "\n").encode("utf-8", errors="replace"))
         finally:
@@ -2157,7 +2157,7 @@ def _hook_tick_log_rotate_if_needed() -> None:
     """If hook-tick.log exceeds the size cap, atomic-rename to .1 (overwriting)."""
     c = _cctally()
     try:
-        size = c.HOOK_TICK_LOG_PATH.stat().st_size
+        size = _cctally_core.HOOK_TICK_LOG_PATH.stat().st_size
     except FileNotFoundError:
         return
     except OSError:
@@ -2165,7 +2165,7 @@ def _hook_tick_log_rotate_if_needed() -> None:
     if size <= c.HOOK_TICK_LOG_ROTATE_BYTES:
         return
     try:
-        os.replace(c.HOOK_TICK_LOG_PATH, c.HOOK_TICK_LOG_ROTATED_PATH)
+        os.replace(_cctally_core.HOOK_TICK_LOG_PATH, _cctally_core.HOOK_TICK_LOG_ROTATED_PATH)
     except OSError:
         pass
 
@@ -2174,7 +2174,7 @@ def _hook_tick_throttle_age_seconds() -> float:
     """Return seconds since last successful OAuth fetch; +inf if never."""
     c = _cctally()
     try:
-        mtime = c.HOOK_TICK_THROTTLE_PATH.stat().st_mtime
+        mtime = _cctally_core.HOOK_TICK_THROTTLE_PATH.stat().st_mtime
     except FileNotFoundError:
         return float("inf")
     except OSError:
@@ -2186,9 +2186,9 @@ def _hook_tick_throttle_touch() -> None:
     """Update mtime to now (creating the file if missing)."""
     c = _cctally()
     try:
-        c.APP_DIR.mkdir(parents=True, exist_ok=True)
-        c.HOOK_TICK_THROTTLE_PATH.touch(exist_ok=True)
-        os.utime(c.HOOK_TICK_THROTTLE_PATH, None)
+        _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
+        _cctally_core.HOOK_TICK_THROTTLE_PATH.touch(exist_ok=True)
+        os.utime(_cctally_core.HOOK_TICK_THROTTLE_PATH, None)
     except OSError:
         pass
 
@@ -2313,9 +2313,9 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
     # immediately after Step 7, so the leak is bounded.
     if not explain:
         try:
-            c.HOOK_TICK_LOG_DIR.mkdir(parents=True, exist_ok=True)
+            _cctally_core.HOOK_TICK_LOG_DIR.mkdir(parents=True, exist_ok=True)
             log_fd = os.open(
-                c.HOOK_TICK_LOG_PATH,
+                _cctally_core.HOOK_TICK_LOG_PATH,
                 os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644,
             )
             os.dup2(log_fd, 1)  # stdout
@@ -2368,10 +2368,10 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
 
         # Throttle check + OAuth (under flock)
         if not no_oauth:
-            c.APP_DIR.mkdir(parents=True, exist_ok=True)
+            _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
             try:
                 lock_fd = os.open(
-                    c.HOOK_TICK_THROTTLE_LOCK_PATH,
+                    _cctally_core.HOOK_TICK_THROTTLE_LOCK_PATH,
                     os.O_WRONLY | os.O_CREAT, 0o644,
                 )
             except OSError:
@@ -2437,7 +2437,7 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
     print("[1/4] Local sync (sync_cache)")
     print(f"      → ingested {max(0, ingested)} new entries")
     print("[2/4] Throttle check")
-    print(f"      → throttle file: {c.HOOK_TICK_THROTTLE_PATH}")
+    print(f"      → throttle file: {_cctally_core.HOOK_TICK_THROTTLE_PATH}")
     if pre_age == float("inf"):
         print("      → mtime: (file absent)")
     else:
@@ -2445,7 +2445,7 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
     print(f"      → threshold: {int(throttle_seconds)}s → {decision}")
     print("[3/4] OAuth refresh")
     print(f"      → status: {oauth_status}")
-    print(f"[4/4] Log written → {c.HOOK_TICK_LOG_PATH}")
+    print(f"[4/4] Log written → {_cctally_core.HOOK_TICK_LOG_PATH}")
     print(f"\nDone in {dur_ms} ms.")
     return rc
 

package/bin/_cctally_setup.py

@@ -64,11 +64,13 @@ def _cctally():
 
 
 # === Honest imports from extracted homes ===================================
-# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
-# import from _cctally_core. Path constants (`APP_DIR`,
-# `CLAUDE_SETTINGS_PATH`, `HOOK_TICK_LOG_PATH`) plus the extensive
-# out-of-scope setup-specific helpers (legacy migration, hook surgery,
-# OAuth token, sync_cache, …) stay on the _cctally() accessor.
+# Spec 2026-05-17 §3.3: kernel symbols import from _cctally_core. Path
+# constants (APP_DIR, CLAUDE_SETTINGS_PATH, HOOK_TICK_LOG_PATH, etc.)
+# moved to _cctally_core 2026-05-22 (#84) and are accessed via call-time
+# ``_cctally_core.X``. The setup-specific helpers (legacy migration, hook
+# surgery, OAuth token, sync_cache, …) that live in bin/cctally itself
+# stay on the _cctally() accessor.
+import _cctally_core
 from _cctally_core import (
     eprint,
     _command_as_of,
@@ -863,7 +865,7 @@ def _setup_count_hook_entries(settings: dict) -> dict[str, int]:
 
 
 def _setup_data_dir_size_bytes() -> int:
-    app_dir = _cctally().APP_DIR
+    app_dir = _cctally_core.APP_DIR
     total = 0
     if not app_dir.exists():
         return 0
@@ -891,7 +893,7 @@ def _setup_recent_log_stats(seconds: float = 24 * 3600) -> dict:
     counts = {"fires": 0, "by_event": {}, "oauth_ok": 0, "throttled": 0,
               "errors": 0, "last_fire_ago_s": None}
     last_ts = 0.0
-    for path in (c.HOOK_TICK_LOG_ROTATED_PATH, c.HOOK_TICK_LOG_PATH):
+    for path in (_cctally_core.HOOK_TICK_LOG_ROTATED_PATH, _cctally_core.HOOK_TICK_LOG_PATH):
         if not path.exists():
             continue
         try:
@@ -1041,7 +1043,7 @@ def _setup_status(args: argparse.Namespace) -> int:
                     "files": bespoke["files"],
                 },
             },
-            "data": {"path": str(c.APP_DIR), "size_bytes": data_bytes},
+            "data": {"path": str(_cctally_core.APP_DIR), "size_bytes": data_bytes},
         }
         print(json.dumps(envelope, indent=2))
         return 0
@@ -1057,7 +1059,7 @@ def _setup_status(args: argparse.Namespace) -> int:
         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})")
+    out.append(f"Hooks ({_cctally_core.CLAUDE_SETTINGS_PATH})")
     for ev in c.SETUP_HOOK_EVENTS:
         marker = "✓" if hook_counts[ev] >= 1 else "✗"
         word = "installed" if hook_counts[ev] >= 1 else "missing"
@@ -1093,7 +1095,7 @@ def _setup_status(args: argparse.Namespace) -> int:
         )
         out.append("                       run `cctally setup --migrate-legacy-hooks` to migrate")
     out.append("Data")
-    out.append(f"  {c.APP_DIR}/    {_setup_format_bytes(data_bytes)}")
+    out.append(f"  {_cctally_core.APP_DIR}/    {_setup_format_bytes(data_bytes)}")
     _setup_emit_text(out)
     return 0
 
@@ -1115,9 +1117,9 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
         try:
             c._write_claude_settings_atomic(settings)
         except OSError as exc:
-            eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
+            eprint(f"setup: failed to write {_cctally_core.CLAUDE_SETTINGS_PATH}: {exc}")
             return 2
-    out.append(f"Removed {removed} hook entries from {c.CLAUDE_SETTINGS_PATH}")
+    out.append(f"Removed {removed} hook entries from {_cctally_core.CLAUDE_SETTINGS_PATH}")
 
     repo_root = _setup_resolve_repo_root()
     dst_dir = _setup_local_bin_dir()
@@ -1201,7 +1203,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                     "hooks_removed": removed,
                     "symlinks_removed": sym_removed,
                     "purged": False,
-                    "data_path": str(c.APP_DIR),
+                    "data_path": str(_cctally_core.APP_DIR),
                     "data_size_bytes": data_bytes,
                     "legacy": {
                         "statusline_snippet_path": str(legacy[0]) if legacy else None,
@@ -1213,7 +1215,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                 try:
                     resp = input(
                         f"Wipe {_setup_format_bytes(data_bytes)} of usage history at "
-                        f"{c.APP_DIR}/? [y/N] "
+                        f"{_cctally_core.APP_DIR}/? [y/N] "
                     )
                 except EOFError:
                     resp = "n"
@@ -1221,10 +1223,10 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                     out.append("Purge declined.")
                     _setup_emit_text(out)
                     return 3
-        if c.APP_DIR.exists():
+        if _cctally_core.APP_DIR.exists():
             try:
-                shutil.rmtree(c.APP_DIR)
-                out.append(f"Wiped {c.APP_DIR}/")
+                shutil.rmtree(_cctally_core.APP_DIR)
+                out.append(f"Wiped {_cctally_core.APP_DIR}/")
             except OSError as exc:
                 if is_json:
                     print(json.dumps({
@@ -1233,7 +1235,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                         "result": "err",
                         "reason": "rmtree_failed",
                         "error": str(exc),
-                        "data_path": str(c.APP_DIR),
+                        "data_path": str(_cctally_core.APP_DIR),
                         "data_size_bytes": data_bytes,
                         "legacy": {
                             "statusline_snippet_path": str(legacy[0]) if legacy else None,
@@ -1241,11 +1243,11 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
                         "exit_code": 1,
                     }, indent=2))
                 else:
-                    eprint(f"setup: failed to wipe {c.APP_DIR}: {exc}")
+                    eprint(f"setup: failed to wipe {_cctally_core.APP_DIR}: {exc}")
                 return 1
     else:
         out.append(
-            f"Note: usage history kept at {c.APP_DIR}/ "
+            f"Note: usage history kept at {_cctally_core.APP_DIR}/ "
             f"({_setup_format_bytes(data_bytes)}). Use --purge to remove."
         )
     if is_json:
@@ -1256,7 +1258,7 @@ def _setup_uninstall(args: argparse.Namespace) -> int:
             "hooks_removed": removed,
             "symlinks_removed": sym_removed,
             "purged": purge,
-            "data_path": str(c.APP_DIR),
+            "data_path": str(_cctally_core.APP_DIR),
             "data_size_bytes": data_bytes,
             "legacy": {
                 "statusline_snippet_path": str(legacy[0]) if legacy else None,
@@ -1305,7 +1307,7 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
         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 {c.CLAUDE_SETTINGS_PATH}:")
+    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))
     import shlex
     quoted = shlex.quote(abs_path)
@@ -1391,7 +1393,7 @@ def _setup_dry_run(args: argparse.Namespace) -> int:
                     }
                     for ev in c.SETUP_HOOK_EVENTS
                 ],
-                "settings_path": str(c.CLAUDE_SETTINGS_PATH),
+                "settings_path": str(_cctally_core.CLAUDE_SETTINGS_PATH),
             },
             # Sibling parity with `_setup_status` and `_setup_install`
             # JSON envelopes (`legacy.bespoke_hooks` shape). Lets the same
@@ -1614,7 +1616,7 @@ def _setup_install(args: argparse.Namespace) -> int:
     try:
         c._write_claude_settings_atomic(settings)
     except OSError as exc:
-        eprint(f"setup: failed to write {c.CLAUDE_SETTINGS_PATH}: {exc}")
+        eprint(f"setup: failed to write {_cctally_core.CLAUDE_SETTINGS_PATH}: {exc}")
         return 2
 
     # ── Post-write migration apply (spec §2 steps 6a, 6b) ──
@@ -1674,7 +1676,7 @@ def _setup_install(args: argparse.Namespace) -> int:
     # The "✓ Wrote …" line follows any migrate-summary line so the
     # narrative reads "we did the migration, then wrote the new entries"
     # — matches the spec's success-path sample (Section 2).
-    out.append(f"✓ Wrote {len(c.SETUP_HOOK_EVENTS)} hook entries to {c.CLAUDE_SETTINGS_PATH}")
+    out.append(f"✓ Wrote {len(c.SETUP_HOOK_EVENTS)} hook entries to {_cctally_core.CLAUDE_SETTINGS_PATH}")
 
     if decision == "skip" and reason in {"user_declined", "no_migrate_flag"}:
         files_str = "{record-usage-stop,usage-poller{,-start,-stop}}.py"
@@ -1773,7 +1775,7 @@ def _setup_install(args: argparse.Namespace) -> int:
             },
             "hooks": {
                 "events_added": list(c.SETUP_HOOK_EVENTS),
-                "settings_path": str(c.CLAUDE_SETTINGS_PATH),
+                "settings_path": str(_cctally_core.CLAUDE_SETTINGS_PATH),
             },
             "auth": {
                 "oauth_token_present": oauth,

package/bin/_cctally_tui.py

@@ -204,6 +204,7 @@ def _cctally():
 
 # === Honest imports from extracted homes ===================================
 # Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3.
+import _cctally_core
 from _cctally_core import (
     eprint,
     parse_iso_datetime,
@@ -1071,6 +1072,16 @@ class DataSnapshot:
     # declares ``ProjectsEnvelope | null`` and the client renders the
     # panel-empty state until the next tick replaces it.
     projects_envelope: dict | None = None
+    # Cache-report panel + modal envelope block (spec
+    # 2026-05-21-cache-report-panel-design.md §4.2). Populated on the
+    # sync thread by ``build_cache_report_snapshot`` alongside the
+    # existing projects build. The dashboard's
+    # ``snapshot_to_envelope`` reads this back unchanged and assigns it
+    # to ``envelope["cache_report"]``. ``None`` on first tick before
+    # sync completes — the TS envelope mirror declares
+    # ``CacheReportEnvelope | null`` and the client renders the
+    # panel-empty state until the next tick replaces it.
+    cache_report: Any | None = None
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -2026,7 +2037,7 @@ def _tui_build_snapshot(
         projects_envelope_block: dict | None = None
         try:
             c = _cctally()
-            cache_db_path = c.CACHE_DB_PATH
+            cache_db_path = _cctally_core.CACHE_DB_PATH
             conn.execute(
                 "ATTACH DATABASE ? AS cache_db",
                 (str(cache_db_path),),
@@ -2113,6 +2124,40 @@ def _tui_build_snapshot(
                 sessions = annotated
             except Exception as exc:
                 errors.append(f"projects-cross-nav-bind: {exc}")
+
+        # Cache-report panel + modal envelope block (spec
+        # 2026-05-21-cache-report-panel-design.md §5.2). Per-tick build
+        # alongside the projects envelope. Threshold is read from
+        # ``config.json:cache_report.anomaly_threshold_pp`` (default
+        # 15); ``anomaly_window_days`` is hardcoded at 14 in v1.
+        # display_tz inherits the same resolved zone as every other
+        # panel so today-bucketing matches the envelope's ``display``
+        # block. Errors record on ``last_sync_error``; ``None`` lands
+        # on the DataSnapshot field and the client renders the empty
+        # state.
+        cache_report_block = None
+        try:
+            cfg_cr = load_config().get("cache_report") or {}
+            threshold_raw = cfg_cr.get("anomaly_threshold_pp", 15)
+            try:
+                threshold_pp = int(threshold_raw)
+            except (TypeError, ValueError):
+                threshold_pp = 15
+            if threshold_pp < 1 or threshold_pp > 100:
+                threshold_pp = 15
+            _dash_mod = sys.modules["_cctally_dashboard"]
+            _bcr = _dash_mod.build_cache_report_snapshot
+            cache_report_block = _bcr(
+                now_utc=now_utc,
+                anomaly_threshold_pp=threshold_pp,
+                # Hardcoded for v1; F10 tracks lifting via cache_report.anomaly_window_days config.
+                anomaly_window_days=_dash_mod.CACHE_REPORT_ANOMALY_WINDOW_DAYS,
+                display_tz=_build_display_tz,
+                skip_sync=skip_sync,
+            )
+        except Exception as exc:
+            errors.append(f"cache-report: {exc}")
+
         return DataSnapshot(
             current_week=cw,
             forecast=fc,
@@ -2141,6 +2186,7 @@ def _tui_build_snapshot(
             trend_history_median_dpp=history_median_dpp,
             forecast_view=fc_view,
             projects_envelope=projects_envelope_block,
+            cache_report=cache_report_block,
         )
     finally:
         conn.close()