cctally 1.10.3 → 1.11.1

package/bin/cctally

@@ -135,15 +135,8 @@ def _load_sibling(name: str):
 _THIS_MODULE = sys.modules.get(__name__) or sys.modules.get("cctally")
 
 
-APP_DIR = pathlib.Path.home() / ".local" / "share" / "cctally"
-LEGACY_APP_DIR = pathlib.Path.home() / ".local" / "share" / "ccusage-subscription"
-# Hook-tick runtime artifacts (Section 1 of onboarding spec).
-HOOK_TICK_LOG_DIR = APP_DIR / "logs"
-HOOK_TICK_LOG_PATH = HOOK_TICK_LOG_DIR / "hook-tick.log"
-HOOK_TICK_LOG_ROTATED_PATH = HOOK_TICK_LOG_DIR / "hook-tick.log.1"
+# Hook-tick non-path constants (Section 1 of onboarding spec).
 HOOK_TICK_LOG_ROTATE_BYTES = 1024 * 1024  # 1 MB
-HOOK_TICK_THROTTLE_PATH = APP_DIR / "hook-tick.last-fetch"
-HOOK_TICK_THROTTLE_LOCK_PATH = APP_DIR / "hook-tick.last-fetch.lock"
 HOOK_TICK_DEFAULT_THROTTLE_SECONDS = 30.0
 
 # User-facing executables symlinked by `cctally setup` (Section 2.2 of spec).
@@ -167,19 +160,6 @@ SETUP_HOOK_EVENTS = ("PostToolBatch", "Stop", "SubagentStop")
 
 # === Release automation (issue #24) ===
 
-_CHANGELOG_OVERRIDE = os.environ.get("CCTALLY_TEST_CHANGELOG_PATH")
-if _CHANGELOG_OVERRIDE:
-    # Fixture-stability hook for `bin/cctally-share-test` — points
-    # `_share_resolve_version()` (and the broader release machinery) at a
-    # per-scenario CHANGELOG so version stamping in goldens stays
-    # deterministic regardless of the in-tree CHANGELOG state. Mirrors the
-    # `CCTALLY_AS_OF` env-only precedent: not in --help, no docstring
-    # surface; consumed exclusively by harness wrappers.
-    CHANGELOG_PATH = pathlib.Path(_CHANGELOG_OVERRIDE)
-else:
-    CHANGELOG_PATH = pathlib.Path(__file__).resolve().parent.parent / "CHANGELOG.md"
-
-
 # Public mirror repo identity (the GitHub `<owner>/<repo>` slug). Used by
 # Phase 3 (mirror push), Phase 4 (`gh release create` / view), and the
 # fallback printout. Distinct from `.mirror-allowlist`, which classifies
@@ -230,6 +210,45 @@ make_week_ref = _cctally_core.make_week_ref
 _get_latest_row_for_week = _cctally_core._get_latest_row_for_week
 get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
 
+# === Path constants — re-exported from _cctally_core ================
+#
+# Promoted 2026-05-22 (docs/superpowers/specs/2026-05-22-cctally-core-data-globals.md).
+# `_cctally_core` is the single source of truth and the only legal
+# monkeypatch target. These re-exports exist for ad-hoc REPL / scripts
+# that read `cctally.APP_DIR` directly.
+
+APP_DIR = _cctally_core.APP_DIR
+LEGACY_APP_DIR = _cctally_core.LEGACY_APP_DIR
+LOG_DIR = _cctally_core.LOG_DIR
+
+DB_PATH = _cctally_core.DB_PATH
+CACHE_DB_PATH = _cctally_core.CACHE_DB_PATH
+
+CACHE_LOCK_PATH = _cctally_core.CACHE_LOCK_PATH
+CACHE_LOCK_CODEX_PATH = _cctally_core.CACHE_LOCK_CODEX_PATH
+CONFIG_LOCK_PATH = _cctally_core.CONFIG_LOCK_PATH
+
+CONFIG_PATH = _cctally_core.CONFIG_PATH
+
+MIGRATION_ERROR_LOG_PATH = _cctally_core.MIGRATION_ERROR_LOG_PATH
+
+CHANGELOG_PATH = _cctally_core.CHANGELOG_PATH
+
+HOOK_TICK_LOG_DIR = _cctally_core.HOOK_TICK_LOG_DIR
+HOOK_TICK_LOG_PATH = _cctally_core.HOOK_TICK_LOG_PATH
+HOOK_TICK_LOG_ROTATED_PATH = _cctally_core.HOOK_TICK_LOG_ROTATED_PATH
+HOOK_TICK_THROTTLE_PATH = _cctally_core.HOOK_TICK_THROTTLE_PATH
+HOOK_TICK_THROTTLE_LOCK_PATH = _cctally_core.HOOK_TICK_THROTTLE_LOCK_PATH
+
+UPDATE_STATE_PATH = _cctally_core.UPDATE_STATE_PATH
+UPDATE_SUPPRESS_PATH = _cctally_core.UPDATE_SUPPRESS_PATH
+UPDATE_LOCK_PATH = _cctally_core.UPDATE_LOCK_PATH
+UPDATE_LOG_PATH = _cctally_core.UPDATE_LOG_PATH
+UPDATE_LOG_ROTATED_PATH = _cctally_core.UPDATE_LOG_ROTATED_PATH
+UPDATE_CHECK_LAST_FETCH_PATH = _cctally_core.UPDATE_CHECK_LAST_FETCH_PATH
+
+CLAUDE_SETTINGS_PATH = _cctally_core.CLAUDE_SETTINGS_PATH
+
 _lib_semver = _load_sibling("_lib_semver")
 _SEMVER_NUM = _lib_semver._SEMVER_NUM
 _SEMVER_RE = _lib_semver._SEMVER_RE
@@ -648,11 +667,15 @@ _saved_dict_from_usage_row = _cctally_record._saved_dict_from_usage_row
 # the ``c = _cctally()`` accessor at call time so
 # ``setitem(ns, "_do_update_check", mock)`` propagates into
 # ``cmd_update_check_internal`` / ``_DashboardUpdateCheckThread.run``.
-# Path constants stay in bin/cctally (defined at L2001-2023 right after
-# APP_DIR) — moved bodies read them via ``c.UPDATE_STATE_PATH`` etc. so
-# ``setitem(ns, "UPDATE_LOG_PATH", tmp)`` in tests propagates with zero
-# sibling-side patches needed (same as Phase D #17/#18 path-constant
-# precedent).
+# Path constants (UPDATE_STATE_PATH, UPDATE_SUPPRESS_PATH,
+# UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH,
+# UPDATE_CHECK_LAST_FETCH_PATH) were promoted to _cctally_core
+# 2026-05-22 (#84). Moved bodies in _cctally_update read them via
+# call-time ``_cctally_core.UPDATE_STATE_PATH`` etc.; tests patch via
+# ``monkeypatch.setattr(_cctally_core, "X", v)`` (the conftest
+# ``redirect_paths()`` helper covers the full set). The legacy
+# ``setitem(ns, …)`` pattern is forbidden by
+# ``test_no_old_style_test_patches_for_promoted_globals``.
 _cctally_update = _load_sibling("_cctally_update")
 UpdateError = _cctally_update.UpdateError
 UpdateValidationError = _cctally_update.UpdateValidationError
@@ -822,64 +845,26 @@ LEGACY_STATUSLINE_PATHS = (
 )
 LEGACY_STATUSLINE_NEEDLE = "cctally record-usage"
 
-DB_PATH = APP_DIR / "stats.db"
-CACHE_DB_PATH = APP_DIR / "cache.db"
-CACHE_LOCK_PATH = APP_DIR / "cache.db.lock"
-CACHE_LOCK_CODEX_PATH = APP_DIR / "cache.db.codex.lock"
 CODEX_SESSIONS_DIR = pathlib.Path.home() / ".codex" / "sessions"
-CONFIG_PATH = APP_DIR / "config.json"
-CONFIG_LOCK_PATH = APP_DIR / "config.json.lock"
-LOG_DIR = APP_DIR / "logs"
-MIGRATION_ERROR_LOG_PATH = LOG_DIR / "migration-errors.log"
-
-# Seed `_cctally_db`'s namespace with path constants the migration
-# framework + error sentinel + cmd_db_* helpers reach via bare-name
-# lookup. We have to do this AFTER LOG_DIR / MIGRATION_ERROR_LOG_PATH
-# / DB_PATH / CACHE_DB_PATH are defined (i.e. here, not at the eager-
-# load site near the top). Bare-name lookup keeps the existing
-# `monkeypatch.setitem(helper.__globals__, "MIGRATION_ERROR_LOG_PATH",
-# tmp)` test pattern working (the helper's `__globals__` is now
-# `_cctally_db.__dict__`, so setitem there hits the bare-name lookup
-# path inside the helper). Tests that redirect HOME via the conftest
-# fixture also work because `redirect_paths` already patches the
-# cctally-side path constants AND will additionally need to patch the
-# sibling-side copy below — that's why we expose this seed: tests can
-# discover the sibling via `cctally_module._cctally_db` and patch via
-# `monkeypatch.setitem(_cctally_db.__dict__, "X", tmp)` if needed.
-_cctally_db.LOG_DIR = LOG_DIR
-_cctally_db.MIGRATION_ERROR_LOG_PATH = MIGRATION_ERROR_LOG_PATH
-_cctally_db.DB_PATH = DB_PATH
-_cctally_db.CACHE_DB_PATH = CACHE_DB_PATH
-
-# Note: `_cctally_cache.py` does NOT need a path-constant seed block
-# parallel to `_cctally_db` above — its moved bodies reach
-# `APP_DIR` / `CACHE_DB_PATH` / `CACHE_LOCK_PATH` /
-# `CACHE_LOCK_CODEX_PATH` / `CODEX_SESSIONS_DIR` via the
-# `c = _cctally()` call-time accessor (spec §5.5). That defers every
-# read until call-time `sys.modules['cctally'].X`, so
-# `monkeypatch.setitem(ns, "CACHE_DB_PATH", tmp)` test patches and
-# conftest `redirect_paths` HOME redirects propagate without
-# touching any sibling-side seeded copy. We chose `c.X` over the
-# `_cctally_db`-style seed block here because cache test sites are
-# widely scattered (record-usage tick, dashboard panels, share
-# render kernel, block tests, every JSONL-reading subcommand
-# fixture) — inline patches against ns by setitem are the
-# established idiom, and the c.X path keeps them all working with
-# zero test-file edits.
+
+# Note: `_cctally_db` reads its four path constants
+# (`LOG_DIR`/`MIGRATION_ERROR_LOG_PATH`/`DB_PATH`/`CACHE_DB_PATH`) via
+# `_cctally_core.X` at call time — the canonical sibling pattern after
+# the data-globals promotion (2026-05-22, issue #84). The previous
+# eager-seed block here is no longer needed: `_cctally_core` is the
+# single source of truth, and `monkeypatch.setattr(_cctally_core, "X",
+# v)` propagates into every reader without a sibling-side mirror.
+#
+# Note: `_cctally_cache.py` reaches `APP_DIR` / `CACHE_DB_PATH` /
+# `CACHE_LOCK_PATH` / `CACHE_LOCK_CODEX_PATH` via call-time
+# `_cctally_core.X` (promoted 2026-05-22, #84). Only `CODEX_SESSIONS_DIR`
+# is out of scope for #84 — that one is still read via the
+# `c = _cctally()` accessor and lives in this file.
 
 # === Update subcommand (Section 1 of update-subcommand spec) ===
