cctally 1.10.3 → 1.11.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.11.1] - 2026-05-22
+
+### Changed
+- Promote 23 path globals (`APP_DIR`, `LEGACY_APP_DIR`, `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`, `CACHE_LOCK_PATH`, `CACHE_LOCK_CODEX_PATH`, `CONFIG_PATH`, `CONFIG_LOCK_PATH`, `MIGRATION_ERROR_LOG_PATH`, `CHANGELOG_PATH`, all five `HOOK_TICK_*` paths, all six `UPDATE_*` paths, and `CLAUDE_SETTINGS_PATH`) from `bin/cctally` into `bin/_cctally_core.py`; `_cctally_core` is now the single source of truth and the single legal monkeypatch target for these names. `bin/cctally` keeps eager re-exports so external `cctally.X` references (ad-hoc REPL, scripts) still resolve, but internal `bin/cctally` reads (~28 sites) and every `bin/_*.py` sibling read (149 sites across 11 siblings) now go through `_cctally_core.X` at call time. `tests/conftest.py:redirect_paths()` patches `_cctally_core` directly (with an `ns["X"]` introspection mirror); the 80 historical `monkeypatch.setitem(ns, "<NAME>", v)` / `monkeypatch.setattr(cctally, "<NAME>", v)` test sites are migrated to `monkeypatch.setattr(_cctally_core, "<NAME>", v)`. `bin/_cctally_alerts.py` drops its `_cctally()` accessor helper (its only data-global use was `LOG_DIR`); other siblings keep the helper for legitimate non-data deps (validators, threshold constants, `PUBLIC_REPO`, `RELEASE_HEADER_RE`, etc.). The 2026-05-17 kernel-extraction spec's §2.3 path-constant accessor carve-out is retired. `tests/test_kernel_extraction_invariants.py` gains four new AST regression guards that lock the new invariants going forward (`test_promoted_globals_live_in_core`, `test_no_sibling_accessor_reads_promoted_globals`, `test_no_old_style_test_patches_for_promoted_globals`, `test_no_value_imports_of_promoted_globals_in_siblings`). (#84)
+
+## [1.11.0] - 2026-05-22
+
+### Added
+- Dashboard: new Cache Report panel and modal exposing the `cctally cache-report` anomaly + savings surface as an always-on watchdog — accent-teal border by default, flips to accent-amber when today crosses an anomaly trigger (`cache_drop` ≥ 15pp drop vs the 14-day median or `net_negative` (`net_usd < 0`)), with a 14-day cache hit % mini-sparkline and a 7-day "+$X saved · N ⚠ days" subline; click the panel for a modal with six sections in order — today's spotlight (status pill + inline stat row + reasons line on anomaly), the full 14-day cache hit % timeline (`CacheSparkline` large variant with a ±5pp tinted baseline band), per-day net $ stacked bars (saved-green + thin red wasted-segment on positive days, downward amber bar on net-negative days), a counterfactual callout ("without caching, you'd have paid +$X more · cache efficiency Y%"), the daily rows table with per-column header colorization (date neutral · cache % cyan · saved green · wasted red · net purple · flag amber), and by-project (magenta) + by-model (blue) breakdown sub-cards. Panel sits at the tail of `DEFAULT_PANEL_ORDER` (position 11) on fresh installs; existing users with a saved `panelOrder` get the panel appended by the existing `reconcilePanelOrder` migration. No new third-party dependencies (hand-rolled SVG for the timeline + bar chart). Envelope is additive + nullable on the `cache_report` field — `envelope_version` stays at 2.
+- Dashboard: `POST /api/settings` now accepts a `cache_report` block with key `anomaly_threshold_pp` (integer 1-100, default 15) — the modal's gear-icon settings popover round-trips through this endpoint and re-evaluates anomalies on the next sync. Invalid values return HTTP 400 with `{error, field}` (matching the existing settings-block validator convention); the popover surfaces the error inline under the input. The CLI's `cctally cache-report --anomaly-threshold-pp` flag is independent in v1 and continues to use its own default; the new `cache_report.anomaly_threshold_pp` config applies only to the dashboard sync path.
+- CSS: new `--accent-teal` design token (the 11th panel accent color) plus `.panel.accent-teal` rule following the same shape as the other nine accent variants, and a `.crm-*` namespace for the Cache Report modal chrome (spotlight sub-card, chart frames, counterfactual callout, daily-rows table with per-column header accents, breakdown sub-cards, settings popover). Pickup follow-up: the panel's mobile collapse (`< 720px`) is now driven by a `useIsMobile()` hook applying the `cache-report-collapsed` modifier class (Implementor B added the CSS rule but left the JS toggle unwired).
+
+### Fixed
+- CLI: `cctally cache-report` now buckets daily rows by the resolved `display.tz` instead of host-local. The pre-existing aggregator at `bin/cctally:2311` correctly resolved `display.tz` for `--since`/`--until` parsing but did NOT pass it to the day-bucketing path, so `--tz America/Los_Angeles` (or any non-host tz) shifted window edges without shifting the day-bucket dates rendered in the table. Threading an explicit `display_tz: ZoneInfo | None` parameter through `_aggregate_cache_by_day` closes the gap. Host-local hosts (the harness convention `TZ=Etc/UTC`) see no goldens change; non-UTC hosts may see day-bucket date strings shift by a day at midnight boundaries. Goldens regenerated via `bin/build-cache-report-fixtures.py`; aggregate per-day USD values are unchanged.
+- HelpOverlay: panels at position 11+ now render an em-dash for the keybind cell instead of a literal `'11'` `<kbd>` label. The digit hotkeys at `main.tsx:62-74` only route to positions 1-10 of the active `panelOrder`; rendering `String(idx + 1)` for `idx > 8` previously emitted a `'11'` chip that wasn't bound to anything. Positional rule, not panel-id-specific — whatever panel sits at position 11 (Cache Report by default; any panel after drag-reorder) renders the em-dash.
+- Dashboard Cache Report: panel chrome (border accent, header text color, "⚠ Today" header badge, sparkline today-marker color) no longer flips to amber during the baseline-building window (first 1–4 captured days). The server-side classifier can fire `net_negative` without a baseline, so `cr.today.anomaly_triggered` arrives true while `baseline_daily_row_count < CACHE_REPORT_MIN_BASELINE_DAYS` (5), but the watchdog is supposed to stay neutral until the 5-day floor exists. A new `chromeAmber = anomaly_triggered && !insufficient` gate at `CacheReportPanel.tsx` decouples the panel chrome from the headline copy — the modal's `.modal-card` accent mirrors the same gate so the panel-to-modal handoff stays teal during baseline-building. Round-2 Codex review finding (issue #77).
+- Dashboard Cache Report: by-project / by-model breakdown cards now aggregate only over the same calendar dates as the displayed 14-day table. The kernel's rolling window can emit 15 distinct display-tz buckets when `now_utc - 14d` and `now_utc` straddle midnight (any non-UTC `display.tz`); `days` was already sliced to `window_days` in `bin/_cctally_dashboard.py`, but the breakdown inputs (raw `entries` for by-project; `result.rows` for by-model) were not — the cards silently included the dropped oldest bucket and stopped reconciling against the visible table / `CacheNetBars`. A `kept_dates = {r.date for r in days}` filter on both sides closes the gap; regression at `tests/test_dashboard_envelope_cache_report.py::test_build_cache_report_snapshot_breakdowns_match_days_window`. Round-2 Codex review finding (issue #77).
+- Dashboard Cache Report modal: the daily-rows table's "Cache %" cell color now tracks each row's own `anomaly_reasons` instead of recomputing every row against today's `baseline_median_percent`. The server-side per-row classifier (`_cctally_cache_report._classify_anomalies`) uses `exclude_row=row` so each row has its own baseline; a window with five early 80% days followed by many 50% days kept the first 50% rows flagged `cache_drop` against the 80% reference, but the previous predicate (`d.cache_hit_percent < today.baseline_median_percent - CACHE_REPORT_BAND_PP`) painted them `hit-good` once today's median also drifted to 50% — green cells next to a ⚠ Flag column on the same row. Switching to `d.anomaly_reasons.includes('cache_drop')` keeps the cell color and the Flag column in lock-step regardless of how today's baseline moves; the `baselineKnown` neutral guard for the cold-start window is preserved. Round-2 Codex review finding (issue #77).
+- Dashboard Cache Report modal: spotlight pill, sub-card border, and reasons line no longer flip to amber `⚠ Anomaly` during the baseline-building window (first 1–4 captured days). The server-side classifier fires `net_negative` without a baseline so `cr.today.anomaly_triggered` arrives true while `baseline_daily_row_count < CACHE_REPORT_MIN_BASELINE_DAYS=5`, but the panel and the outer modal-card chrome already gate the amber flip behind `!insufficient`. `CacheReportSpotlight` checked `anomaly_triggered` before `insufficient`, so the spotlight contradicted the panel and modal-card by rendering ⚠ Anomaly on the same day the rest of the surface said "Building baseline". The pill precedence now puts `insufficient` first, mirroring the gate at `CacheReportPanel.tsx:147` and `CacheReportModal.tsx:111`. Round-3 Codex review finding.
+- Dashboard Cache Report modal settings: the anomaly-threshold popover now rejects fractional input (e.g. `1.5`, `15.9`, `1.0`, `15e2`) inline instead of silently truncating via `parseInt(value, 10)` and POSTing a different value than the user typed. The Save handler trims the input and matches against `/^-?\d+$/` before parsing, so any non-integer literal fails the existing `Must be an integer between 1 and 100` guard. `type="number"` does not block fractional typing/pasting on its own, and only the server previously rejected fractional values. Round-3 Codex review finding.
+- Dashboard Cache Report modal: daily-rows "Cache %" cell color now tracks the same ±`CACHE_REPORT_BAND_PP`=5 band the sparkline draws around today's baseline median, replacing the round-2 binding to `anomaly_reasons.includes('cache_drop')`. The previous binding used the configurable `anomaly_threshold_pp` (default 15) for cell color, so any day 6-14pp below baseline rendered green even though it visibly sat outside the sparkline's highlighted band; raising the configured threshold widened the gap further. The Flag column (`flag-warn` / `flag-ok`) stays bound to each row's own `anomaly_triggered`, so the two signals — display-band coloring vs. per-row anomaly classifier — now stay independent and each carries its own meaning. Round-3 Codex review finding.
+
 ## [1.10.3] - 2026-05-21
 
 ### Fixed

