cctally 1.65.0 → 1.66.0

package/bin/_lib_json_envelope.py

@@ -0,0 +1,38 @@
+"""Pure JSON wire-format helpers: schemaVersion envelope + canonical UTC-Z serializer.
+
+stamp_schema_version() is the single chokepoint for the additive camelCase
+``schemaVersion: 1`` envelope adopted across reporting ``--json`` surfaces
+(#279 S6 W1; convention: docs/cli-contract.md). _iso_z() is the canonical
+None-safe seconds-precision UTC-Z serializer (the forecast/dashboard-envelope
+behavior; _lib_doctor._iso_z deliberately diverges — see its docstring).
+
+Pure kernel: stdlib-only, no cctally back-import (split design §5.3).
+"""
+from __future__ import annotations
+
+import datetime as dt
+
+SCHEMA_VERSION_KEY = "schemaVersion"
+
+
+def stamp_schema_version(payload: dict, *, version: int = 1,
+                         key: str = SCHEMA_VERSION_KEY) -> dict:
+    """Return a new dict with ``key: version`` first.
+
+    Always returns a shallow copy; never mutates ``payload``. If ``key`` is
+    already present the copy preserves the existing value AND key order
+    (value- and order-idempotent no-op). Formatting is the caller's concern:
+    this returns a dict, each emitter keeps its own json.dumps arguments.
+    """
+    if key in payload:
+        return dict(payload)
+    out = {key: version}
+    out.update(payload)
+    return out
+
+
+def _iso_z(d: "dt.datetime | None") -> "str | None":
+    """None-safe UTC ISO-8601 with Z suffix, seconds precision."""
+    if d is None:
+        return None
+    return d.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

package/bin/_lib_jsonl.py

@@ -25,7 +25,7 @@ import json
 import pathlib
 import re
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -109,6 +109,13 @@ def _parse_usage_entries(
 ) -> list[UsageEntry]:
     """Parse one JSONL file's assistant entries within [range_start, range_end].
 
+    Per-line gating is `parse_cost_entry`'s — the SINGLE implementation shared
+    with the cache-ingest path (#279 S3 F2). This fallback (used when cache.db
+    can't be opened) no longer re-implements the type -> timestamp -> usage ->
+    model -> synthetic -> costUSD gating inline, so the two paths can never
+    drift. The only fallback-specific step is the range filter, applied to the
+    constructed `entry.timestamp` (inclusive bounds preserved).
+
     Dedup contract (matches ccusage's `push_deduped_entry`):
     - Entries with non-null (msg_id, req_id) go into `dedupe_map`; if a key
       already maps to an entry, replace iff `_should_replace(candidate, existing)`.
@@ -117,13 +124,14 @@ def _parse_usage_entries(
       land in a separate list — partial UNIQUE index on the cache mirrors
       this behavior.
     - `<synthetic>` model rows are dropped entirely (matches ccusage's
-      claude_loader.rs:454).
+      claude_loader.rs:454) — `parse_cost_entry` returns None for them.
 
     Caller is responsible for sorting the returned list by timestamp if
     needed; `_collect_entries_direct` does this once across all files
     after flattening `dedupe_map.values()`.
     """
     no_key_entries: list[UsageEntry] = []
+    path_str = str(jsonl_path)
     try:
         with open(jsonl_path, "r", encoding="utf-8", errors="replace") as fh:
             for line in fh:
