cctally 1.89.2 → 1.90.1

package/bin/_cctally_dashboard_sources.py

@@ -761,14 +761,15 @@ def resolve_dashboard_source_semantics(
     quota_alerts = c._get_quota_alerts_config(raw_config)
     raw_cache_report = raw_config.get("cache_report")
     raw_cache_threshold = (
-        raw_cache_report.get("anomaly_threshold_pp", 15)
-        if isinstance(raw_cache_report, Mapping) else 15
-    )
-    cache_threshold = (
-        int(raw_cache_threshold)
-        if isinstance(raw_cache_threshold, int) and not isinstance(raw_cache_threshold, bool)
-        and 1 <= raw_cache_threshold <= 100 else 15
+        raw_cache_report.get("anomaly_threshold_pp")
+        if isinstance(raw_cache_report, Mapping) else None
     )
+    # #443 S3 F17: one definition of what the setting means, shared with
+    # the Claude read path and the persistence gate. An absent key
+    # reaches the resolver as None and defaults there, not here.
+    cache_threshold = c._load_sibling(
+        "_lib_cache_report"
+    ).resolve_cache_report_threshold(raw_cache_threshold)
     raw_codex_budget = budget_config.get("codex")
     codex_budget = (
         MappingProxyType(dict(raw_codex_budget))
@@ -1043,6 +1044,8 @@ def _codex_cache_report_wire(
     """
     c = sys.modules["cctally"]
     crk = c._load_sibling("_lib_cache_report")
+    # #443 S2 F18 — the one serializer shared with the Claude producer.
+    wire = c._load_sibling("_lib_cache_report_wire")
     display_tz = ZoneInfo(display_tz_name) if display_tz_name else None
     cutoff = now_utc - dt.timedelta(days=window_days)
 
@@ -1107,24 +1110,35 @@ def _codex_cache_report_wire(
             },
         ))
 
-    today_iso = now_utc.astimezone(display_tz or UTC).strftime("%Y-%m-%d")
+    # One current day per invocation (#443 S3 F23): the focal day and the
+    # entry filter below both resolve through the SAME zone the kernel
+    # buckets by. ``display_tz or UTC`` diverged from host-local bucketing
+    # on every non-UTC host, which published a fabricated spotlight and let
+    # the breakdowns draw from a different entry population than the days.
+    bucket_tz = crk._resolve_bucket_tz(display_tz)
+    today_iso = now_utc.astimezone(bucket_tz).strftime("%Y-%m-%d")
     if not wrapped:
-        return {
-            "window_days": window_days,
-            "anomaly_threshold_pp": anomaly_threshold_pp,
-            "anomaly_window_days": window_days,
-            "today": {
+        # An empty store measured nothing, so ``observed`` is False and
+        # every applicable predicate is unevaluated. The client
+        # short-circuits on ``is_empty`` before reading either, so this
+        # costs nothing and keeps the empty and populated returns one shape.
+        return wire.build_cache_report_wire(
+            provider="codex", window_days=window_days,
+            anomaly_threshold_pp=anomaly_threshold_pp,
+            anomaly_window_days=window_days,
+            today={
                 "date": today_iso, "cache_hit_percent": 0.0,
                 "baseline_median_percent": None, "delta_pp": None,
                 "net_usd": 0.0, "saved_usd": 0.0, "wasted_usd": 0.0,
                 "anomaly_triggered": False, "anomaly_reasons": (),
                 "baseline_daily_row_count": 0,
+                "anomaly_unevaluated": wire.CODEX_PREDICATES, "observed": False,
             },
-            "days": (), "by_project": (), "by_model": (),
-            "seven_day_net_usd": 0.0, "seven_day_anomaly_count": 0,
-            "fourteen_day_counterfactual_usd": 0.0,
-            "fourteen_day_efficiency_ratio": 0.0, "is_empty": True,
-        }
+            days=(), by_project=(), by_model=(),
+            seven_day_net_usd=0.0, seven_day_anomaly_count=0,
+            fourteen_day_counterfactual_usd=0.0,
+            fourteen_day_efficiency_ratio=0.0, is_empty=True,
+        )
 
     result = crk._build_cache_report(
         wrapped,
@@ -1137,7 +1151,14 @@ def _codex_cache_report_wire(
         cost_calculator=lambda _model, _usage, _mode, cost: float(cost or 0.0),
     )
     raw_rows = sorted(result.rows, key=lambda row: row.date or "", reverse=True)
-    days = tuple({
+    today_row = next((row for row in raw_rows if row.date == today_iso), None)
+    # #443 F13/F14 — both charts label their rightmost element "Today"
+    # positionally, so an idle day left the newest REAL row wearing that
+    # label while the spotlight published a fabricated 0%. The Claude
+    # builder solves this with a synthetic row for exactly this reason;
+    # Codex now does the same. Slice AFTER inserting, as Claude does.
+    synthetic_today = today_row is None
+    day_dicts = [{
         "date": row.date or "",
         "cache_hit_percent": row.cache_hit_percent,
         "input_tokens": row.input_tokens,
@@ -1149,15 +1170,28 @@ def _codex_cache_report_wire(
         "net_usd": row.net_usd,
         "anomaly_triggered": row.anomaly_triggered,
         "anomaly_reasons": tuple(row.anomaly_reasons),
-    } for row in raw_rows[:window_days])
-    today_row = next((row for row in raw_rows if row.date == today_iso), None)
-    baseline_count = sum(1 for row in raw_rows if row.date != today_iso)
+        "anomaly_unevaluated": tuple(getattr(row, "anomaly_unevaluated", ())),
+        "observed": True,
+    } for row in raw_rows]
+    if synthetic_today:
+        day_dicts.insert(0, {
+            "date": today_iso, "cache_hit_percent": 0.0,
+            "input_tokens": 0, "output_tokens": 0,
+            "cache_creation_tokens": 0, "cache_read_tokens": 0,
+            "saved_usd": 0.0, "wasted_usd": 0.0, "net_usd": 0.0,
+            "anomaly_triggered": False, "anomaly_reasons": (),
+            "anomaly_unevaluated": wire.CODEX_PREDICATES, "observed": False,
+        })
+    days = tuple(day_dicts[:window_days])
+    # #443 S3 F22: the rows the median was actually taken over, not every
+    # non-today row. The old count was unbounded by the baseline window.
+    baseline_count = result.today_baseline_sample_count
     baseline = result.today_baseline_median
     today_hit = today_row.cache_hit_percent if today_row else 0.0
     kept_dates = {row["date"] for row in days}
     kept_entries = [
         entry for entry in wrapped
-        if entry.timestamp.astimezone(display_tz or UTC).strftime("%Y-%m-%d") in kept_dates
+        if entry.timestamp.astimezone(bucket_tz).strftime("%Y-%m-%d") in kept_dates
     ]
     by_project = crk._aggregate_cache_breakdown(
         kept_entries, key_fn=lambda entry: entry.project_path,
@@ -1171,11 +1205,12 @@ def _codex_cache_report_wire(
     saved_total = stable_sum(float(row["saved_usd"]) for row in days)
     wasted_total = stable_sum(float(row["wasted_usd"]) for row in days)
     efficiency_denom = saved_total + abs(wasted_total)
-    return {
-        "window_days": window_days,
-        "anomaly_threshold_pp": anomaly_threshold_pp,
-        "anomaly_window_days": window_days,
-        "today": {
+    return wire.build_cache_report_wire(
+        provider="codex",
+        window_days=window_days,
+        anomaly_threshold_pp=anomaly_threshold_pp,
+        anomaly_window_days=window_days,
+        today={
             "date": today_iso,
             "cache_hit_percent": today_hit,
             "baseline_median_percent": baseline,
@@ -1186,24 +1221,34 @@ def _codex_cache_report_wire(
             "anomaly_triggered": today_row.anomaly_triggered if today_row else False,
             "anomaly_reasons": tuple(today_row.anomaly_reasons) if today_row else (),
             "baseline_daily_row_count": baseline_count,
+            "anomaly_unevaluated": (
+                tuple(getattr(today_row, "anomaly_unevaluated", ()))
+                if today_row else wire.CODEX_PREDICATES
+            ),
+            "observed": today_row is not None,
         },
-        "days": days,
-        "by_project": tuple({
+        days=days,
+        by_project=tuple({
             "key": row.key, "cache_hit_percent": row.cache_hit_percent,
             "net_usd": row.net_usd,
         } for row in by_project),
-        "by_model": tuple({
+        by_model=tuple({
             "key": row.key, "cache_hit_percent": row.cache_hit_percent,
             "net_usd": row.net_usd,
         } for row in by_model),
-        "seven_day_net_usd": stable_sum(float(row["net_usd"]) for row in seven),
-        "seven_day_anomaly_count": sum(bool(row["anomaly_triggered"]) for row in seven),
-        "fourteen_day_counterfactual_usd": saved_total,
-        "fourteen_day_efficiency_ratio": (
+        seven_day_net_usd=stable_sum(float(row["net_usd"]) for row in seven),
+        # Placeholder: on the Codex path the builder RECOMPUTES this from
+        # the day blocks it has already filtered, because a count taken
+        # here would still include verdicts whose only reason is about to
+        # be dropped as inapplicable. Computing it twice would just invite
+        # the two to drift.
+        seven_day_anomaly_count=0,
+        fourteen_day_counterfactual_usd=saved_total,
+        fourteen_day_efficiency_ratio=(
             saved_total / efficiency_denom if efficiency_denom > 1e-9 else 0.0
         ),
-        "is_empty": False,
-    }
+        is_empty=False,
+    )
 
 
 def _codex_conversation_metadata(

package/bin/_cctally_db.py

@@ -302,6 +302,33 @@ class StatsEpochMismatchError(sqlite3.DatabaseError):
     DB failure; ``main()`` maps it to a staged exit 3."""
 
 
+class StatsEpochRebuildDeferred(BaseException):
+    """A readable wrong-epoch stats index is rebuilding out of process.
+
+    Ordinary callers must not read the schema-incompatible old index or pay
+    whole-journal replay latency inline. ``outcome`` records whether this
+    caller spawned the worker, observed an existing attempt, or could not
+    spawn it; ``main()`` maps every case to prompt retry guidance and exit 3.
+    This deliberately derives directly from ``BaseException``: reporting
+    kernels contain many broad ``Exception`` / ``sqlite3.DatabaseError``
+    fallbacks that turn missing optional data into ``n/a``. Swallowing this
+    control signal there would publish a misleading partial report. The CLI
+    boundary, dashboard, and statusline catch it explicitly; ``finally``
+    cleanup still runs normally.
+    """
+
+    def __init__(self, outcome: str) -> None:
+        self.outcome = str(outcome)
+        message = (
+            "could not start the stats.db index epoch rebuild; retry this "
+            "command shortly"
+            if self.outcome == "failed"
+            else "stats.db index epoch rebuild is running in the background; "
+                 "retry shortly"
+        )
+        super().__init__(message)
+
+
 _SQLITE_CORRUPTION_MESSAGES = (
     "database disk image is malformed",
     "file is not a database",

package/bin/_cctally_parser.py

@@ -3357,6 +3357,25 @@ def _build_codex_quota_verify_parser(subparsers, name, *, help_text, xref=None):
     )
     qv.set_defaults(func=c.cmd_codex_quota_verify_internal)
 
+def _build_stats_epoch_rebuild_parser(subparsers, name, *, help_text, xref=None):
+    """Build the issue-#453 detached stats epoch worker parser."""
+    c = _cctally()
+    worker = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+                    """\
+                    Internal subcommand: converge a readable post-legacy
+                    wrong-epoch stats index through the existing journal
+                    resolver. Spawned by ordinary stats-backed commands so
+                    whole-journal replay never lands on their blocking path.
+                    Always returns 0; failures are logged and remain retryable.
+                    """
+                ),
+    )
+    worker.set_defaults(func=c.cmd_stats_epoch_rebuild_internal)
+
 def _build_codex_replay_drain_parser(subparsers, name, *, help_text, xref=None):
     """Build the `_codex-replay-drain` parser (public #5 §4)."""
     c = _cctally()
@@ -3458,6 +3477,7 @@ _REGISTRATION = (
     _Reg('_update-check', _build_update_check_parser, argparse.SUPPRESS, None, None),
     _Reg('_telemetry-beat', _build_telemetry_beat_parser, argparse.SUPPRESS, None, None),
     _Reg('_codex-quota-verify', _build_codex_quota_verify_parser, argparse.SUPPRESS, None, None),
+    _Reg('_stats-epoch-rebuild', _build_stats_epoch_rebuild_parser, argparse.SUPPRESS, None, None),
     _Reg('_codex-replay-drain', _build_codex_replay_drain_parser, argparse.SUPPRESS, None, None),
     _Reg('repair-symlinks', _build_repair_symlinks_parser, argparse.SUPPRESS, None, None),
 )

package/bin/_cctally_record.py

@@ -4766,47 +4766,18 @@ def _codex_lifecycle_roots():
 
 
 def _stats_epoch_rebuild_pending() -> bool:
-    """Would opening stats.db right now trigger a whole-journal rebuild?
-
-    Side-effect-free: a raw read-only ``PRAGMA user_version``, the same probe
-    ``resolve_stats_epoch_mismatch`` re-checks under the maintenance lock.
-
-    Deliberately narrow. A MISSING stats.db is a fresh install, where building
-    the index is cheap and skipping it would leave the hook with nothing to do
-    forever. An UNREADABLE one belongs to the corruption auto-heal path, not
-    here. A LEGACY index (``user_version <= LEGACY_STATS_HEAD``) takes the
-    migration route rather than the epoch rebuild, and predates every epoch
-    this decision is about. Only a readable, post-legacy, wrong-epoch index —
-    exactly what an upgrade across a ``STATS_INDEX_EPOCH`` bump produces —
-    answers True.
-    """
-    path = _cctally_core.DB_PATH
-    try:
-        if not path.exists():
-            return False
-    except OSError:
-        return False
+    """Delegate the side-effect-free epoch probe to the store boundary."""
     try:
         import _cctally_store
-        version = _cctally_store._raw_user_version(path)
+        return _cctally_store.stats_epoch_rebuild_pending()
     except Exception:
         return False
-    if version < 0 or version <= _cctally_core.LEGACY_STATS_HEAD:
-        return False
-    return version != _cctally_core.STATS_INDEX_EPOCH
 
 
 def _defer_stats_epoch_rebuild() -> str:
-    """Hand a pending stats.db epoch rebuild to the detached quota worker.
-
-    Reuses ``_codex-quota-verify`` rather than adding a third worker: its
-    ``force_full`` pass opens stats.db, which is what performs the rebuild, and
-    the whole-history pass it then runs is exactly the one the freshly rebuilt
-    index needs anyway. Sharing the worker also shares its attempt-stamped
-    throttle, so a rebuild that keeps dying cannot spawn one worker per tick.
-    """
-    from _cctally_quota import _defer_codex_quota_verification
-    return _defer_codex_quota_verification()
+    """Hand a pending epoch rebuild to the dedicated store worker."""
+    import _cctally_store
+    return _cctally_store.defer_stats_epoch_rebuild()
 
 
 def _cmd_hook_tick_codex(
@@ -4866,10 +4837,9 @@ def _cmd_hook_tick_codex(
     # journal rebuild — against Codex's 30-second hook timeout. A killed rebuild
     # commits nothing, so the next tick repeats it: a non-converging
     # 30-second-per-turn loop, which is the reported defect delivered by the
-    # fix. Hand it to the same detached worker the periodic verification uses
-    # (its `force_full` pass opens stats.db and therefore performs the rebuild)
-    # and acknowledge this tick as a no-op. No lifecycle marker is stamped, so
-    # the next Codex turn re-checks immediately; the spawn itself is throttled.
+    # fix. Hand it to the dedicated store-owned epoch worker and acknowledge
+    # this tick as a no-op. No lifecycle marker is stamped, so the next Codex
+    # turn re-checks immediately; store admission suppresses duplicate workers.
     if _stats_epoch_rebuild_pending():
         _defer_stats_epoch_rebuild()
         log_outcome(sync="deferred", result="noop")

package/bin/_cctally_statusline.py

@@ -769,7 +769,10 @@ def _read_db_projection_once() -> "_candidates.DbProjection":
 def _read_db_projection_stable(*, attempts: int = 3) -> "_candidates.DbProjection":
     for _ in range(attempts):
         before = _db_file_fingerprint()
-        projection = _read_db_projection_once()
+        try:
+            projection = _read_db_projection_once()
+        except _cctally().StatsEpochRebuildDeferred:
+            return _candidates.DbProjection(None, None, db_files=before)
         after = _db_file_fingerprint()
         if before == after and after["main"] is not None:
             return dataclasses.replace(projection, db_files=after)
@@ -1009,6 +1012,8 @@ def _authoritative_record_usage(
 
     try:
         rc = _cctally().cmd_record_usage(args)
+    except _cctally().StatsEpochRebuildDeferred as exc:
+        return _AuthoritativeRecordResult("record_failed", str(exc))
     except Exception as exc:
         return _AuthoritativeRecordResult("record_failed", str(exc))
     if rc != 0:
@@ -1163,7 +1168,13 @@ def _statusline_reduce_and_publish() -> "_candidates.ReductionDecision | None":
     # statusline's AUTHORITATIVE publication step (`_authoritative_record_usage`)
     # keeps the default authoritative mode — it is already try/except-wrapped to
     # "record_failed".
-    if _cctally().cmd_record_usage(args, ingest_mode="opportunistic") != 0:
+    try:
+        record_rc = _cctally().cmd_record_usage(
+            args, ingest_mode="opportunistic"
+        )
+    except _cctally().StatsEpochRebuildDeferred:
+        return decision
+    if record_rc != 0:
         return decision
     after = _read_db_projection_stable()
     if _projection_changed(projection, after):
@@ -1586,6 +1597,10 @@ def _build_statusline_injections(warn_once):
                     range_start - c.BLOCK_DURATION, now + c.BLOCK_DURATION,
                 )
             )
+        except c.StatsEpochRebuildDeferred:
+            recorded_windows, block_start_overrides, canonical_intervals = (
+                [], {}, {},
+            )
         except Exception:
             recorded_windows, block_start_overrides, canonical_intervals = (
                 [], {}, {},
@@ -1622,6 +1637,8 @@ def _build_statusline_injections(warn_once):
         _acct_params = () if _sl_account is None else (_sl_account,)
         try:
             conn = open_db()
+        except c.StatsEpochRebuildDeferred:
+            return (None, None)
         except Exception:
             return (None, None)
         try:
@@ -1707,6 +1724,8 @@ def _build_statusline_injections(warn_once):
     def _db_latest_rate_limits():
         try:
             conn = open_db()
+        except _cctally().StatsEpochRebuildDeferred:
+            return None
         except Exception:
             return None
         try:

package/bin/_cctally_store.py

@@ -1460,6 +1460,185 @@ HEAL_HOOK = _stats_heal_hook
 # a HARD ERROR (``StatsEpochMismatchError``) — never a silent rebuild-to-empty.
 
 _EPOCH_MISMATCH_ACTIVE = False
+STATS_EPOCH_REBUILD_COMMAND = "_stats-epoch-rebuild"
+_STATS_EPOCH_REBUILD_RETRY_SECONDS = 60.0
+
+
+def _stats_epoch_rebuild_path(name: str) -> pathlib.Path:
+    return pathlib.Path(_cctally_core.APP_DIR) / name
+
+
+def _stats_epoch_rebuild_marker_path() -> pathlib.Path:
+    return _stats_epoch_rebuild_path("stats-epoch-rebuild.pending")
+
+
+def _stats_epoch_rebuild_admission_path() -> pathlib.Path:
+    return _stats_epoch_rebuild_path("stats-epoch-rebuild.admission.lock")
+
+
+def _stats_epoch_rebuild_worker_path() -> pathlib.Path:
+    return _stats_epoch_rebuild_path("stats-epoch-rebuild.worker.lock")
+
+
+def _stats_epoch_rebuild_log_path() -> pathlib.Path:
+    return pathlib.Path(_cctally_core.LOG_DIR) / "stats-epoch-rebuild.log"
+
+
+def _unlink_stats_epoch_marker() -> None:
+    try:
+        _stats_epoch_rebuild_marker_path().unlink()
+    except FileNotFoundError:
+        pass
+
+
+def _stats_epoch_rebuild_worker_active() -> bool:
+    """Probe the worker flock without waiting or disturbing its owner."""
+    try:
+        fd = os.open(
+            _stats_epoch_rebuild_worker_path(),
+            os.O_WRONLY | os.O_CREAT,
+            0o600,
+        )
+    except OSError:
+        return False
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            return True
+        except OSError:
+            return False
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        return False
+    finally:
+        os.close(fd)
+
+
+def _log_stats_epoch_rebuild(outcome: str, *, error: Exception | None = None) -> None:
+    """Append one path-safe worker result line.
+
+    Detached worker streams are `/dev/null`; this small log is its only
+    diagnostic. Error detail is deliberately structural (class plus numeric
+    SQLite/OS code), never free-form exception text that may carry private
+    paths or `key=value` fragments.
+    """
+    try:
+        log_path = _stats_epoch_rebuild_log_path()
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        detail = ""
+        if error is not None:
+            code = getattr(error, "sqlite_errorcode", None)
+            if code is None:
+                code = getattr(error, "errno", None)
+            detail = f" error={type(error).__name__}"
+            if code is not None:
+                detail += f" code={int(code)}"
+        line = (
+            f"{_cctally_core.now_utc_iso()} worker=stats-epoch-rebuild "
+            f"result={outcome}{detail}\n"
+        ).encode("utf-8")
+        fd = os.open(log_path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+        try:
+            os.write(fd, line)
+        finally:
+            os.close(fd)
+    except Exception:
+        pass
+
+
+def defer_stats_epoch_rebuild() -> str:
+    """Schedule one retryable detached epoch worker without blocking callers."""
+    try:
+        pathlib.Path(_cctally_core.APP_DIR).mkdir(parents=True, exist_ok=True)
+        admission_fd = os.open(
+            _stats_epoch_rebuild_admission_path(),
+            os.O_WRONLY | os.O_CREAT,
+            0o600,
+        )
+    except OSError:
+        return "failed"
+    try:
+        try:
+            fcntl.flock(admission_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return "pending"
+        marker = _stats_epoch_rebuild_marker_path()
+        try:
+            age = time.time() - marker.stat().st_mtime
+        except FileNotFoundError:
+            age = None
+        except OSError:
+            return "failed"
+        if age is not None and age < _STATS_EPOCH_REBUILD_RETRY_SECONDS:
+            return "pending"
+        if _stats_epoch_rebuild_worker_active():
+            # A representative replay outlives the marker retry interval.
+            # Refresh the admission stamp instead of launching a process that
+            # can only lose the worker flock and exit.
+            try:
+                os.utime(marker, None)
+            except OSError:
+                pass
+            return "pending"
+        try:
+            marker_fd = os.open(marker, os.O_WRONLY | os.O_CREAT, 0o600)
+            os.close(marker_fd)
+            os.utime(marker, None)
+        except OSError:
+            return "failed"
+        from _cctally_update import _spawn_detached
+        if _spawn_detached(STATS_EPOCH_REBUILD_COMMAND):
+            return "spawned"
+        _unlink_stats_epoch_marker()
+        return "failed"
+    finally:
+        try:
+            fcntl.flock(admission_fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        os.close(admission_fd)
+
+
+def cmd_stats_epoch_rebuild_internal(args) -> int:
+    """Hidden detached worker: converge a pending stats epoch exactly once."""
+    del args
+    try:
+        pathlib.Path(_cctally_core.APP_DIR).mkdir(parents=True, exist_ok=True)
+        worker_fd = os.open(
+            _stats_epoch_rebuild_worker_path(),
+            os.O_WRONLY | os.O_CREAT,
+            0o600,
+        )
+    except OSError as exc:
+        _log_stats_epoch_rebuild("error", error=exc)
+        return 0
+    try:
+        try:
+            fcntl.flock(worker_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return 0
+        if not stats_epoch_rebuild_pending():
+            _unlink_stats_epoch_marker()
+            _log_stats_epoch_rebuild("current")
+            return 0
+        try:
+            conn = resolve_stats_epoch_mismatch()
+            conn.close()
+        except Exception as exc:
+            _log_stats_epoch_rebuild("error", error=exc)
+            return 0
+        _unlink_stats_epoch_marker()
+        _log_stats_epoch_rebuild("success")
+        return 0
+    finally:
+        try:
+            fcntl.flock(worker_fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        os.close(worker_fd)
 
 
 def _raw_user_version(path) -> int:
@@ -1475,6 +1654,27 @@ def _raw_user_version(path) -> int:
         return -1
 
 
+def stats_epoch_rebuild_pending(path=None) -> bool:
+    """Whether an ordinary live open would require whole-journal replay.
+
+    Missing indexes are cheap fresh installs. Unreadable indexes belong to the
+    corruption classifier, and legacy indexes take the one-time cutover path.
+    Only a readable post-legacy index at a non-current epoch is deferrable.
+    """
+    candidate = pathlib.Path(
+        _cctally_core.DB_PATH if path is None else path
+    )
+    try:
+        if not candidate.exists():
+            return False
+    except OSError:
+        return False
+    version = _raw_user_version(candidate)
+    if version < 0 or version <= _cctally_core.LEGACY_STATS_HEAD:
+        return False
+    return version != _cctally_core.STATS_INDEX_EPOCH
+
+
 def resolve_stats_epoch_mismatch():
     """Resolve a version-mismatched stats.db by journal rebuild (spec §7.1).
     Called by ``open_db`` after ``conn.close()`` — returns a fresh steady-state

package/bin/_cctally_tui.py

@@ -3719,8 +3719,12 @@ def _tui_build_snapshot_once(
         # Cache-report panel + modal envelope block (spec
         # 2026-05-21-cache-report-panel-design.md §5.2). Per-tick build
         # alongside the projects envelope. Threshold is read from
-        # ``config.json:cache_report.anomaly_threshold_pp`` (default
-        # 15); ``anomaly_window_days`` is hardcoded at 14 in v1.
+        # ``config.json:cache_report.anomaly_threshold_pp`` and resolved
+        # by ``_lib_cache_report.resolve_cache_report_threshold`` — the
+        # one definition shared with the Codex read path and the
+        # persistence gate (#443 S3 F17), strict and silent (anything
+        # that is not an in-range int becomes the default 15);
+        # ``anomaly_window_days`` is hardcoded at 14 in v1.
         # display_tz inherits the same resolved zone as every other
         # panel so today-bucketing matches the envelope's ``display``
         # block. Errors record on ``last_sync_error``; ``None`` lands
@@ -3730,13 +3734,11 @@ def _tui_build_snapshot_once(
         with _perf.phase("build.cache_report"):
             try:
                 cfg_cr = load_config().get("cache_report") or {}
-                threshold_raw = cfg_cr.get("anomaly_threshold_pp", 15)
-                try:
-                    threshold_pp = int(threshold_raw)
-                except (TypeError, ValueError):
-                    threshold_pp = 15
-                if threshold_pp < 1 or threshold_pp > 100:
-                    threshold_pp = 15
+                threshold_pp = _cctally()._load_sibling(
+                    "_lib_cache_report"
+                ).resolve_cache_report_threshold(
+                    cfg_cr.get("anomaly_threshold_pp")
+                )
                 _dash_mod = sys.modules["_cctally_dashboard"]
                 _bcr = _dash_mod.build_cache_report_snapshot
                 cache_report_block = _bcr(
@@ -6609,6 +6611,28 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
             snap = dataclasses.replace(snap, last_sync_at=None, hydrating=False)
             ref.set(snap)
             hub.publish(snap)
+        except _cctally().StatsEpochRebuildDeferred as exc:
+            # #453: the first periodic tick runs before HTTP bind. Preserve the
+            # initial hydrating/degraded frame while the dedicated replay owns
+            # stats maintenance; a generic crash frame would clear the latch
+            # before any client could observe it. The loop retries normally on
+            # its next cadence and publishes a full frame after convergence.
+            prev = ref.get()
+            pending = dataclasses.replace(
+                prev,
+                last_sync_error=f"stats-open: {exc}",
+                sync_failures=(
+                    SyncFailureAttribution(
+                        leg="stats-open",
+                        database="stats",
+                        corruption=False,
+                    ),
+                ),
+                generated_at=dt.datetime.now(dt.timezone.utc),
+                hydrating=True,
+            )
+            ref.set(pending)
+            hub.publish(pending)
         except Exception as exc:
             prev = ref.get()
             crashed = dataclasses.replace(