cctally 1.80.0 → 1.80.2

package/CHANGELOG.md

@@ -5,6 +5,17 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.80.2] - 2026-07-23
+
+### Fixed
+- The dashboard no longer crashes with a native SQLite `SIGBUS` when a corrupt `cache.db` is detected while another dashboard or hook reader is active. Cache recovery now blocks new opens, refuses to replace a file family with live handles, preserves the complete family in quarantine, and retries recreation only after replacement is safe.
+- Re-reading the same retained Codex quota observation now produces a byte-identical journal record instead of a new command-time identity. A compact natural-key index also recognizes records already written by v1.80.1, preventing cache recovery from multiplying historical quota records and making subsequent rebuilds progressively slower.
+
+## [1.80.1] - 2026-07-23
+
+### Fixed
+- Corrupted `stats.db` indexes now auto-heal correctly on Linux: the locked re-check reads the SQLite header instead of accepting a constant-only query that could succeed without touching the damaged file.
+
 ## [1.80.0] - 2026-07-23
 
 ### Added

package/bin/_cctally_cache.py

@@ -1211,26 +1211,25 @@ def _append_codex_quota_obs(quota_rows: list) -> None:
     lock is a LEAF — legal to take inside a provider flock, spec §4.3) and BEFORE
     the cache write / offset advance, so a crash re-reads the same bytes and
     re-appends (idempotent at the QUOTA_APPLIER's natural-key INSERT OR IGNORE)
-    rather than losing the observation. ``at`` is the detection clock
-    (``_command_as_of()``-aware, honoring the CCTALLY_AS_OF test hook); the raw
-    row (incl. its own ``captured_at_utc``) rides the payload (spec §4.2 raw
-    capture — no derivation baked into the stored line). $CODEX_HOME multi-root
-    scoping is preserved: each row carries its own ``source_root_key`` and roots
-    are never combined."""
+    rather than losing the observation. ``at`` is the observation's retained
+    ``captured_at_utc`` rather than the later sync clock, so re-reading the same
+    rollout bytes emits the same content id and byte-identical journal record.
+    $CODEX_HOME multi-root scoping is preserved: each row carries its own
+    ``source_root_key`` and roots are never combined."""
     if not quota_rows:
         return
     import _cctally_journal as _jr
     import _lib_journal as _jl
-    at = (
-        _cctally_core._command_as_of()
-        .isoformat(timespec="seconds")
-        .replace("+00:00", "Z")
-    )
     for row in quota_rows:
         (source, source_root_key, source_path, line_offset, captured_at_utc,
          observed_slot, logical_limit_key, limit_id, limit_name, window_minutes,
          used_percent, resets_at_utc, plan_type, individual_limit_json,
          reached_type, observed_model) = row
+        at = captured_at_utc or (
+            _cctally_core._command_as_of()
+            .isoformat(timespec="seconds")
+            .replace("+00:00", "Z")
+        )
         try:
             _jr.append_record(_jl.make_obs(
                 at=at, src="codex-quota", provider="codex",
@@ -1246,7 +1245,7 @@ def _append_codex_quota_obs(quota_rows: list) -> None:
                     "plan_type": plan_type,
                     "individual_limit_json": individual_limit_json,
                     "reached_type": reached_type, "observed_model": observed_model,
-                }))
+                }), dedupe_codex_quota=True)
         except Exception as exc:  # best-effort; a journal append must not break sync
             eprint(f"[codex-cache] quota obs journal append failed: {exc}")
 
@@ -4789,12 +4788,113 @@ def _harden_cache_sidecars() -> None:
 # === Region 6: open_cache_db (was bin/cctally:9040-9155) ===
 
 
