cctally 1.65.0 → 1.67.0

package/bin/_cctally_record.py

@@ -111,8 +111,30 @@ What stays in bin/cctally:
   ``_RESET_PCT_DROP_THRESHOLD`` — boundary helpers, already-extracted
   subsystems, or constants reached through the cctally namespace
   (``_RESET_PCT_DROP_THRESHOLD`` now lives in ``bin/_cctally_weekrefs.py``,
-  re-exported on the cctally ns). All accessed via the same shim/``c.X``
-  pattern.
+  re-exported on the cctally ns). Accessed via the shim/``c.X`` pattern
+  EXCEPT the names honest-imported by the #279 S4 F5 collapse below.
+
+  #279 S4 F5 (the #50 treatment): the forwarding shims for
+  ``open_cache_db`` (→ ``_cctally_cache``), ``_floor_to_hour`` (→
+  ``_lib_blocks``), ``_resolve_display_tz_obj`` (→ ``_lib_display_tz``),
+  ``_build_alert_payload_{weekly,five_hour,budget,project_budget,
+  codex_budget,projected}`` (→ ``_lib_alerts_payload``), and
+  ``_get_oauth_usage_config`` (→ ``_cctally_refresh``) were replaced by
+  honest top-level imports — each real def lives in a sibling
+  bin/cctally eager-loads BEFORE _cctally_record, and none is
+  monkeypatched through the cctally namespace / this module's route.
+  The remaining 38 shims below STAY: patched surfaces (``load_config``,
+  ``sync_cache``, ``_dispatch_alert_notification``, ``compute_budget_status``,
+  ``_apply_reset_events_to_weekrefs``, ``resolve_display_tz``,
+  ``_sum_cost_by_project``, ``_project_budget_labels``,
+  ``get_claude_session_entries``, ``_compute_cost_for_weekref``,
+  ``_get_canonical_boundary_for_date``, ``_hook_tick_oauth_refresh``),
+  bin/cctally-homed residues (``_resolve_primary_model_for_block``,
+  ``_warn_alerts_bad_config_once``, ``_warn_budget_bad_config_once``,
+  ``_hook_tick_make_mock_refresh``, ``cmd_sync_week``), and names whose
+  real home (``_cctally_milestones`` / ``_cctally_forecast`` /
+  ``_cctally_weekrefs``) bin/cctally eager-loads AFTER _cctally_record —
+  honest-importing those at module top would force an early sibling load.
 
 §5.6 audit on this extraction's monkeypatch surface:
 - ``cmd_record_usage`` — patched via ``monkeypatch.setitem(ns, …)``
@@ -177,18 +199,99 @@ from _cctally_core import (
     _BudgetConfigError,
     _command_as_of,
 )
-from _lib_five_hour import _canonical_5h_window_key
+from _lib_five_hour import _canonical_5h_window_key, five_hour_milestone_range
 from _lib_pricing import _calculate_entry_cost
 
 
-# Module-level back-ref shims. Each shim resolves
-# ``sys.modules['cctally'].X`` at CALL TIME (not bind time), so
-# monkeypatches on cctally's namespace propagate into the moved code
-# unchanged. `load_config` and `get_claude_session_entries` STAY as
-# shims even though their natural homes are decentralized
-# (_cctally_config / _cctally_cache) — tests monkeypatch them via
-# `ns["X"]` (21 sites total, audited 2026-05-17); direct imports would
-# silently bypass the patches.
+import importlib.util as _ilu
+
+
+def _ensure_sibling_loaded(name: str) -> None:
+    """Register a NON-eager-loaded ``_lib_*`` sibling in ``sys.modules``.
+
+    Every ``_lib_*`` this module imports at body-time is eager-loaded by
+    ``bin/cctally`` EXCEPT the #279 S4 kernels (``_lib_credit``,
+    ``_lib_record``) — those are consumer-only and were deliberately kept
+    out of ``bin/cctally``'s eager-load block so ``bin/cctally`` stays
+    byte-untouched (spec §2 re-export continuity). Under the
+    ``SourceFileLoader`` harness path (``bin/`` absent from ``sys.path``) a
+    bare ``from _lib_X import`` would then miss, so this pre-registers the
+    sibling ``__file__``-relative first — mirroring ``_cctally_cache.
+    _load_lib`` and ``_lib_conversation_query``'s ``_lib_perf`` fallback.
+    The honest ``from _lib_X import`` that follows is a ``sys.modules`` hit
+    in every load context (prod script, conftest, harness).
+    """
+    if name in sys.modules:
+        return
+    try:
+        __import__(name)  # bin/ on sys.path: prod script / conftest / pytest
+        return
+    except ModuleNotFoundError:
+        pass
+    _p = os.path.join(os.path.dirname(__file__), f"{name}.py")
+    _spec = _ilu.spec_from_file_location(name, _p)
+    _mod = _ilu.module_from_spec(_spec)
+    sys.modules[name] = _mod
+    _spec.loader.exec_module(_mod)
+
+
+_ensure_sibling_loaded("_lib_credit")
+from _lib_credit import (
+    _PERCENT_NORMALIZE_DECIMALS,
+    _normalize_percent,
+    CreditPlan,
+    _parse_credit_at,
+    _build_credit_plan,
+)
+_ensure_sibling_loaded("_lib_record")
+from _lib_record import (
+    check_resets_at_plausibility,
+    plan_weekly_credit_debounce,
+    plan_five_hour_credit,
+    hwm_clamp_applies,
+    milestone_coverage_owes,
+    hwm_file_next,
+    projected_crossings,
+    FIRE_IMMEDIATE,
+    CONFIRM_RESET,
+    CLEAR_MARKER,
+    ARM_MARKER,
+)
+
+# === #279 S4 F5: forwarding-shim wall collapse (the #50 treatment) =========
+# Names whose real def lives in a sibling that bin/cctally eager-loads BEFORE
+# _cctally_record (so these are sys.modules hits in every load context) AND
+# that no test monkeypatches through the cctally namespace / _cctally_record
+# route are honest-imported here instead of routed through a
+# ``sys.modules["cctally"].X`` shim. The audit (full table in the commit body)
+# used the suite as the authority; every name below survived the full
+# bin/cctally-test-all. Patched / bin/cctally-homed / post-889-homed names
+# keep their shims below.
+from _cctally_cache import open_cache_db
+from _lib_blocks import _floor_to_hour
+from _lib_display_tz import _resolve_display_tz_obj
+from _lib_alerts_payload import (
+    _build_alert_payload_weekly,
+    _build_alert_payload_five_hour,
+    _build_alert_payload_budget,
+    _build_alert_payload_project_budget,
+    _build_alert_payload_codex_budget,
+    _build_alert_payload_projected,
+)
+from _cctally_refresh import _get_oauth_usage_config
+
+
+# Module-level back-ref shims (the REMAINING wall after the #279 S4 F5
+# collapse above pulled 10 unpatched, pre-889-homed names up to honest
+# imports). Each shim below resolves ``sys.modules['cctally'].X`` at CALL
+# TIME (not bind time), so monkeypatches on cctally's namespace propagate
+# into the moved code unchanged. `load_config` and
+# `get_claude_session_entries` STAY as shims even though their natural
+# homes are decentralized (_cctally_config / _cctally_cache) — tests
+# monkeypatch them via `ns["X"]`; direct imports would silently bypass the
+# patches. The rest stay because they are patched, bin/cctally-homed, or
+# their real home is eager-loaded AFTER this module (see the F5 note in the
+# module docstring for the full STAY/COLLAPSE audit).
 # See spec §3.5 (carve-out) and §3.7 (stays-on-shim allowlist).
 def load_config(*args, **kwargs):
     return sys.modules["cctally"].load_config(*args, **kwargs)
@@ -198,18 +301,10 @@ def get_claude_session_entries(*args, **kwargs):
     return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
 
 
-def open_cache_db(*args, **kwargs):
-    return sys.modules["cctally"].open_cache_db(*args, **kwargs)
-
-
 def sync_cache(*args, **kwargs):
     return sys.modules["cctally"].sync_cache(*args, **kwargs)
 
 
-def _floor_to_hour(*args, **kwargs):
-    return sys.modules["cctally"]._floor_to_hour(*args, **kwargs)
-
-
 def _get_canonical_boundary_for_date(*args, **kwargs):
     return sys.modules["cctally"]._get_canonical_boundary_for_date(*args, **kwargs)
 
@@ -250,30 +345,6 @@ def _resolve_primary_model_for_block(*args, **kwargs):
     return sys.modules["cctally"]._resolve_primary_model_for_block(*args, **kwargs)
 
 
-def _resolve_display_tz_obj(*args, **kwargs):
-    return sys.modules["cctally"]._resolve_display_tz_obj(*args, **kwargs)
-
-
-def _build_alert_payload_weekly(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_weekly(*args, **kwargs)
-
-
-def _build_alert_payload_five_hour(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_five_hour(*args, **kwargs)
-
-
-def _build_alert_payload_budget(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_budget(*args, **kwargs)
-
-
-def _build_alert_payload_project_budget(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_project_budget(*args, **kwargs)
-
-
-def _build_alert_payload_codex_budget(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_codex_budget(*args, **kwargs)
-
-
 def _budget_crossings(*args, **kwargs):
     return sys.modules["cctally"]._budget_crossings(*args, **kwargs)
 
@@ -334,10 +405,6 @@ def _projected_levels_already_latched(*args, **kwargs):
     return sys.modules["cctally"]._projected_levels_already_latched(*args, **kwargs)
 
 
-def _build_alert_payload_projected(*args, **kwargs):
-    return sys.modules["cctally"]._build_alert_payload_projected(*args, **kwargs)
-
-
 def _fetch_current_week_snapshots(*args, **kwargs):
     return sys.modules["cctally"]._fetch_current_week_snapshots(*args, **kwargs)
 
@@ -370,10 +437,6 @@ def _warn_budget_bad_config_once(*args, **kwargs):
     return sys.modules["cctally"]._warn_budget_bad_config_once(*args, **kwargs)
 
 
-def _get_oauth_usage_config(*args, **kwargs):
-    return sys.modules["cctally"]._get_oauth_usage_config(*args, **kwargs)
-
-
 def _hook_tick_oauth_refresh(*args, **kwargs):
     """Shim for ``_hook_tick_oauth_refresh``.
 
@@ -400,10 +463,10 @@ def _hook_tick_make_mock_refresh(*args, **kwargs):
 # ``cmd_hook_tick`` for the three rewrites.
 
 
-# Constants referenced by the moved bodies. Defined here (rather than
-# `c.X`-routed) because they're pure literals — no monkeypatch surface
-# and no dependency on cctally's module instance.
-_PERCENT_NORMALIZE_DECIMALS = 10
+# ``_PERCENT_NORMALIZE_DECIMALS`` + ``_normalize_percent`` now live in
+# ``bin/_lib_credit.py`` (#279 S4 F1); re-imported at module top so
+# ``bin/cctally``'s ``_cctally_record._PERCENT_NORMALIZE_DECIMALS`` /
+# ``_normalize_percent`` re-exports keep resolving unchanged.
 
 # Plausibility band for --resets-at / --five-hour-resets-at (issue #112).
 # Out-of-band epochs are guarded at cmd_record_usage ingress before any
@@ -459,27 +522,8 @@ _logged_window_key_coerce_failure = False
 #   c._RESET_PCT_DROP_THRESHOLD       — bin/_cctally_weekrefs.py constant (re-exported on cctally ns)
 #   c._is_reset_drop                  — bin/_cctally_weekrefs.py helper (re-exported on cctally ns)
 #   c.HOOK_TICK_DEFAULT_THROTTLE_SECONDS
-
-
-def _normalize_percent(value: "float | int | None") -> "float | None":
-    """Flush IEEE 754 ULP noise out of an ingress percent value.
-
-    Single chokepoint applied at every site where a raw percent enters
-    cctally's runtime path (OAuth fetch, hook-tick OAuth refresh, and
-    the cmd_record_usage CLI ingress). Downstream consumers — HWM
-    files, ``weekly_usage_snapshots.{weekly,five_hour}_percent`` REAL
-    columns, ``five_hour_blocks.final_five_hour_percent``, milestone
-    crossing values, and the SSE envelope's ``used_percent`` field —
-    all read the cleaned value, so a single round here stops
-    ``5h=7.000000000000001`` style strings from reaching any log or
-    serialized surface.
-
-    ``None`` is the canonical absent-percent sentinel; preserve it
-    unchanged so the optional-5h branches stay simple.
-    """
-    if value is None:
-        return None
-    return round(float(value), _PERCENT_NORMALIZE_DECIMALS)
+# (#279 S4 F5 collapsed only function-forwarding shims to honest imports;
+#  these call-time constant/helper accessors are untouched.)
 
 
 def _resolve_active_five_hour_reset_event_id(
@@ -1316,16 +1360,18 @@ def maybe_record_projected_alert(
                     proj = _weekly_pct_week_avg_projection(conn, now_utc)
                     if proj is not None and not proj[1]:
                         value = proj[0]
-                        for t in levels:
-                            if value + 1e-9 >= t:
-                                pending.append(dict(
-                                    week_start_at=week_key,
-                                    period="subscription-week",
-                                    metric="weekly_pct",
-                                    threshold=t,
-                                    projected_value=value,
-                                    denominator=100.0,
-                                ))
+                        # weekly_pct comparand == raw threshold (denominator 100).
+                        for t in projected_crossings(
+                            value, [(t, float(t)) for t in levels]
+                        ):
+                            pending.append(dict(
+                                week_start_at=week_key,
+                                period="subscription-week",
+                                metric="weekly_pct",
+                                threshold=t,
+                                projected_value=value,
+                                denominator=100.0,
+                            ))
 
         # ── budget_usd leg (any Claude period — #135; shared factory) ────────
         if budget_on:
@@ -1359,16 +1405,19 @@ def maybe_record_projected_alert(
                         status = compute_budget_status(inputs)
                         if not status.low_confidence:
                             value = status.week_avg_projection_usd
-                            for t in thresholds:
-                                if value + 1e-9 >= (t / 100.0) * float(target):
-                                    pending.append(dict(
-                                        week_start_at=b_week_key,
-                                        period=claude_period,
-                                        metric="budget_usd",
-                                        threshold=t,
-                                        projected_value=value,
-                                        denominator=float(target),
-                                    ))
+                            # budget comparand == (t/100)*target (glue pre-scales).
+                            for t in projected_crossings(
+                                value,
+                                [(t, (t / 100.0) * float(target)) for t in thresholds],
+                            ):
+                                pending.append(dict(
+                                    week_start_at=b_week_key,
+                                    period=claude_period,
+                                    metric="budget_usd",
+                                    threshold=t,
+                                    projected_value=value,
+                                    denominator=float(target),
+                                ))
 
         # ── codex_budget_usd leg (#135; skip_sync=False — R5) ────────────────
         if codex_on:
@@ -1405,16 +1454,19 @@ def maybe_record_projected_alert(
                         c_status = compute_budget_status(c_inputs)
                         if not c_status.low_confidence:
                             value = c_status.week_avg_projection_usd
-                            for t in c_thresholds:
-                                if value + 1e-9 >= (t / 100.0) * float(c_target):
-                                    pending.append(dict(
-                                        week_start_at=c_week_key,
-                                        period=c_period,
-                                        metric="codex_budget_usd",
-                                        threshold=t,
-                                        projected_value=value,
-                                        denominator=float(c_target),
-                                    ))
+                            # codex comparand == (t/100)*target (glue pre-scales).
+                            for t in projected_crossings(
+                                value,
+                                [(t, (t / 100.0) * float(c_target)) for t in c_thresholds],
+                            ):
+                                pending.append(dict(
+                                    week_start_at=c_week_key,
+                                    period=c_period,
+                                    metric="codex_budget_usd",
+                                    threshold=t,
+                                    projected_value=value,
+                                    denominator=float(c_target),
+                                ))
 
         # ── arm (set-then-dispatch): INSERT + stamp alerted_at in one txn ────
         fired: list[dict[str, Any]] = []
@@ -1865,12 +1917,17 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                 ).fetchone()
                 max_existing = row["m"] if row and row["m"] is not None else None
 
-                if max_existing is None:
-                    start_threshold = current_floor   # first observation: only current floor
-                else:
-                    start_threshold = int(max_existing) + 1
+                # Which integer 5h-% thresholds to attempt: the pure fencing
+                # decision (floor snap + first-obs / resume-above-max rule).
+                # `milestone_range.start` is the start_threshold used for the
+                # marginal-cost check below; a non-empty range is exactly the
+                # old `start_threshold <= current_floor` guard.
+                milestone_range = five_hour_milestone_range(
+                    float(five_hour_percent), max_existing
+                )
+                start_threshold = milestone_range.start
 
-                if start_threshold <= current_floor:
+                if milestone_range:
                     # block_id was resolved above (before the children writes) and
                     # is still in scope here.
 
@@ -1893,7 +1950,7 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                         if prev_row is not None:
                             prior_cost = float(prev_row["block_cost_usd"])
 
-                    for pct in range(start_threshold, current_floor + 1):
+                    for pct in milestone_range:
                         if pct == start_threshold and prior_cost is not None:
                             marginal: float | None = totals["cost_usd"] - prior_cost
                         else:
@@ -2175,85 +2232,10 @@ def _read_reset_zero_marker():
     return (week_start_date, cur_end_canon, baseline_pct, first_zero_iso)
 
 
-@dataclass(frozen=True)
-class CreditPlan:
-    week_start_date: str
-    week_start_at: str
-    week_end_at: str
-    cur_end_canon: str
-    from_pct: float
-    from_source: str          # "hwm" | "explicit" | "prior_credit"
-    to_pct: float
-    effective_iso: str        # weekly_credit_floors.effective_at_utc (floored to hour)
-    captured_iso: str         # synthetic snapshot captured_at_utc (un-floored), 'Z'
-
-
-def _parse_credit_at(value, now):
-    """Parse --at as an aware UTC datetime; default to `now`. Naive => UTC
-    (mirrors bin/_cctally_five_hour.py:88), NOT parse_iso_datetime (host-local)."""
-    if value is None:
-        return now
-    try:
-        parsed = dt.datetime.fromisoformat(value)
-    except ValueError as e:
-        raise ValueError(f"--at: {e}") from e
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=dt.timezone.utc)
-    return parsed.astimezone(dt.timezone.utc)
-
-
-def _build_credit_plan(*, week_start_date, week_start_at, week_end_at,
-                       from_pct, from_source, to_pct, at_dt, now,
-                       effective_override=None):
-    """Validate inputs and build a CreditPlan. Pure (no DB/file I/O).
-    Raises ValueError(msg) on any violation — caller maps to exit 2.
-
-    `effective_override` (an ISO string) is the completion-path reuse of an
-    EXISTING `weekly_credit_floors.effective_at_utc` (spec §4a): when present,
-    the plan's effective is that value rather than `floor_to_hour(at)`, so a
-    rerun of a half-applied credit at a later wall-clock keeps the original
-    floor moment and never leaks a stale pre-credit replay into the floored
-    MAX. The synthetic snapshot's captured timestamp stays the un-floored
-    `at` either way."""
-    to_pct = _normalize_percent(to_pct)
-    from_pct = _normalize_percent(from_pct)
-    # Defensive None-guard (issue #212 N3). `_normalize_percent` returns None
-    # for a None input. The CLI never reaches here with None (`--to` is
-    # required + type=float; `--from` always resolves to a float or the caller
-    # errors out first), but this is a public pure helper called directly by
-    # tests and any future non-CLI caller — surface a None as a clear ValueError
-    # (caller -> exit 2) instead of a TypeError from the `0.0 <= None` compare
-    # immediately below.
-    if to_pct is None or from_pct is None:
-        raise ValueError("--to/--from must be numeric")
-    if not (0.0 <= to_pct <= 100.0) or not (0.0 <= from_pct <= 100.0):
-        raise ValueError("--to/--from must be in [0, 100]")
-    if to_pct >= from_pct:
-        raise ValueError(f"not a credit: to >= from ({to_pct} >= {from_pct})")
-    ws = parse_iso_datetime(week_start_at, "week_start_at")
-    we = parse_iso_datetime(week_end_at, "week_end_at")
-    if not (ws <= at_dt < we):
-        raise ValueError(f"--at {at_dt.isoformat()} is outside the week window")
-    if at_dt > now:
-        raise ValueError("--at is in the future")
-    if effective_override is not None:
-        effective_iso = parse_iso_datetime(
-            effective_override, "effective_override"
-        ).astimezone(dt.timezone.utc).isoformat(timespec="seconds")
-    else:
-        effective_iso = _floor_to_hour(at_dt).isoformat(timespec="seconds")
-    cur_end_canon = _canonicalize_optional_iso(week_end_at, "record-credit.week_end")
-    return CreditPlan(
-        week_start_date=week_start_date,
-        week_start_at=week_start_at,
-        week_end_at=week_end_at,
-        cur_end_canon=cur_end_canon,
-        from_pct=from_pct,
-        from_source=from_source,
-        to_pct=to_pct,
-        effective_iso=effective_iso,
-        captured_iso=at_dt.isoformat(timespec="seconds").replace("+00:00", "Z"),
-    )
+# ``CreditPlan`` / ``_parse_credit_at`` / ``_build_credit_plan`` now live in
+# ``bin/_lib_credit.py`` (#279 S4 F1); re-imported at module top so the
+# ``bin/cctally`` re-exports and this module's own callers
+# (``cmd_record_credit``) resolve them unchanged.
 
 
 def _fire_in_place_credit(conn, week_start_date, cur_end_canon, weekly_percent,
@@ -2734,6 +2716,12 @@ def cmd_record_credit(args) -> int:
                   f"{plan.from_pct:g}% -> {plan.to_pct:g}% "
                   f"(effective {plan.effective_iso})")
         return 0
+    except _cctally().StatsDbCorruptError:
+        # #279 S1 F4: the global corrupt-DB contract (one-line diagnosis +
+        # exit 2) wins over record-credit's documented exit-3 DB-error mapping.
+        # StatsDbCorruptError subclasses sqlite3.DatabaseError, so without this
+        # re-raise the handler below would swallow it and return 3.
+        raise
     except sqlite3.DatabaseError as e:
         # Documented exit 3 (docs/commands/record-credit.md "3 — a database
         # error"). The inner ValueError->2 / EOFError paths return before
@@ -2768,9 +2756,11 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     # of silently reporting success on a dropped payload.
     now_dt = _command_as_of()
     now_epoch = int(now_dt.timestamp())
-    if not (now_epoch - _RECORD_USAGE_WEEK_PAST_SLACK_S
-            <= resets_at
-            <= now_epoch + _RECORD_USAGE_WEEK_FUTURE_BAND_S):
+    if not check_resets_at_plausibility(
+        resets_at, now_epoch,
+        past_slack_s=_RECORD_USAGE_WEEK_PAST_SLACK_S,
+        future_band_s=_RECORD_USAGE_WEEK_FUTURE_BAND_S,
+    ):
         eprint(
             f"[record-usage] rejecting --resets-at={resets_at}: outside "
             f"plausibility band [now-30d, now+8d]; "
@@ -2799,9 +2789,11 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
         #       _compute_block_totals charges entries past the real
         #       reset to this block). Dropping the 5h portion here
         #       skips maybe_update_five_hour_block entirely.
-        if not (now_epoch - _RECORD_USAGE_5H_PAST_SLACK_S
-                <= five_hour_resets_at_epoch
-                <= now_epoch + _RECORD_USAGE_5H_FUTURE_BAND_S):
+        if not check_resets_at_plausibility(
+            five_hour_resets_at_epoch, now_epoch,
+            past_slack_s=_RECORD_USAGE_5H_PAST_SLACK_S,
+            future_band_s=_RECORD_USAGE_5H_FUTURE_BAND_S,
+        ):
             eprint(
                 f"[record-usage] dropping --five-hour-resets-at="
                 f"{five_hour_resets_at_epoch}: outside plausibility band "
@@ -2980,14 +2972,28 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     # reachable. See the spec for the midpoint rationale.
                     prior_end_dt = parse_iso_datetime(prior_end_canon, "prior.week_end_at")
                     if prior_end_dt > now_utc and prior_pct is not None:
-                        drop = float(prior_pct) - float(weekly_percent)
-                        big_drop = drop >= c._RESET_PCT_DROP_THRESHOLD
-                        zero_only = (
-                            (not big_drop)
-                            and float(weekly_percent) <= c._RESET_ZERO_FLOOR_PCT
-                            and drop >= c._RESET_ZERO_MIN_DROP_PCT
+                        # Read the pending reset-to-zero marker up front (pure
+                        # file read) and compute whether it is armed for THIS
+                        # window; the debounce CLASSIFIER (pure) decides the
+                        # action from those values + the c._RESET_* constants,
+                        # then the glue below executes the decided I/O. The 5
+                        # branch outcomes (fire-immediate / confirm / clear /
+                        # arm / none) map 1:1 to the pre-extraction structure.
+                        marker = _read_reset_zero_marker()
+                        armed = (
+                            marker is not None
+                            and marker[0] == week_start_date
+                            and marker[1] == cur_end_canon
                         )
-                        if big_drop:
+                        decision = plan_weekly_credit_debounce(
+                            prior_pct, weekly_percent,
+                            drop_threshold=c._RESET_PCT_DROP_THRESHOLD,
+                            zero_floor_pct=c._RESET_ZERO_FLOOR_PCT,
+                            zero_min_drop_pct=c._RESET_ZERO_MIN_DROP_PCT,
+                            marker_armed=armed,
+                            marker_baseline=(marker[2] if armed else None),
+                        ).action
+                        if decision == FIRE_IMMEDIATE:
                             # >=25pp goodwill credit — fire immediately, never
                             # debounced. Clear any pending arm (now moot).
                             _clear_reset_zero_marker()
@@ -2996,53 +3002,42 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                                 observed_pre_credit_pct=float(prior_pct),
                                 effective_dt=_floor_to_hour(now_utc),
                             )
-                        else:
-                            marker = _read_reset_zero_marker()
-                            armed = (
-                                marker is not None
-                                and marker[0] == week_start_date
-                                and marker[1] == cur_end_canon
+                        elif decision == CONFIRM_RESET:
+                            # Second reading stayed low → confirm. Anchor the
+                            # reset at the FIRST-zero instant from the marker
+                            # (UTC-normalized like the backfill in-place path).
+                            first_zero_dt = parse_iso_datetime(
+                                marker[3], "reset_zero_marker.first_zero"
+                            ).astimezone(dt.timezone.utc)
+                            _fire_in_place_credit(
+                                conn, week_start_date, cur_end_canon,
+                                weekly_percent,
+                                observed_pre_credit_pct=marker[2],
+                                effective_dt=_floor_to_hour(first_zero_dt),
                             )
-                            if armed:
-                                baseline_pct = marker[2]
-                                if float(weekly_percent) <= baseline_pct / 2.0:
-                                    # Second reading stayed low → confirm. Anchor
-                                    # the reset at the FIRST-zero instant from the
-                                    # marker (UTC-normalized like the backfill
-                                    # in-place path).
-                                    first_zero_dt = parse_iso_datetime(
-                                        marker[3], "reset_zero_marker.first_zero"
-                                    ).astimezone(dt.timezone.utc)
-                                    _fire_in_place_credit(
-                                        conn, week_start_date, cur_end_canon,
-                                        weekly_percent,
-                                        observed_pre_credit_pct=baseline_pct,
-                                        effective_dt=_floor_to_hour(first_zero_dt),
-                                    )
-                                    # Clear ONLY after the fire completes (P2a):
-                                    # a mid-fire crash leaves the marker armed so
-                                    # the next zero re-confirms + re-runs the
-                                    # idempotent pivots.
-                                    _clear_reset_zero_marker()
-                                else:
-                                    # Recovered toward baseline → transient zero,
-                                    # not a reset. Clear, do not fire.
-                                    _clear_reset_zero_marker()
-                            elif zero_only:
-                                # First ~0 → arm; do NOT fire. The write clamp
-                                # suppresses this 0 (no event row yet), so the
-                                # prior snapshot stays at the baseline and this
-                                # shape re-evaluates next tick. first_zero_iso is
-                                # the _command_as_of() value (now_utc), NOT
-                                # wall-clock — it becomes the effective anchor.
-                                _arm_reset_zero_marker(
-                                    week_start_date, cur_end_canon,
-                                    baseline_pct=float(prior_pct),
-                                    first_zero_iso=now_utc.isoformat(timespec="seconds"),
-                                )
-                            # else: not a reset shape and not armed → nothing.
-                            #       A non-matching stale marker is inert (ignored
-                            #       on key mismatch, overwritten by the next arm).
+                            # Clear ONLY after the fire completes (P2a): a
+                            # mid-fire crash leaves the marker armed so the next
+                            # zero re-confirms + re-runs the idempotent pivots.
+                            _clear_reset_zero_marker()
+                        elif decision == CLEAR_MARKER:
+                            # Recovered toward baseline → transient zero, not a
+                            # reset. Clear, do not fire.
+                            _clear_reset_zero_marker()
+                        elif decision == ARM_MARKER:
+                            # First ~0 → arm; do NOT fire. The write clamp
+                            # suppresses this 0 (no event row yet), so the prior
+                            # snapshot stays at the baseline and this shape
+                            # re-evaluates next tick. first_zero_iso is the
+                            # _command_as_of() value (now_utc), NOT wall-clock —
+                            # it becomes the effective anchor.
+                            _arm_reset_zero_marker(
+                                week_start_date, cur_end_canon,
+                                baseline_pct=float(prior_pct),
+                                first_zero_iso=now_utc.isoformat(timespec="seconds"),
+                            )
+                        # else NO_ACTION: not a reset shape and not armed →
+                        #     nothing. A non-matching stale marker is inert
+                        #     (ignored on key mismatch, overwritten by next arm).
 
             # ── 5h in-place credit detection (parallel to weekly above) ──
             # Spec §2.2 of
@@ -3098,10 +3093,10 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         # outer try block from
                         # ``dt.datetime.now(dt.timezone.utc)``; reuse it
                         # so both branches see the same instant.
-                        if (
-                            prior_5h_resets_dt > now_utc
-                            and (prior_5h_pct - float(five_hour_percent))
-                                >= c._FIVE_HOUR_RESET_PCT_DROP_THRESHOLD
+                        if plan_five_hour_credit(
+                            prior_5h_pct, float(five_hour_percent),
+                            drop_threshold=c._FIVE_HOUR_RESET_PCT_DROP_THRESHOLD,
+                            prior_resets_in_future=(prior_5h_resets_dt > now_utc),
                         ):
                             # Pair-check dedup pre-check (spec §2.2;
                             # refined by Codex r4 P1 finding). The
@@ -3305,7 +3300,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
             """,
             (week_start_date, clamp_floor_iso),
         ).fetchone()
-        if max_row and max_row["v"] is not None and round(weekly_percent, 1) < round(float(max_row["v"]), 1):
+        if hwm_clamp_applies(weekly_percent, max_row["v"] if max_row else None):
             should_insert = False
         else:
             # 5-hour usage is monotonically non-decreasing within a window
@@ -3350,11 +3345,8 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     """,
                     (int(five_hour_window_key), int(five_hour_window_key)),
                 ).fetchone()
-                if (
-                    max_5h_row
-                    and max_5h_row["v"] is not None
-                    and round(five_hour_percent, 1)
-                        < round(float(max_5h_row["v"]), 1)
+                if hwm_clamp_applies(
+                    five_hour_percent, max_5h_row["v"] if max_5h_row else None
                 ):
                     five_hour_percent = float(max_5h_row["v"])
 
@@ -3450,9 +3442,12 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         "WHERE week_start_date = ? AND reset_event_id = ?",
                         (week_start_date, heal_segment),
                     ).fetchone()
-                    if max_existing is None or max_existing["m"] is None:
-                        need_milestone_heal = True
-                    elif int(max_existing["m"]) < latest_floor:
+                    existing_m = (
+                        int(max_existing["m"])
+                        if max_existing and max_existing["m"] is not None
+                        else None
+                    )
+                    if milestone_coverage_owes(existing_m, latest_floor):
                         need_milestone_heal = True
 
                 # Probe 2: do we owe a 5h-block update? Either no row
@@ -3515,14 +3510,14 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                                     "  AND reset_event_id = ?",
                                     (int(window_key), heal_5h_segment),
                                 ).fetchone()
-                                if (
-                                    max_5h_existing is None
-                                    or max_5h_existing["m"] is None
-                                ):
-                                    need_5h_heal = True
-                                elif (
+                                existing_5h_m = (
                                     int(max_5h_existing["m"])
-                                    < latest_5h_floor
+                                    if max_5h_existing
+                                    and max_5h_existing["m"] is not None
+                                    else None
+                                )
+                                if milestone_coverage_owes(
+                                    existing_5h_m, latest_5h_floor
                                 ):
                                     need_5h_heal = True
             finally:
@@ -3651,7 +3646,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                 existing_hwm = float(parts[1])
         except (FileNotFoundError, ValueError, OSError):
             pass
-        if weekly_percent >= existing_hwm:
+        if hwm_file_next(existing_hwm, weekly_percent) is not None:
             hwm_path.write_text(f"{week_start_date} {weekly_percent}\n")
     except OSError:
         pass
@@ -3674,7 +3669,7 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                     existing_hwm5 = float(parts5[1])
             except (FileNotFoundError, ValueError, OSError):
                 pass
-            if five_hour_percent >= existing_hwm5:
+            if hwm_file_next(existing_hwm5, five_hour_percent) is not None:
                 hwm5_path.write_text(f"{five_resets_key} {five_hour_percent}\n")
         except OSError:
             pass
@@ -3777,12 +3772,14 @@ def _hook_tick_session_short(sid: str) -> str:
 
 
 def _hook_tick_format_log_line(
-    event: str, session: str, ingested: int, oauth_status: str, dur_ms: int
+    event: str, session: str, ingested: int, oauth_status: str, dur_ms: int,
+    *, malformed: int = 0, skipped: int = 0,
 ) -> str:
     ts = now_utc_iso()
     return (
         f"{ts} event={event:14s} session={session} "
-        f"ingested={ingested} oauth={oauth_status} dur_ms={dur_ms}"
+        f"ingested={ingested} malformed={malformed} skipped={skipped} "
+        f"oauth={oauth_status} dur_ms={dur_ms}"
     )
 
 
@@ -3880,6 +3877,10 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
     # --- Steps 3-7: wrap remainder in try/except (always exit 0 in normal mode) ---
     start = time.monotonic()
     ingested = 0
+    # #279 S2 F1: parse-health counters from the local sync, surfaced on the
+    # hook-tick log line (uniform fields — always emitted, defaulted to 0).
+    parse_malformed = 0
+    parse_skipped = 0
     oauth_status = "skipped-no-oauth" if no_oauth else "throttled(age=?s)"
     # Pre-fetch throttle state captured for --explain output. The OAuth
     # block re-touches the throttle marker after a successful fetch, so
@@ -3898,6 +3899,8 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
             try:
                 stats = sync_cache(cache_conn)
                 ingested = int(stats.rows_changed)
+                parse_malformed = int(stats.lines_malformed)
+                parse_skipped = int(stats.assistant_lines_skipped)
             finally:
                 try:
                     cache_conn.close()
@@ -3958,6 +3961,8 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
         ingested=ingested,
         oauth_status=oauth_status,
         dur_ms=dur_ms,
+        malformed=parse_malformed,
+        skipped=parse_skipped,
     )
     _hook_tick_log_line(line)
     _hook_tick_log_rotate_if_needed()