cctally 1.100.0 → 1.102.0

package/bin/_lib_snapshot_cache.py

@@ -1549,14 +1549,58 @@ _PROJECTS_ENV_LAST_SEEN: dict = {}    # {"max_id", "max_wus_id", "sf_sig"}
 _PROJECTS_ENV_CURRENT: dict = {"state": None}  # single-slot current-week fold
 
 
-def projects_env_week_key(week_start):
-    """Canonical UTC-ISO key for a Monday-anchored subscription week start.
+_PROJECTS_ENV_KEY_SEP = "|"
 
-    The dashboard resolves week starts as aware-UTC datetimes; normalizing to
+
+def projects_env_week_key(week_start, week_end=None):
+    """Canonical UTC-ISO identity for one subscription-week INTERVAL.
+
+    #620 S1: the key carries both bounds, not the start alone. This cache was
+    structurally seven-day — the start was the whole identity and
+    ``reconcile_projects_env_cache`` reconstructed the end as ``start + 7d``
+    — which was sound only while a week could not move. Once the Projects
+    panel follows real reset instants, an early reset delivered mid-week ends
+    a week sooner without moving its start, so a start-keyed entry answers
+    with an aggregate folded over a window that no longer exists. Carrying
+    the end makes that a MISS, which is the invalidation: the week is
+    recomputed over its new interval and re-stored under its new identity.
+
+    ``week_end=None`` means the nominal seven-day week, so every pre-existing
+    single-argument caller keeps its exact meaning.
+
+    The dashboard resolves week bounds as aware-UTC datetimes; normalizing to
     UTC before serializing keeps the key stable and parseable back by