+def _cache_open_guarded() -> sqlite3.Connection:
+    """Open cache.db while excluding a destructive recovery handshake.
+
+    The shared maintenance flock covers both marker checks and the SQLite
+    connect/probe. A repair owns the exclusive side; after it claims the marker,
+    no new cctally opener can escape into the live family while it verifies that
+    all pre-marker handles have drained.
+    """
+    path = pathlib.Path(_cctally_core.CACHE_DB_PATH)
+    marker = _cctally_db_sib._repair_marker_path(path)
+    lock_path = pathlib.Path(_cctally_core.CACHE_LOCK_MAINTENANCE_PATH)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    lock_fh = open(lock_path, "a+")
+    conn = None
+    try:
+        fcntl.flock(lock_fh, fcntl.LOCK_SH)
+        if marker.exists():
+            raise sqlite3.DatabaseError(
+                f"cache.db maintenance is in progress ({marker})"
+            )
+        conn = _cctally_store.open_index("cache")
+        # Force a real header/schema read. SELECT 1 is constant-folded and can
+        # report success without touching a malformed database file.
+        conn.execute("PRAGMA schema_version").fetchone()
+        if marker.exists():
+            conn.close()
+            conn = None
+            raise sqlite3.DatabaseError(
+                f"cache.db maintenance is in progress ({marker})"
+            )
+        return conn
+    except Exception:
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+        raise
+    finally:
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_UN)
+        finally:
+            lock_fh.close()
+
+
+def _recover_corrupt_cache(exc: sqlite3.DatabaseError) -> bool:
+    """Quarantine a corrupt cache family only after every reader has drained.
+
+    Returns True after a safe quarantine, so the caller may create a fresh
+    re-derivable cache. Raises a guided DatabaseError when recovery cannot prove
+    exclusivity; callers then use their established direct-JSONL fallback.
+    """
+    if not _cctally_db_sib._is_sqlite_corruption_error(exc):
+        return False
+
+    path = pathlib.Path(_cctally_core.CACHE_DB_PATH)
+    try:
+        claimed, reason = _cctally_db_sib._claim_repair_marker(path)
+    except OSError as marker_exc:
+        raise sqlite3.DatabaseError(
+            f"cache.db recovery could not claim maintenance: {marker_exc}"
+        ) from exc
+    if not claimed:
+        raise sqlite3.DatabaseError(
+            f"cache.db maintenance is in progress: {reason}"
+        ) from exc
+
+    lock_path = pathlib.Path(_cctally_core.CACHE_LOCK_MAINTENANCE_PATH)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    lock_fh = open(lock_path, "a+")
+    try:
+        fcntl.flock(lock_fh, fcntl.LOCK_EX)
+        open_pids = _cctally_db_sib._db_family_open_pids(path)
+        if open_pids is None:
+            raise sqlite3.DatabaseError(
+                "cache.db recovery cannot verify that the database family has "
+                "no open handles; leaving it untouched"
+            ) from exc
+        if open_pids:
+            raise sqlite3.DatabaseError(
+                "cache.db is still open in process(es) "
+                + ", ".join(str(pid) for pid in sorted(open_pids))
+                + "; leaving the live family untouched"
+            ) from exc
+
+        _cctally_db_sib.write_corruption_forensics(path, db_label="cache")
+        incident = _cctally_db_sib.quarantine_db_family(path)
+        eprint(
+            f"[cache] corrupt cache DB ({exc}); quarantined its file family "
+            f"under {incident} and recreating from source JSONL"
+        )
+        return True
+    finally:
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_UN)
+        finally:
+            lock_fh.close()
+        _cctally_db_sib._release_repair_marker(path)
+
+
 def open_cache_db() -> sqlite3.Connection:
     """Open (or create) the session-entry cache DB.
 
     Enables WAL mode so queries can run concurrently with an in-progress
-    ingest. On sqlite3.DatabaseError (corruption) the file is unlinked and
-    recreated — the cache is fully re-derivable from JSONL, so this is safe.
+    ingest. On positively classified corruption, the whole file family is
+    quarantined and recreated only after a marker + maintenance flock + active
+    handle check prove replacement cannot invalidate a live WAL reader.
     """
     c = _cctally()
     _cctally_core.APP_DIR.mkdir(parents=True, exist_ok=True)
@@ -4807,22 +4907,13 @@ def open_cache_db() -> sqlite3.Connection:
     except OSError as exc:
         eprint(f"[cache] could not chmod data dir 0700 ({exc}); continuing")
     try:
-        # Connect + install row factory / test trace hook via the unified
-        # opener (spec §6.1). PRAGMAs are applied AFTER the corruption probe so
-        # a mode-change never writes a WAL onto a DB we are about to unlink.
-        conn = _cctally_store.open_index("cache")
-        conn.execute("SELECT 1").fetchone()
+        conn = _cache_open_guarded()
     except sqlite3.DatabaseError as exc:
-        eprint(f"[cache] corrupt cache DB ({exc}); recreating")
-        try:
-            conn.close()
-        except Exception:
-            pass
-        try:
-            _cctally_core.CACHE_DB_PATH.unlink()
-        except FileNotFoundError:
-            pass
-        conn = _cctally_store.open_index("cache")
+        if not _recover_corrupt_cache(exc):
+            raise
+        # One retry only. A second failure surfaces to the existing direct-JSONL
+        # fallback instead of looping through destructive recovery.
+        conn = _cache_open_guarded()
 
     # Best-effort 0600 on cache.db itself (the 0700 dir above backstops the
     # sidecars until the first write hardens them in sync_cache).

