cctally 1.64.0 → 1.66.0

package/bin/_lib_pricing_check.py

@@ -162,6 +162,23 @@ def stale_allowlist_entries(allowlist, claude_tbl, codex_tbl, litellm_scoped) ->
     return stale
 
 
+def expired_allowlist_entries(allowlist, as_of_date) -> list:
+    """Return allowlist entries whose optional ``expires`` (``YYYY-MM-DD``) date
+    has PASSED as of ``as_of_date`` (a date/datetime or ISO string).
+
+    Date-derived, so it needs no network (runs offline too — #279 S7 W7): an
+    expired suppression is a signal to remove the entry / re-sync the embedded
+    snapshot even before LiteLLM has reverted, so the deliberate divergence
+    doesn't silently ossify past its stated cutover. An entry with no
+    ``expires`` field never expires. Comparison is strict — an entry expiring ON
+    a date is still valid THROUGH that date and only expired the day AFTER."""
+    as_of = str(as_of_date)[:10]
+    return [
+        e for e in (allowlist or [])
+        if e.get("expires") and str(e["expires"])[:10] < as_of
+    ]
+
+
 _CLAUDE_REQUIRED = ("input_cost_per_token", "output_cost_per_token",
                     "cache_creation_input_token_cost", "cache_read_input_token_cost")
 _CODEX_REQUIRED = ("input_cost_per_token", "cache_read_input_token_cost",
@@ -194,8 +211,13 @@ def check_table_shapes(claude_tbl, codex_tbl, zero_sentinels) -> list:
     return problems
 
 
-def pricing_issue_action(drift_present: bool, existing_open: bool) -> str:
-    """Decide the cron's GitHub-issue action. Pure; the YAML executes it."""
-    if drift_present:
+def pricing_issue_action(findings_present: bool, existing_open: bool) -> str:
+    """Decide the cron's GitHub-issue action. Pure; the YAML executes it.
+
+    ``findings_present`` is ANY actionable finding the cron tracks — value
+    drift, missing-from-us, OR (as of #279 S7 W7) a stale/expired allowlist
+    suppression. The name generalizes the former ``drift_present``; the
+    two-state machine is unchanged."""
+    if findings_present:
         return "update" if existing_open else "create"
     return "close" if existing_open else "noop"

package/bin/_lib_record.py

@@ -0,0 +1,179 @@
+"""Record write-path decision kernels for cctally.
+
+Pure-fn leaf (stdlib only, no I/O at import time): values in, decisions
+out. Every DB read, config load, accessor reach (``c.<constant>``,
+``c._is_reset_drop``, ``c._floor_to_ten_minutes``), SQL statement, file
+write, and ``eprint`` stays in the I/O glue in ``bin/_cctally_record.py``
+— this module never touches the ``cctally`` namespace. That single rule
+is what preserves the entire ns-patch surface of ``cmd_record_usage`` /
+``maybe_record_projected_alert`` while their decision cores move here.
+
+Each kernel mirrors the exact comparison operators of the fragment it was
+lifted from (``round(x, 1)`` on the HWM clamp, ``+ 1e-9`` snap on every
+percent/threshold crossing, inclusive band bounds) so behavior is
+byte-identical. Glue call site is named in each kernel's docstring.
+
+Spec: docs/superpowers/specs/2026-07-09-279-s4-record-kernelization-design.md
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# ── Fragment 1: --resets-at / --five-hour-resets-at plausibility band ──────
+def check_resets_at_plausibility(
+    epoch: int, now_epoch: int, *, past_slack_s: int, future_band_s: int
+) -> bool:
+    """Return True when ``epoch`` sits inside the inclusive plausibility band
+    ``[now_epoch - past_slack_s, now_epoch + future_band_s]``.
+
+    Glue call sites (``cmd_record_usage``): the 7d leg (day-scale slack;
+    out-of-band → eprint + exit 2) and the 5h leg (10-min-past / 6h-future;
+    out-of-band → drop the 5h fields and continue). The two leg-specific
+    eprint literals and the differing consequences stay in glue; only the
+    raw second-granularity band check moves here.
+    """
+    return now_epoch - past_slack_s <= epoch <= now_epoch + future_band_s
+
+
+# ── Fragment 2: weekly in-place-credit / reset-to-zero debounce ────────────
+FIRE_IMMEDIATE = "fire_immediate"
+CONFIRM_RESET = "confirm_reset"
+CLEAR_MARKER = "clear_marker"
+ARM_MARKER = "arm_marker"
+NO_ACTION = "none"
+
+
+@dataclass(frozen=True)
+class WeeklyDebounceDecision:
+    """Which weekly credit/reset-to-zero action ``cmd_record_usage``'s
+    same-week (``prior_end == cur_end``) branch should take. ``action`` is one
+    of the module constants FIRE_IMMEDIATE / CONFIRM_RESET / CLEAR_MARKER /
+    ARM_MARKER / NO_ACTION — mirroring the branch outcomes at the glue site."""
+    action: str
+
+
+def plan_weekly_credit_debounce(
+    prev_pct, new_pct, *, drop_threshold, zero_floor_pct, zero_min_drop_pct,
+    marker_armed, marker_baseline,
+):
+    """Classify the same-window weekly-credit debounce decision (glue call
+    site: ``cmd_record_usage`` under ``prior_end_canon == cur_end_canon`` and
+    ``prior_end_dt > now_utc and prior_pct is not None``).
+
+    Mirrors the branch structure exactly:
+      - ``big_drop`` (drop >= drop_threshold) → FIRE_IMMEDIATE (>=25pp goodwill
+        credit; fires now, never debounced; glue also clears any pending arm).
+      - else, marker armed for this window:
+          - ``new_pct <= marker_baseline / 2.0`` → CONFIRM_RESET (stayed low).
+          - else → CLEAR_MARKER (recovered toward baseline → transient zero).
+      - else, ``zero_only`` (not big_drop AND new_pct <= zero_floor_pct AND
+        drop >= zero_min_drop_pct) → ARM_MARKER (first ~0).
+      - else → NO_ACTION.
+
+    Glue reads the ``c._RESET_*`` constants + the marker file, computes
+    ``marker_armed`` (window-key match) and passes ``marker_baseline``
+    (marker[2] when armed), then executes the decided I/O.
+    """
+    drop = float(prev_pct) - float(new_pct)
+    big_drop = drop >= drop_threshold
+    zero_only = (
+        (not big_drop)
+        and float(new_pct) <= zero_floor_pct
+        and drop >= zero_min_drop_pct
+    )
+    if big_drop:
+        return WeeklyDebounceDecision(FIRE_IMMEDIATE)
+    if marker_armed:
+        if float(new_pct) <= marker_baseline / 2.0:
+            return WeeklyDebounceDecision(CONFIRM_RESET)
+        return WeeklyDebounceDecision(CLEAR_MARKER)
+    if zero_only:
+        return WeeklyDebounceDecision(ARM_MARKER)
+    return WeeklyDebounceDecision(NO_ACTION)
+
+
+# ── Fragment 3: 5h in-place-credit detection guard ─────────────────────────
+def plan_five_hour_credit(
+    prior_pct: float, new_pct: float, *, drop_threshold: float,
+    prior_resets_in_future: bool,
+) -> bool:
+    """Return True when a 5h in-place credit is detected (glue call site:
+    ``cmd_record_usage``'s 5h-detection block).
+
+    Mirrors the one-line guard ``prior_5h_resets_dt > now_utc and
+    (prior_5h_pct - five_hour_percent) >= threshold``. ``is_dup`` is NOT an
+    input (gate P3-7): it gates only the glue INSERT, while the pivots
+    (hwm-5h force-write, stale-replica DELETE) fire unconditionally once a
+    credit is detected — all of that stays in glue.
+    """
+    return prior_resets_in_future and (prior_pct - new_pct) >= drop_threshold
+
+
+# ── Fragment 4: reset-aware HWM clamp comparison ───────────────────────────
+def hwm_clamp_applies(incoming_pct: float, recorded_max_pct) -> bool:
+    """Return True when ``incoming_pct`` is below the reset-aware recorded MAX
+    at tenths granularity (``round(x, 1)`` on both sides), i.e. the clamp fires.
+
+    Glue call sites (``cmd_record_usage``), each with a DISTINCT consequence
+    the glue keeps: the 7d leg sets ``should_insert = False`` (suppresses the
+    row); the 5h leg — NESTED inside the 7d ``else:`` — clamps the value up
+    (``five_hour_percent = float(max_5h_row["v"])``) and never touches
+    ``should_insert``. ``recorded_max_pct`` is the MAX cell (may be ``None``
+    when there is no in-window row); the SELECTs (including
+    ``_reset_aware_floor``) stay in glue verbatim.
+    """
+    if recorded_max_pct is None:
+        return False
+    return round(incoming_pct, 1) < round(float(recorded_max_pct), 1)
+
+
+# ── Fragment 5 (residue): self-heal milestone-coverage predicate ───────────
+def milestone_coverage_owes(existing_max_threshold, floor: int) -> bool:
+    """Return True when the milestone ledger for the ACTIVE segment owes a
+    heal — no rows yet (``existing_max_threshold is None``) or the highest
+    recorded threshold sits below the latest floor.
+
+    The load-bearing decision repeated at BOTH self-heal milestone-coverage
+    probes in ``cmd_record_usage``'s dedup self-heal block (weekly Probe 1 and
+    the 5h probe's milestone-coverage else-leg). Glue runs the DB probes,
+    reduces each to ``existing_max_threshold`` (int or None), and OR-s the
+    result into ``need_milestone_heal`` / ``need_5h_heal``. The broader
+    ``assess_self_heal`` aggregate stays glue-only (gate P3-5): its need-flags
+    are thin residues interleaved with four nesting levels of DB probes and
+    the staleness checks (``block_row is None`` / ``last_observed <
+    captured``), which are not cleanly separable without moving I/O.
+    """
+    return existing_max_threshold is None or existing_max_threshold < floor
+
+
+# ── Fragment 6: hwm-7d / hwm-5h monotonic file step ────────────────────────
+def hwm_file_next(existing, incoming: float):
+    """Return the value to write to the HWM file, or ``None`` when the write
+    should be skipped (glue call sites: ``cmd_record_usage``'s hwm-7d and
+    hwm-5h writers).
+
+    Mirrors the real ``>=`` operator: write when ``incoming >= existing``
+    (equality rewrites the same bytes — the code writes, so this returns the
+    value, not None). ``existing is None`` (no prior value) always writes. The
+    file read/parse and the actual ``write_text`` stay in glue.
+    """
+    if existing is None or incoming >= existing:
+        return incoming
+    return None
+
+
+# ── Fragment 7: projected-pace alert threshold crossings ───────────────────
+def projected_crossings(value: float, levels) -> list:
+    """Return the threshold labels crossed by ``value`` at the ``+ 1e-9`` snap.
+
+    ``levels`` is a list of ``(threshold_label, comparand)`` pairs — glue
+    pre-scales each comparand per leg (weekly_pct: ``(t, float(t))``; the two
+    budget legs: ``(t, (t / 100.0) * float(target))``), so this kernel never
+    rescales. A label crosses when ``value + 1e-9 >= comparand``. Glue maps
+    the returned labels back into the per-leg ``pending.append(dict(...))``
+    bodies; the leg-level ``_projected_levels_already_latched`` pre-gate stays
+    in glue (gate P2-2 — it is a per-leg gate BEFORE the loop, not a
+    per-threshold filter).
+    """
+    return [t for (t, comparand) in levels if value + 1e-9 >= comparand]

package/bin/_lib_render.py

@@ -100,6 +100,11 @@ _short_model_name = _lib_pricing._short_model_name
 _lib_display_tz = _load_lib("_lib_display_tz")
 _resolve_tz = _lib_display_tz._resolve_tz
 
+# JSON wire-format kernel — the additive camelCase schemaVersion stamp
+# (#279 S6 W1; convention docs/cli-contract.md).
+_lib_json_envelope = _load_lib("_lib_json_envelope")
+stamp_schema_version = _lib_json_envelope.stamp_schema_version
+
 # fmt/color/table primitives honest-imported from _lib_fmt (#126 C11)
 _lib_fmt = _load_lib("_lib_fmt")
 _supports_color_stdout = _lib_fmt._supports_color_stdout
@@ -812,7 +817,8 @@ def _bucket_to_json(
     """
     bucket_list = [_daily_row_dict(d, date_key=date_key) for d in buckets]
     totals = _bucket_totals_dict(buckets)
-    return json.dumps({list_key: bucket_list, "totals": totals}, indent=2)
+    payload = stamp_schema_version({list_key: bucket_list, "totals": totals})
+    return json.dumps(payload, indent=2)
 
 
 def _bucket_by_project_to_json(project_groups, *, date_key: str = "date") -> str:
@@ -825,10 +831,9 @@ def _bucket_by_project_to_json(project_groups, *, date_key: str = "date") -> str
     for label, buckets in project_groups:
         projects[label] = [_daily_row_dict(b, date_key=date_key) for b in buckets]
         all_buckets.extend(buckets)
-    return json.dumps(
-        {"projects": projects, "totals": _bucket_totals_dict(all_buckets)},
-        indent=2,
-    )
+    payload = stamp_schema_version(
+        {"projects": projects, "totals": _bucket_totals_dict(all_buckets)})
+    return json.dumps(payload, indent=2)
 
 
 def _weekly_to_json(
@@ -912,7 +917,7 @@ def _weekly_to_json(
             "totalCost": tot_cost,
         },
     }
-    return json.dumps(payload, indent=2)
+    return json.dumps(stamp_schema_version(payload), indent=2)
 
 
 def _daily_compact_split(bucket: str) -> str:
@@ -976,7 +981,8 @@ def _emit_codex_no_data(args: argparse.Namespace, list_key: str) -> None:
     filter_applied = bool(getattr(args, "since", None) or getattr(args, "until", None))
     if getattr(args, "json", False):
         # Compact separators to match Node's `JSON.stringify(obj)` output exactly.
-        print(json.dumps({list_key: [], "totals": None}, separators=(",", ":")))
+        print(json.dumps(stamp_schema_version({list_key: [], "totals": None}),
+                         separators=(",", ":")))
     else:
         if filter_applied:
             print("No Codex usage data found for provided filters.")
@@ -1056,7 +1062,8 @@ def _codex_bucket_to_json(
         "totalTokens": tot_tokens,
         "costUSD": tot_cost,
     }
-    return json.dumps({list_key: bucket_list, "totals": totals}, indent=2)
+    payload = stamp_schema_version({list_key: bucket_list, "totals": totals})
+    return json.dumps(payload, indent=2)
 
 
 def _codex_root_short_labels(roots: list[str]) -> list[str]:
@@ -1161,7 +1168,8 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
         "totalTokens": tot_tokens,
         "costUSD": tot_cost,
     }
-    return json.dumps({"sessions": session_list, "totals": totals}, indent=2)
+    payload = stamp_schema_version({"sessions": session_list, "totals": totals})
+    return json.dumps(payload, indent=2)
 
 
 def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
@@ -1227,7 +1235,7 @@ def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
             "totalCost": tot_cost,
         },
     }