-    ``reconcile_projects_env_cache`` (for the ``week_end`` watermark compare).
+    ``projects_env_week_bounds`` (for the watermark compare).
+    """
+    start = week_start.astimezone(dt.timezone.utc)
+    end = (
+        start + dt.timedelta(days=7) if week_end is None
+        else week_end.astimezone(dt.timezone.utc)
+    )
+    return f"{start.isoformat()}{_PROJECTS_ENV_KEY_SEP}{end.isoformat()}"
+
+
+def projects_env_week_bounds(week_iso):
+    """Parse a key produced by ``projects_env_week_key`` back to
+    ``(start, end)``, or ``None`` when it is not one.
+
+    Returning ``None`` rather than raising is deliberate: the watermark
+    eviction below treats an unparseable key as dirty, and over-eviction is
+    byte-safe (the week is simply recomputed) while a raised exception on the
+    sync thread is not.
     """
-    return week_start.astimezone(dt.timezone.utc).isoformat()
+    if not isinstance(week_iso, str):
+        return None
+    start_s, sep, end_s = week_iso.partition(_PROJECTS_ENV_KEY_SEP)
+    if not sep:
+        return None
+    try:
+        return (
+            dt.datetime.fromisoformat(start_s),
+            dt.datetime.fromisoformat(end_s),
+        )
+    except ValueError:
+        return None
 
 
 def reset_projects_env_state():
@@ -1819,11 +1863,20 @@ def reconcile_projects_env_cache(cache_conn, *, max_entry_id, max_mutation_seq,
     ):
         # NOTE (#271 §9): max_wus_id is deliberately NOT a full-clear trigger. The
         # cached per-(project, week) aggregates are session_entries-only; a WUS
-        # bump (a `record-usage` write) changes only the attribution denominator,
+        # bump (a `record-usage` write) changes the attribution denominator,
         # which the whole-envelope memo (_PROJECTS_ENV_MEMO, still keyed on
-        # max_wus_id) recomputes fresh on its own miss. Reusing this cost cache
-        # across a WUS bump is byte-identical. Do NOT re-add
+        # max_wus_id) recomputes fresh on its own miss. Do NOT re-add
         # `max_wus_id != ls["max_wus_id"]` here.
+        #
+        # #620 S1 amends the REASON, not the decision. A WUS bump can now also
+        # move a week BOUNDARY, because the Projects panel follows real reset
+        # instants — so the old justification ("a WUS bump changes only the
+        # denominator") is no longer true. A full clear is still unnecessary,
+        # because the cache identity now carries the interval: a moved
+        # boundary produces a different key, which misses and recomputes,
+        # while every week whose interval did not move stays a legitimate hit.
+        # That is a strictly narrower invalidation than a full clear and is
+        # what keeps a `record-usage` write from re-folding twelve weeks.
         _PROJECTS_ENV_WEEK_CACHE.clear()
         _PROJECTS_ENV_WEEK_TOTALS.clear()
         # #271 M4 (spec §20): the current-week accumulator rides the SAME
@@ -1838,11 +1891,16 @@ def reconcile_projects_env_cache(cache_conn, *, max_entry_id, max_mutation_seq,
     if max_mutation_seq > ls["max_seq"]:
         wm = changed_min_timestamp(cache_conn, ls["max_seq"])
         if wm is not None:
-            dirty = [
-                wk
-                for wk in list(_PROJECTS_ENV_WEEK_TOTALS)
-                if dt.datetime.fromisoformat(wk) + dt.timedelta(days=7) >= wm
-            ]
+            # #620 S1: the week's real end comes off the key rather than being
+            # reconstructed as `start + 7d`, because a drifted reset day makes
+            # a genuinely short week and a `+7d` reconstruction would compare
+            # the wrong instant. An unparseable key is treated as dirty;
+            # over-eviction is byte-safe (the week is recomputed).
+            dirty = []
+            for wk in list(_PROJECTS_ENV_WEEK_TOTALS):
+                bounds = projects_env_week_bounds(wk)
+                if bounds is None or bounds[1] >= wm:
+                    dirty.append(wk)
             for wk in dirty:
                 _PROJECTS_ENV_WEEK_TOTALS.pop(wk, None)
                 for key in [k for k in _PROJECTS_ENV_WEEK_CACHE if k[1] == wk]:

package/bin/_lib_source_identity.py

@@ -2,14 +2,61 @@
 from __future__ import annotations
 
 import base64
+import contextlib
+import contextvars
 import hashlib
 import json
+import os
 import re
 
 
 IDENTITY_VERSION = 1
 _SOURCES = frozenset(("claude", "codex"))
 _SOURCE_ROOT_KEY_RE = re.compile(r"[0-9a-f]{32}\Z")
+_IDENTITY_PATH_ALIAS = contextvars.ContextVar(
+    "cctally_identity_path_alias", default=None,
+)
+
+
+@contextlib.contextmanager
+def identity_path_alias(physical_root: object, logical_root: object):
+    """Temporarily map one physical fixture root to a stable logical root.
+
+    Production callers never enter this context.  The generated benchmark
+    corpus does so when a byte-stable cross-platform oracle needs provider and
+    file identities that do not change merely because macOS resolves ``/tmp``
+    through ``/private/tmp``.  The mapping is boundary-aware and scoped through
+    a ContextVar so nested callers restore the previous identity exactly.
+    """
+    physical = os.path.normpath(os.fspath(physical_root))
+    logical = os.path.normpath(os.fspath(logical_root))
+    if not os.path.isabs(physical) or not os.path.isabs(logical):
+        raise ValueError("identity path aliases must use absolute roots")
+    token = _IDENTITY_PATH_ALIAS.set((physical, logical))
+    try:
+        yield
+    finally:
+        _IDENTITY_PATH_ALIAS.reset(token)
+
+
+def identity_path(value: str) -> str:
+    """Return the active logical spelling for an identity-bearing path.
+
+    This is deliberately a no-op outside ``identity_path_alias``.  Oracle
+    renderers use it at the last path-bearing identity seam; ordinary runtime
+    callers therefore retain their existing physical-path identity contract.
+    """
+    alias = _IDENTITY_PATH_ALIAS.get()
+    if alias is None:
+        return value
+    physical, logical = alias
+    normalized = os.path.normpath(value)
+    if normalized == physical:
+        return logical
+    prefix = physical + os.sep
+    if normalized.startswith(prefix):
+        return logical + normalized[len(physical):]
+    return value
 
 
 def _required_string(value: object, name: str) -> str:
@@ -20,7 +67,7 @@ def _required_string(value: object, name: str) -> str:
 
 def source_root_key(canonical_root: str) -> str:
     """Return the non-reversible, domain-separated key for one source root."""
-    root = _required_string(canonical_root, "canonical_root")
+    root = identity_path(_required_string(canonical_root, "canonical_root"))
     digest = hashlib.sha256(b"cctally-source-root-v1\0" + root.encode("utf-8"))
     return digest.hexdigest()[:32]
 
@@ -41,7 +88,8 @@ def codex_file_key(root_key: str, canonical_physical_path: str) -> str:
     durable key never embeds an operator path.
     """
     root = _required_string(root_key, "root_key")