package/bin/_cctally_db.py

@@ -6695,7 +6695,7 @@ def _db_backup_timestamp() -> str:
 
 
 def _repair_marker_path(path: pathlib.Path) -> pathlib.Path:
-    return path.with_name("stats.db.repairing")
+    return path.with_name(f"{path.name}.repairing")
 
 
 def _pid_is_alive(pid: int) -> bool:
@@ -6722,7 +6722,9 @@ def _claim_repair_marker(path: pathlib.Path) -> "tuple[bool, str]":
             except (OSError, ValueError):
                 owner = -1
             if _pid_is_alive(owner):
-                return False, f"another stats.db repair owns {marker} (pid {owner})"
+                return False, (
+                    f"another {path.name} repair owns {marker} (pid {owner})"
+                )
             try:
                 marker.unlink()
             except FileNotFoundError:

package/bin/_cctally_journal.py

@@ -45,6 +45,15 @@ import _lib_record
 _TAIL_WINDOW = 64 * 1024
 _MAX_LINE_BYTES = _TAIL_WINDOW
 
+# Process-local acceleration for the durable Codex-quota dedupe index. The
+# compact index is re-derivable from the journal and lets short-lived hook
+# processes load ~20-byte natural-key digests instead of rescanning every full
+# JSONL segment.
+_QUOTA_DEDUP_INDEX_NAME = ".quota-observation-keys"
+_QUOTA_DEDUP_DIR: str | None = None
+_QUOTA_DEDUP_KEYS: set[str] = set()
+_QUOTA_DEDUP_LOADED = False
+
 
 class JournalError(Exception):
     """A structural journal-append failure (line too long, unrepairable tail)."""
@@ -134,17 +143,136 @@ def _repair_torn_tail(fd: int) -> None:
 # public append surface
 # --------------------------------------------------------------------------
 