package/bin/_cctally_alerts.py

@@ -24,11 +24,11 @@ in `bin/_lib_alerts_payload.py` (Phase A extraction); this module
 imports them directly via `_load_lib`, which keeps the dispatch path
 free of an extra bounce through cctally's re-exports.
 
-bin/cctally back-references via `_cctally()` (spec §5.5 pattern, same
-as `bin/_cctally_setup.py`):
-- `LOG_DIR` — base dir under which `alerts.log` lives (subject to
-  HOME-redirection by test fixtures via `monkeypatch.setitem(ns,
-  "LOG_DIR", ...)`).
+Kernel reads from `bin/_cctally_core` (call-time module-attribute access):
+- `LOG_DIR` — base dir under which `alerts.log` lives. Promoted to
+  `_cctally_core` 2026-05-22 (#84); test fixtures redirect via
+  `monkeypatch.setattr(_cctally_core, "LOG_DIR", tmp)` (or the
+  conftest `redirect_paths()` helper).
 - `now_utc_iso` — single timestamp source used for both the log-line
   timestamp and the synthetic test payload's `crossed_at_utc`.
 
@@ -50,10 +50,7 @@ import pathlib
 import subprocess
 import sys
 
-
-def _cctally():
-    """Resolve the current `cctally` module at call-time (spec §5.5)."""
-    return sys.modules["cctally"]
+import _cctally_core
 
 
 def _load_lib(name: str):
@@ -77,22 +74,21 @@ _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_h
 
 
 # === Honest imports from extracted homes ===================================
-# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
-# import from _cctally_core. `LOG_DIR` stays on the _cctally() accessor
-# per Q1=B (path constants propagate via monkeypatch.setitem against the
-# cctally namespace).
+# Spec 2026-05-17 §3.3: kernel symbols import from _cctally_core.
+# LOG_DIR was promoted to _cctally_core 2026-05-22 (#84) and is read
+# via call-time module-attribute access (this sibling no longer needs
+# the historical _cctally() accessor).
 from _cctally_core import now_utc_iso
 
 
 def _alerts_log_path() -> "pathlib.Path":
     """Return ``~/.local/share/cctally/logs/alerts.log`` (parent dirs created).
 
-    Resolves through the same ``APP_DIR`` / ``LOG_DIR`` derived at module
-    import time from ``Path.home()``, so a HOME override before import (the
-    pattern used elsewhere in this codebase — e.g. ``cctally-config-test``)
-    transparently relocates the log without a separate env-var convention.
+    Reads ``LOG_DIR`` from ``_cctally_core`` at call time. Tests patch via
+    ``monkeypatch.setattr(_cctally_core, "LOG_DIR", tmp)`` (or the
+    conftest ``redirect_paths()`` helper).
     """
-    log_dir = _cctally().LOG_DIR
+    log_dir = _cctally_core.LOG_DIR
     log_dir.mkdir(parents=True, exist_ok=True)
     return log_dir / "alerts.log"
 

package/bin/_cctally_cache.py

@@ -41,21 +41,18 @@ Holds:
 - ``cmd_cache_sync`` — entry point for ``cctally cache-sync
   [--source {claude,codex,all}] [--rebuild]``.
 
-What stays in bin/cctally:
+What lives in bin/_cctally_core (promoted 2026-05-22, #84):
 - Path constants ``APP_DIR``, ``CACHE_DB_PATH``, ``CACHE_LOCK_PATH``,
-  ``CACHE_LOCK_CODEX_PATH``, ``CODEX_SESSIONS_DIR`` — referenced from
-  the moved bodies via the ``c = _cctally()`` call-time accessor
-  pattern (spec §5.5, same as ``bin/_lib_subscription_weeks.py`` and
-  ``bin/_lib_aggregators.py``). The accessor resolves
-  ``sys.modules['cctally'].X`` on every call, so
-  ``monkeypatch.setitem(ns, "CACHE_DB_PATH", tmp)`` and conftest
-  ``redirect_paths`` HOME redirects propagate transparently with NO
-  test-side changes (tests already patch ``ns["CACHE_DB_PATH"]`` etc.
-  by setitem on the dict-as-module bridge). We chose ``c.X`` over the
-  ``_cctally_db.py``-style seed block here because cache tests are
-  widely scattered (record-usage tick, dashboard panels, share render
-  kernel, block tests, every JSONL-reading subcommand fixture) and
-  Phase C-style inline patching would touch dozens of sites.
+  ``CACHE_LOCK_CODEX_PATH``. Moved bodies read these via call-time
+  ``_cctally_core.X`` and tests patch via
+  ``monkeypatch.setattr(_cctally_core, "X", v)`` (or the conftest
+  ``redirect_paths()`` helper). The legacy
+  ``setitem(ns, "CACHE_DB_PATH", …)`` pattern is forbidden by
+  ``test_no_old_style_test_patches_for_promoted_globals``.
+
+What stays in bin/cctally:
+- ``CODEX_SESSIONS_DIR`` — out of scope for #84; still read via the
+  ``c = _cctally()`` call-time accessor (spec §5.5).
 - ``_sum_cost_for_range`` — sits at the cache↔report boundary; 6+
   callers outside cache (forecast, weekly, report, project, doctor),
   so the directive keeps it on the bin/cctally side.
@@ -122,6 +119,7 @@ def _cctally():
 # Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
 # (Z-leaf + Z-mid) import from _cctally_core. The legacy shim function
 # for ``eprint`` is deleted.
+import _cctally_core
 from _cctally_core import eprint
 
 
@@ -175,11 +173,12 @@ _CACHE_MIGRATIONS = _cctally_db_sib._CACHE_MIGRATIONS
 
 
 # === BEGIN MOVED REGIONS ===
-# Path constants (APP_DIR, CACHE_DB_PATH, CACHE_LOCK_PATH,
-# CACHE_LOCK_CODEX_PATH, CODEX_SESSIONS_DIR) are accessed via the
-# `c = _cctally()` call-time accessor inside each function that
-# needs them — so ``monkeypatch.setitem(ns, "CACHE_DB_PATH", tmp)``
-# in tests resolves on every read (no stale module-level binding).
+# Path constants APP_DIR / CACHE_DB_PATH / CACHE_LOCK_PATH /
+# CACHE_LOCK_CODEX_PATH live in _cctally_core (promoted 2026-05-22, #84);
+# moved bodies read them via call-time ``_cctally_core.X`` and tests
+# patch via ``monkeypatch.setattr(_cctally_core, "X", v)``.
+# CODEX_SESSIONS_DIR stays in bin/cctally (out of scope for #84) and is
+# still accessed via the ``c = _cctally()`` call-time accessor.
 
 # === Region 1: ProjectKey + _resolve_project_key (was bin/cctally:1994-2069) ===
 
@@ -422,10 +421,10 @@ def sync_cache(
     """
     stats = IngestStats()
     c = _cctally()
-    c.APP_DIR.mkdir(parents=True, exist_ok=True)
-    c.CACHE_LOCK_PATH.touch()
+    _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
+    _cctally_core.CACHE_LOCK_PATH.touch()
 
-    lock_fh = open(c.CACHE_LOCK_PATH, "w")
+    lock_fh = open(_cctally_core.CACHE_LOCK_PATH, "w")
     try:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
@@ -914,10 +913,10 @@ def sync_codex_cache(
     """
     stats = CodexIngestStats()
     c = _cctally()
-    c.APP_DIR.mkdir(parents=True, exist_ok=True)
-    c.CACHE_LOCK_CODEX_PATH.touch()
+    _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
+    _cctally_core.CACHE_LOCK_CODEX_PATH.touch()
 
-    lock_fh = open(c.CACHE_LOCK_CODEX_PATH, "w")
+    lock_fh = open(_cctally_core.CACHE_LOCK_CODEX_PATH, "w")
     try:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
@@ -1263,17 +1262,17 @@ def open_cache_db() -> sqlite3.Connection:
     recreated — the cache is fully re-derivable from JSONL, so this is safe.
     """
     c = _cctally()
-    c.APP_DIR.mkdir(parents=True, exist_ok=True)
+    _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
     try:
-        conn = sqlite3.connect(c.CACHE_DB_PATH)
+        conn = sqlite3.connect(_cctally_core.CACHE_DB_PATH)
         conn.execute("SELECT 1").fetchone()
     except sqlite3.DatabaseError as exc:
         eprint(f"[cache] corrupt cache DB ({exc}); recreating")
         try:
-            c.CACHE_DB_PATH.unlink()
+            _cctally_core.CACHE_DB_PATH.unlink()
         except FileNotFoundError:
             pass
-        conn = sqlite3.connect(c.CACHE_DB_PATH)
+        conn = sqlite3.connect(_cctally_core.CACHE_DB_PATH)
 
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute("PRAGMA busy_timeout=5000")