@@ -134,60 +142,12 @@ def _parse_usage_entries(
                     obj = json.loads(line)
                 except json.JSONDecodeError:
                     continue
-
-                if obj.get("type") != "assistant":
-                    continue
-
-                ts_raw = obj.get("timestamp")
-                if not isinstance(ts_raw, str) or not ts_raw.strip():
-                    continue
-
-                msg = obj.get("message")
-                if not isinstance(msg, dict):
-                    msg = obj
-
-                usage = msg.get("usage")
-                if not isinstance(usage, dict):
-                    continue
-
-                model = msg.get("model") or obj.get("model")
-                if not isinstance(model, str) or not model.strip():
-                    continue
-                model = model.strip()
-                if model == "<synthetic>":
-                    # Matches ccusage's claude_loader.rs:454 — synthetic
-                    # placeholder rows carry no billable usage.
+                parsed = parse_cost_entry(obj, path_str)
+                if parsed is None:
                     continue
-
-                try:
-                    ts = dt.datetime.fromisoformat(
-                        ts_raw.strip().replace("Z", "+00:00")
-                    )
-                    if ts.tzinfo is None:
-                        ts = ts.replace(tzinfo=dt.timezone.utc)
-                except ValueError:
-                    continue
-
-                if ts < range_start or ts > range_end:
+                entry, msg_id, req_id = parsed
+                if entry.timestamp < range_start or entry.timestamp > range_end:
                     continue
-
-                msg_id = msg.get("id")
-                req_id = obj.get("requestId")
-                cost_usd_raw = obj.get("costUSD")
-                cost_usd = (
-                    float(cost_usd_raw)
-                    if cost_usd_raw is not None
-                    else None
-                )
-
-                entry = UsageEntry(
-                    timestamp=ts,
-                    model=model,
-                    usage=usage,
-                    cost_usd=cost_usd,
-                    source_path=str(jsonl_path),
-                )
-
                 if msg_id is None or req_id is None:
                     no_key_entries.append(entry)
                     continue
@@ -203,24 +163,25 @@ def _parse_usage_entries(
     return no_key_entries
 
 
-def parse_cost_entry(obj, path_str: str):
-    """Pure per-line cost parser: given a parsed JSONL object, return
-    ``(UsageEntry, msg_id, req_id)`` when it is a billable assistant entry, or
-    ``None`` otherwise (non-assistant, missing/invalid usage, model, or
-    timestamp, or a ``<synthetic>`` placeholder). No I/O, no byte offset — the
-    caller owns the readline()+tell() loop.
+_DELIBERATE_SKIP_REASONS = ("not-assistant", "synthetic")
 
-    Extracted (#138) so the streaming ``_iter_jsonl_entries_with_offsets`` reader
-    and the fused single-pass sync walker (``_cctally_cache._iter_sync_entries``)
-    share ONE gating implementation — each JSONL line is ``json.loads``-parsed
-    once and classified once, never re-parsed for a separate second walk.
+
+def _classify_cost_entry(obj, path_str: str):
+    """Reason-returning core of ``parse_cost_entry`` (#279 S2 F1). Returns
+    ``(parsed, reason)`` where exactly one is non-None; ``parsed`` is the
+    ``(UsageEntry, msg_id, req_id)`` tuple. Reasons: ``not-assistant`` /
+    ``synthetic`` (deliberate skips) and the drift trio ``bad-timestamp`` /
+    ``no-usage`` / ``no-model``. The gating ORDER is the contract — it must
+    stay identical to the pre-#279 ``parse_cost_entry`` body (type ->
+    raw-timestamp -> usage -> model -> synthetic -> timestamp-parse) so the
+    public wrapper's behavior is unchanged.
     """
     if obj.get("type") != "assistant":
-        return None
+        return None, "not-assistant"
 
     ts_raw = obj.get("timestamp")
     if not isinstance(ts_raw, str) or not ts_raw.strip():
-        return None
+        return None, "bad-timestamp"
 
     msg = obj.get("message")
     if not isinstance(msg, dict):
@@ -228,29 +189,35 @@ def parse_cost_entry(obj, path_str: str):
 
     usage = msg.get("usage")
     if not isinstance(usage, dict):
-        return None
+        return None, "no-usage"
 
     model = msg.get("model") or obj.get("model")
     if not isinstance(model, str) or not model.strip():
-        return None
+        return None, "no-model"
     model = model.strip()
     if model == "<synthetic>":
         # Matches ccusage's claude_loader.rs:454. Filtered here so the cache
         # ingest path can't accidentally store these rows even if a downstream
         # loop forgets to double-check (see `sync_cache` in _cctally_cache.py).
-        return None
+        return None, "synthetic"
 
     try:
         ts = dt.datetime.fromisoformat(ts_raw.strip().replace("Z", "+00:00"))
         if ts.tzinfo is None:
             ts = ts.replace(tzinfo=dt.timezone.utc)
     except ValueError:
-        return None
+        return None, "bad-timestamp"
 
     msg_id = msg.get("id")
     req_id = obj.get("requestId")
     cost_usd_raw = obj.get("costUSD")
-    cost_usd = float(cost_usd_raw) if cost_usd_raw is not None else None
+    try:
+        cost_usd = float(cost_usd_raw) if cost_usd_raw is not None else None
+    except (TypeError, ValueError):
+        # Drift-hardened (#279 S3, Codex gate F1): a malformed costUSD must
+        # not abort a whole sync/read — degrade to "no raw cost"; the
+        # token-derived cost still computes at query time.
+        cost_usd = None
 
     return (
         UsageEntry(
@@ -262,7 +229,41 @@ def parse_cost_entry(obj, path_str: str):
         ),
         msg_id,
         req_id,
-    )
+    ), None
+
+
+def parse_cost_entry(obj, path_str: str):
+    """Pure per-line cost parser: given a parsed JSONL object, return
+    ``(UsageEntry, msg_id, req_id)`` when it is a billable assistant entry, or
+    ``None`` otherwise (non-assistant, missing/invalid usage, model, or
+    timestamp, or a ``<synthetic>`` placeholder). No I/O, no byte offset — the
+    caller owns the readline()+tell() loop.
+
+    Extracted (#138) so the streaming ``_iter_jsonl_entries_with_offsets`` reader
+    and the fused single-pass sync walker (``_cctally_cache._iter_sync_entries``)
+    share ONE gating implementation — each JSONL line is ``json.loads``-parsed
+    once and classified once, never re-parsed for a separate second walk.
+
+    The body now delegates to ``_classify_cost_entry`` (#279 S2 F1) so the
+    parse-health drift classifier and this cost parser can never disagree on
+    the gating order; the public contract (returns the tuple or ``None``) is
+    unchanged.
+    """
+    parsed, _reason = _classify_cost_entry(obj, path_str)
+    return parsed
+
+
+def assistant_skip_reason(obj) -> "str | None":
+    """Drift classifier for parse-health counters (#279 S2 F1): the reason
+    a line that LOOKS like an assistant cost entry was skipped, or None
+    when the skip is deliberate (non-assistant, ``<synthetic>``) or the
+    line parses fine. Callers invoke this only for lines where
+    ``parse_cost_entry`` returned None, so the double-classify cost is
+    bounded to skipped lines."""
+    parsed, reason = _classify_cost_entry(obj, "")
+    if parsed is not None or reason in _DELIBERATE_SKIP_REASONS:
+        return None
+    return reason
 
 
 def _iter_jsonl_entries_with_offsets(fh, path_str: str):
@@ -319,7 +320,27 @@ class _CodexIterState:
     """
     session_id: str | None = None
     model: str | None = None
+    # #279 S3 F1: the REAL dedup watermark. Seeded by the caller (non-zero
+    # wins over the initial_total_tokens kwarg) and STAMPED by the iterator on
+    # every yield to the cumulative `total_token_usage.total_tokens` the guard
+    # admitted — so after the iterator drains this equals the guard's terminal
+    # watermark by construction, and the caller persists exactly it (replacing
+    # the old reconstructed initial+Σ(per-turn) sum, which could diverge).
     total_tokens: int = 0
+    # #279 S2 F1 parse-health counters — per-iterator-call; sync_codex_cache
+    # folds them into CodexIngestStats after each file drains. Reason
+    # vocabulary: info-non-dict / no-last-token-usage / bad-timestamp /
+    # no-session-id. Rate-limit-only events (info None) and cumulative-dedup
+    # re-emissions are NORMAL and never counted.
+    lines_seen: int = 0
+    lines_malformed: int = 0
+    token_events_skipped: int = 0
+    skip_reasons: dict = field(default_factory=dict)
+
+
+def _codex_skip(state: "_CodexIterState", reason: str) -> None:
+    state.token_events_skipped += 1
+    state.skip_reasons[reason] = state.skip_reasons.get(reason, 0) + 1
 
 
 def _iter_codex_jsonl_entries_with_offsets(
@@ -375,7 +396,14 @@ def _iter_codex_jsonl_entries_with_offsets(
         state.session_id = initial_session_id
     if state.model is None and initial_model is not None:
         state.model = initial_model
-    last_total_tokens: int = int(initial_total_tokens or 0)
+    # #279 S3 F1: the state carries the REAL dedup watermark. Seeding
+    # precedence mirrors session_id/model: a caller-supplied NON-ZERO state
+    # wins; the kwarg seeds otherwise. (total_tokens has no None sentinel —
+    # 0 IS the unset value; a genuine 0 watermark and "unset" are the same
+    # thing: both mean "dedupe against nothing".)
+    if state.total_tokens == 0 and initial_total_tokens:
+        state.total_tokens = int(initial_total_tokens)
+    last_total_tokens: int = state.total_tokens
     # Suppress the filename-UUID fallback warning when we already have a
     # seeded session_id (delta resume path). Without this, every resume
     # into a slice of the file that doesn't re-observe session_meta would
@@ -395,9 +423,11 @@ def _iter_codex_jsonl_entries_with_offsets(
         stripped = line.strip()
         if not stripped:
             continue
+        state.lines_seen += 1  # #279 S2 F1: non-blank lines (malformed included)
         try:
             obj = json.loads(stripped)
         except json.JSONDecodeError:
+            state.lines_malformed += 1
             continue
 
         rtype = obj.get("type")
@@ -421,10 +451,14 @@ def _iter_codex_jsonl_entries_with_offsets(
         if payload.get("type") != "token_count":
             continue
         info = payload.get("info")
+        if info is None:
+            continue  # rate-limit-only event — normal, not drift
         if not isinstance(info, dict):
+            _codex_skip(state, "info-non-dict")
             continue
         ltu = info.get("last_token_usage")
         if not isinstance(ltu, dict):
+            _codex_skip(state, "no-last-token-usage")
             continue
 
         # Dedupe re-emitted token_count events. Codex re-emits `last_token_usage`
@@ -445,12 +479,14 @@ def _iter_codex_jsonl_entries_with_offsets(
 
         ts_raw = obj.get("timestamp")
         if not isinstance(ts_raw, str) or not ts_raw.strip():
+            _codex_skip(state, "bad-timestamp")
             continue
         try:
             ts = dt.datetime.fromisoformat(ts_raw.strip().replace("Z", "+00:00"))
             if ts.tzinfo is None:
                 ts = ts.replace(tzinfo=dt.timezone.utc)
         except ValueError:
+            _codex_skip(state, "bad-timestamp")
             continue
 
         session_id = state.session_id
@@ -464,6 +500,7 @@ def _iter_codex_jsonl_entries_with_offsets(
                 filename_session_id_warned = True
             if session_id is None:
                 # No session_meta and no parseable filename UUID — skip row.
+                _codex_skip(state, "no-session-id")
                 continue
 
         model = state.model or "unknown"
@@ -491,5 +528,10 @@ def _iter_codex_jsonl_entries_with_offsets(
         )
         # Advance the cumulative watermark only after a successful yield so
         # resume-from-offset continues to dedupe against the last counted turn.
+        # #279 S3 F1: stamp the state too — after the iterator drains,
+        # state.total_tokens IS the guard's terminal watermark, which the
+        # caller persists (the old reconstructed initial+Σ(per-turn) sum could
+        # diverge from it and double-count/skip on resume).
         if isinstance(ttu, dict) and cumulative is not None:
             last_total_tokens = cumulative
+            state.total_tokens = cumulative

package/bin/_lib_log.py

@@ -0,0 +1,96 @@
+"""Stdlib-logging chokepoint (issue #279 S2, F2).
+
+One place decides backend verbosity: ``CCTALLY_DEBUG`` gates DEBUG-level
+stderr output (tracebacks via ``exc_info=True``); the default posture is
+WARNING+ only, so adopters like the dashboard ``log_error`` surface
+errors without any env flag. Pure leaf — no sibling imports (mirrors
+``_lib_perf``'s env handling). The falsey set matches
+``_cctally_core._truthy_env`` EXACTLY (pinned by tests/test_lib_log.py,
+not by import coupling): unset/empty/``0``/``false``/``no`` are off,
+anything else is on. Deliberately NOT ``_lib_perf._FALSEY`` (which also
+treats ``off`` as false) — #279 S2 Codex review P2-5.
+
+Optional file sink: ``CCTALLY_DEBUG_LOG=<path>`` attaches an append-mode
+FileHandler at that explicit path (no LOG_DIR default — the module stays
+leaf-pure). Handler-attach failures degrade silently to stderr-only.
+
+The stderr handler resolves ``sys.stderr`` at EMIT time (late binding) so
+pytest capsys replacement and hook-tick's dup2 stdio redirect both see
+records; a handler bound at configure time would write to a dead stream.
+
+The configure-once latch lives on ``logging.getLogger("cctally").handlers``
+(process-global), NOT on a module global — a SourceFileLoader re-import of
+this module must not attach a second handler and double-print.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+_FALSEY = ("", "0", "false", "no")
+
+
+def _env_truthy(name: str) -> bool:
+    v = os.environ.get(name)
+    return v is not None and v.strip().lower() not in _FALSEY
+
+
+_DEBUG = _env_truthy("CCTALLY_DEBUG")
+
+
+def debug_enabled() -> bool:
+    return _DEBUG
+
+
+def set_debug(value: bool) -> None:
+    """Flip debug at runtime (tests). Re-levels an already-configured
+    logger so a latch created before the flip follows it."""
+    global _DEBUG
+    _DEBUG = bool(value)
+    root = logging.getLogger("cctally")
+    if root.handlers:
+        root.setLevel(logging.DEBUG if _DEBUG else logging.WARNING)
+
+
+class _LateStderrHandler(logging.StreamHandler):
+    """StreamHandler that resolves sys.stderr at emit time."""
+
+    def __init__(self):
+        super().__init__(sys.stderr)
+
+    @property
+    def stream(self):
+        return sys.stderr
+
+    @stream.setter
+    def stream(self, value):  # StreamHandler.__init__ assigns; ignore.
+        pass
+
+
+_FORMAT = "%(asctime)s [%(name)s] %(levelname)s: %(message)s"
+_DATEFMT = "%Y-%m-%dT%H:%M:%S"
+
+
+def get_logger(name: str = "cctally") -> logging.Logger:
+    """Return the chokepoint logger. Pass the bare suffix:
+    ``get_logger("dashboard")`` -> logger ``cctally.dashboard``."""
+    root = logging.getLogger("cctally")
+    if not root.handlers:  # configure-once latch (process-global)
+        formatter = logging.Formatter(_FORMAT, datefmt=_DATEFMT)
+        handler = _LateStderrHandler()
+        handler.setFormatter(formatter)
+        root.addHandler(handler)
+        sink = (os.environ.get("CCTALLY_DEBUG_LOG") or "").strip()
+        if sink:
+            try:
+                fh = logging.FileHandler(sink, encoding="utf-8")
+                fh.setFormatter(formatter)
+                root.addHandler(fh)
+            except OSError:
+                pass  # degrade to stderr-only
+        root.setLevel(logging.DEBUG if _DEBUG else logging.WARNING)
+        root.propagate = False
+    if name in ("", "cctally"):
+        return root
+    return logging.getLogger(f"cctally.{name}")

package/bin/_lib_pricing.py

@@ -53,7 +53,7 @@ def _chip_for_model(name: str) -> str:
 # Date the embedded pricing snapshots below were last verified against
 # vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
 # is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
-PRICING_SNAPSHOT_DATE = "2026-07-01"
+PRICING_SNAPSHOT_DATE = "2026-07-10"
 PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
 
 # Canonical machine-readable pricing source (Claude values + Codex values).
@@ -77,6 +77,11 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
     {
         "model": "claude-sonnet-5",
         "field": field,
+        # Structured cutover date (#279 S7 W7): the intro rate is in effect
+        # THROUGH 2026-08-31, so this suppression is valid through then and
+        # `expired_allowlist_entries` flags it the day after. Keep the prose in
+        # `reason`; the date here is what the offline expiry check + the cron read.
+        "expires": "2026-08-31",
         "reason": (
             "LiteLLM tracks the claude-sonnet-5 introductory rate "
             "($2/$10 per MTok, through 2026-08-31); we deliberately embed the "
@@ -322,6 +327,11 @@ _unknown_model_warnings: set[str] = set()
 #   nothing missing. Models absent from this table still fall back to `gpt-5`
 #   pricing with isFallback=true (matches upstream's LEGACY_FALLBACK_MODEL
 #   behavior); a one-shot stderr warning is emitted per unknown model name.
+#   2026-07-10: added the gpt-5.6 family (gpt-5.6, gpt-5.6-sol, gpt-5.6-terra,
+#   gpt-5.6-luna) that LiteLLM published since the last sync — flagged by
+#   `pricing-check` as missing_from_us (gpt-5.6-sol had real usage falling back
+#   to gpt-5). Exact model_prices_and_context_window.json values, each with the
+#   above-272k tier (max_input_tokens 1050000).
 #
 # Billing rules:
 # - reasoning_output_tokens is billed at the *output* rate (matches
@@ -414,6 +424,42 @@ CODEX_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_read_input_token_cost_above_272k_tokens": 1e-06,
         "output_cost_per_token_above_272k_tokens": 4.5e-05,
     },
+    # ── 2026-07-10 sync: gpt-5.6 family (LiteLLM openai-provider entries) ──
+    # Exact model_prices_and_context_window.json values; each carries the
+    # above-272k tier (max_input_tokens 1050000). gpt-5.6 and gpt-5.6-sol share
+    # gpt-5.5's rate card; -terra matches gpt-5.4; -luna is the cheapest tier.
+    "gpt-5.6": {
+        "input_cost_per_token": 5e-06,
+        "cache_read_input_token_cost": 5e-07,
+        "output_cost_per_token": 3e-05,
+        "input_cost_per_token_above_272k_tokens": 1e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 1e-06,
+        "output_cost_per_token_above_272k_tokens": 4.5e-05,
+    },
+    "gpt-5.6-sol": {
+        "input_cost_per_token": 5e-06,
+        "cache_read_input_token_cost": 5e-07,
+        "output_cost_per_token": 3e-05,
+        "input_cost_per_token_above_272k_tokens": 1e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 1e-06,
+        "output_cost_per_token_above_272k_tokens": 4.5e-05,
+    },
+    "gpt-5.6-terra": {
+        "input_cost_per_token": 2.5e-06,
+        "cache_read_input_token_cost": 2.5e-07,
+        "output_cost_per_token": 1.5e-05,
+        "input_cost_per_token_above_272k_tokens": 5e-06,
+        "cache_read_input_token_cost_above_272k_tokens": 5e-07,
+        "output_cost_per_token_above_272k_tokens": 2.25e-05,
+    },
+    "gpt-5.6-luna": {
+        "input_cost_per_token": 1e-06,
+        "cache_read_input_token_cost": 1e-07,
+        "output_cost_per_token": 6e-06,
+        "input_cost_per_token_above_272k_tokens": 2e-06,
+        "cache_read_input_token_cost_above_272k_tokens": 2e-07,
+        "output_cost_per_token_above_272k_tokens": 9e-06,
+    },
     # ── Issue #123: full gpt-5.x LiteLLM sync (2026-05-30 snapshot) ──
     # Exact model_prices_and_context_window.json values for every
     # openai-provider gpt-5* model `pricing-check`'s scope flags but the

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"