-def append_record(record: dict, *, now_utc: dt.datetime | None = None) -> tuple[str, int]:
+def _is_codex_quota_obs(record: dict) -> bool:
+    return (
+        record.get("t") == "obs"
+        and record.get("provider") == "codex"
+        and (record.get("payload") or {}).get("kind") == "quota_window_snapshot"
+    )
+
+
+def _codex_quota_natural_key(record: dict) -> str | None:
+    """Digest the cache table's stable UNIQUE key for one quota observation."""
+    if not _is_codex_quota_obs(record):
+        return None
+    payload = record.get("payload") or {}
+    source = payload.get("source")
+    source_path = payload.get("source_path")
+    line_offset = payload.get("line_offset")
+    logical_limit_key = payload.get("logical_limit_key")
+    if (
+        not isinstance(source, str)
+        or not isinstance(source_path, str)
+        or not isinstance(line_offset, int)
+        or not isinstance(logical_limit_key, str)
+    ):
+        return None
+    return _lib_journal.content_id({
+        "t": "quota-natural-key",
+        "payload": {
+            "source": source,
+            "source_path": source_path,
+            "line_offset": line_offset,
+            "logical_limit_key": logical_limit_key,
+        },
+    })
+
+
+def _load_quota_dedup_keys() -> None:
+    """Load or atomically rebuild the re-derivable quota natural-key index.
+
+    Caller owns journal.lock, so an initial full scan observes one stable
+    journal prefix and only one process can publish the compact index. Normal
+    quota appends fsync the journal first and this index second; a crash in
+    between can cause at most one harmless duplicate on retry, never a skipped
+    durable observation.
+    """
+    global _QUOTA_DEDUP_DIR, _QUOTA_DEDUP_LOADED
+    journal_dir = _cctally_core.JOURNAL_DIR
+    dir_key = str(journal_dir)
+    if _QUOTA_DEDUP_DIR != dir_key:
+        _QUOTA_DEDUP_DIR = dir_key
+        _QUOTA_DEDUP_KEYS.clear()
+        _QUOTA_DEDUP_LOADED = False
+    if _QUOTA_DEDUP_LOADED:
+        return
+
+    index_path = journal_dir / _QUOTA_DEDUP_INDEX_NAME
+    try:
+        raw_keys = index_path.read_text(encoding="ascii").splitlines()
+        if any(not item.startswith("o:") or len(item) != 18 for item in raw_keys):
+            raise ValueError("invalid quota dedupe index")
+        _QUOTA_DEDUP_KEYS.update(raw_keys)
+        _QUOTA_DEDUP_LOADED = True
+        return
+    except (FileNotFoundError, OSError, UnicodeError, ValueError):
+        _QUOTA_DEDUP_KEYS.clear()
+
+    for name in list_segments():
+        with (journal_dir / name).open("rb") as fh:
+            for raw in fh:
+                if not raw.endswith(b"\n"):
+                    break
+                decoded = _lib_journal.decode_line(raw)
+                if decoded is not None:
+                    natural_key = _codex_quota_natural_key(decoded)
+                    if natural_key is not None:
+                        _QUOTA_DEDUP_KEYS.add(natural_key)
+
+    tmp = index_path.with_name(
+        f"{index_path.name}.tmp-{os.getpid()}-{time.monotonic_ns()}"
+    )
+    try:
+        fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        try:
+            payload = "".join(
+                f"{natural_key}\n" for natural_key in sorted(_QUOTA_DEDUP_KEYS)
+            ).encode("ascii")
+            _write_all(fd, payload)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(str(tmp), str(index_path))
+        _fsync_dir(journal_dir)
+    finally:
+        try:
+            tmp.unlink()
+        except FileNotFoundError:
+            pass
+    _QUOTA_DEDUP_LOADED = True
+
+
+def _append_quota_dedup_key(natural_key: str) -> None:
+    """Journal-first second leg: append+fsync one key to the compact index."""
+    index_path = _cctally_core.JOURNAL_DIR / _QUOTA_DEDUP_INDEX_NAME
+    fd = os.open(str(index_path), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+    try:
+        _write_all(fd, f"{natural_key}\n".encode("ascii"))
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    _QUOTA_DEDUP_KEYS.add(natural_key)
+
+
+def append_record(
+    record: dict,
+    *,
+    now_utc: dt.datetime | None = None,
+    dedupe_codex_quota: bool = False,
+) -> tuple[str, int] | None:
     """Append one encoded line to the current UTC month's segment.
 
     Implements spec §4.3 exactly: ``O_RDWR|O_APPEND|O_CREAT`` (0o600) → blocking
     leaf flock → torn-tail repair → loop-write the full line → ``fsync(fd)`` →
     parent-dir fsync on first segment/dir creation → unlock.
 
-    ``now_utc`` selects the segment (defaults to the current UTC time). Returns
-    ``(segment_basename, end_offset)`` where ``end_offset`` is the file size
-    just past the appended line — the byte position the ingest cursor advances
-    to when it consumes this line."""
+    ``now_utc`` selects the segment (defaults to the current UTC time).
+    ``dedupe_codex_quota`` skips a retained Codex quota obs whose table natural
+    key already exists in any segment; this is the cache-recovery replay path
+    and returns ``None`` on a skip. Otherwise returns ``(segment_basename,
+    end_offset)`` where ``end_offset`` is the file size just past the appended
+    line — the byte position the ingest cursor advances to when it consumes
+    this line."""
     if now_utc is None:
         now_utc = dt.datetime.now(dt.timezone.utc)
     data = _lib_journal.encode_line(record)
@@ -167,6 +295,20 @@ def append_record(record: dict, *, now_utc: dt.datetime | None = None) -> tuple[
 
     lock_fd = _acquire_leaf_lock()
     try:
+        if dedupe_codex_quota:
+            if not _is_codex_quota_obs(record):
+                raise ValueError(
+                    "dedupe_codex_quota is valid only for Codex quota obs"
+                )
+            _load_quota_dedup_keys()
+            natural_key = _codex_quota_natural_key(record)
+            if natural_key is None:
+                raise ValueError(
+                    "dedupe_codex_quota requires a complete quota natural key"
+                )
+            if natural_key in _QUOTA_DEDUP_KEYS:
+                return None
+
         seg_created = not seg_path.exists()
         fd = os.open(str(seg_path), os.O_RDWR | os.O_APPEND | os.O_CREAT, 0o600)
         try:
@@ -181,6 +323,8 @@ def append_record(record: dict, *, now_utc: dt.datetime | None = None) -> tuple[
             end_offset = os.fstat(fd).st_size
         finally:
             os.close(fd)
+        if dedupe_codex_quota:
+            _append_quota_dedup_key(natural_key)
         # Durably record new directory entries (spec §4.3: fsync the parent
         # directory on first creation of a segment or the journal dir).
         if seg_created:

package/bin/_cctally_store.py

@@ -363,7 +363,10 @@ def _probe_stats_ok(path) -> bool:
     try:
         c = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
         try:
-            c.execute("SELECT 1").fetchone()
+            # Force SQLite to read the database header.  A constant-only
+            # ``SELECT 1`` can succeed on Linux without touching a corrupt file,
+            # falsely reporting that a sibling already healed the index.
+            c.execute("PRAGMA schema_version").fetchone()
         finally:
             c.close()
         return True

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.80.0",
+  "version": "1.80.2",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {