cctally 1.11.0 → 1.12.0

package/bin/_lib_jsonl.py

@@ -59,14 +59,64 @@ class CodexEntry:
     source_path: str
 
 
+def _entry_token_total(entry: "UsageEntry") -> int:
+    """Sum of the four billed token fields. Mirrors ccusage's
+    `usage_token_total` in rust/crates/ccusage/src/claude_loader.rs:516."""
+    u = entry.usage
+    return (
+        int(u.get("input_tokens", 0) or 0)
+        + int(u.get("output_tokens", 0) or 0)
+        + int(u.get("cache_creation_input_tokens", 0) or 0)
+        + int(u.get("cache_read_input_tokens", 0) or 0)
+    )
+
+
+def _should_replace(
+    candidate: "UsageEntry", existing: "UsageEntry"
+) -> bool:
+    """Port of ccusage's `should_replace_deduped_entry` in
+    rust/crates/ccusage/src/claude_loader.rs:531. Higher token total wins;
+    on equal totals, the row with `speed` set (non-null) wins (the post-stream
+    finalization row carries `speed`; streaming intermediates don't).
+
+    The `usage.get("speed") is not None` check matches the SQL UPDATE WHERE
+    clause's `json_extract(..., '$.speed') IS NOT NULL` in `sync_cache`'s
+    INSERT … ON CONFLICT … DO UPDATE, keeping the direct-parse fallback and
+    cache-ingest paths in lockstep on the rare-but-possible "explicit JSON
+    null" payload.
+    """
+    c_total = _entry_token_total(candidate)
+    e_total = _entry_token_total(existing)
+    if c_total != e_total:
+        return c_total > e_total
+    return (candidate.usage.get("speed") is not None
+            and existing.usage.get("speed") is None)
+
+
 def _parse_usage_entries(
     jsonl_path: pathlib.Path,
     range_start: dt.datetime,
     range_end: dt.datetime,
-    seen_hashes: set[str] | None = None,
+    *,
+    dedupe_map: "dict[str, UsageEntry]",
 ) -> list[UsageEntry]:
-    """Parse assistant entries from a JSONL file within the given time range."""
-    entries: list[UsageEntry] = []
+    """Parse one JSONL file's assistant entries within [range_start, range_end].
+
+    Dedup contract (matches ccusage's `push_deduped_entry`):
+    - Entries with non-null (msg_id, req_id) go into `dedupe_map`; if a key
+      already maps to an entry, replace iff `_should_replace(candidate, existing)`.
+    - Entries with null msg_id or null req_id (rare in modern Claude Code,
+      but possible on synthetic / legacy emissions) skip the dedup map and
+      land in a separate list — partial UNIQUE index on the cache mirrors
+      this behavior.
+    - `<synthetic>` model rows are dropped entirely (matches ccusage's
+      claude_loader.rs:454).
+
+    Caller is responsible for sorting the returned list by timestamp if
+    needed; `_collect_entries_direct` does this once across all files
+    after flattening `dedupe_map.values()`.
+    """
+    no_key_entries: list[UsageEntry] = []
     try:
         with open(jsonl_path, "r", encoding="utf-8", errors="replace") as fh:
             for line in fh:
@@ -96,6 +146,11 @@ def _parse_usage_entries(
                 model = msg.get("model") or obj.get("model")
                 if not isinstance(model, str) or not model.strip():
                     continue
+                model = model.strip()
+                if model == "<synthetic>":
+                    # Matches ccusage's claude_loader.rs:454 — synthetic
+                    # placeholder rows carry no billable usage.
+                    continue
 
                 try:
                     ts = dt.datetime.fromisoformat(
@@ -109,16 +164,8 @@ def _parse_usage_entries(
                 if ts < range_start or ts > range_end:
                     continue
 
-                # Deduplicate by message.id + requestId (same as ccusage)
                 msg_id = msg.get("id")
                 req_id = obj.get("requestId")
-                if msg_id is not None and req_id is not None:
-                    entry_hash = f"{msg_id}:{req_id}"
-                    if seen_hashes is not None:
-                        if entry_hash in seen_hashes:
-                            continue
-                        seen_hashes.add(entry_hash)
-
                 cost_usd_raw = obj.get("costUSD")
                 cost_usd = (
                     float(cost_usd_raw)
@@ -126,16 +173,26 @@ def _parse_usage_entries(
                     else None
                 )
 
-                entries.append(UsageEntry(
+                entry = UsageEntry(
                     timestamp=ts,
-                    model=model.strip(),
+                    model=model,
                     usage=usage,
                     cost_usd=cost_usd,
-                ))
+                )
+
+                if msg_id is None or req_id is None:
+                    no_key_entries.append(entry)
+                    continue
+                key = f"{msg_id}:{req_id}"
+                existing = dedupe_map.get(key)
+                if existing is None or _should_replace(entry, existing):
+                    dedupe_map[key] = entry
     except OSError as exc:
         _eprint(f"[cost] could not read {jsonl_path}: {exc}")
 
-    return entries
+    # The function returns ONLY this file's no-key entries; the caller
+    # flattens `dedupe_map.values()` once at the end across all files.
+    return no_key_entries
 
 
 def _iter_jsonl_entries_with_offsets(fh):
@@ -185,6 +242,13 @@ def _iter_jsonl_entries_with_offsets(fh):
         model = msg.get("model") or obj.get("model")
         if not isinstance(model, str) or not model.strip():
             continue
+        model = model.strip()
+        if model == "<synthetic>":
+            # Matches ccusage's claude_loader.rs:454. Filtered at the
+            # iterator level so the cache ingest path can't accidentally
+            # store these rows even if a downstream loop forgets to
+            # double-check (see `sync_cache` in _cctally_cache.py).
+            continue
 
         try:
             ts = dt.datetime.fromisoformat(ts_raw.strip().replace("Z", "+00:00"))
@@ -202,7 +266,7 @@ def _iter_jsonl_entries_with_offsets(fh):
             offset,
             UsageEntry(
                 timestamp=ts,
-                model=model.strip(),
+                model=model,
                 usage=usage,
                 cost_usd=cost_usd,
             ),

package/bin/_lib_share_templates.py

@@ -21,6 +21,18 @@ from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from typing import Any
 
+# NOTE: ``_cctally_core`` is imported lazily inside ``_release_version()``
+# (the sole consumer in this module) so that loading this file directly
+# via ``importlib.util.spec_from_file_location`` — the established
+# pattern used by ``_render_share_v2_fixture.py``,
+# ``_compose_share_v2_fixture.py``, and ``tests/test_lib_share_templates.py``
+# — does NOT depend on ``bin/`` being on ``sys.path`` at module-import
+# time. A module-top ``import _cctally_core`` would raise
+# ``ModuleNotFoundError`` for any standalone loader that hasn't already
+# arranged for ``_cctally_core`` to be importable, regressing the
+# parallel-loader pattern this module uses for ``_lib_share`` itself
+# (see ``_import_share_lib`` below).
+
 
 # --- Panel set ---
 #
@@ -288,22 +300,28 @@ def _utc_now() -> _dt.datetime:
 def _release_version() -> str:
     """Read CHANGELOG-stamped latest version.
 
-    Honors `CCTALLY_TEST_CHANGELOG_PATH` override (the documented test pattern
-    at `bin/cctally:86`). Falls back to `"dev"` when CHANGELOG is unreadable
-    or has no stamped release entry yet (pre-release dev builds).
+    Resolves through ``_cctally_core.CHANGELOG_PATH`` so the kernel's
+    env override (``CCTALLY_TEST_CHANGELOG_PATH``) and any test-side
+    ``monkeypatch.setattr(_cctally_core, "CHANGELOG_PATH", ...)`` both
+    propagate transparently. Falls back to ``"dev"`` when CHANGELOG is
+    unreadable or has no stamped release entry yet (pre-release dev
+    builds).
 
-    Parallel to `_lib_changelog._read_latest_changelog_version`
-    (re-exported on `bin/cctally` under the historical
-    `_release_read_latest_release_version` name) — intentionally
+    Parallel to ``_lib_changelog._read_latest_changelog_version``
+    (re-exported on ``bin/cctally`` under the historical
+    ``_release_read_latest_release_version`` name) — intentionally
     duplicated so the template module stays free of any
-    `bin/cctally` import. If CHANGELOG header format changes, update both.
+    ``bin/cctally`` import. If CHANGELOG header format changes, update both.
+
+    ``_cctally_core`` is imported lazily here (rather than at module top)
+    so that standalone loaders — see the note at the top of this file
+    and the ``_import_share_lib`` pattern below — can exec this module
+    without ``bin/`` already being on ``sys.path``. By the time
+    ``_release_version()`` is actually called, the caller (CLI boot,
+    dashboard, or fixture driver) has resolved the sibling layout.
     """
-    from pathlib import Path
-    p = os.environ.get("CCTALLY_TEST_CHANGELOG_PATH")
-    if p:
-        path = Path(p)
-    else:
-        path = Path(__file__).resolve().parent.parent / "CHANGELOG.md"
+    import _cctally_core  # noqa: PLC0415 — lazy by design (see module-top NOTE)
+    path = _cctally_core.CHANGELOG_PATH
     try:
         for line in path.read_text(encoding="utf-8").splitlines():
             if line.startswith("## [") and "Unreleased" not in line:

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,
     )
 
@@ -7723,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")
@@ -7744,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")
@@ -7761,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")
@@ -8415,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)}
 
@@ -8436,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(
@@ -8534,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"
@@ -8564,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"
@@ -8607,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"
@@ -8622,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:

package/package.json

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