cctally 1.82.0 → 1.83.0

package/bin/_cctally_update.py

@@ -1468,6 +1468,94 @@ def _resolved_install_target(state: dict, channel: str) -> "str | None":
     return None
 
 
+def _beta_refresh_fallback_message(state: dict) -> str:
+    """Actionable diagnostic for an install-time beta refresh failure."""
+    cached = state.get("latest_version")
+    status = state.get("check_status") or "fetch_failed"
+    detail = state.get("check_error")
+    reason = f"{status}: {detail}" if detail else str(status)
+    if cached:
+        return (
+            f"could not refresh beta update target ({reason}); using cached "
+            f"{cached}. Check npm registry access or rerun with "
+            "`cctally update --version X.Y.Z`."
+        )
+    return (
+        f"could not refresh beta update target ({reason}); no cached target "
+        "is available. Check npm registry access or rerun with "
+        "`cctally update --version X.Y.Z`."
+    )
+
+
+def _resolve_install_operation_target(
+    method: InstallMethod,
+    state: dict,
+    channel: str,
+    *,
+    explicit_version: "str | None",
+    persist_refresh: bool,
+) -> "tuple[str | None, dict, str | None]":
+    """Resolve one user-initiated install's truthful target.
+
+    Explicit pins and every non-beta-npm path are byte-preserving pass-throughs.
+    An unpinned npm beta operation resolves the live SemVer-max(beta, latest)
+    before no-op/downgrade decisions. Real installs reuse the canonical check
+    pipeline (including marker-first and last-known-good persistence); dry-runs
+    perform the same registry resolution against an in-memory state copy so
+    their no-mutation contract remains exact.
+
+    Returns ``(target, effective_state, warning)``. A failed refresh falls back
+    to the cached target when one exists and supplies an actionable warning.
+    """
+    c = _cctally()
+    if explicit_version is not None:
+        return (explicit_version, state, None)
+    if method.method != "npm" or channel != "beta":
+        return (c._resolved_install_target(state, channel), state, None)
+
+    effective = dict(state)
+    prior_cached_target = state.get("latest_version")
+    warning = None
+    if persist_refresh:
+        c._do_update_check()
+        effective = c._load_update_state() or effective
+        if effective.get("check_status") != "ok":
+            warning = _beta_refresh_fallback_message(effective)
+    else:
+        try:
+            latest, dist_tag = c._resolve_npm_channel_target("beta")
+            effective["latest_version"] = latest
+            effective["latest_version_channel"] = "beta"
+            effective["resolved_dist_tag"] = dist_tag
+        except UpdateCheckRateLimited as e:
+            effective["check_status"] = "rate_limited"
+            effective["check_error"] = str(e)[:200]
+        except (UpdateCheckNetworkError, UpdateCheckHTTPError) as e:
+            effective["check_status"] = "fetch_failed"
+            effective["check_error"] = str(e)[:200]
+        except UpdateCheckParseError as e:
+            effective["check_status"] = "parse_failed"
+            effective["check_error"] = str(e)[:200]
+        else:
+            effective["check_status"] = "ok"
+            effective["check_error"] = None
+        if effective.get("check_status") != "ok":
+            warning = _beta_refresh_fallback_message(effective)
+
+    # `_do_update_check` defaults a never-seen `latest_version` to the running
+    # version so banner formatting remains comparable. That synthetic value is
+    # not a last-known-good registry target and must not turn a failed first
+    # install-time refresh into a misleading successful no-op.
+    target = prior_cached_target if warning else effective.get("latest_version")
+    if target is None:
+        missing_cache_state = dict(effective)
+        missing_cache_state.pop("latest_version", None)
+        raise UpdateError(
+            _beta_refresh_fallback_message(missing_cache_state)
+        )
+    return (target, effective, warning)
+
+
 def _resolved_update_command(state: dict, config: "dict | None") -> str:
     """Channel-aware install command for the `--check` renderers / envelope.
 
@@ -1936,11 +2024,20 @@ def _do_update_install(
     channel = c.resolve_update_channel(config)
     state = c._load_update_state() or {}
 
-    # Beta resolves the exact target from the cached max(beta, latest); an
-    # explicit --version pin always wins (the deliberate override).
-    resolved_version = version
-    if resolved_version is None:
-        resolved_version = c._resolved_install_target(state, channel)
+    # A user-initiated bare beta operation refreshes before exact-target
+    # selection and before the no-op/downgrade guard. Dry-run resolves the same
+    # live target without writing state or the throttle marker.
+    resolved_version, state, refresh_warning = (
+        _resolve_install_operation_target(
+            method,
+            state,
+            channel,
+            explicit_version=version,
+            persist_refresh=not dry_run,
+        )
+    )
+    if refresh_warning:
+        print(f"Warning: {refresh_warning}", file=sys.stderr)
 
     # Downgrade refusal for a BARE (unpinned) install: no-op + exit 0 when
     # the resolved target is not SemVer-newer than the installed version.
@@ -2152,12 +2249,40 @@ class UpdateWorker:
         log_fd = None
         try:
             method = c._detect_install_method(mutate=True)
-            c._preflight_install(method, version)
+            config = c.load_config()
+            channel = c.resolve_update_channel(config)
+            state = c._load_update_state() or {}
+            resolved_version, _state, refresh_warning = (
+                _resolve_install_operation_target(
+                    method,
+                    state,
+                    channel,
+                    explicit_version=version,
+                    persist_refresh=True,
+                )
+            )
+            if refresh_warning:
+                self._emit(
+                    run_id,
+                    {"type": "stderr", "data": f"Warning: {refresh_warning}"},
+                )
+            if resolved_version is not None:
+                self._emit(
+                    run_id,
+                    {
+                        "type": "target",
+                        "version": resolved_version,
+                        "command": c._format_update_command(
+                            method.method, resolved_version
+                        ),
+                    },
+                )
+            c._preflight_install(method, resolved_version)
             _cctally_core.UPDATE_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
             lock_fd = c._acquire_update_lock()
             log_fd = open(_cctally_core.UPDATE_LOG_PATH, "a", encoding="utf-8")
             _log_update_event(log_fd, "INSTALL_START", method=method.method)
-            for step_name, cmd in c._build_update_steps(method, version):
+            for step_name, cmd in c._build_update_steps(method, resolved_version):
                 self._emit(run_id, {"type": "step", "name": step_name})
                 _log_update_event(log_fd, "STEP_START", name=step_name)
                 rc = c._run_streaming(
@@ -2176,7 +2301,7 @@ class UpdateWorker:
                     self._emit(run_id, {"type": "done", "success": False})
                     return
             _log_update_event(log_fd, "INSTALL_SUCCESS")
-            c._stamp_install_success_to_state(version, method)
+            c._stamp_install_success_to_state(resolved_version, method)
             entrypoint, exec_argv = c._resolve_execvp_target()
             self._emit(run_id, {"type": "execvp", "argv": exec_argv})
             try:

package/bin/_cctally_weekrefs.py

@@ -576,6 +576,7 @@ def _week_ref_has_reset_event(
 
 def _compute_cost_for_weekref(
     ref: WeekRef, *, skip_sync: bool = False, account_key: "str | None" = None,
+    as_of: "str | None" = None,
 ) -> float | None:
     """Live-compute USD cost over `ref`'s (possibly reset-adjusted) range
     straight from session_entries. Mirrors what cmd_sync_week writes into
