cctally 1.88.2 → 1.89.1

package/bin/_cctally_doctor.py

@@ -414,6 +414,65 @@ def _codex_lifecycle_activity_24h(
     return records
 
 
+def _codex_quota_verify_activity_24h(*, now_utc: "dt.datetime") -> dict:
+    """Aggregate the detached `_codex-quota-verify` worker's 24h outcomes.
+
+    The worker's three streams are `/dev/null` and its exit code is observed by
+    nobody, so `hook-tick.log` is the only place its outcome can land — which is
+    why it writes there. `_codex_lifecycle_activity_24h` above cannot supply
+    this: worker lines carry no `source_root_key`, so its root filter drops
+    every one of them.
+
+    Same bounded-read contract as its sibling — timestamped records, aggregate
+    counters only, never session/prompt/response content.
+    """
+    cutoff = now_utc - dt.timedelta(hours=24)
+    counts: dict = {
+        "success_count_24h": 0,
+        "error_count_24h": 0,
+        "spawn_failure_count_24h": 0,
+        "last_success_at": None,
+    }
+    for path in (
+        _cctally_core.HOOK_TICK_LOG_ROTATED_PATH,
+        _cctally_core.HOOK_TICK_LOG_PATH,
+    ):
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            tokens = line.split()
+            if not tokens:
+                continue
+            try:
+                captured_at = parse_iso_datetime(
+                    tokens[0], "codex quota verify log timestamp")
+                captured_at = captured_at.astimezone(dt.timezone.utc)
+            except (IndexError, ValueError, TypeError):
+                continue
+            if captured_at > now_utc or captured_at < cutoff:
+                continue
+            fields = {
+                token.split("=", 1)[0]: token.split("=", 1)[1]
+                for token in tokens[1:] if "=" in token
+            }
+            if fields.get("provider") != "codex":
+                continue
+            op = fields.get("op")
+            outcome = fields.get("result")
+            if op == "quota-verify" and outcome == "success":
+                counts["success_count_24h"] += 1
+                prior = counts["last_success_at"]
+                if prior is None or captured_at > prior:
+                    counts["last_success_at"] = captured_at
+            elif op == "quota-verify" and outcome == "error":
+                counts["error_count_24h"] += 1
+            elif op == "quota-verify-spawn" and outcome == "failed":
+                counts["spawn_failure_count_24h"] += 1
+    return counts
+
+
 def _gather_accounts_state(now_utc: "dt.datetime") -> dict:
     """Best-effort account-attribution state for the doctor `accounts.*` legs
     (#341). Never raises: identity + registry reads are read-only and each guard
@@ -1120,6 +1179,12 @@ def _doctor_gather_state_impl(
     except Exception:
         codex_lifecycle_activity_24h = {}
 
+    try:
+        codex_quota_verify_activity = _codex_quota_verify_activity_24h(
+            now_utc=now_utc)
+    except Exception:
+        codex_quota_verify_activity = None
+
     # ── Parse health (#279 S2 F5a) ───────────────────────────────────
     parse_health_claude = parse_health_codex = None
     # #416 review B4: the durable record that a torn Codex `auth.json` halted
@@ -1131,19 +1196,30 @@ def _doctor_gather_state_impl(
     # from the kernel constants, never inline literals.
     codex_replay_pending = None
     codex_replay_blocked = None
+    # public #5: the budgeted-decline record. Same JSON-dict contract as the
+    # blocked one, and the only signal a hook-only install produces when its
+    # Codex ingest is frozen behind an un-runnable replay.
+    codex_replay_deferred = None
+    # public #5 spec §5: the hook's budgeted-ingest backlog record. Absent means
+    # a zero backlog — a drained walk DELETES the row rather than zeroing it, so
+    # None and "nothing owed" are the same state by construction.
+    codex_ingest_backlog = None
     try:
         import _lib_codex_conversation as _codex_kern
         _blocked_key = _codex_kern.CODEX_REPLAY_BLOCKED_KEY
         _pending_key = _codex_kern.CODEX_REPLAY_FROM_ZERO_KEY
+        _deferred_key = _codex_kern.CODEX_REPLAY_DEFERRED_KEY
     except Exception:
         _blocked_key = "codex_replay_from_zero_blocked"
         _pending_key = "codex_replay_from_zero_pending"
+        _deferred_key = "codex_replay_from_zero_deferred"
     try:
         if _cache_probe_allowed and _cctally_core.CACHE_DB_PATH.exists():
             conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
             try:
                 for _key in ("parse_health_claude", "parse_health_codex",
-                             "codex_torn_auth_deferred", _blocked_key):
+                             "codex_torn_auth_deferred", _blocked_key,
+                             _deferred_key, "codex_ingest_backlog"):
                     try:
                         row = conn.execute(
                             "SELECT value FROM cache_meta WHERE key = ?",
@@ -1158,6 +1234,10 @@ def _doctor_gather_state_impl(
                                     parse_health_codex = _parsed
                                 elif _key == _blocked_key:
                                     codex_replay_blocked = _parsed
+                                elif _key == _deferred_key:
+                                    codex_replay_deferred = _parsed
+                                elif _key == "codex_ingest_backlog":
+                                    codex_ingest_backlog = _parsed
                                 else:
                                     codex_torn_deferred = _parsed
                     except (sqlite3.OperationalError, ValueError):
@@ -1744,8 +1824,10 @@ def _doctor_gather_state_impl(
         parse_health_claude=parse_health_claude,
         parse_health_codex=parse_health_codex,
         codex_torn_deferred=codex_torn_deferred,
+        codex_ingest_backlog=codex_ingest_backlog,
         codex_replay_pending=codex_replay_pending,
         codex_replay_blocked=codex_replay_blocked,
+        codex_replay_deferred=codex_replay_deferred,
         stats_db_quick_check=stats_db_quick_check,
         cache_db_quick_check=cache_db_quick_check,
         conversations_db_quick_check=conversations_db_quick_check,
@@ -1765,6 +1847,7 @@ def _doctor_gather_state_impl(
         codex_quota_windows=codex_quota_windows,
         codex_hook_roots=codex_hook_roots,
         codex_lifecycle_activity_24h=codex_lifecycle_activity_24h,
+        codex_quota_verify_activity=codex_quota_verify_activity,
         # #311: precomputed statusLine.refreshInterval classification.
         statusline_refresh_state=statusline_refresh_state,
         statusline_pipeline=statusline_pipeline,

package/bin/_cctally_journal.py

@@ -4244,6 +4244,7 @@ _REBUILD_REQUIRED_TABLES = frozenset(
         "projected_milestones",
         "quota_alert_arming",
         "quota_percent_milestones",
+        "quota_projection_ledger_state",
         "quota_projection_state",
         "quota_threshold_events",
         "quota_window_blocks",
@@ -4298,7 +4299,7 @@ _REBUILD_REQUIRED_INDEXES = frozenset(
 # omitted column, constraint, partial predicate, or index definition.  An epoch
 # schema change must update this contract alongside STATS_INDEX_EPOCH.
 _REBUILD_SCHEMA_FINGERPRINT = (
-    "3e0ec46a965c9fa10ac827cfd1656c66ecae50ed289e3aa1c34d2cf6a3e5c4a3"
+    "1e0a8cc22b3dc754cb8a6074ff9d2ef28df77b656dfc65347e4afbcb6edfdfae"
 )
 
 

package/bin/_cctally_parser.py

@@ -3337,6 +3337,46 @@ def _build_telemetry_beat_parser(subparsers, name, *, help_text, xref=None):
     )
     tb.set_defaults(func=c.cmd_telemetry_beat_internal)
 
+def _build_codex_quota_verify_parser(subparsers, name, *, help_text, xref=None):
+    """Build the `_codex-quota-verify` parser (public #5 spec §2)."""
+    c = _cctally()
+    qv = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+                    """\
+                    Internal subcommand: detached worker that runs the Codex
+                    quota projection's periodic whole-history verification
+                    pass. Spawned by the Codex hook tick when the pass comes
+                    due, so the one unbounded operation in the incremental
+                    design never runs on the blocking hook path. Always returns
+                    0; the deadline is stamped only if the pass completes.
+                    """
+                ),
+    )
+    qv.set_defaults(func=c.cmd_codex_quota_verify_internal)
+
+def _build_codex_replay_drain_parser(subparsers, name, *, help_text, xref=None):
+    """Build the `_codex-replay-drain` parser (public #5 §4)."""
+    c = _cctally()
+    rd = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+                    """\
+                    Internal subcommand: detached worker that performs the
+                    byte-zero Codex replay a budgeted hook tick declined. The
+                    replay is not sliceable, so the hook never attempts one and
+                    a hook-only install would otherwise freeze all Codex ingest
+                    permanently. Always returns 0; failures are written to
+                    hook-tick.log.
+                    """
+                ),
+    )
+    rd.set_defaults(func=c.cmd_codex_replay_drain_internal)
+
 def _build_repair_symlinks_parser(subparsers, name, *, help_text, xref=None):
     """Build the `repair-symlinks` parser (registered via _REGISTRATION; #279 S6 W3).
 
@@ -3417,6 +3457,8 @@ _REGISTRATION = (
     _Reg('update', _build_update_parser, "Update cctally to the latest version", None, None),
     _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('_codex-replay-drain', _build_codex_replay_drain_parser, argparse.SUPPRESS, None, None),
     _Reg('repair-symlinks', _build_repair_symlinks_parser, argparse.SUPPRESS, None, None),
 )