-    path = _required_string(canonical_physical_path, "canonical_physical_path")
+    path = identity_path(
+        _required_string(canonical_physical_path, "canonical_physical_path"))
     digest = hashlib.sha256(
         b"cctally-codex-file-v1\0" + root.encode("utf-8")
         + b"\0" + path.encode("utf-8")

package/bin/_lib_subscription_weeks.py

@@ -279,6 +279,71 @@ def _apply_reset_events_to_subweeks(
     return out
 
 
+def subscription_window_probe_range(
+    anchor_utc: "dt.datetime", weeks_back: int,
+) -> "tuple[dt.datetime, dt.datetime]":
+    """The generous ``[range_start, range_end)`` to compute subscription
+    weeks over when the caller wants ``weeks_back`` intervals ending at the
+    one containing ``anchor_utc``.
+
+    ONE definition, shared by the dashboard Projects panel and by
+    ``cctally project``. The range matters beyond covering the answer:
+    ``_compute_subscription_weeks`` picks its extrapolation anchor relative
+    to ``range_start``, so two callers asking the same question over
+    different ranges can receive differently-phased intervals for the same
+    pre-snapshot history.
+
+    The lower bound allows one extra week because the anchor's own interval
+    can start up to a week before an ISO-Monday snap of it; the upper bound
+    allows two so the containing interval is always emitted whole.
+    """
+    base = anchor_utc.astimezone(dt.timezone.utc)
+    monday = (base - dt.timedelta(days=base.weekday())).replace(
+        hour=0, minute=0, second=0, microsecond=0,
+    )
+    return (monday - dt.timedelta(days=7 * (weeks_back + 1)),
+            monday + dt.timedelta(days=14))
+
+
+def subscription_window_ending_at(
+    bounds: "list[tuple[dt.datetime, dt.datetime]]",
+    cw_start: "dt.datetime",
+    weeks_back: int,
+) -> "list[tuple[dt.datetime, dt.datetime]]":
+    """The last ``weeks_back`` intervals up to and including the one starting
+    at ``cw_start``, oldest first.
+
+    ONE definition, shared by the dashboard Projects panel
+    (``_ProjectsWeekGrid.window_ending_at``) and by ``cctally project``, so
+    the two surfaces cannot resolve different windows for the same request.
+    ``cmd_project`` used to step back in seven-day multiples instead, which
+    is short of the truth by the accumulated shortfall of every drifted week
+    in the window — one day per six-day week — and the leading extrapolated
+    slice covering that deficit then carried real cost, moved the
+    ``usedPercent`` denominator by a whole extra week, and drove a rendered
+    note claiming a week had no usage snapshot.
+
+    ``bounds`` must be sorted by start. When fewer than ``weeks_back``
+    intervals sit at or before ``cw_start``, the head is padded backwards in
+    seven-day steps: that padding is a genuine no-anchor tail — history older
+    than any snapshot — so the seven-day assumption is the right one there.
+
+    Returns ``[]`` when ``cw_start`` is not itself an interval start in
+    ``bounds``; a caller that cannot locate its own anchor must not silently
+    receive a window anchored somewhere else.
+    """
+    starts = [b[0] for b in bounds]
+    idx = bisect.bisect_right(starts, cw_start) - 1
+    if idx < 0 or starts[idx] != cw_start:
+        return []
+    lo = max(0, idx + 1 - weeks_back)
+    window = [(bounds[i][0], bounds[i][1]) for i in range(lo, idx + 1)]
+    while len(window) < weeks_back:
+        s = window[0][0] - dt.timedelta(days=7)
+        window.insert(0, (s, window[0][0]))
+    return window
+
+
 def _compute_subscription_weeks(
     conn: sqlite3.Connection,
     range_start: dt.datetime,

package/bin/cctally

@@ -93,8 +93,10 @@ def _load_sibling(name: str):
     `_lib_transcript_access.transcripts_allowed`), then self-heal once the body
     finished. `_SIBLING_LOCK` serializes the load so a concurrent caller blocks
     until the body completes; `_LOADED_SIBLINGS` gates a lock-free fast path for
-    already-loaded siblings. Fail-closed by construction — a race waits, it never
-    returns a partial module early.
+    already-loaded siblings and retains the completed object owned by this
+    cctally module generation. Fail-closed by construction — a race waits, it
+    never returns a partial module early or adopts one registered by a newer
+    test-loader generation.
 
     For `_cctally_*.py` siblings that back-reference `cctally`, the sibling
     module exposes a `_cctally()` accessor that reads `sys.modules['cctally']`
@@ -115,19 +117,23 @@ def _load_sibling(name: str):
     # _load_sibling closure — regardless of pytest re-imports.
     sys.modules["cctally"] = _THIS_MODULE
     # Fast path: a sibling whose body has FULLY executed is returned without
-    # contending on the load lock. `_LOADED_SIBLINGS` is only ever added to,
-    # after a successful exec_module (below), so its membership is a stable
-    # "complete" signal — keeping the hot path lock-free for the ~50 sequential
-    # sibling loads at CLI startup and every warm request-thread lazy-load.
-    if name in _LOADED_SIBLINGS:
-        return sys.modules[name]
+    # contending on the load lock. The mapping is populated only after a
+    # successful exec_module (below), so its value is both a stable "complete"
+    # signal and the exact module object this cctally generation completed.
+    # Tests deliberately replace sys.modules entries between load_script()
+    # generations while older request threads may still run; consulting the
+    # process-global entry here would let an old loader adopt a newer partial.
+    loaded = _LOADED_SIBLINGS.get(name)
+    if loaded is not None:
+        return loaded
     # Slow path — serialize the actual load (#306). Any concurrent caller blocks
     # here until the owning thread finishes exec_module and records the name
     # complete, so it can never observe the half-initialized module.
     with _SIBLING_LOCK:
         # Completed while we waited for the lock.
-        if name in _LOADED_SIBLINGS:
-            return sys.modules[name]
+        loaded = _LOADED_SIBLINGS.get(name)
+        if loaded is not None:
+            return loaded
         cached = sys.modules.get(name)
         if cached is not None:
             # Registered but not yet recorded complete. Under the lock this is
@@ -159,7 +165,7 @@ def _load_sibling(name: str):
             # broken module is never recorded complete (mirrors importlib).
             sys.modules.pop(name, None)
             raise
-        _LOADED_SIBLINGS.add(name)
+        _LOADED_SIBLINGS[name] = mod
         return mod
 
 
@@ -185,12 +191,12 @@ _THIS_MODULE = sys.modules.get(__name__) or sys.modules.get("cctally")
 # conversation-path siblings are lazy-loaded on those threads. `_SIBLING_LOCK`
 # serializes the actual load so a concurrent caller can never observe a module
 # that is registered in sys.modules but whose exec_module is still mid-body (the
-# pre-registration window below), and `_LOADED_SIBLINGS` records the names whose
-# bodies have fully executed, gating a lock-free fast path. RLock (not Lock) so a
-# circular import that re-enters _load_sibling on the SAME thread during
-# exec_module cannot self-deadlock.
+# pre-registration window below), and `_LOADED_SIBLINGS` records the completed
+# module objects, gating a lock-free and generation-local fast path. RLock (not
+# Lock) lets a circular import re-enter _load_sibling on the SAME thread during
+# exec_module without self-deadlocking.
 _SIBLING_LOCK = threading.RLock()
-_LOADED_SIBLINGS: set[str] = set()
+_LOADED_SIBLINGS: dict[str, object] = {}
 
 
 # Hook-tick non-path constants (Section 1 of onboarding spec).
@@ -204,6 +210,7 @@ SETUP_SYMLINK_NAMES = (
     "cctally-budget",
     "cctally-dashboard",
     "cctally-dollar-per-percent",
+    "cctally-explain",
     "cctally-five-hour-blocks",
     "cctally-five-hour-breakdown",
     "cctally-forecast",
@@ -404,6 +411,40 @@ project_linear = _lib_budget.project_linear
 calendar_month_window = _lib_budget.calendar_month_window
 calendar_week_window = _lib_budget.calendar_week_window
 
+# Diagnosis kernel (#620 S2): the pure classification layer behind
+# `cctally explain` and `GET /api/diagnosis`. Re-exported like the other
+# _lib_* kernels; the store adapter and the renderer are separate siblings.
+_lib_diagnosis = _load_sibling("_lib_diagnosis")
+DIAGNOSIS_CONTRACT_VERSION = _lib_diagnosis.DIAGNOSIS_CONTRACT_VERSION
+DIAGNOSIS_CONTRIBUTOR_SHARE_FLOOR = _lib_diagnosis.DIAGNOSIS_CONTRIBUTOR_SHARE_FLOOR
+DIAGNOSIS_SHARE_FLOOR_EPSILON = _lib_diagnosis.DIAGNOSIS_SHARE_FLOOR_EPSILON
+DIAGNOSIS_TIE_EPSILON_USD = _lib_diagnosis.DIAGNOSIS_TIE_EPSILON_USD
+CONTRIBUTOR_REGISTRY = _lib_diagnosis.CONTRIBUTOR_REGISTRY
+ContributorSpec = _lib_diagnosis.ContributorSpec
+ContributorRow = _lib_diagnosis.ContributorRow
+ClassResult = _lib_diagnosis.ClassResult
+DiagnosisReport = _lib_diagnosis.DiagnosisReport
+DiagnosisWindow = _lib_diagnosis.DiagnosisWindow
+Denominator = _lib_diagnosis.Denominator
+EvidenceField = _lib_diagnosis.EvidenceField
+PopulationCoverage = _lib_diagnosis.PopulationCoverage
+SubjectFacts = _lib_diagnosis.SubjectFacts
+ProviderResult = _lib_diagnosis.ProviderResult
+EstablishmentError = _lib_diagnosis.EstablishmentError
+EstablishmentFailure = _lib_diagnosis.EstablishmentFailure
+WithheldCause = _lib_diagnosis.WithheldCause
+BaselineOutcome = _lib_diagnosis.BaselineOutcome
+VerdictState = _lib_diagnosis.VerdictState
+OverallVerdict = _lib_diagnosis.OverallVerdict
+assess_confidence = _lib_diagnosis.assess_confidence
+support_shortfall = _lib_diagnosis.support_shortfall
+classify_class = _lib_diagnosis.classify_class
+rank_rows = _lib_diagnosis.rank_rows
+overall_verdict = _lib_diagnosis.overall_verdict
+build_provider_result = _lib_diagnosis.build_provider_result
+build_report = _lib_diagnosis.build_report
+unreadable_store_is_terminal = _lib_diagnosis.unreadable_store_is_terminal
+
 # CLAUDE_MODEL_CONTEXT_WINDOWS / …_DEFAULT_FAMILY moved to _cctally_statusline.py (re-exported below).
 
 _lib_display_tz = _load_sibling("_lib_display_tz")
@@ -484,6 +525,7 @@ _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
 _build_alert_payload_project_budget = _lib_alerts_payload._build_alert_payload_project_budget
 _build_alert_payload_codex_budget = _lib_alerts_payload._build_alert_payload_codex_budget
 _build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
+synthetic_preview_week_start = _lib_alerts_payload.synthetic_preview_week_start
 
 _lib_alert_dispatch = _load_sibling("_lib_alert_dispatch")
 resolve_notifier = _lib_alert_dispatch.resolve_notifier
@@ -503,6 +545,8 @@ _clamp_end_ats_to_next_start = _lib_subscription_weeks._clamp_end_ats_to_next_st
 _apply_overlap_clamp_to_subweeks = _lib_subscription_weeks._apply_overlap_clamp_to_subweeks
 _apply_reset_events_to_subweeks = _lib_subscription_weeks._apply_reset_events_to_subweeks
 _compute_subscription_weeks = _lib_subscription_weeks._compute_subscription_weeks
+subscription_window_ending_at = _lib_subscription_weeks.subscription_window_ending_at
+subscription_window_probe_range = _lib_subscription_weeks.subscription_window_probe_range
 
 # Codex quota-pool classification (#373).  A pure leaf: stdlib only, no
 # cctally imports, so `_lib_jsonl` can consume it without dragging in the
@@ -1116,6 +1160,12 @@ maybe_record_codex_budget_milestone = _cctally_record.maybe_record_codex_budget_
 maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
 _weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
 _compute_block_totals = _cctally_record._compute_block_totals
+# #620 S2 E2: the pure fold lifted out of _compute_block_totals, plus the
+# canonical priced record and bucket shapes it folds over.
+PricedEntry = _cctally_record.PricedEntry
+BlockBucket = _cctally_record.BlockBucket
+BlockTotals = _cctally_record.BlockTotals
+fold_block_totals = _cctally_record.fold_block_totals
 maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
 cmd_record_usage = _cctally_record.cmd_record_usage
 CreditPlan = _cctally_record.CreditPlan
@@ -1407,6 +1457,12 @@ legacy_project_labels = _cctally_dashboard.legacy_project_labels
 build_cached_claude_range_aggregates = (
     _cctally_dashboard.build_cached_claude_range_aggregates
 )
+capture_cached_claude_range_aggregates = (
+    _cctally_dashboard.capture_cached_claude_range_aggregates
+)
+build_cached_claude_range_aggregates_from_capture = (
+    _cctally_dashboard.build_cached_claude_range_aggregates_from_capture
+)
 reset_claude_range_aggregate_memo = (
     _cctally_dashboard.reset_claude_range_aggregate_memo
 )
@@ -1581,6 +1637,7 @@ cmd_range_cost = _cctally_reporting.cmd_range_cost   # parser: c.cmd_range_cost
 # here.
 _cctally_forecast = _load_sibling("_cctally_forecast")
 cmd_report = _cctally_forecast.cmd_report
+render_report_terminal = _cctally_forecast.render_report_terminal
 cmd_forecast = _cctally_forecast.cmd_forecast
 cmd_budget = _cctally_forecast.cmd_budget
 ForecastInputs = _cctally_forecast.ForecastInputs
@@ -2989,6 +3046,28 @@ cmd_diff                 = _cctally_diff.cmd_diff                  # parser: c.c
 _emit_diff_debug_samples = _cctally_diff._emit_diff_debug_samples  # test_debug_sample_emission mod._emit_diff_debug_samples
 
 
+# Eager re-export of bin/_cctally_diagnosis.py — the `explain` handler, the
+# ONE wire adapter both surfaces serialize through, and the canonical
+# projection their equivalence is defined over (#620 S2). MUST load after the
+# _lib_diff_kernel block above, because `explain` resolves its window through
+# the same `_parse_diff_window` grammar. The store adapter it calls stays
+# lazily loaded, so an ordinary `cctally` invocation never opens a database
+# it does not need.
+#
+# Measured 2026-08-19: loading this sibling costs 20.5 ms of the median
+# `cctally --version`, which is compiling this module plus `_lib_diagnosis`.
+# It stays EAGER anyway, for the reason recorded at the `_lib_diff_kernel`
+# block below: the test surface reaches these symbols by dict-key access on
+# `mod.__dict__`, which no lazy binding can serve, and spec §4.8 makes the
+# eager pattern mandatory rather than preferred. Recovering the 20 ms belongs
+# to a change that shortens `cctally`'s import path as a whole.
+_cctally_diagnosis = _load_sibling("_cctally_diagnosis")
+cmd_explain          = _cctally_diagnosis.cmd_explain               # parser: c.cmd_explain
+diagnosis_to_wire    = _cctally_diagnosis.diagnosis_to_wire
+canonical_projection = _cctally_diagnosis.canonical_projection
+render_diagnosis_terminal = _cctally_diagnosis.render_terminal
+
+
 # Provider-aware analytics deliberately wrap the established command entries
 # here, leaving their Claude implementation modules untouched below the branch.
 _cmd_project_claude = cmd_project
@@ -3567,6 +3646,14 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         return
     if command == "doctor":
         return
+    if command == "explain":
+        # Read-only diagnostic by contract (#620 S3, spec 5.1): every store it
+        # touches is opened `mode=ro`, and it must reach no update check, no
+        # telemetry beat and no configuration write. Without this early return
+        # `_spawn_background_update_check` writes `update-state.json` and
+        # `update.log` into a data directory the command only read from. Same
+        # rationale class as `doctor` and `pricing-check` below.
+        return
     if command == "pricing-check":
         # Read-only diagnostic (same rationale as doctor): load_config() would
         # call ensure_dirs() and write a stub config.json on a fresh HOME, and

package/bin/cctally-explain

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Thin wrapper: `cctally-explain` → `cctally explain`.
+# Mirrors `cctally-forecast` / `cctally-project` pattern.
+set -euo pipefail
+exec "$(dirname "$0")/cctally" explain "$@"

package/dashboard/static/assets/dashboardStream.shared-worker-1XTMV3nr.js

@@ -0,0 +1 @@
+(function(){function e(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function t(e){return typeof e==`number`&&Number.isSafeInteger(e)&&e>0}function n(t){if(!e(t)||t.envelope_version!==2||typeof t.generated_at!=`string`||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(t.generated_at)||!Number.isFinite(Date.parse(t.generated_at)))return!1;let n=t=>t==null||e(t);return e(t.header)&&n(t.current_week)&&n(t.forecast)&&n(t.trend)&&e(t.weekly)&&Array.isArray(t.weekly.rows)&&e(t.monthly)&&Array.isArray(t.monthly.rows)&&e(t.blocks)&&Array.isArray(t.blocks.rows)&&e(t.daily)&&Array.isArray(t.daily.rows)&&e(t.sessions)&&Array.isArray(t.sessions.rows)&&n(t.projects)&&e(t.display)&&Array.isArray(t.alerts)&&e(t.alerts_settings)}function r(n){return!e(n)||n.version!==1||!t(n.generation)?!1:n.type===`subscribe`||n.type===`suspend`||n.type===`resume`||n.type===`unsubscribe`}let i=new class{createEventSource;parse;ports=new Map;stream=null;lastSnapshot=null;deliveryGeneration=0;constructor(e,t=JSON.parse){this.createEventSource=e,this.parse=t}connect(e){this.ports.set(e,{port:e,active:!1,generation:0}),e.onmessage=t=>this.onPortMessage(e,t.data);try{e.start()}catch{this.ports.delete(e)}}onPortMessage(e,t){let n=this.ports.get(e);if(n==null||!r(t))return;let i=t;if(!(i.generation<=n.generation)){if(n.generation=i.generation,i.type===`unsubscribe`){this.ports.delete(e),this.reconcileStream();return}n.active=i.type===`subscribe`||i.type===`resume`,this.reconcileStream(),n.active&&this.stream!=null&&(n.port.postMessage({version:1,type:`ready`,generation:n.generation}),this.lastSnapshot!=null&&n.port.postMessage({version:1,type:`snapshot`,generation:n.generation,deliveryGeneration:this.lastSnapshot.deliveryGeneration,snapshot:this.lastSnapshot.snapshot}))}}reconcileStream(){let e=[...this.ports.values()].some(e=>e.active);e&&this.stream==null&&this.openStream(),!e&&this.stream!=null&&(this.stream.close(),this.stream=null)}openStream(){let e;try{e=this.createEventSource()}catch{this.broadcastError();return}this.stream=e,e.addEventListener(`update`,t=>{if(this.stream===e)try{let e=this.parse(t.data);if(!n(e))throw Error(`invalid dashboard envelope`);let r=e;this.deliveryGeneration+=1,this.lastSnapshot={snapshot:r,deliveryGeneration:this.deliveryGeneration};for(let e of this.ports.values())e.active&&e.port.postMessage({version:1,type:`snapshot`,generation:e.generation,deliveryGeneration:this.deliveryGeneration,snapshot:r})}catch{console.error(`Dashboard stream frame was rejected.`)}}),e.onerror=()=>{this.stream===e&&this.broadcastError()}}broadcastError(){for(let e of this.ports.values()){if(!e.active)continue;let t={version:1,type:`stream_error`,generation:e.generation};e.port.postMessage(t)}}}(()=>new EventSource(`/api/events`)),a=globalThis;a.onconnect=e=>{for(let t of e.ports)i.connect(t)}})();