-# Path constants for the `cctally update` feature. Centralised here
-# (alongside other APP_DIR-derived paths) so the test fixture loader in
-# tests/conftest.py:redirect_paths can monkeypatch them, and so later
-# tasks (install detection, version-check pipeline, dashboard worker)
-# don't have to revisit constant placement.
-UPDATE_STATE_PATH         = APP_DIR / "update-state.json"
-UPDATE_SUPPRESS_PATH      = APP_DIR / "update-suppress.json"
-UPDATE_LOCK_PATH          = APP_DIR / "update.lock"
-UPDATE_LOG_PATH           = APP_DIR / "update.log"
-UPDATE_LOG_ROTATED_PATH   = APP_DIR / "update.log.1"
+# Non-path constants for the `cctally update` feature. Path constants
+# now live in bin/_cctally_core.py (promoted 2026-05-22; see #84).
 UPDATE_LOG_ROTATE_BYTES   = 1024 * 1024  # 1 MB; spec §1.5
-UPDATE_CHECK_LAST_FETCH_PATH = APP_DIR / "update-check.last-fetch"
 
 UPDATE_NPM_REGISTRY_URL = os.environ.get(
     "CCTALLY_TEST_UPDATE_NPM_URL",
@@ -904,14 +889,14 @@ def _migrate_legacy_data_dir() -> None:
     Removable in a future major version once early users have been on
     cctally long enough that the legacy dir is gone everywhere.
     """
-    if APP_DIR.exists():
+    if _cctally_core.APP_DIR.exists():
         return  # already migrated, or fresh install at the new path
-    if not LEGACY_APP_DIR.exists():
+    if not _cctally_core.LEGACY_APP_DIR.exists():
         return  # fresh install, no legacy data
-    APP_DIR.parent.mkdir(parents=True, exist_ok=True)
-    os.rename(LEGACY_APP_DIR, APP_DIR)
+    _cctally_core.APP_DIR.parent.mkdir(parents=True, exist_ok=True)
+    os.rename(_cctally_core.LEGACY_APP_DIR, _cctally_core.APP_DIR)
     print(
-        f"cctally: migrated data dir {LEGACY_APP_DIR} -> {APP_DIR}",
+        f"cctally: migrated data dir {_cctally_core.LEGACY_APP_DIR} -> {_cctally_core.APP_DIR}",
         file=sys.stderr,
     )
 
@@ -2179,71 +2164,24 @@ def _trend_row_recency_seconds(row: dict[str, Any]) -> float:
     return 0.0
 
 
-@dataclass
-class CacheModelBreakdown:
-    model_name: str
-    input_tokens: int
-    output_tokens: int
-    cache_creation_tokens: int
-    cache_read_tokens: int
-    cache_hit_percent: float
-    cost: float
-    saved_usd: float = 0.0
-    wasted_usd: float = 0.0
-    net_usd: float = 0.0
-
-
-@dataclass
-class CacheRow:
-    # Identity (exactly one group populated)
-    date: str | None = None
-    session_id: str | None = None
-    project_path: str | None = None
-    last_activity: dt.datetime | None = None
-    source_paths: list[str] = field(default_factory=list)
-
-    # Token counters
-    input_tokens: int = 0
-    output_tokens: int = 0
-    cache_creation_tokens: int = 0
-    cache_read_tokens: int = 0
-
-    # Financials (populated by Task 2; zero here)
-    cost: float = 0.0
-    saved_usd: float = 0.0
-    wasted_usd: float = 0.0
-    net_usd: float = 0.0
-
-    # Per-model breakdown children
-    model_breakdowns: list[CacheModelBreakdown] = field(default_factory=list)
-
-    # Anomaly (populated by Task 5; defaults here)
-    anomaly_triggered: bool = False
-    anomaly_reasons: list[str] = field(default_factory=list)
-
-    @property
-    def total_tokens(self) -> int:
-        return (
-            self.input_tokens + self.output_tokens
-            + self.cache_creation_tokens + self.cache_read_tokens
-        )
-
-    @property
-    def cache_hit_percent(self) -> float:
-        return _compute_cache_hit_percent(
-            self.input_tokens, self.cache_creation_tokens, self.cache_read_tokens
-        )
-
-
-def _compute_cache_hit_percent(
-    input_tokens: int,
-    cache_creation_tokens: int,
-    cache_read_tokens: int,
-) -> float:
-    total_input = input_tokens + cache_creation_tokens + cache_read_tokens
-    if total_input == 0:
-        return 0.0
-    return (cache_read_tokens / total_input) * 100
+# === Cache-report kernel re-exports (Task A2 onward) =========================
+# The dataclasses + pure helpers below previously lived inline in bin/cctally;
+# the cache-report panel/modal effort moved them to bin/_cctally_cache_report
+# so the dashboard sync builder can reuse the same pure aggregation as the
+# CLI. cctally-side callers continue to reach for ``CacheRow`` /
+# ``CacheModelBreakdown`` / ``_compute_cache_hit_percent`` /
+# ``_compute_entry_cache_dollars`` by bare name (extensive — every cache-report
+# renderer + JSON emitter); per-symbol re-export here preserves the call sites
+# unchanged. ``_compute_entry_cache_dollars`` keeps its pre-extraction
+# signature on this side by wrapping the kernel version with the embedded
+# ``CLAUDE_MODEL_PRICING`` injected as the ``pricing`` kwarg.
+#
+# Spec: docs/superpowers/specs/2026-05-21-cache-report-panel-design.md §5.2
+_cctally_cache_report = _load_sibling("_cctally_cache_report")
+CacheModelBreakdown = _cctally_cache_report.CacheModelBreakdown
+CacheRow = _cctally_cache_report.CacheRow
+_compute_cache_hit_percent = _cctally_cache_report._compute_cache_hit_percent
+_compute_entry_cache_dollars_kernel = _cctally_cache_report._compute_entry_cache_dollars
 
 
 def _compute_entry_cache_dollars(
@@ -2251,142 +2189,57 @@ def _compute_entry_cache_dollars(
     cache_creation_tokens: int,
     cache_read_tokens: int,
 ) -> tuple[float, float, float]:
-    """Return (saved_usd, wasted_usd, net_usd) for a single API-call entry.
-
-    saved_usd  = cache_read_tokens  x (base_rate - read_rate)
-                 "what you'd have paid without caching"
-    wasted_usd = cache_creation_tokens x (create_rate - base_rate)
-                 "the premium paid to write cache"
-    net_usd    = saved_usd - wasted_usd
-                 positive = caching helped; negative = caching hurt
-
-    Applies Anthropic's per-call >200K-tokens tier (mirrors the
-    `_tiered` helper in `_calculate_entry_cost`). Aggregating tokens
-    across multiple calls and then pricing would under-count savings on
-    any single call that crossed the tier. Resolves `anthropic/` and
-    `anthropic.` aliases via `_resolve_model_pricing` so cache-dollar
-    numbers stay aligned with cost numbers.
+    """Compatibility wrapper — pre-extraction signature.
+
+    The kernel function takes ``pricing`` explicitly so it stays pure;
+    bin/cctally callers inject the embedded ``CLAUDE_MODEL_PRICING``.
+    ``_lookup_pricing`` inside the kernel handles the ``anthropic/`` /
+    ``anthropic.`` alias-stripping that the legacy ``_resolve_model_pricing``
+    did, but without the stderr warning (the warning is the CLI's concern
+    and already fires elsewhere via ``_calculate_entry_cost``).
     """