@@ -588,6 +589,11 @@ def _compute_cost_for_weekref(
     once at the top of the rebuild); ``build_trend_view`` calls this once per
     reset-event week, so without the flag each reset week re-globbed the whole
     ``~/.claude/projects`` tree — the CPU peg the sync-once refactor removes.
+
+    ``as_of`` (#410 Task A) is the retained triggering observation clock. The
+    reset-adjusted range end is clamped to it before the cache query so this
+    alternate milestone-cost path has the same replay boundary as
+    ``compute_week_cost(as_of=...)``.
     """
     c = _cctally()
     if not ref.week_start_at or not ref.week_end_at:
@@ -599,6 +605,14 @@ def _compute_cost_for_weekref(
         return None
     if end <= start:
         return 0.0
+    if as_of is not None:
+        try:
+            retained_end = parse_iso_datetime(as_of, "asOf")
+        except ValueError:
+            return None
+        end = min(end, retained_end)
+        if end <= start:
+            return 0.0
     return c._sum_cost_for_range(
         start, end, mode="auto", skip_sync=skip_sync, account_key=account_key)
 

package/bin/_lib_aggregators.py

@@ -69,6 +69,8 @@ CodexEntry = _lib_jsonl.CodexEntry
 
 _lib_pricing = _load_lib("_lib_pricing")
 _calculate_entry_cost = _lib_pricing._calculate_entry_cost
+# #195: the single construction point for every cost-feeding usage dict.
+claude_usage_dict = _lib_pricing.claude_usage_dict
 _calculate_codex_entry_cost = _lib_pricing._calculate_codex_entry_cost
 _is_codex_fallback = _lib_pricing._is_codex_fallback
 
@@ -800,12 +802,14 @@ def _aggregate_claude_sessions(
             if entry.project_path:
                 sess["project_path"] = entry.project_path
 
-        usage = {
-            "input_tokens": entry.input_tokens,
-            "output_tokens": entry.output_tokens,
-            "cache_creation_input_tokens": entry.cache_creation_tokens,
-            "cache_read_input_tokens": entry.cache_read_tokens,
-        }
+        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=mode, cost_usd=entry.cost_usd)
 
         sess["input"] += entry.input_tokens

package/bin/_lib_cache_report.py

@@ -56,6 +56,52 @@ def _import_stable_sum():
 stable_sum = _import_stable_sum()
 
 
+def _import_pricing_kernel():
+    """Resolve the ``_lib_pricing`` symbols this kernel needs (#195/#413):
+    ``CACHE_WRITE_1H_MULTIPLIER`` (the derived 1-hour cache-write rate) and
+    ``claude_usage_dict`` (the single cost-feeding usage-dict constructor).
+
+    Same shape and same justification as ``_import_stable_sum`` above:
+    ``_lib_pricing`` is a PURE stdlib leaf with no sibling imports, so binding
+    it here is acyclic and leaves this kernel's purity contract (no I/O, no
+    logging, no environment reads, no SQLite) intact. In practice both loaders
+    of this file have already imported ``_lib_pricing``, so the ``sys.modules``
+    fast path is what runs; the path-load fallback exists for a bare
+    file-path load.
+    """
+    import sys
+    if "_lib_pricing" in sys.modules:
+        m = sys.modules["_lib_pricing"]
+        return (
+            m.CACHE_WRITE_1H_MULTIPLIER,
+            m._claude_fast_multiplier,
+            m.claude_usage_dict,
+        )
+    from pathlib import Path
+    import importlib.util
+    bin_dir = Path(__file__).resolve().parent
+    if str(bin_dir) not in sys.path:
+        sys.path.insert(0, str(bin_dir))
+    spec = importlib.util.spec_from_file_location(
+        "_lib_pricing", bin_dir / "_lib_pricing.py")
+    m = importlib.util.module_from_spec(spec)
+    sys.modules["_lib_pricing"] = m
+    try:
+        spec.loader.exec_module(m)
+    except Exception:
+        sys.modules.pop("_lib_pricing", None)
+        raise
+    return (
+        m.CACHE_WRITE_1H_MULTIPLIER,
+        m._claude_fast_multiplier,
+        m.claude_usage_dict,
+    )
+
+
+(CACHE_WRITE_1H_MULTIPLIER, _claude_fast_multiplier,
+ claude_usage_dict) = _import_pricing_kernel()
+
+
 # Anthropic's per-call >200K-tokens tier — kept in sync with bin/_lib_pricing.
 # Callers may override via the ``tiered_threshold`` kwarg.
 DEFAULT_TIERED_THRESHOLD = 200_000
@@ -232,13 +278,18 @@ def _compute_entry_cache_dollars(
     *,
     pricing: dict,
     tiered_threshold: int = DEFAULT_TIERED_THRESHOLD,
+    cache_1h_tokens: int | None = None,
+    speed=None,
 ) -> tuple[float, float, float]:
     """Return ``(saved_usd, wasted_usd, net_usd)`` for a single entry.
 
     ``saved_usd``  = ``cache_read_tokens × (base_rate − read_rate)``
         — what you'd have paid without caching.
-    ``wasted_usd`` = ``cache_creation_tokens × (create_rate − base_rate)``
-        — premium paid to write cache.
+    ``wasted_usd`` = the cache-WRITE premium over base input, priced by TTL
+        (#195): the 1-hour portion against ``2 ×`` base input, the REMAINDER
+        against today's create rate. ``cache_1h_tokens is None`` (split
+        unknown) and ``== 0`` (all-5m) both take the verbatim pre-#195
+        expression, so this stays byte-identical for every pre-split row.
     ``net_usd``    = ``saved_usd − wasted_usd``. Positive = caching helped.
 
     Applies Anthropic's per-call >200K-tokens tier (mirrors the
@@ -289,8 +340,29 @@ def _compute_entry_cache_dollars(
         "cache_creation_input_token_cost_above_200k_tokens",
     )
 
+    multiplier = (
+        _claude_fast_multiplier(model) if speed == "fast" else 1.0
+    )
+    if multiplier != 1.0:
+        base_for_read *= multiplier
+        read_rate *= multiplier
+        base_for_create *= multiplier
+        create_rate *= multiplier
+
     saved = cache_read_tokens * max(0.0, base_for_read - read_rate)
-    wasted = cache_creation_tokens * max(0.0, create_rate - base_for_create)
+    # #195: the write premium is TTL-dependent. Split the creation tokens the
+    # same way _cache_create_cost does — 1h portion against the 2x rate, the
+    # REMAINDER against today's create_rate — so Wasted $/Net $ cannot disagree
+    # with the total cost the pricing kernel reports. Cache reads remain 0.1x
+    # of the effective base rate, so fast mode scales their absolute savings.
+    h = 0 if cache_1h_tokens is None else max(
+        0, min(int(cache_1h_tokens), cache_creation_tokens))
+    if h == 0:
+        wasted = cache_creation_tokens * max(0.0, create_rate - base_for_create)
+    else:
+        rate_1h = base_for_create * CACHE_WRITE_1H_MULTIPLIER
+        wasted = (h * max(0.0, rate_1h - base_for_create)
+                  + (cache_creation_tokens - h) * max(0.0, create_rate - base_for_create))
     net = saved - wasted
     return (saved, wasted, net)
 
@@ -369,6 +441,10 @@ def _aggregate_cache_by_day(
         else:
             saved, wasted, net = _compute_entry_cache_dollars(
                 entry.model, create_tok, read_tok, pricing=pricing,
+                # #195: the normalized flat key the ingest chokepoint writes;
+                # absent on a pre-split row -> None -> unchanged pricing.
+                cache_1h_tokens=entry.usage.get("cache_creation_1h_input_tokens"),
+                speed=entry.usage.get("speed"),
             )
         models = day_model_buckets.setdefault(day_key, {})
         b = models.setdefault(entry.model, _Bucket())
@@ -522,12 +598,15 @@ def _aggregate_cache_by_session(
             mb_raw.cache_read_tokens += entry.cache_read_tokens
             mb_raw.cost += cost_calculator(
                 entry.model,
-                {
-                    "input_tokens": entry.input_tokens,
-                    "output_tokens": entry.output_tokens,
-                    "cache_creation_input_tokens": entry.cache_creation_tokens,
-                    "cache_read_input_tokens": entry.cache_read_tokens,
-                },
+                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,
+                    # getattr: duck-typed entry contract (see below).
+                    cache_1h_tokens=getattr(entry, "cache_1h_tokens", None),
+                    speed=getattr(entry, "speed", None),
+                ),
                 "auto",
                 entry.cost_usd,
             )
@@ -536,6 +615,13 @@ def _aggregate_cache_by_session(
                 entry.cache_creation_tokens,
                 entry.cache_read_tokens,
                 pricing=pricing,
+                # #195: getattr, not attribute access. This is a PURE kernel with
+                # a duck-typed entry contract — callers pass `_JoinedClaudeEntry`
+                # in production and lightweight stand-ins in tests, so a hard
+                # `.cache_1h_tokens` would break every stand-in. Default None ==
+                # split unknown, which prices exactly as before.
+                cache_1h_tokens=getattr(entry, "cache_1h_tokens", None),
+                speed=getattr(entry, "speed", None),
             )
             mb_raw.saved_usd += saved
             mb_raw.wasted_usd += wasted
@@ -813,6 +899,10 @@ def _aggregate_cache_breakdown(
                 getattr(e, "cache_creation_tokens", 0),
                 getattr(e, "cache_read_tokens", 0),
                 pricing=pricing,
+                # #195: getattr default None == split unknown, so an entry type
+                # that does not carry the split prices exactly as before.
+                cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
+                speed=getattr(e, "speed", None),
             )
         b.saved_usd += saved
         b.wasted_usd += wasted
@@ -921,6 +1011,8 @@ def aggregate_by_day_project(
         read_tok = getattr(e, "cache_read_tokens", 0)
         _s, _w, net = _compute_entry_cache_dollars(
             model, create_tok, read_tok, pricing=pricing,
+            cache_1h_tokens=getattr(e, "cache_1h_tokens", None),   # #195
+            speed=getattr(e, "speed", None),
         )
         nets.setdefault(k, []).append(net)
         t = toks.setdefault(k, [0, 0, 0])

package/bin/_lib_codex_pools.py

@@ -0,0 +1,82 @@
+"""Codex quota-pool classification (#373).
+
+A pure leaf module: stdlib only, no cctally imports. It lives apart from
+``_lib_quota.py`` so ``_lib_jsonl`` need not import the quota kernel (and
+``_lib_accounts`` through it) merely to classify a pool label, and so module
+load order in ``bin/cctally`` is unaffected.
+
+Spec: docs/superpowers/specs/2026-07-25-373-codex-foreign-pool-phantom-week.md
+"""
+from __future__ import annotations
+
+import json
+
+
+def codex_model_scoped_quota_pool(model: object) -> str | None:
+    """Return the native model pool when Codex documents it as separate.
+
+    GPT Codex Spark runs against its own allowance and does not consume the
+    standard Codex quota.  Accepts either the sticky rollout model or the
+    native ``limit_name``; both spell the pool the same way once normalized.
+    """
+    if not isinstance(model, str):
+        return None
+    normalized = model.strip().lower()
+    return normalized if "-codex-spark" in normalized else None
+
+
+def is_model_scoped_codex_quota(logical_limit_key: object, limit_name: object) -> bool:
+    """Whether a window sits outside account-level standard quota.
+
+    Two INDEPENDENT axes -- an unparseable key leaves the first unknown but
+    must still let the second fire.  ``limit_id`` is deliberately not an axis:
+    treating an unknown id as non-standard would demote the real account quota
+    the moment the provider renamed it (#373 spec §6 Q1).
+    """
+    if _key_has_model_pool(logical_limit_key):
+        return True
+    return codex_model_scoped_quota_pool(limit_name) is not None
+
+
+def _key_has_model_pool(logical_limit_key: object) -> bool:
+    if not isinstance(logical_limit_key, str):
+        return False
+    try:
+        payload = json.loads(logical_limit_key)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return False
+    return (
+        isinstance(payload, dict)
+        and isinstance(payload.get("modelPool"), str)
+        and bool(payload["modelPool"].strip())
+    )
+
+
+def codex_history_is_model_scoped(history, *, baseline=None) -> bool:
+    """Classify one QuotaHistory, reading the label from an AUTHORITATIVE
+    observation rather than from ``history.identity``.
+
+    ``build_history`` groups by identity equality and ``limit_id``/``limit_name``
+    are ``compare=False``, so ``history.identity`` retains whichever label was
+    seen FIRST.  The authority is the baseline observation when the caller has
+    one, else the latest physical observation.
+
+    ``history.identity`` is NEVER consulted for the label, not even as a
+    last-resort widening when the authority is unlabelled (#373 spec §7.1).
+    The retained identity is an artefact of iteration order, so reading it
+    would make the same two observations classify differently depending on the
+    order they arrived in — nondeterminism, not a safety net.  Unlabelled
+    evidence therefore fails closed to ``False`` (standard quota), a direction
+    that can only keep a window in the account cycle and never demote a real
+    one out of it.
+    """
+    identity = getattr(history, "identity", None)
+    if _key_has_model_pool(getattr(identity, "logical_limit_key", None)):
+        return True
+    authority = baseline
+    if authority is None:
+        physical = getattr(history, "physical_observations", ()) or ()
+        if physical:
+            authority = max(physical, key=lambda o: o.captured_at)
+    label = getattr(getattr(authority, "identity", None), "limit_name", None)
+    return codex_model_scoped_quota_pool(label) is not None