-    return json.dumps(payload, indent=2)
+    return json.dumps(stamp_schema_version(payload), indent=2)
 
 
 def _render_bucket_table(

package/bin/_lib_snapshot_cache.py

@@ -290,6 +290,47 @@ def current_generation() -> int:
         return _GENERATION
 
 
+# === Owner-thread tripwire (#279 S5 F6.3, spec §8) =========================
+# The snapshot caches are single-writer-AT-A-TIME, under ``sync_lock`` — NOT
+# "the periodic sync thread only": /api/sync and /api/settings legitimately
+# rebuild on REQUEST threads while holding the lock (gate P1-1). So ownership
+# means "the thread currently holding sync_lock for this rebuild", marked
+# overwrite-on-call at the entry of the locked rebuild body
+# (bin/_cctally_tui.py::_make_run_sync_now_locked._locked). Unarmed (never
+# marked) => _assert_owner is a NO-OP, so every existing test and the TUI
+# (which never arm) are untouched; a raise (not a log) on an armed foreign-
+# thread mutation is deliberate — silent cache corruption is the failure mode
+# being priced out.
+_OWNER_THREAD_IDENT: int | None = None
+
+
+def mark_owner_thread() -> None:
+    """Record the calling thread as the cache owner (overwrite-on-call).
+
+    Called at the entry of the locked rebuild body
+    (``_make_run_sync_now_locked._locked``) — ownership means "the thread
+    currently holding ``sync_lock``", NOT "the periodic sync thread":
+    /api/sync and /api/settings legitimately rebuild on request threads
+    (#279 S5 gate P1-1). Unarmed (never marked) => _assert_owner is a
+    no-op, so tests and the TUI need no changes.
+    """
+    global _OWNER_THREAD_IDENT
+    _OWNER_THREAD_IDENT = threading.get_ident()
+
+
+def reset_owner_thread() -> None:
+    global _OWNER_THREAD_IDENT
+    _OWNER_THREAD_IDENT = None
+
+
+def _assert_owner() -> None:
+    if _OWNER_THREAD_IDENT is not None and threading.get_ident() != _OWNER_THREAD_IDENT:
+        raise RuntimeError(
+            "snapshot-cache mutation from non-owner thread; rebuilds must "
+            "run under sync_lock (see mark_owner_thread)"
+        )
+
+
 # === Task 0.4 — Group A bucket cache holder ================================
 
 
@@ -431,6 +472,7 @@ def reset_group_a_state() -> None:
     cached bucket and reset the watermarks so the next rebuild recomputes
     from scratch (spec §7 / Codex F4).
     """
+    _assert_owner()
     _GROUP_A_CACHE.clear()
     _GROUP_A_LAST_SEEN.clear()
     reset_group_a_current_state()
@@ -470,6 +512,7 @@ _GROUP_A_CURRENT: "dict[str, CurrentBucketAccumulator]" = {}
 
 def reset_group_a_current_state() -> None:
     """Drop every builder's current-bucket accumulator (prune-site + full-invalidate)."""
+    _assert_owner()
     _GROUP_A_CURRENT.clear()
 
 
@@ -671,6 +714,7 @@ def build_cached_group_a(
     labels, fresh recompute for current + dirty), in ``all_bucket_labels``
     order, and updates this builder's last-seen state.
     """
+    _assert_owner()
     cur_max_id = _max_id(cache_conn, "session_entries")
     # #270 §7c: split max_id's two duties — the incremental watermark + "any
     # new work?" gate move to the O(1) `cache_meta` mutation counter (an
@@ -829,6 +873,7 @@ def reset_session_cache_state() -> None:
     cached session and reset the watermark so the next rebuild re-aggregates
     the whole window from scratch (spec §7 / Codex F4).
     """
+    _assert_owner()
     _SESSION_CACHE.clear()
     _SESSION_LAST_SEEN.clear()
 
@@ -863,6 +908,7 @@ def build_cached_sessions(
     its resolved ``session_id`` (which the aggregator sets to the stem for
     fallback sessions), so the cache keys match ``affected_session_keys``.
     """
+    _assert_owner()
     cur_max_id = _max_id(cache_conn, "session_entries")
     # #270 §7c/§7d: the warm "any new work?" gate + the affected-set query key
     # on the `mutation_seq` counter (an id-stable in-place finalization of an
@@ -997,6 +1043,7 @@ def store_dispatch_state(dispatch_key: object, snapshot: object) -> None:
     Called once per rebuild (idle or full) so the next tick compares against the
     key the just-published snapshot was built from.
     """
+    _assert_owner()
     global _LAST_DISPATCH_KEY, _LAST_PUBLISHED_SNAPSHOT
     _LAST_DISPATCH_KEY = dispatch_key
     _LAST_PUBLISHED_SNAPSHOT = snapshot
@@ -1010,6 +1057,7 @@ def reset_dispatch_state() -> None:
     part of the M5.2 prune invalidation — the generation bump (a signature leg)
     already forces the next rebuild off the idle path.
     """
+    _assert_owner()
     global _LAST_DISPATCH_KEY, _LAST_PUBLISHED_SNAPSHOT
     _LAST_DISPATCH_KEY = None
     _LAST_PUBLISHED_SNAPSHOT = None
@@ -1056,6 +1104,7 @@ def reset_weekref_cost_state():
     possibly WITHOUT lowering ``MAX(id)``, so the reconcile's max-id-regression
     check cannot catch it — the explicit clear must) and as a test hook.
     """
+    _assert_owner()
     _WEEKREF_COST_CACHE.clear()
     _WEEKREF_COST_LAST_SEEN.clear()
 
@@ -1116,6 +1165,7 @@ def reconcile_weekref_cache(cache_conn, *, max_entry_id, max_mutation_seq, reset
     ``max_mutation_seq > last_seen_seq`` branch; the caller passes a short-lived
     cache connection, opened for that query.
     """
+    _assert_owner()
     ls = _WEEKREF_COST_LAST_SEEN
     if not ls:  # cold
         ls["max_id"] = max_entry_id
@@ -1207,6 +1257,7 @@ def reset_projects_env_state():
     current-week slot rides this same clear (spec §20): a prune can re-key a
     current-week bucket_path, so it must cold-refold next tick.
     """
+    _assert_owner()
     _PROJECTS_ENV_WEEK_CACHE.clear()
     _PROJECTS_ENV_WEEK_TOTALS.clear()
     _PROJECTS_ENV_LAST_SEEN.clear()
@@ -1222,6 +1273,7 @@ def reset_projects_env_current_state():
     / prune / cache.db rebuild cold-refolds the current week the same tick the
     closed-week cache clears.
     """
+    _assert_owner()
     _PROJECTS_ENV_CURRENT["state"] = None
 
 
@@ -1283,6 +1335,7 @@ def projects_env_week_put(week_iso, buckets_by_bp, total) -> None:
     computed-empty week is a HIT (not a perpetual miss). Values are stored
     as-is (immutable); this never mutates a stored aggregate in place.
     """
+    _assert_owner()
     _PROJECTS_ENV_WEEK_TOTALS[week_iso] = total
     for bp, agg in buckets_by_bp.items():
         _PROJECTS_ENV_WEEK_CACHE[(bp, week_iso)] = agg
@@ -1354,6 +1407,7 @@ def accumulate_projects_current_week(*, week_key, cur_max_id, cur_max_seq,
     snapshot — ``finalize`` builds a FRESH bucket map each tick, so mutating
     ``mut`` next tick cannot tear a prior snapshot.
     """
+    _assert_owner()
     prior = _PROJECTS_ENV_CURRENT["state"]
     cold = (
         prior is None
@@ -1439,6 +1493,7 @@ def reconcile_projects_env_cache(cache_conn, *, max_entry_id, max_mutation_seq,
     watermark query). The short-lived ``cache_conn`` is used only for the
     watermark query on the ``max_mutation_seq > last_seen_seq`` branch (Codex-4).
     """
+    _assert_owner()
     ls = _PROJECTS_ENV_LAST_SEEN
     if not ls:  # cold
         ls["max_id"] = max_entry_id
@@ -1574,6 +1629,7 @@ def reset_bugk_segment_state():
     possibly WITHOUT lowering ``MAX(id)``, so the reconcile's max-id-regression
     check cannot catch it — the explicit clear must) and as a test hook.
     """
+    _assert_owner()
     _BUGK_SEGMENT_CACHE.clear()
     _BUGK_SEGMENT_LAST_SEEN.clear()
 
@@ -1630,6 +1686,7 @@ def reconcile_bugk_cache(cache_conn, *, max_entry_id, max_mutation_seq, reset_si
     ``changed_min_timestamp`` query on the ``max_mutation_seq > last_seen_seq``
     branch (Codex-4 lifecycle from §4).
     """
+    _assert_owner()
     ls = _BUGK_SEGMENT_LAST_SEEN
     if not ls:  # cold
         ls["max_id"] = max_entry_id
@@ -1682,6 +1739,7 @@ def reset_cache_report_state():
     as a test hook. Mirrors ``reset_bugk_segment_state`` /
     ``reset_projects_env_state``.
     """
+    _assert_owner()
     _CACHE_REPORT_DAY_CACHE.clear()
     _CACHE_REPORT_LAST_SEEN.clear()
 
@@ -1693,6 +1751,7 @@ def cache_report_day_get(date_key):
 
 def cache_report_day_store(date_key, value) -> None:
     """Store one CLOSED day's immutable ``CachedCacheReportDay`` (never mutated)."""
+    _assert_owner()
     _CACHE_REPORT_DAY_CACHE[date_key] = value
 
 
@@ -1711,6 +1770,7 @@ def cache_report_day_evict_before(oldest_key) -> None:
     byte-safe (a re-needed day just re-populates on the next cold tick), so the
     predicate is a plain lexical ``<`` on the ``YYYY-MM-DD`` keys.
     """
+    _assert_owner()
     for date_key in [d for d in _CACHE_REPORT_DAY_CACHE if d < oldest_key]:
         del _CACHE_REPORT_DAY_CACHE[date_key]
 
@@ -1762,6 +1822,7 @@ def reconcile_cache_report_cache(
        same-signature second call sees ``max_mutation_seq == last_seen_seq`` and
        no sig delta → no watermark re-query, no eviction.
     """
+    _assert_owner()
     ls = _CACHE_REPORT_LAST_SEEN
     if not ls:  # cold
         ls.update(

package/bin/_lib_transcript_access.py

@@ -55,6 +55,29 @@ def is_loopback(host: str) -> bool:
         return False
 
 
+def debug_backend_allowed(peer_ip, host) -> bool:
+    """Gate for the loopback-only ``/api/debug/backend`` diagnostic endpoint
+    (issue #276, Session A).
+
+    STRICTER than the transcript gate — it never opens to the LAN. Two checks:
+
+      * PRIMARY: the TCP peer (``client_address[0]``) must be a loopback
+        literal. This is the unspoofable signal — the dashboard can bind
+        ``0.0.0.0`` (``dashboard.bind = lan``), and a ``Host``-header-only
+        check would let a LAN client connect to the LAN socket while sending
+        ``Host: 127.0.0.1``. The peer address cannot be spoofed that way.
+      * DEFENSE-IN-DEPTH: the ``Host`` authority must ALSO be an IP-literal
+        loopback (anti-DNS-rebinding) — a hostname ``Host`` (a rebinding
+        vector) is rejected even from a loopback peer.
+
+    ``dashboard.expose_transcripts`` is NEVER consulted — this surface is
+    loopback-only, ALWAYS. Fail closed on a missing/empty peer or Host.
+    """
+    if not is_loopback(peer_ip):
+        return False
+    return is_loopback(authority_host(host))
+
+
 def transcripts_allowed(bind_host, expose: bool) -> bool:
     """Are transcripts served AT ALL on this bind? Loopback bind always; a
     non-loopback (LAN) bind only under the explicit ``expose`` opt-in."""

package/bin/cctally

@@ -141,6 +141,7 @@ HOOK_TICK_DEFAULT_THROTTLE_SECONDS = 30.0
 SETUP_SYMLINK_NAMES = (
     "cctally",
     "cctally-alerts",
+    "cctally-budget",
     "cctally-dashboard",
     "cctally-dollar-per-percent",
     "cctally-five-hour-blocks",
@@ -292,6 +293,7 @@ classify_coverage = _lib_pricing_check.classify_coverage
 scope_litellm = _lib_pricing_check.scope_litellm
 diff_pricing = _lib_pricing_check.diff_pricing
 stale_allowlist_entries = _lib_pricing_check.stale_allowlist_entries
+expired_allowlist_entries = _lib_pricing_check.expired_allowlist_entries
 check_table_shapes = _lib_pricing_check.check_table_shapes
 pricing_issue_action = _lib_pricing_check.pricing_issue_action
 CoverageGap = _lib_pricing_check.CoverageGap
@@ -435,6 +437,17 @@ _parse_blocks_token_limit = _lib_blocks._parse_blocks_token_limit
 _lib_statusline = _load_sibling("_lib_statusline")
 STATUSLINE_BURN_RATE_BANDS = _lib_statusline.STATUSLINE_BURN_RATE_BANDS
 
+# #279 S2 F2: stdlib-logging chokepoint (CCTALLY_DEBUG tracebacks on the
+# top-level catch-all; adopted by the dashboard log_error surface).
+_lib_log = _load_sibling("_lib_log")
+
+# #279 S6 W1: pure JSON wire-format kernel — the schemaVersion stamp helper
+# (single chokepoint for the additive camelCase envelope across reporting
+# --json surfaces) + the canonical _iso_z (bound in W4/Task 9, not here).
+# Convention: docs/cli-contract.md.
+_lib_json_envelope = _load_sibling("_lib_json_envelope")
+stamp_schema_version = _lib_json_envelope.stamp_schema_version
+
 _lib_changelog = _load_sibling("_lib_changelog")
 # Backward-compat re-export: callers and tests reach the helper through
 # ``cctally._release_read_latest_release_version`` (incl. monkeypatch
@@ -790,6 +803,7 @@ _MIGRATION_NAME_RE = _cctally_db._MIGRATION_NAME_RE
 Migration = _cctally_db.Migration
 DowngradeDetected = _cctally_db.DowngradeDetected
 ProdMigrationRefused = _cctally_db.ProdMigrationRefused
+StatsDbCorruptError = _cctally_db.StatsDbCorruptError
 _STATS_MIGRATIONS = _cctally_db._STATS_MIGRATIONS
 _CACHE_MIGRATIONS = _cctally_db._CACHE_MIGRATIONS
 _make_migration_decorator = _cctally_db._make_migration_decorator
@@ -1107,7 +1121,8 @@ _dashboard_build_blocks_panel = _cctally_dashboard._dashboard_build_blocks_panel
 _dashboard_build_blocks_view = _cctally_dashboard._dashboard_build_blocks_view
 _dashboard_build_daily_panel = _cctally_dashboard._dashboard_build_daily_panel
 _empty_dashboard_snapshot = _cctally_dashboard._empty_dashboard_snapshot
-_iso_z = _cctally_dashboard._iso_z
+# _iso_z is NOT bound here anymore — the former dashboard-then-forecast
+# double-bind collapses to a single canonical bind below (#279 S6 W4).
 # Projects panel + modal (spec 2026-05-19-projects-panel-design.md).
 # Re-export so the sync-thread builder at `_cctally_tui._tui_build_snapshot`
 # can reach the dashboard sibling's aggregator via `c = _cctally()`.
@@ -1201,9 +1216,7 @@ cmd_range_cost = _cctally_reporting.cmd_range_cost   # parser: c.cmd_range_cost
 # are the parser's set_defaults(func=c.cmd_*) targets; the forecast cluster is
 # reached by TUI/dashboard/refresh/view_models via shim/accessor, and tests
 # retrieve any of these off the cctally namespace. So EVERY moved symbol lives
-# here. _iso_z is LAST: it overrides the L943 `_iso_z = _cctally_dashboard._iso_z`
-# binding so cctally._iso_z stays the FORECAST version (the dt-only variant
-# _lib_diff_kernel + _cctally_five_hour depend on). This block MUST be after L943.
+# here.
 _cctally_forecast = _load_sibling("_cctally_forecast")
 cmd_report = _cctally_forecast.cmd_report
 cmd_forecast = _cctally_forecast.cmd_forecast
@@ -1252,8 +1265,12 @@ _budget_emit_json = _cctally_forecast._budget_emit_json
 _build_budget_snapshot = _cctally_forecast._build_budget_snapshot
 _build_budget_no_data_snapshot = _cctally_forecast._build_budget_no_data_snapshot
 _build_budget_no_budget_snapshot = _cctally_forecast._build_budget_no_budget_snapshot
-# _iso_z LAST — overrides the L943 dashboard binding (forecast version wins).
-_iso_z = _cctally_forecast._iso_z
+# #279 S6 W4: single canonical _iso_z bind (None-safe seconds-precision UTC-Z),
+# placed where the old forecast-wins override sat so the _lib_diff_kernel /
+# _cctally_five_hour shim lookups resolve to the same object. forecast and the
+# dashboard envelope now alias this same canonical; doctor keeps its divergent
+# name-shared copy.
+_iso_z = _lib_json_envelope._iso_z
 
 
 RELEASE_HEADER_RE = re.compile(
@@ -2801,15 +2818,42 @@ def main(argv: list[str] | None = None) -> int:
     _print_migration_error_banner_if_needed(args)
     try:
         rc = int(args.func(args))
+        # Flush now, inside the guard, so a buffered broken pipe (small output
+        # that never filled the pipe buffer, e.g. `cctally daily | head`)
+        # surfaces HERE and is handled below — not as an "Exception ignored in
+        # sys.stdout" at interpreter shutdown (CPython exit code 120). #279 S1 F5.
+        sys.stdout.flush()
     except KeyboardInterrupt:
         return 130
+    except BrokenPipeError:
+        # Reader went away (`cctally daily | head`). Not an error: redirect
+        # stdout to /dev/null so the interpreter's shutdown-flush doesn't emit
+        # an "Exception ignored" line, then exit 0 immediately — skipping the
+        # post-command update hooks (stdout is dead, banners are pointless).
+        # Mirrors the KeyboardInterrupt immediate-return precedent. #279 S1 F5.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return 0
     except DowngradeDetected as exc:
         eprint(f"cctally: {exc}")
         return 2
     except ProdMigrationRefused as exc:
         eprint(f"{exc}")  # message already carries the 'cctally:' prefix
         return 2
+    except StatsDbCorruptError as exc:
+        # #279 S1 F4: corrupt stats.db (non-re-derivable) — one-line diagnosis
+        # + recovery guidance, exit 2. Caught before the generic handler so it
+        # never renders as a raw traceback.
+        eprint(f"cctally: {exc}")
+        return 2
     except Exception as exc:  # pragma: no cover
+        # #279 S2 F2: CCTALLY_DEBUG=1 surfaces the full traceback on stderr
+        # via the _lib_log chokepoint; default mode stays byte-identical.
+        if _lib_log.debug_enabled():
+            _lib_log.get_logger("cli").debug(
+                "unhandled exception in %r",
+                getattr(args, "command", None), exc_info=True,
+            )
         eprint(f"Error: {exc}")
         rc = 1
     # Post-command update hooks (spec §4.2). Best-effort: any exception
@@ -2868,7 +2912,7 @@ def _post_command_update_hooks(command: str | None, args) -> None:
     otherwise races that detached writer re-creating the dir after the
     command returns. Setting this env var makes such harnesses
     deterministic without disabling the feature for real users."""
-    if os.environ.get("CCTALLY_DISABLE_UPDATE_CHECK"):
+    if _cctally_core._truthy_env("CCTALLY_DISABLE_UPDATE_CHECK"):
         return
     if command == "setup" and getattr(args, "uninstall", False):
         return

package/bin/cctally-dashboard

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# Wrapper that forwards to `cctally dashboard`.
-# Keeps CLI ergonomics in line with cctally-tui / cctally-forecast.
+# Thin wrapper: `cctally-dashboard` → `cctally dashboard`.
+set -euo pipefail
 exec "$(dirname "$0")/cctally" dashboard "$@"