-    pricing = _resolve_model_pricing(model) or {}
-
-    def _tiered_rate(tokens: int, base_key: str, tiered_key: str) -> float:
-        """Blended $/token rate for a single-call token count under tiered pricing."""
-        base_rate = pricing.get(base_key, 0.0)
-        tiered_rate = pricing.get(tiered_key)
-        if tokens <= 0:
-            return 0.0
-        if tokens > TIERED_THRESHOLD and tiered_rate is not None:
-            below = TIERED_THRESHOLD
-            above = tokens - TIERED_THRESHOLD
-            return (below * base_rate + above * tiered_rate) / tokens
-        return base_rate
-
-    base_for_read = _tiered_rate(
-        cache_read_tokens,
-        "input_cost_per_token",
-        "input_cost_per_token_above_200k_tokens",
-    )
-    read_rate = _tiered_rate(
-        cache_read_tokens,
-        "cache_read_input_token_cost",
-        "cache_read_input_token_cost_above_200k_tokens",
-    )
-    base_for_create = _tiered_rate(
-        cache_creation_tokens,
-        "input_cost_per_token",
-        "input_cost_per_token_above_200k_tokens",
-    )
-    create_rate = _tiered_rate(
-        cache_creation_tokens,
-        "cache_creation_input_token_cost",
-        "cache_creation_input_token_cost_above_200k_tokens",
-    )
-
-    saved = cache_read_tokens * max(0.0, base_for_read - read_rate)
-    wasted = cache_creation_tokens * max(0.0, create_rate - base_for_create)
-    net = saved - wasted
-    return (saved, wasted, net)
+    return _compute_entry_cache_dollars_kernel(
+        model, cache_creation_tokens, cache_read_tokens,
+        pricing=CLAUDE_MODEL_PRICING,
+        tiered_threshold=TIERED_THRESHOLD,
+    )
 
 
 def _aggregate_cache_by_day(
     since: dt.datetime,
     until: dt.datetime,
     project: str | None = None,
+    *,
+    display_tz: "ZoneInfo | None" = None,
 ) -> list[CacheRow]:
-    """Group Claude Code entries by local date within [since, until]."""
-    # internal fallback: host-local intentional
-    local_tz = dt.datetime.now().astimezone().tzinfo
-
-    day_model_buckets: dict[str, dict[str, dict[str, Any]]] = {}
-    for entry in get_entries(since, until, project=project):
-        day_key = entry.timestamp.astimezone(local_tz).strftime("%Y-%m-%d")
-        cost = _calculate_entry_cost(
-            entry.model, entry.usage, mode="auto", cost_usd=entry.cost_usd
-        )
-        create_tok = entry.usage.get("cache_creation_input_tokens", 0)
-        read_tok = entry.usage.get("cache_read_input_tokens", 0)
-        saved, wasted, net = _compute_entry_cache_dollars(
-            entry.model, create_tok, read_tok
-        )
-        models = day_model_buckets.setdefault(day_key, {})
-        b = models.setdefault(entry.model, {
-            "inputTokens": 0, "outputTokens": 0,
-            "cacheCreationTokens": 0, "cacheReadTokens": 0, "cost": 0.0,
-            "savedUsd": 0.0, "wastedUsd": 0.0, "netUsd": 0.0,
-        })
-        b["inputTokens"] += entry.usage.get("input_tokens", 0)
-        b["outputTokens"] += entry.usage.get("output_tokens", 0)
-        b["cacheCreationTokens"] += create_tok
-        b["cacheReadTokens"] += read_tok
-        b["cost"] += cost
-        b["savedUsd"] += saved
-        b["wastedUsd"] += wasted
-        b["netUsd"] += net
-
-    result: list[CacheRow] = []
-    for day_key in sorted(day_model_buckets.keys()):
-        models = day_model_buckets[day_key]
-        row = CacheRow(date=day_key)
-        for model_name in sorted(models.keys()):
-            b = models[model_name]
-            mb = CacheModelBreakdown(
-                model_name=model_name,
-                input_tokens=b["inputTokens"],
-                output_tokens=b["outputTokens"],
-                cache_creation_tokens=b["cacheCreationTokens"],
-                cache_read_tokens=b["cacheReadTokens"],
-                cache_hit_percent=_compute_cache_hit_percent(
-                    b["inputTokens"], b["cacheCreationTokens"], b["cacheReadTokens"]
-                ),
-                cost=b["cost"],
-                saved_usd=b["savedUsd"],
-                wasted_usd=b["wastedUsd"],
-                net_usd=b["netUsd"],
-            )
-            row.model_breakdowns.append(mb)
-            row.input_tokens += mb.input_tokens
-            row.output_tokens += mb.output_tokens
-            row.cache_creation_tokens += mb.cache_creation_tokens
-            row.cache_read_tokens += mb.cache_read_tokens
-            row.cost += mb.cost
-            row.saved_usd += mb.saved_usd
-            row.wasted_usd += mb.wasted_usd
-            row.net_usd += mb.net_usd
-        result.append(row)
-    return result
-
+    """CLI adapter: pulls entries from ``get_entries`` and delegates to the
+    pure-fn kernel ``_cctally_cache_report._aggregate_cache_by_day``.
+
+    Adds an explicit ``display_tz`` kwarg (closes the pre-existing minor bug
+    where ``--tz`` shifted the window edges but not the day-bucketing —
+    spec §1.6, plan A3). Passes the embedded ``CLAUDE_MODEL_PRICING`` +
+    ``_calculate_entry_cost`` into the kernel so the kernel itself stays
+    free of pricing globals / cost-dispatch I/O.
+
+    Direct callers that don't pass ``display_tz`` (legacy contract) fall
+    back to host-local via the kernel's ``None``-tz handling, matching
+    pre-extraction behavior byte-for-byte. ``since`` / ``until`` bound
+    the I/O query here; the kernel itself trusts the caller's pre-filter.
+    """
+    entries = list(get_entries(since, until, project=project))
+    return _cctally_cache_report._aggregate_cache_by_day(
+        entries,
+        display_tz=display_tz,
+        pricing=CLAUDE_MODEL_PRICING,
+        cost_calculator=_calculate_entry_cost,
+    )
 
