cctally 1.101.0 → 1.103.0

package/bin/_cctally_forecast.py

@@ -82,7 +82,11 @@ def _ensure_sibling_loaded(name: str) -> None:
 
 
 _ensure_sibling_loaded("_lib_forecast")
-from _lib_forecast import ForecastInputs, BudgetRow, ForecastOutput, _compute_forecast
+from _lib_forecast import (
+    ForecastInputs, BudgetRow, ForecastOutput, _compute_forecast,
+    ForecastConfidenceAssessment, ForecastConfidenceCause,
+    assess_forecast_confidence,
+)
 
 # #279 S6 W4: the canonical None-safe UTC-Z serializer. forecast's former local
 # _iso_z (dt-only, no None guard) collapses to this single definition; the union
@@ -485,17 +489,23 @@ def _select_dollars_per_percent(
 
 
 def _assess_forecast_confidence(
-    elapsed_hours: float, p_now: float, snapshot_count: int
+    elapsed_hours: float, p_now: float, snapshot_count: int,
+    *, has_sample_ge_24h: bool = True,
 ) -> tuple[str, list[str]]:
-    """Binary confidence (spec §2)."""
-    reasons: list[str] = []
-    if elapsed_hours < 24:
-        reasons.append("elapsed_hours<24")
-    if p_now < 2:
-        reasons.append("percent<2")
-    if snapshot_count < 3:
-        reasons.append("snapshots<3")
-    return ("low", reasons) if reasons else ("high", [])
+    """Alias onto the pure predicate in `_lib_forecast` (#620 S2 E3).
+
+    Four import paths reach this name — `bin/cctally:1600`,
+    `bin/_cctally_record.py:427-428`, `bin/_cctally_record.py:1539` and
+    `tests/test_620_confidence_wording.py:141` — so it keeps its three
+    positional parameters and its `(confidence, list_of_reasons)` return
+    shape. `has_sample_ge_24h` defaults to True, which is what makes a
+    three-argument call emit exactly the three reasons it always did.
+    """
+    assessment = assess_forecast_confidence(
+        elapsed_hours, p_now, snapshot_count,
+        has_sample_ge_24h=has_sample_ge_24h,
+    )
+    return assessment.confidence, list(assessment.reasons)
 
 
 def _pick_p_24h_ago(
@@ -576,12 +586,12 @@ def _load_forecast_inputs(
         use_weekref_cost_cache=use_weekref_cost_cache,
         account_key=account_key,
     )
-    confidence, reasons = _assess_forecast_confidence(elapsed_hours, p_now, len(samples))
     target_24h = now_utc - dt.timedelta(hours=24)
     has_sample_ge_24h = any(s[0] <= target_24h for s in samples)
-    if not has_sample_ge_24h:
-        reasons = list(reasons) + ["no_sample_ge_24h"]
-        confidence = "low"
+    confidence, reasons = _assess_forecast_confidence(
+        elapsed_hours, p_now, len(samples),
+        has_sample_ge_24h=has_sample_ge_24h,
+    )
 
     return ForecastInputs(
         now_utc=now_utc,

package/bin/_cctally_parser.py

@@ -2385,6 +2385,89 @@ def _build_diff_parser(subparsers, name, *, help_text, xref=None, fixed_source=N
     _add_account_arg(diff_p)
     diff_p.set_defaults(func=c.cmd_diff)
 
+def _build_explain_parser(subparsers, name, *, help_text, xref=None):
+    """Build the `explain` parser (registered via _REGISTRATION; #620 S2).
+
+    `explain` deliberately does NOT adopt the shareable-output surface
+    (`--format`/`--theme`/`--output`/`--copy`/`--open`). That surface is a
+    separate concern with its own render kernel and byte-stability gates;
+    only `--reveal-projects` is shared, because privacy is part of what the
+    diagnosis publishes rather than part of how it is shared.
+    """
+    c = _cctally()
+    explain_p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Explain where locally retained usage went, over seven
+            contributor classes. Four are accounting-native: expensive model
+            mix, one project dominating, one session dominating, and
+            concentrated 5-hour bursts. Three are conversation-derived:
+            prompt-cache churn, short conversations carrying large context,
+            and subagent fan-out.
+
+            Each class reports a contributor when its top subject reaches the
+            classification floor of its named denominator, reports no
+            contributor when it is measured and nothing reaches the floor,
+            and withholds with a typed cause when it cannot be measured. The
+            classes overlap, so shares do not sum to 100 percent. Each class
+            states the rule in force, so a verdict can be reproduced rather
+            than inferred.
+
+            The three conversation-derived classes read the local transcript
+            store, so they are withheld where it is absent or unreadable.
+            Codex subagent attribution is derived from accounting metadata
+            and needs no transcript access.
+
+            Exit codes: 0 for a valid report, including a healthy one and one
+            whose fields are withheld; 2 for selector and usage errors; 3 for
+            a report-establishment failure.
+            """
+        ),
+    )
+    explain_p.add_argument(
+        # Defaulted to None rather than to the token itself, so the mutual
+        # exclusion below can tell "the user asked for a window" from "nobody
+        # said". `cmd_explain` resolves the absent case to `this-week`, which
+        # is what keeps the default behaviour and the --help text unchanged.
+        "--window", default=None,
+        help="Window token (this-week | last-week | Nw-ago | this-month | "
+             "last-month | Nm-ago | last-Nd | prev-Nd | "
+             "YYYY-MM-DD..YYYY-MM-DD). Default: this-week.",
+    )
+    # Exact instants, because date grammar cannot express the window a warning
+    # fired against: a five-hour block starts at an instant, not on a calendar
+    # day. This is the pair the dashboard route already accepts, and the pair
+    # every conversation-derived next step carries, so following one reproduces
+    # the population the row measured rather than a day that contains it.
+    explain_p.add_argument(
+        "--start-at", default=None, metavar="ISO",
+        help="Exact window start instant, inclusive (ISO 8601, e.g. "
+             "2026-08-10T00:00:00Z). Requires --end-at and cannot be "
+             "combined with --window.",
+    )
+    explain_p.add_argument(
+        "--end-at", default=None, metavar="ISO",
+        help="Exact window end instant, EXCLUSIVE (ISO 8601). Requires "
+             "--start-at and cannot be combined with --window.",
+    )
+    explain_p.add_argument("--json", dest="emit_json", action="store_true",
+        help="Emit the stamped JSON envelope instead of the terminal report.")
+    explain_p.add_argument(
+        "--reveal-projects", action="store_true", dest="reveal_projects",
+        help="Show derived project display labels instead of the default "
+             "project-1, project-2, ... anonymization. Never shows "
+             "filesystem paths, and never widens session identities.",
+    )
+    explain_p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
+        help="Display timezone: local, utc, or IANA name. "
+             "Overrides config display.tz for this call.")
+    _add_source_args(explain_p, speed=True)
+    _add_account_arg(explain_p)
+    explain_p.set_defaults(func=c.cmd_explain)
+
 def _build_claude_parser(subparsers, name, *, help_text, xref=None):
     """Build the `claude` parser (registered via _REGISTRATION; #279 S6 W3).
 
@@ -3743,6 +3826,7 @@ _REGISTRATION = (
     _Reg('alerts', _build_alerts_parser, "Manage threshold alerts", None, None),
     _Reg('setup', _build_setup_parser, "Install provider hooks/handlers + symlinks", None, None),
     _Reg('db', _build_db_parser, "Migration / DB management (status, skip, unskip)", None, None),
+    _Reg('explain', _build_explain_parser, "Explain where locally retained usage went, ranked with evidence", None, None),
     _Reg('doctor', _build_doctor_parser, "Diagnose data freshness and install state", None, None),
     _Reg('dashboard-perf', _build_dashboard_perf_parser, "Read a running dashboard's tick cost; arm its phase trace", None, None),
     _Reg('pricing-check', _build_pricing_check_parser, "Detect stale or missing embedded model pricing", None, None),

package/bin/_cctally_quota.py

@@ -194,6 +194,7 @@ PROJECTION_READ_CHOKEPOINTS: "frozenset[str]" = frozenset({
     "_cctally_quota.py::_orphan_unseen::quota_window_blocks",
     "_cctally_quota.py::_orphan_unseen_scoped::quota_window_blocks",
     "_cctally_quota.py::_apply_quota_projection_rows::quota_projection_state",
+    "_cctally_diagnosis_sources.py::<module>::quota_window_blocks",
 })
 
 #: What each enumerated site does about the gate.
@@ -246,6 +247,10 @@ PROJECTION_READ_SITE_ACTIONS: "dict[str, str]" = {
         "projector",
     "_cctally_quota.py::_apply_quota_projection_rows::quota_projection_state":
         "projector",
+    # `cctally explain` holds its Codex block SQL as a module-level constant,
+    # so the function that executes it gates instead.
+    "_cctally_diagnosis_sources.py::<module>::quota_window_blocks":
+        "gate_at_caller",
 }
 
 #: For each `gate_at_caller` site, the `<file>::<function>` callers that run the
@@ -274,6 +279,15 @@ PROJECTION_GATE_CALLERS: "dict[str, tuple[str, ...]]" = {
         "_cctally_tui.py::_tui_compute_dispatch_signature",
         "_cctally_dashboard_sources.py::_codex_quota_reuse_identity",
     ),
+    # Two functions in that module execute module-level SQL against
+    # `quota_window_blocks` — the block read and the observation-horizon read —
+    # and the scanner sees both as the one `<module>` site. Both are named,
+    # because "the horizon read is safe today because of call order" is not a
+    # property this guard can check, and a reordering would not fail it.
+    "_cctally_diagnosis_sources.py::<module>::quota_window_blocks": (
+        "_cctally_diagnosis_sources.py::_read_codex_blocks",
+        "_cctally_diagnosis_sources.py::_read_store_horizon",
+    ),
 }
 
 #: Dynamic-target read sites per file — a `FROM`/`JOIN` whose target is

package/bin/_cctally_record.py

@@ -173,8 +173,8 @@ import re
 import sqlite3
 import sys
 import time
-from dataclasses import dataclass
-from typing import Any
+from dataclasses import dataclass, field
+from typing import Any, Iterable
 
 
 def _cctally():
@@ -1509,11 +1509,12 @@ def _weekly_pct_week_avg_projection(conn, now_utc):
     binds the fired value to forecast's ``week_avg_projection_pct`` within
     1e-9, so the two MUST share the formula by construction.
 
-    LOW CONF mirrors the displayed forecast confidence: the binary
-    ``_assess_forecast_confidence(elapsed_hours, p_now, len(samples))`` plus the
-    ``no_sample_ge_24h`` clause ``_load_forecast_inputs`` appends — so a thin
-    early-week window that forecast renders ``LOW CONF`` never fires a
-    projected alert.
+    LOW CONF mirrors the displayed forecast confidence: ONE call to
+    ``_assess_forecast_confidence(elapsed_hours, p_now, len(samples),
+    has_sample_ge_24h=…)``, whose fourth trigger ``no_sample_ge_24h`` moved
+    inside the predicate with #620 S2 E3 — so a thin early-week window that
+    forecast renders ``LOW CONF`` never fires a projected alert, and glue no
+    longer appends a reason of its own.
 
     Deliberately does NOT call ``_sum_cost_for_range`` (the weekly-% projection
     needs no spend; the forecast kernel's ``week_avg_projection_pct`` is also
@@ -1534,15 +1535,14 @@ def _weekly_pct_week_avg_projection(conn, now_utc):
     r_avg = p_now / elapsed_hours if elapsed_hours > 0 else 0.0
     projected_pct = p_now + r_avg * remaining_hours
 
-    # Confidence: same predicate + the same no_sample_ge_24h augmentation that
-    # _load_forecast_inputs applies, so this LOW CONF gate == forecast's.
+    # Confidence comes from the predicate in one call, fourth trigger
+    # included, so this LOW CONF gate == forecast's and glue no longer
+    # downgrades a confidence the predicate returned (#620 S2 E3).
+    target_24h = now_utc - dt.timedelta(hours=24)
     confidence, _reasons = _assess_forecast_confidence(
-        elapsed_hours, p_now, len(samples)
+        elapsed_hours, p_now, len(samples),
+        has_sample_ge_24h=any(s[0] <= target_24h for s in samples),
     )
-    target_24h = now_utc - dt.timedelta(hours=24)
-    has_sample_ge_24h = any(s[0] <= target_24h for s in samples)
-    if not has_sample_ge_24h:
-        confidence = "low"
     return (projected_pct, confidence == "low")
 
 
@@ -1882,6 +1882,112 @@ def maybe_record_projected_alert(
                 eprint(f"[projected-alert] payload build failed: {build_exc}")
 
 
+@dataclass
+class PricedEntry:
+    """One accounting entry after pricing, as the block fold consumes it.
+
+    The canonical priced record: the fields `fold_block_totals` reads and
+    nothing else. `_compute_block_totals` builds these from
+    `_JoinedClaudeEntry` rows it has already priced; the diagnosis
+    (#620 S2) builds them from its own half-open account-scoped window.
+    """
+    model: str
+    project_path: str | None
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+    cost_usd: float
+
+
+@dataclass
+class BlockBucket:
+    """One model or project bucket inside a block's totals."""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_create_tokens: int = 0
+    cache_read_tokens: int = 0
+    cost_usd: float = 0.0
+    entry_count: int = 0
+
+    def as_legacy_dict(self) -> dict[str, Any]:
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cache_create_tokens": self.cache_create_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cost_usd": self.cost_usd,
+            "entry_count": self.entry_count,
+        }
+
+
+@dataclass
+class BlockTotals:
+    """The summed result of `fold_block_totals`."""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_create_tokens: int = 0
+    cache_read_tokens: int = 0
+    cost_usd: float = 0.0
+    entry_count: int = 0
+    by_model: dict[str, BlockBucket] = field(default_factory=dict)
+    by_project: dict[str, BlockBucket] = field(default_factory=dict)
+
+    def as_legacy_dict(self) -> dict[str, Any]:
+        """The exact dict `_compute_block_totals` has always returned.
+
+        Key order is preserved because callers and fixture builders read
+        this dict directly, and `entry_count` is deliberately absent at the
+        top level: it exists on the dataclass for the diagnosis, and adding
+        it here would change a shape every existing caller sees.
+        """
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cache_create_tokens": self.cache_create_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cost_usd": self.cost_usd,
+            "by_model": {k: v.as_legacy_dict() for k, v in self.by_model.items()},
+            "by_project": {k: v.as_legacy_dict() for k, v in self.by_project.items()},
+        }
+
+
+def fold_block_totals(entries: "Iterable[PricedEntry]") -> BlockTotals:
+    """Sum priced entries into block totals plus model and project buckets.
+
+    Pure: it opens nothing, prices nothing, and reads no clock. Summation
+    follows the iteration order of `entries`, and bucket insertion order
+    follows first appearance, both of which the callers observe.
+
+    A NULL `project_path` buckets under `(unknown)` so the reconcile
+    invariant `SUM(child.cost) == parent.total` continues to hold. The
+    JSONL-fallback loader always populates `project_path`, so `(unknown)`
+    only appears on the cache-backed path during the brief `session_files`
+    lazy-backfill window.
+    """
+    totals = BlockTotals()
+    for entry in entries:
+        totals.input_tokens += entry.input_tokens
+        totals.output_tokens += entry.output_tokens
+        totals.cache_create_tokens += entry.cache_creation_tokens
+        totals.cache_read_tokens += entry.cache_read_tokens
+        totals.cost_usd += entry.cost_usd
+        totals.entry_count += 1
+
+        for key, bucket_dict in (
+            (entry.model, totals.by_model),
+            (entry.project_path or "(unknown)", totals.by_project),
+        ):
+            b = bucket_dict.setdefault(key, BlockBucket())
+            b.input_tokens += entry.input_tokens
+            b.output_tokens += entry.output_tokens
+            b.cache_create_tokens += entry.cache_creation_tokens
+            b.cache_read_tokens += entry.cache_read_tokens
+            b.cost_usd += entry.cost_usd
+            b.entry_count += 1
+    return totals
+
+
 def _compute_block_totals(
     block_start_at: dt.datetime,
     range_end: dt.datetime,
@@ -1907,64 +2013,32 @@ def _compute_block_totals(
                                      cost_usd, entry_count}]
       by_project: dict[project_path_or_'(unknown)' -> same shape]
     """
-    totals: dict[str, Any] = {
-        "input_tokens": 0,
-        "output_tokens": 0,
-        "cache_create_tokens": 0,
-        "cache_read_tokens": 0,
-        "cost_usd": 0.0,
-        "by_model": {},
-        "by_project": {},
-    }
-    for entry in get_claude_session_entries(
-        block_start_at, range_end, skip_sync=skip_sync,
-    ):
-        usage = claude_usage_dict(   # #195 chokepoint
-            input_tokens=entry.input_tokens,
-            output_tokens=entry.output_tokens,
-            cache_creation_tokens=entry.cache_creation_tokens,
-            cache_read_tokens=entry.cache_read_tokens,
-            cache_1h_tokens=getattr(entry, "cache_1h_tokens", None),
-            speed=getattr(entry, "speed", None),
-        )
-        cost = _calculate_entry_cost(
-            entry.model, usage, mode="auto", cost_usd=entry.cost_usd,
-        )
-
-        totals["input_tokens"]        += entry.input_tokens
-        totals["output_tokens"]       += entry.output_tokens
-        totals["cache_create_tokens"] += entry.cache_creation_tokens
-        totals["cache_read_tokens"]   += entry.cache_read_tokens
-        totals["cost_usd"]            += cost
-
-        # Bucket by model and by project_path. NULL project_path → sentinel
-        # so reconcile invariant SUM(child.cost) == parent.total holds.
-        # Note: the JSONL-fallback path (_direct_parse_claude_session_entries)
-        # always populates project_path = cwd (never NULL); '(unknown)' only
-        # appears on the cache-backed path during the brief session_files
-        # lazy-backfill window.
-        for key, bucket_dict in (
-            (entry.model, totals["by_model"]),
-            (entry.project_path or "(unknown)", totals["by_project"]),
+    def _priced():
+        for entry in get_claude_session_entries(
+            block_start_at, range_end, skip_sync=skip_sync,
         ):
-            b = bucket_dict.setdefault(
-                key,
-                {
-                    "input_tokens": 0,
-                    "output_tokens": 0,
-                    "cache_create_tokens": 0,
-                    "cache_read_tokens": 0,
-                    "cost_usd": 0.0,
-                    "entry_count": 0,
-                },
+            usage = claude_usage_dict(   # #195 chokepoint
+                input_tokens=entry.input_tokens,
+                output_tokens=entry.output_tokens,
+                cache_creation_tokens=entry.cache_creation_tokens,
+                cache_read_tokens=entry.cache_read_tokens,
+                cache_1h_tokens=getattr(entry, "cache_1h_tokens", None),
+                speed=getattr(entry, "speed", None),
             )
-            b["input_tokens"]        += entry.input_tokens
-            b["output_tokens"]       += entry.output_tokens
-            b["cache_create_tokens"] += entry.cache_creation_tokens
-            b["cache_read_tokens"]   += entry.cache_read_tokens
-            b["cost_usd"]            += cost
-            b["entry_count"]         += 1
-    return totals
+            cost = _calculate_entry_cost(
+                entry.model, usage, mode="auto", cost_usd=entry.cost_usd,
+            )
+            yield PricedEntry(
+                model=entry.model,
+                project_path=entry.project_path,
+                input_tokens=entry.input_tokens,
+                output_tokens=entry.output_tokens,
+                cache_creation_tokens=entry.cache_creation_tokens,
+                cache_read_tokens=entry.cache_read_tokens,
+                cost_usd=cost,
+            )
+
+    return fold_block_totals(_priced()).as_legacy_dict()
 
 
 def maybe_update_five_hour_block(