cctally 1.27.1 → 1.29.0

package/bin/_lib_doctor.py

@@ -140,6 +140,14 @@ class DoctorState:
     # token_total); the kernel only reads `.kind`/`.model`/`.entry_count`/
     # `.token_total`, so any duck-typed equivalent works for tests.
     pricing_coverage: Optional[list] = None
+    # Conversation viewer (Plan 2, spec §5): the resolved
+    # `dashboard.expose_transcripts` opt-in. Only consequential when the bind
+    # is LAN — `_check_safety_dashboard_bind` then surfaces an extra
+    # "transcripts exposed on LAN" detail on top of the existing LAN-bind
+    # WARN. Defaulted False (placed last after the other defaulted fields) so
+    # existing constructors stay valid and a loopback bind is byte-identical
+    # whether or not expose is set.
+    expose_transcripts: bool = False
 
 
 @dataclasses.dataclass(frozen=True)
@@ -556,6 +564,45 @@ def _check_db_migrations_pending(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_db_version_ahead(s: DoctorState) -> CheckResult:
+    """FAIL/WARN when a DB's user_version exceeds the running binary's
+    registry head (issue #145). stats.db ahead bricks commands (FAIL);
+    cache.db ahead auto-heals on the next open (WARN). doctor reads raw
+    user_version (no dispatcher), so it can report without healing/bricking.
+    """
+    def _eval(status):
+        if not status:
+            return None
+        uv = status.get("user_version", 0) or 0
+        rs = status.get("registry_size", 0) or 0
+        return {"user_version": uv, "registry_size": rs, "ahead": uv > rs}
+
+    stats = _eval(s.stats_db_status)
+    cache = _eval(s.cache_db_status)
+    details = {"stats.db": stats, "cache.db": cache}
+    stats_ahead = bool(stats and stats["ahead"])
+    cache_ahead = bool(cache and cache["ahead"])
+
+    if stats_ahead:
+        return CheckResult(
+            id="db.version_ahead", title="Version ahead", severity="fail",
+            summary=f"stats.db ahead (v{stats['user_version']} > known v{stats['registry_size']})",
+            remediation="Run `cctally db recover --db stats --yes` (or restore from backup)",
+            details=details,
+        )
+    if cache_ahead:
+        return CheckResult(
+            id="db.version_ahead", title="Version ahead", severity="warn",
+            summary=f"cache.db ahead (v{cache['user_version']} > known v{cache['registry_size']}) — auto-heals",
+            remediation="Auto-heals on next command, or run `cctally db recover --db cache`",
+            details=details,
+        )
+    return CheckResult(
+        id="db.version_ahead", title="Version ahead", severity="ok",
+        summary="none ahead", remediation=None, details=details,
+    )
+
+
 def _check_data_latest_snapshot_age(s: DoctorState) -> CheckResult:
     if s.latest_snapshot_at is None:
         return CheckResult(
@@ -859,13 +906,24 @@ def _check_safety_dashboard_bind(s: DoctorState) -> CheckResult:
     rem += "."
     note = ("A separate running dashboard process may have overridden via --host; "
             "the CLI sees config only.") if s.runtime_bind is None else None
+    # Conversation viewer (Plan 2, spec §5): a LAN bind WITH the
+    # `dashboard.expose_transcripts` opt-in serves raw conversation prose to
+    # the LAN. Surface that ONLY here (the bind already WARNs and is
+    # non-loopback by construction), additively — a loopback bind never
+    # reaches this branch, so the loopback report stays byte-identical
+    # regardless of the expose flag.
+    extra = {}
+    if s.expose_transcripts:
+        notes.append("transcripts exposed on LAN")
+        extra["transcripts_exposed_on_lan"] = True
     return CheckResult(
         id="safety.dashboard_bind", title="Dashboard bind",
         severity="warn", summary="; ".join(notes),
         remediation=rem,
         details={"config": s.dashboard_bind_stored,
                  "runtime_bind": s.runtime_bind,
-                 **({"note": note} if note else {})},
+                 **({"note": note} if note else {}),
+                 **extra},
     )
 
 
@@ -1052,6 +1110,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
     ("db", "Database", (
         ("db.stats.file", "_check_db_stats_file"),
         ("db.cache.file", "_check_db_cache_file"),
+        ("db.version_ahead", "_check_db_version_ahead"),
         ("db.migrations.applied", "_check_db_migrations_applied"),
         ("db.migrations.pending", "_check_db_migrations_pending"),
     )),

package/bin/_lib_jsonl.py

@@ -201,6 +201,68 @@ 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.
+
+    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.
+    """
+    if obj.get("type") != "assistant":
+        return None
+
+    ts_raw = obj.get("timestamp")
+    if not isinstance(ts_raw, str) or not ts_raw.strip():
+        return None
+
+    msg = obj.get("message")
+    if not isinstance(msg, dict):
+        msg = obj
+
+    usage = msg.get("usage")
+    if not isinstance(usage, dict):
+        return None
+
+    model = msg.get("model") or obj.get("model")
+    if not isinstance(model, str) or not model.strip():
+        return None
+    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
+
+    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
+
+    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
+
+    return (
+        UsageEntry(
+            timestamp=ts,
+            model=model,
+            usage=usage,
+            cost_usd=cost_usd,
+            source_path=path_str,
+        ),
+        msg_id,
+        req_id,
+    )
+
+
 def _iter_jsonl_entries_with_offsets(fh, path_str: str):
     """Yield (byte_offset, UsageEntry, msg_id, req_id) for each assistant
     entry starting from fh's current position.
@@ -209,7 +271,9 @@ def _iter_jsonl_entries_with_offsets(fh, path_str: str):
     accurate for resume-from-offset after partial ingests. Malformed JSON
     and non-assistant lines are skipped, but the offset still advances past
     them so they are never re-read. Range filtering is intentionally NOT
-    done here — filters are applied at query time by iter_entries().
+    done here — filters are applied at query time by iter_entries(). The
+    per-line gating lives in ``parse_cost_entry`` (shared with the fused
+    single-pass sync walker, #138).
     """
     while True:
         offset = fh.tell()
@@ -230,56 +294,11 @@ def _iter_jsonl_entries_with_offsets(fh, path_str: str):
             obj = json.loads(stripped)
         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():
+        parsed = parse_cost_entry(obj, path_str)
+        if parsed is None:
             continue
-        model = model.strip()
-        if model == "<synthetic>":
-            # Matches ccusage's claude_loader.rs:454. Filtered at the
-            # iterator level 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).
-            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
-
-        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
-
-        yield (
-            offset,
-            UsageEntry(
-                timestamp=ts,
-                model=model,
-                usage=usage,
-                cost_usd=cost_usd,
-                source_path=path_str,
-            ),
-            msg_id,
-            req_id,
-        )
+        entry, msg_id, req_id = parsed
+        yield (offset, entry, msg_id, req_id)
 
 
 _CODEX_FILENAME_UUID_RE = re.compile(

package/bin/_lib_transcript_access.py

@@ -0,0 +1,80 @@
+"""Pure loopback / Host gate predicates for the conversation-viewer transcript
+endpoints (Plan 2, spec §5).
+
+No I/O, no globals — directly unit-testable. The dashboard's
+``_require_transcripts_allowed`` composes ``transcripts_allowed`` (is this bind
+served at all?) with ``host_allowed_for_transcripts`` (anti-DNS-rebinding on the
+request's Host header). Loopback-by-default kills rebinding (it needs a
+hostname that resolves to 127.0.0.1); under the explicit ``expose`` opt-in the
+LAN device reaches the dashboard at its IP literal (allowed), while an
+attacker's rebinding *domain* (a hostname) is rejected.
+"""
+from __future__ import annotations
+import ipaddress
+
+# Public surface (Plan 2): shipped in the npm tarball + brew formula + public
+# mirror — imported by the dashboard's transcript gate at runtime.
+
+_LOOPBACK_NAMES = {"localhost", "::1"}
+
+
+def authority_host(host_header) -> str:
+    """Extract the lowercased host from an HTTP authority (``Host`` header or a
+    bind string). Strips the port, the ``[...]`` IPv6 brackets, and any
+    ``%zone`` id. IPv6-safe (does NOT ``split(':')``). Empty string on missing
+    input."""
+    if not host_header:
+        return ""
+    h = str(host_header).strip()
+    if h.startswith("["):
+        # [IPv6]:port  ->  IPv6
+        end = h.find("]")
+        if end != -1:
+            h = h[1:end]
+        else:
+            h = h[1:]
+    elif h.count(":") == 1:
+        # host:port (a single colon can't be a bare IPv6 literal)
+        h = h.split(":", 1)[0]
+    # else: bare IPv6 literal (multiple colons) or bare host — leave as-is
+    h = h.split("%", 1)[0]   # drop IPv6 zone id
+    return h.lower()
+
+
+def is_loopback(host: str) -> bool:
+    """True for the loopback names plus any IPv4/IPv6 loopback literal
+    (127.0.0.0/8, ::1)."""
+    if not host:
+        return False
+    h = host.lower()
+    if h in _LOOPBACK_NAMES:
+        return True
+    try:
+        return ipaddress.ip_address(h).is_loopback
+    except ValueError:
+        return False
+
+
+def transcripts_allowed(bind_host, expose: bool) -> bool:
+    """Are transcripts served AT ALL on this bind? Loopback bind always; a
+    non-loopback (LAN) bind only under the explicit ``expose`` opt-in."""
+    return is_loopback(authority_host(bind_host)) or bool(expose)
+
+
+def host_allowed_for_transcripts(host_header, expose: bool) -> bool:
+    """Anti-DNS-rebinding Host allowlist. Loopback Host always OK. Otherwise
+    only an IP-literal Host under ``expose`` (the LAN IP the dashboard is
+    reached at) — a rebinding *domain* (any hostname) is rejected. Fail closed
+    on missing/empty Host."""
+    h = authority_host(host_header)
+    if not h:
+        return False
+    if is_loopback(h):
+        return True
+    if not expose:
+        return False
+    try:
+        ipaddress.ip_address(h)   # IP literal can't be DNS-rebound
+        return True
+    except ValueError:
+        return False              # hostname (rebinding vector) — reject

package/bin/cctally

@@ -306,6 +306,8 @@ BudgetInputs = _lib_budget.BudgetInputs
 BudgetStatus = _lib_budget.BudgetStatus
 compute_budget_status = _lib_budget.compute_budget_status
 project_linear = _lib_budget.project_linear
+calendar_month_window = _lib_budget.calendar_month_window
+calendar_week_window = _lib_budget.calendar_week_window
 
 # CLAUDE_MODEL_CONTEXT_WINDOWS / …_DEFAULT_FAMILY moved to _cctally_statusline.py (re-exported below).
 
@@ -377,12 +379,14 @@ _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
 _alert_text_budget = _lib_alerts_payload._alert_text_budget
 _alert_text_project_budget = _lib_alerts_payload._alert_text_project_budget
+_alert_text_codex_budget = _lib_alerts_payload._alert_text_codex_budget
 _alert_text_projected = _lib_alerts_payload._alert_text_projected
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
 _build_alert_payload_project_budget = _lib_alerts_payload._build_alert_payload_project_budget
+_build_alert_payload_codex_budget = _lib_alerts_payload._build_alert_payload_codex_budget
 _build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
 
 _lib_alert_dispatch = _load_sibling("_lib_alert_dispatch")
@@ -736,6 +740,7 @@ add_column_if_missing = _cctally_db.add_column_if_missing
 _MIGRATION_NAME_RE = _cctally_db._MIGRATION_NAME_RE
 Migration = _cctally_db.Migration
 DowngradeDetected = _cctally_db.DowngradeDetected
+ProdMigrationRefused = _cctally_db.ProdMigrationRefused
 _STATS_MIGRATIONS = _cctally_db._STATS_MIGRATIONS
 _CACHE_MIGRATIONS = _cctally_db._CACHE_MIGRATIONS
 _make_migration_decorator = _cctally_db._make_migration_decorator
@@ -743,7 +748,9 @@ stats_migration = _cctally_db.stats_migration
 cache_migration = _cctally_db.cache_migration
 _LEGACY_MARKER_ALIASES_BY_DB = _cctally_db._LEGACY_MARKER_ALIASES_BY_DB
 _bootstrap_rename_legacy_markers = _cctally_db._bootstrap_rename_legacy_markers
+_stamp_applied = _cctally_db._stamp_applied
 _run_pending_migrations = _cctally_db._run_pending_migrations
+_recover_version_ahead = _cctally_db._recover_version_ahead
 _log_migration_error = _cctally_db._log_migration_error
 _clear_migration_error_log_entries = _cctally_db._clear_migration_error_log_entries
 _render_migration_error_banner = _cctally_db._render_migration_error_banner
@@ -757,6 +764,7 @@ _db_resolve_migration_name = _cctally_db._db_resolve_migration_name
 _db_path_for_label = _cctally_db._db_path_for_label
 cmd_db_skip = _cctally_db.cmd_db_skip
 cmd_db_unskip = _cctally_db.cmd_db_unskip
+cmd_db_recover = _cctally_db.cmd_db_recover
 
 
 # Session-entry cache subsystem (Claude + Codex) — read-through delta
@@ -782,6 +790,7 @@ IngestStats = _cctally_cache.IngestStats
 _progress_stderr = _cctally_cache._progress_stderr
 _ensure_session_files_row = _cctally_cache._ensure_session_files_row
 sync_cache = _cctally_cache.sync_cache
+backfill_conversation_messages = _cctally_cache.backfill_conversation_messages
 iter_entries = _cctally_cache.iter_entries
 _collect_entries_direct = _cctally_cache._collect_entries_direct
 _JoinedClaudeEntry = _cctally_cache._JoinedClaudeEntry
@@ -793,6 +802,7 @@ sync_codex_cache = _cctally_cache.sync_codex_cache
 iter_codex_entries = _cctally_cache.iter_codex_entries
 _collect_codex_entries_direct = _cctally_cache._collect_codex_entries_direct
 get_codex_entries = _cctally_cache.get_codex_entries
+_sum_codex_cost_for_range = _cctally_cache._sum_codex_cost_for_range
 get_entries = _cctally_cache.get_entries
 open_cache_db = _cctally_cache.open_cache_db
 cmd_cache_sync = _cctally_cache.cmd_cache_sync
@@ -822,6 +832,7 @@ _normalize_percent = _cctally_record._normalize_percent
 maybe_record_milestone = _cctally_record.maybe_record_milestone
 maybe_record_budget_milestone = _cctally_record.maybe_record_budget_milestone
 maybe_record_project_budget_milestone = _cctally_record.maybe_record_project_budget_milestone
+maybe_record_codex_budget_milestone = _cctally_record.maybe_record_codex_budget_milestone
 maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
 _weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
 _compute_block_totals = _cctally_record._compute_block_totals
@@ -1101,6 +1112,7 @@ _fetch_current_week_snapshots = _cctally_forecast._fetch_current_week_snapshots
 _apply_midweek_reset_override = _cctally_forecast._apply_midweek_reset_override
 _resolve_current_budget_window = _cctally_forecast._resolve_current_budget_window
 _build_budget_status_inputs = _cctally_forecast._build_budget_status_inputs
+_build_vendor_budget_inputs = _cctally_forecast._build_vendor_budget_inputs
 _select_dollars_per_percent = _cctally_forecast._select_dollars_per_percent
 _assess_forecast_confidence = _cctally_forecast._assess_forecast_confidence
 _pick_p_24h_ago = _cctally_forecast._pick_p_24h_ago
@@ -1115,6 +1127,12 @@ _forecast_color_enabled = _cctally_forecast._forecast_color_enabled
 _render_forecast_progress_bar = _cctally_forecast._render_forecast_progress_bar
 _render_forecast_terminal = _cctally_forecast._render_forecast_terminal
 _BUDGET_JSON_SCHEMA_VERSION = _cctally_forecast._BUDGET_JSON_SCHEMA_VERSION
+# Single-sourced `--period` spellings (code-review #5): the parser's `choices=`
+# derives from the same map the handler normalizer uses, so they can't drift.
+_BUDGET_PERIOD_ALIASES = _cctally_forecast._BUDGET_PERIOD_ALIASES
+_BUDGET_PERIOD_CHOICES = _cctally_forecast._BUDGET_PERIOD_CHOICES
+_normalize_budget_period = _cctally_forecast._normalize_budget_period
+_resolve_calendar_window = _cctally_forecast._resolve_calendar_window
 _cmd_budget_set = _cctally_forecast._cmd_budget_set
 _cmd_budget_unset = _cctally_forecast._cmd_budget_unset
 # Per-project budget set/unset (#19/#121, spec §4.3 / §7).
@@ -2082,12 +2100,18 @@ get_max_milestone_for_week          = _cctally_milestones.get_max_milestone_for_
 get_milestone_cost_for_week         = _cctally_milestones.get_milestone_cost_for_week         # record shim
 get_milestones_for_week             = _cctally_milestones.get_milestones_for_week             # forecast c.; tui shim; percent-breakdown c.
 insert_percent_milestone            = _cctally_milestones.insert_percent_milestone            # record shim; idempotency-test mod.
-insert_budget_milestone             = _cctally_milestones.insert_budget_milestone             # record shim
+insert_budget_milestone             = _cctally_milestones.insert_budget_milestone             # record shim; test_budget_alerts / test_project_budget_dashboard ns[] (+ test_codex_budget_alerts / test_projected_alerts post-#143 vendor-param unification)
 insert_project_budget_milestone     = _cctally_milestones.insert_project_budget_milestone     # record shim; project-budget-config-test ns[]
+_budget_crossings                   = _cctally_milestones._budget_crossings                   # record shim (shared INSERT-and-arm core for the budget axis, both vendors, #143)
+_resolve_codex_budget_period_window = _cctally_milestones._resolve_codex_budget_period_window # record shim; milestones c. (codex period window)
+_resolve_budget_window              = _cctally_milestones._resolve_budget_window              # record shim; milestones c. (per-vendor cheap budget window dispatcher, #143)
+_budget_spend_for_vendor            = _cctally_milestones._budget_spend_for_vendor            # record shim; milestones c. (per-vendor budget spend dispatcher, #143)
+_reconcile_codex_budget_on_config_write = _cctally_milestones._reconcile_codex_budget_on_config_write  # forecast/config c. (forward-only codex-budget reconcile)
+_resolve_claude_budget_window       = _cctally_milestones._resolve_claude_budget_window       # record shim; milestones c. (period-aware Claude budget window)
 _project_crossings                  = _cctally_milestones._project_crossings                  # record shim; milestones c. (#130 firing/reconcile shared crossing arithmetic)
 insert_projected_milestone          = _cctally_milestones.insert_projected_milestone          # record shim
 _projected_levels_already_latched   = _cctally_milestones._projected_levels_already_latched   # record shim
-_reconcile_budget_milestones_on_set = _cctally_milestones._reconcile_budget_milestones_on_set # test_budget_alerts ns[]
+_reconcile_budget_milestones_on_set = _cctally_milestones._reconcile_budget_milestones_on_set # test_budget_alerts / test_codex_budget_alerts ns[] (vendor-param, #143)
 _reconcile_budget_on_config_write   = _cctally_milestones._reconcile_budget_on_config_write   # forecast/config/dashboard c.; test_forecast_ns_patch mod. patch
 _reconcile_project_budget_milestones_on_write = _cctally_milestones._reconcile_project_budget_milestones_on_write  # forecast/config/dashboard c. (forward-only project-budget reconcile)
 
@@ -2672,6 +2696,9 @@ def main(argv: list[str] | None = None) -> int:
     except DowngradeDetected as exc:
         eprint(f"cctally: {exc}")
         return 2
+    except ProdMigrationRefused as exc:
+        eprint(f"{exc}")  # message already carries the 'cctally:' prefix
+        return 2
     except Exception as exc:  # pragma: no cover
         eprint(f"Error: {exc}")
         rc = 1