-def _filename_uuid_stem(path: str) -> str:
-    """Extract the UUID stem from a JSONL filename.
 
-    Claude JSONL files are named `<uuid>.jsonl`; fall back to the full
-    filename (without extension) if the stem isn't a valid UUID shape.
-    Matches the `session` subcommand's convention for unresolved session
-    IDs.
-    """
-    base = os.path.basename(path)
-    stem, _, _ = base.partition(".")
-    return stem
+# Re-export the kernel's filename stem helper so any bare-name callers
+# inside bin/cctally (and tests poking via ``ns["_filename_uuid_stem"]``)
+# resolve unchanged. Kernel is pure-string; ``os.path.basename``
+# equivalence is asserted by ``test_aggregate_by_session_falls_back_*``.
+_filename_uuid_stem = _cctally_cache_report._filename_uuid_stem
 
 
 def _aggregate_cache_by_session(
@@ -2394,135 +2247,40 @@ def _aggregate_cache_by_session(
     until: dt.datetime,
     project: str | None = None,
 ) -> list[CacheRow]:
-    """Group Claude entries by sessionId (resumed-merged) within [since, until].
-
-    Uses get_claude_session_entries for the existing session_entries x
-    session_files LEFT JOIN. Entries with NULL session_id fall back to
-    the filename UUID stem of source_path (matches the `session`
-    subcommand's convention). A one-shot stderr warning fires when any
-    entry used the fallback. `project`, when set, filters by the same
-    slug semantics as `get_entries(project=...)`.
+    """CLI adapter: pulls Claude session entries from
+    ``get_claude_session_entries`` and delegates to the pure-fn kernel
+    ``_cctally_cache_report._aggregate_cache_by_session``.
+
+    Preserves the legacy one-shot ``Warning: N entries lacked
+    session_files rows (cache may be catching up).`` stderr line by
+    consuming the kernel's ``fallback_count`` and calling ``eprint``
+    here (kept on the I/O side; kernel stays pure). Injects
+    ``CLAUDE_MODEL_PRICING`` + ``_calculate_entry_cost`` +
+    ``_decode_escaped_cwd`` so the kernel doesn't reach for cctally
+    globals. ``since`` / ``until`` bound the I/O query; the kernel
+    itself trusts the caller's pre-filter.
     """
     entries = get_claude_session_entries(since, until, project=project)
     if not entries:
         return []
 
-    # buckets[sid] = {"entries": [...], "project_path": str|None,
-    #                 "last_activity": dt|None, "source_paths": set[str]}
-    buckets: dict[str, dict[str, Any]] = {}
-    fallback_count = 0
-    for entry in entries:
-        # Skip synthetic entries (Claude Code internal markers, not real
-        # model calls). Mirrors `_aggregate_claude_sessions` (line ~2992).
-        # Must occur before the session_id fallback so synthetic entries
-        # don't inflate fallback_count either.
-        if entry.model == "<synthetic>":
-            continue
-        sid = entry.session_id
-        if sid is None:
-            sid = _filename_uuid_stem(entry.source_path)
-            fallback_count += 1
-        b = buckets.setdefault(sid, {
-            "entries": [],
-            # Seed with decoded-cwd fallback so rows still resolve a
-            # Project cell while session_files backfill is incomplete.
-            # Real project_path from session_files (if present on any
-            # joined row) overrides below.
-            "project_path": _decode_escaped_cwd(
-                os.path.basename(os.path.dirname(entry.source_path))
-            ),
-            "last_activity": None,
-            "source_paths": set(),
-        })
-        b["entries"].append(entry)
-        b["source_paths"].add(entry.source_path)
-        if b["last_activity"] is None or entry.timestamp > b["last_activity"]:
-            b["last_activity"] = entry.timestamp
-            # Project path from most-recent in-window entry that has it.
-            if entry.project_path:
-                b["project_path"] = entry.project_path
-
-    if fallback_count:
-        eprint(
-            f"Warning: {fallback_count} entries lacked session_files rows "
-            "(cache may be catching up)."
+    def _project_decoder(source_path: str) -> str:
+        return _decode_escaped_cwd(
+            os.path.basename(os.path.dirname(source_path))
         )
 
-    result: list[CacheRow] = []
-    for sid, b in buckets.items():
-        # Per-model sub-buckets scoped to this session's entries.
-        model_buckets: dict[str, dict[str, Any]] = {}
-        for entry in b["entries"]:
-            mb_raw = model_buckets.setdefault(entry.model, {
-                "inputTokens": 0, "outputTokens": 0,
-                "cacheCreationTokens": 0, "cacheReadTokens": 0, "cost": 0.0,
-                "savedUsd": 0.0, "wastedUsd": 0.0, "netUsd": 0.0,
-            })
-            mb_raw["inputTokens"] += entry.input_tokens
-            mb_raw["outputTokens"] += entry.output_tokens
-            mb_raw["cacheCreationTokens"] += entry.cache_creation_tokens
-            mb_raw["cacheReadTokens"] += entry.cache_read_tokens
-            mb_raw["cost"] += _calculate_entry_cost(
-                entry.model,
-                {
-                    "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,
-                },
-                mode="auto",
-                cost_usd=entry.cost_usd,
-            )
-            saved, wasted, net = _compute_entry_cache_dollars(
-                entry.model,
-                entry.cache_creation_tokens,
-                entry.cache_read_tokens,
-            )
-            mb_raw["savedUsd"] += saved
-            mb_raw["wastedUsd"] += wasted
-            mb_raw["netUsd"] += net
-
-        row = CacheRow(
-            session_id=sid,
-            project_path=b["project_path"],
-            last_activity=b["last_activity"],
-            source_paths=sorted(b["source_paths"]),
+    agg = _cctally_cache_report._aggregate_cache_by_session(
+        entries,
+        pricing=CLAUDE_MODEL_PRICING,
+        cost_calculator=_calculate_entry_cost,
+        project_decoder=_project_decoder,
+    )
+    if agg.fallback_count:
+        eprint(
+            f"Warning: {agg.fallback_count} entries lacked session_files rows "
+            "(cache may be catching up)."
         )
-        for model_name in sorted(model_buckets.keys()):
-            mb_raw = model_buckets[model_name]
-            mb = CacheModelBreakdown(
-                model_name=model_name,
-                input_tokens=mb_raw["inputTokens"],
-                output_tokens=mb_raw["outputTokens"],
-                cache_creation_tokens=mb_raw["cacheCreationTokens"],
-                cache_read_tokens=mb_raw["cacheReadTokens"],
-                cache_hit_percent=_compute_cache_hit_percent(
-                    mb_raw["inputTokens"],
-                    mb_raw["cacheCreationTokens"],
-                    mb_raw["cacheReadTokens"],
-                ),
-                cost=mb_raw["cost"],
-                saved_usd=mb_raw["savedUsd"],
-                wasted_usd=mb_raw["wastedUsd"],
-                net_usd=mb_raw["netUsd"],
-            )
-            row.model_breakdowns.append(mb)
-            row.input_tokens += mb.input_tokens
-            row.output_tokens += mb.output_tokens
-            row.cache_creation_tokens += mb.cache_creation_tokens
-            row.cache_read_tokens += mb.cache_read_tokens
-            row.cost += mb.cost
-            row.saved_usd += mb.saved_usd
-            row.wasted_usd += mb.wasted_usd
-            row.net_usd += mb.net_usd
-        result.append(row)
-
-    # Initial ordering descending by last_activity; Task 6 adds --sort and
-    # will change the session-mode default. Use tz-aware sentinel to avoid
-    # naive-vs-aware comparison errors on rows missing last_activity.
-    _min_dt = dt.datetime.min.replace(tzinfo=dt.timezone.utc)
-    result.sort(key=lambda r: r.last_activity or _min_dt, reverse=True)
-    return result
+    return agg.rows
 
 
 def _annotate_anomalies(
@@ -2532,83 +2290,20 @@ def _annotate_anomalies(
     *,
     enabled: bool = True,
 ) -> None:
-    """Mutate each row's anomaly_triggered / anomaly_reasons in place.
-
-    Trigger 1 (net_negative): net_usd < 0 (strict). Skipped when the row has
-    zero cache activity (no-op session, not a bug).
-    Trigger 2 (cache_drop): cache_hit_percent is >= threshold_pp below the
-    trailing window_days median of OTHER rows. Requires minimum 5 (daily)
-    or 10 (session) baseline samples; silently skipped otherwise.
+    """CLI adapter: thin shim around the kernel's ``_classify_anomalies``.
 
-    Mode is inferred from the first row: if it has a session_id, session
-    mode (window_days back to <= last_activity - 1s); else daily mode
-    (window_days back to <= date - 1 day).
+    Kept under the original name so the existing call site in
+    ``cmd_cache_report`` resolves unchanged. The kernel mutates each row
+    in place (same contract as the pre-extraction implementation —
+    ``anomaly_triggered`` / ``anomaly_reasons`` set on each ``CacheRow``).
     """
-    import statistics
-
-    if not enabled:
-        for row in rows:
-            row.anomaly_triggered = False
-            row.anomaly_reasons = []
-        return
-    if not rows:
-        return
-
-    # Determine mode + baseline minimum from the first row's identity.
-    is_session_mode = rows[0].session_id is not None
-    min_baseline = 10 if is_session_mode else 5
-
-    def _row_anchor(r: CacheRow) -> dt.datetime | None:
-        """Return the row's position in time for baseline-window comparison."""
-        if r.last_activity is not None:
-            return r.last_activity
-        if r.date:
-            # Use .astimezone() (not .replace(tzinfo=...)) so the OS tzdb
-            # gives the correct offset for the given date — avoids DST drift
-            # on dates that straddle a DST boundary. Mirrors the idiom in
-            # _parse_cli_date_range.
-            # internal fallback: host-local intentional
-            return dt.datetime.strptime(r.date, "%Y-%m-%d").astimezone()
-        return None
-
-    window = dt.timedelta(days=window_days)
-    upper_offset = (
-        dt.timedelta(seconds=1) if is_session_mode else dt.timedelta(days=1)
+    _cctally_cache_report._classify_anomalies(
+        rows,
+        threshold_pp=threshold_pp,
+        window_days=window_days,
+        enabled=enabled,
     )
 
-    # Pre-compute anchors once to avoid O(n^2 * datetime-parse) overhead.
-    anchors: list[dt.datetime | None] = [_row_anchor(r) for r in rows]
-
-    for i, row in enumerate(rows):
-        reasons: list[str] = []
-
-        # Trigger 1: net_negative (no baseline needed; cache-activity guard).
-        if row.cache_creation_tokens + row.cache_read_tokens > 0:
-            if row.net_usd < 0:
-                reasons.append("net_negative")
-
-        # Trigger 2: cache_drop (requires baseline).
-        anchor = anchors[i]
-        if anchor is not None:
-            lower_bound = anchor - window
-            upper_bound = anchor - upper_offset
-            baseline_values: list[float] = []
-            for j, other in enumerate(rows):
-                if j == i:
-                    continue
-                other_anchor = anchors[j]
-                if other_anchor is None:
-                    continue
-                if lower_bound <= other_anchor <= upper_bound:
-                    baseline_values.append(other.cache_hit_percent)
-            if len(baseline_values) >= min_baseline:
-                median = statistics.median(baseline_values)
-                if (median - row.cache_hit_percent) >= threshold_pp:
-                    reasons.append("cache_drop")
-
-        row.anomaly_reasons = reasons
-        row.anomaly_triggered = bool(reasons)
-
 
 @dataclass
 class WeekCostResult:
@@ -8013,11 +7708,17 @@ class SetupError(RuntimeError):
     """Raised when setup hits a hard prerequisite failure (Section 2 of spec)."""
 
 
-CLAUDE_SETTINGS_PATH = pathlib.Path.home() / ".claude" / "settings.json"
-
+def _load_claude_settings(path: pathlib.Path | None = None) -> dict:
+    """Read ~/.claude/settings.json. Empty/missing → {}. Malformed → SetupError.
 
-def _load_claude_settings(path: pathlib.Path = CLAUDE_SETTINGS_PATH) -> dict:
-    """Read ~/.claude/settings.json. Empty/missing → {}. Malformed → SetupError."""
+    ``path`` resolves to ``_cctally_core.CLAUDE_SETTINGS_PATH`` at CALL
+    TIME when omitted, so ``monkeypatch.setattr(_cctally_core,
+    "CLAUDE_SETTINGS_PATH", tmp)`` propagates without needing to swap
+    out this callable. Capturing the default at def-time would silently
+    pin the maintainer's real ``~/.claude/settings.json``.
+    """
+    if path is None:
+        path = _cctally_core.CLAUDE_SETTINGS_PATH
     if not path.exists():
         return {}
     raw = path.read_text(encoding="utf-8")
@@ -8034,8 +7735,14 @@ def _load_claude_settings(path: pathlib.Path = CLAUDE_SETTINGS_PATH) -> dict:
     return data
 
 
-def _backup_claude_settings(path: pathlib.Path = CLAUDE_SETTINGS_PATH) -> pathlib.Path | None:
-    """Best-effort daily backup; return backup path or None."""
+def _backup_claude_settings(path: pathlib.Path | None = None) -> pathlib.Path | None:
+    """Best-effort daily backup; return backup path or None.
+
+    ``path`` resolves to ``_cctally_core.CLAUDE_SETTINGS_PATH`` at CALL
+    TIME when omitted (see ``_load_claude_settings`` for rationale).
+    """
+    if path is None:
+        path = _cctally_core.CLAUDE_SETTINGS_PATH
     if not path.exists():
         return None
     today = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%d")
@@ -8051,9 +7758,15 @@ def _backup_claude_settings(path: pathlib.Path = CLAUDE_SETTINGS_PATH) -> pathli
 
 
 def _write_claude_settings_atomic(
-    settings: dict, path: pathlib.Path = CLAUDE_SETTINGS_PATH
+    settings: dict, path: pathlib.Path | None = None
 ) -> None:
-    """Atomic write with 2-space indent, trailing newline."""
+    """Atomic write with 2-space indent, trailing newline.
+
+    ``path`` resolves to ``_cctally_core.CLAUDE_SETTINGS_PATH`` at CALL
+    TIME when omitted (see ``_load_claude_settings`` for rationale).
+    """
+    if path is None:
+        path = _cctally_core.CLAUDE_SETTINGS_PATH
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(path.suffix + ".tmp")
     tmp.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
@@ -8444,7 +8157,13 @@ def cmd_cache_report(args: argparse.Namespace) -> int:
     if mode == "session":
         rows = _aggregate_cache_by_session(since, until, project=args.project)
     else:
-        rows = _aggregate_cache_by_day(since, until, project=args.project)
+        # Task A3: pass the resolved display_tz so day buckets match the
+        # ``--tz`` flag (closes the pre-existing minor bug where the
+        # window edges shifted but day buckets stayed on host-local —
+        # spec §1.6 / plan A3).
+        rows = _aggregate_cache_by_day(
+            since, until, project=args.project, display_tz=tz,
+        )
 
     if not rows:
         if args.json:
@@ -8699,19 +8418,19 @@ def doctor_gather_state(
 
     # ── DB ───────────────────────────────────────────────────────────
     try:
-        stats_db_status = _db_status_for(DB_PATH, _STATS_MIGRATIONS, "stats.db")
-        if not DB_PATH.exists():
+        stats_db_status = _db_status_for(_cctally_core.DB_PATH, _STATS_MIGRATIONS, "stats.db")
+        if not _cctally_core.DB_PATH.exists():
             stats_db_status["_file_exists"] = False
     except sqlite3.Error as exc:
-        stats_db_status = {"path": str(DB_PATH), "user_version": 0,
+        stats_db_status = {"path": str(_cctally_core.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 = _db_status_for(_cctally_core.CACHE_DB_PATH, _CACHE_MIGRATIONS, "cache.db")
+        if not _cctally_core.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,
+        cache_db_status = {"path": str(_cctally_core.CACHE_DB_PATH), "user_version": 0,
                            "registry_size": len(_CACHE_MIGRATIONS),
                            "migrations": [], "_open_error": str(exc)}
 
@@ -8720,8 +8439,8 @@ def doctor_gather_state(
     forked_bucket_counts: dict | None = None
     credited_weeks: list[dict] | None = None
     try:
-        if DB_PATH.exists():
-            conn = sqlite3.connect(str(DB_PATH))
+        if _cctally_core.DB_PATH.exists():
+            conn = sqlite3.connect(str(_cctally_core.DB_PATH))
             try:
                 try:
                     row = conn.execute(
@@ -8818,8 +8537,8 @@ def doctor_gather_state(
     cache_entries_count = None
     cache_last_entry_at = None
     try:
-        if CACHE_DB_PATH.exists():
-            conn = sqlite3.connect(str(CACHE_DB_PATH))
+        if _cctally_core.CACHE_DB_PATH.exists():
+            conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
             try:
                 row = conn.execute(
                     "SELECT COUNT(*), MAX(timestamp_utc) FROM session_entries"
@@ -8848,8 +8567,8 @@ def doctor_gather_state(
     codex_entries_count = None
     codex_last_entry_at = None
     try:
-        if CACHE_DB_PATH.exists():
-            conn = sqlite3.connect(str(CACHE_DB_PATH))
+        if _cctally_core.CACHE_DB_PATH.exists():
+            conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
             try:
                 row = conn.execute(
                     "SELECT COUNT(*), MAX(timestamp_utc) FROM codex_session_entries"
@@ -8891,8 +8610,8 @@ def doctor_gather_state(
     # 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 _cctally_core.CONFIG_PATH.exists():
+            raw_cfg = json.loads(_cctally_core.CONFIG_PATH.read_text(encoding="utf-8"))
             if isinstance(raw_cfg, dict):
                 dashboard_bind_stored = (
                     _config_known_value(raw_cfg, "dashboard.bind") or "loopback"
@@ -8906,8 +8625,8 @@ def doctor_gather_state(
     # (codex H1).
     config_json_error = None
     try:
-        if CONFIG_PATH.exists():
-            json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        if _cctally_core.CONFIG_PATH.exists():
+            json.loads(_cctally_core.CONFIG_PATH.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
         config_json_error = f"{type(exc).__name__}: {exc}"
     except OSError as exc: