cctally 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-05-26
+
+### Added
+- **Running `cctally` from a git checkout now uses a separate `~/.local/share/cctally-dev/` data dir instead of the installed copy's `~/.local/share/cctally/`, so developing against the source tree can no longer corrupt the production instance.** Previously both the source checkout and the npm/brew-installed copy resolved every runtime path from `~/.local/share/cctally/`, so a single dev run that advanced the schema would trip a version mismatch on the still-installed prod binary (and on its background Claude Code hooks) — and vice versa. A checkout is now auto-detected (its `bin/` parent contains a `.git` directory or file, which also covers worktrees) and transparently relocated to `cctally-dev/`; the npm and brew copies ship without `.git`, so installed users are byte-for-byte unaffected. The real Claude session JSONL, `~/.claude/settings.json`, and OAuth credentials stay shared read-only, so dev cost numbers remain real. `cctally doctor` now reports whether it is the installed copy or a dev checkout plus the resolved data dir, `cctally --version` shows a dev-mode marker, and `cctally setup` refuses to wire a dev checkout into `~/.claude/settings.json` (read-only `--status`/`--dry-run` still work) unless given `--force-dev`. Set `CCTALLY_DATA_DIR` to point the data dir somewhere explicit (e.g. a distinct dir per feature branch).
+
+### Changed
+- **`cctally session` `totalTokens` (the table column, the `--breakdown` per-model sub-rows, and the `--json` per-session + `totals` fields) now sums all four token components — input + output + cache create + cache read — matching `daily`/`monthly` and upstream `ccusage` v20.** Previously it counted input + output only (the original Spec A2.8 convention), which left the session roll-up ~99% below `ccusage` v20 even though the four component token fields and cost already matched within rounding. The `--json` `totalTokens` field name and shape are unchanged — only the value widened to include cache, so a consumer that previously read it as input+output will now see the cache-inclusive figure. `codex-session` deliberately keeps input + output because Codex `inputTokens` is already cache-inclusive (LiteLLM convention), so it already reports the same "all tokens processed" total. (#104)
+
+### Fixed
+- **`cctally codex-session` no longer misaligns its table on narrow terminals (including the default 120-column width) or under `--compact`.** On any terminal narrower than the table's natural width the scale-down branch could shrink a column below its header-label width, and headers like `Reasoning`, `Cache Read`, `Total Tokens` and `Last Activity` are padded — never truncated — in the header render, so the header row grew wider than the box border and the grid broke. Column widths now mirror the `session` and `project` tables via the shared scale-down policy: numeric columns keep their full value (never ellipsis-truncated), header and text labels ellipsize to fit, and every box-drawing line shares one width. (#99)
+- **`cctally`'s `stats.db` write paths are hardened against a `SQLITE_BUSY_SNAPSHOT` "database is locked" crash under concurrent multi-process use** (multiple dashboards plus background `record-usage` / `hook-tick`, magnified by worktrees that share one `~/.local/share/cctally/stats.db`). The one-shot `five_hour_blocks` historical backfill ran a deferred transaction that read its source rows before its first write, so a competing commit landing in that window raised "database is locked" *instantly* — a `busy_timeout` can never absorb that case — and rolled the whole backfill back; it and the live 5h-block upsert now take the write lock up front via `BEGIN IMMEDIATE`. Contrary to the issue's original framing, `busy_timeout` was never the missing piece: `sqlite3.connect()`'s default `timeout=5.0` already gives every `stats.db` open a 5s retry window, so the real fix is acquiring the write lock before the first read so the busy handler can actually wait. Regression: `tests/test_stats_db_busy_timeout.py`. (#87)
+- **`cctally`'s cache-rebuild migration can no longer corrupt session history when it runs concurrently with a cache ingest.** The cache-`db` migration that wipes and recomputes derived state now acquires the same `cache.db.lock` `fcntl` flock that `sync_cache` holds — in one consistent `fcntl`→SQLite acquisition order — before its `BEGIN IMMEDIATE`, so the wipe and a concurrent ingest walk are mutually exclusive and the partial-walk straddle is structurally impossible; under contention the migration defers and retries on the next open rather than interleaving. (#105)
+- **`cctally refresh-usage` no longer crashes when the current 5-hour window is inactive.** When the OAuth usage payload reports the 5h window with a `null` `resets_at` (no active window), `refresh-usage` previously fed that missing reset timestamp into 5h-window-key derivation and raised; the inactive window is now dropped instead.
+
+## [1.13.0] - 2026-05-25
+
+### Added
+- **Every Claude reporting command now accepts the `ccusage` flag surface, so `ccusage <cmd> [flags]` invocations paste into `cctally` unchanged.** Across all 10 reporting subcommands (`daily`, `monthly`, `weekly`, `session`, `blocks`, `five-hour-blocks`, `project`, `diff`, `range-cost`, `cache-report`): `-z`/`--timezone` aliases the existing `--tz`; the 8 date-taking commands accept `--since`/`--until` in both `YYYY-MM-DD` and `YYYYMMDD` forms; `--compact` forces compact table layout; `--color`/`--no-color` (plus the `NO_COLOR` / `FORCE_COLOR` env vars) control ANSI on the color-emitting commands (`project`, `diff`) and are accepted-but-inert elsewhere; and `-O`/`--offline`, `--single-thread`, `-d`/`--debug`, and `--config` are accepted as documented no-ops where cctally has no divergent behavior. A top-level `-v` short alias for `--version` is also added. The pass is purely additive — no existing output changes. (#86)
+- **`cctally session` gains `-i`/`--id <session-id>` to filter to a single session.** Exact-string match against the post-resume-merge `sessionId`; an unknown id renders empty and exits 0. (#86)
+- **`--config <path>` is now a real per-invocation config override.** Previously a documented no-op from the flag-alias pass, `--config` now loads configuration from the given path for that invocation only, leaving the persisted `~/.local/share/cctally/config.json` untouched. (#88)
+- **`-d`/`--debug` now emits a real "Pricing Mismatch Debug Report" on stderr for the Claude reporting commands.** The report compares each entry's recorded `costUSD` against the token-recomputed cost, surfacing totals + per-model stats + a sample of the largest discrepancies, matching ccusage's `printMismatchReport` shape. `--debug-samples N` caps the sample block (default 5; `N=0` prints totals only; negative N rejected at parse time). The report goes to stderr only — `--json` / `--format` pipelines stay byte-stable — and `diff` emits one report per window. (#89)
+- **`--compact` now reshapes output on the 5 reporting commands where it was previously accepted-but-inert: `five-hour-blocks`, `project`, `diff`, `range-cost`, and `cache-report`.** Brings them in line with the commands that already honored `--compact`. (#91)
+- **`codex-daily` / `codex-monthly` / `codex-weekly` / `codex-session` now accept `-d/--debug` + `--debug-samples N`**, extending the Claude-side `--debug` diagnostic surface to the Codex commands. Because Codex JSONL records no `costUSD` to diff against, the report is a Codex variant — a "Codex Pricing Debug Report" on stderr with totals (entries processed, models seen, total computed cost) plus a "Sample Top Entries" block of the N highest computed-cost entries (`Recorded cost: (none)` per sample; `gpt-5`-fallback models tagged `(fallback→gpt-5)`). `--debug-samples` caps the sample block (default 5; `N=0` prints totals only). (#92)
+
+### Fixed
+- **`project --compact` and `session --compact` no longer corrupt numeric values or overflow the terminal on narrow widths.** The header-width column floor added to fix box misalignment had two flip-side bugs on sub-fit terminals: (A) any cell wider than its column was ellipsis-truncated — including numeric columns, so a token count like `12,345,678` rendered as the silently-wrong `12,345,…`; and (B) when the header floors summed past the available width nothing shrank them, so the box drew WIDER than the terminal. The scale-down policy is now: numeric (right-aligned) columns are floored at their full value width and are never ellipsis-truncated (a wrong number is worse than honest overflow), while text columns — and their header labels, which now truncate the same way data cells do — absorb the squeeze so the table fits when the numbers allow and stays box-aligned when they don't. Shared `_scale_down_col_widths` + `_ellipsize` helpers centralize the policy across both renderers. The codex session renderer is intentionally left as-is (ccusage/codex parity). Regression: `tests/test_compact_rendering.py` (numeric-never-truncated + box-fits + unit coverage); project goldens regenerated. (#102)
+- **`cache-report --since/--until` again accept space-separated datetimes (`'2026-05-01 12:30:00'`) and ISO week-dates (`2026-W18-1`).** The Session A dual-form refactor replaced cache-report's date-only fallthrough with a parser that rejects anything other than `YYYY-MM-DD` / `YYYYMMDD`, silently dropping the other forms that `datetime.fromisoformat` (and the pre-refactor code) accepted — they now failed with `--since must be YYYY-MM-DD or YYYYMMDD format`. The `parse_iso_datetime` second-chance is restored for inputs the dual-form parser rejects; a full datetime is used verbatim (no `--until` end-of-day rounding), matching the old behavior. Genuinely invalid input (e.g. `26-01-01`) still surfaces the clearer centralized `YYYY-MM-DD or YYYYMMDD` diagnostic rather than the generic ISO message, and the dual-form parse is attempted silently so a successful second-chance never leaks a spurious error line to stderr. cache-report is the only date command with this leniency; `daily` / `monthly` / `weekly` / `blocks` accept the two canonical forms only. Regression: `tests/test_cache_report_since_until_fallthrough.py`. (#101)
+- **`diff` and `project` no longer emit ANSI color into a piped or redirected stdout when `CI` is set.** The `--color` resolver placed its `CI` rung above the `stdout.isatty()` check, so on a CI runner `cctally diff … | cat` (or `> out.txt`) wrote raw escape sequences into the capture — a behavior change from the pre-Session-A contract, which keyed color on `sys.stdout.isatty()` alone and always produced clean text on a pipe. The `CI` rung is now gated behind `sys.stdout.isatty()`: CI still forces color on a real terminal (over a dumb `TERM`, matching picocolors), but a non-TTY stdout stays plain text regardless of `CI`. `FORCE_COLOR` / `NO_COLOR` / `--color` / `--no-color` precedence is unchanged. Regression: `tests/test_color_resolution.py::test_ci_with_piped_stdout_stays_uncolored` + `::test_ci_with_tty_stdout_enables`. (#100)
+
 ## [1.12.0] - 2026-05-24
 
 ### Fixed

package/bin/_cctally_cache.py

@@ -661,7 +661,7 @@ def sync_cache(
             try:
                 with open(jp, "r", encoding="utf-8", errors="replace") as fh:
                     fh.seek(start_offset)
-                    for offset, entry, msg_id, req_id in _iter_jsonl_entries_with_offsets(fh):
+                    for offset, entry, msg_id, req_id in _iter_jsonl_entries_with_offsets(fh, str(jp)):
                         usage = entry.usage
                         inp = int(usage.get("input_tokens", 0) or 0)
                         out = int(usage.get("output_tokens", 0) or 0)
@@ -839,7 +839,8 @@ def iter_entries(
 
     sql = (
         "SELECT timestamp_utc, model, input_tokens, output_tokens, "
-        "cache_create_tokens, cache_read_tokens, usage_extra_json, cost_usd_raw "
+        "cache_create_tokens, cache_read_tokens, usage_extra_json, "
+        "cost_usd_raw, source_path "
         "FROM session_entries "
         "WHERE timestamp_utc >= ? AND timestamp_utc <= ?"
     )
@@ -875,6 +876,7 @@ def iter_entries(
             model=row[1],
             usage=usage,
             cost_usd=row[7],
+            source_path=row[8],
         ))
     return entries
 

package/bin/_cctally_config.py

@@ -46,6 +46,7 @@ import json
 import os
 import secrets
 import sys
+from pathlib import Path
 from typing import Any
 
 
@@ -162,17 +163,60 @@ def config_writer_lock():
         fh.close()
 
 
-def load_config() -> dict[str, Any]:
+def _load_config_from_explicit_path(path: "str | Path") -> dict[str, Any]:
+    """Read config from an explicit per-invocation override path (issue #88).
+
+    Contract differs from the default ``load_config()``:
+      - Missing file → ``SystemExit(2)`` with a clear stderr message.
+      - Unreadable / malformed JSON / non-object root → ``SystemExit(2)``
+        with a clear stderr message.
+      - Never writes, never acquires ``config_writer_lock``, never
+        creates the on-disk default config — the override is read-only
+        for this invocation.
+
+    Used by the ccusage drop-in ``--config <path>`` flag wired onto the
+    10 Claude reporting commands (spec §3 T1.6 / issue #86 Session A).
+    """
+    p = Path(path)
+    if not p.exists():
+        eprint(f"cctally: --config: file not found: {p}")
+        raise SystemExit(2)
+    try:
+        raw = p.read_text(encoding="utf-8")
+    except OSError as exc:
+        eprint(f"cctally: --config: read failed for {p}: {exc}")
+        raise SystemExit(2) from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        eprint(f"cctally: --config: invalid JSON in {p}: {exc}")
+        raise SystemExit(2) from exc
+    if not isinstance(data, dict):
+        eprint(
+            f"cctally: --config: {p} top-level must be a JSON object"
+        )
+        raise SystemExit(2)
+    return data
+
+
+def load_config(path: "str | Path | None" = None) -> dict[str, Any]:
     """Read config.json, falling back to in-memory defaults on corruption.
 
-    Concurrent-safety: readers see either the pre-rename or post-rename
-    contents thanks to save_config's atomic os.replace. On corrupt or
-    non-object JSON, emits a one-shot stderr warning and returns
-    in-memory defaults WITHOUT re-saving — the next legitimate
-    save_config call (under config_writer_lock) will overwrite the bad
-    bytes atomically. On first run (file missing), creates the file
-    with a fresh collector token under the writer lock so two parallel
-    first-run processes don't clobber each other.
+    When ``path`` is None (default): reads the persisted user config at
+    ``_cctally_core.CONFIG_PATH``, creating it on first run with a fresh
+    collector token under the writer lock. Concurrent-safety: readers see
+    either the pre-rename or post-rename contents thanks to save_config's
+    atomic os.replace. On corrupt or non-object JSON, emits a one-shot
+    stderr warning and returns in-memory defaults WITHOUT re-saving — the
+    next legitimate save_config call (under config_writer_lock) will
+    overwrite the bad bytes atomically.
+
+    When ``path`` is set (issue #88 ccusage drop-in ``--config <path>``):
+    reads from the explicit override path and bypasses the default-path
+    branch entirely. Missing / unreadable / malformed paths surface as
+    ``SystemExit(2)`` with a clear stderr message — see
+    ``_load_config_from_explicit_path``. No writes, no first-run create,
+    no mutation of the on-disk default config.
 
     DEADLOCK NOTE: `fcntl.flock` is per-fd even within the same
     process. Callers that already hold config_writer_lock MUST use
@@ -180,6 +224,8 @@ def load_config() -> dict[str, Any]:
     inside an outer lock would block forever (verified during issue
     #17 fix).
     """
+    if path is not None:
+        return _load_config_from_explicit_path(path)
     c = _cctally()
     ensure_dirs()
     parsed = _try_read_config()

package/bin/_cctally_core.py

@@ -58,7 +58,7 @@ def _init_paths_from_env() -> None:
     break tests that cached the module object via a top-level
     `import _cctally_core`).
     """
-    global APP_DIR, LEGACY_APP_DIR, LOG_DIR
+    global APP_DIR, LEGACY_APP_DIR, LOG_DIR, DEV_MODE
     global DB_PATH, CACHE_DB_PATH
     global CACHE_LOCK_PATH, CACHE_LOCK_CODEX_PATH, CONFIG_LOCK_PATH
     global CONFIG_PATH, MIGRATION_ERROR_LOG_PATH, CHANGELOG_PATH
@@ -70,7 +70,23 @@ def _init_paths_from_env() -> None:
     global CLAUDE_PROJECTS_DIR
 
     home = pathlib.Path.home()
-    APP_DIR = home / ".local" / "share" / "cctally"
+
+    # Dev-instance isolation (docs/superpowers/specs/2026-05-26-dev-instance-
+    # isolation-design.md). Resolve the APP_DIR base first; all other path
+    # constants derive from it. First match wins:
+    #   1. explicit CCTALLY_DATA_DIR override (also the test/harness pin)
+    #   2. auto-detected dev checkout -> cctally-dev (sets DEV_MODE)
+    #   3. prod default (byte-identical to pre-feature behavior)
+    _data_dir_override = os.environ.get("CCTALLY_DATA_DIR", "").strip()
+    if _data_dir_override:
+        APP_DIR = pathlib.Path(_data_dir_override).expanduser()
+        DEV_MODE = False
+    elif _is_dev_checkout():
+        APP_DIR = home / ".local" / "share" / "cctally-dev"
+        DEV_MODE = True
+    else:
+        APP_DIR = home / ".local" / "share" / "cctally"
+        DEV_MODE = False
     LEGACY_APP_DIR = home / ".local" / "share" / "ccusage-subscription"
     LOG_DIR = APP_DIR / "logs"
 
@@ -122,6 +138,27 @@ def _init_paths_from_env() -> None:
     CLAUDE_PROJECTS_DIR = home / ".claude" / "projects"
 
 
+def _repo_root() -> pathlib.Path:
+    """Repo root when running from a source checkout: this file lives at
+    ``<repo>/bin/_cctally_core.py``, so the root is two parents up. Factored
+    out as the single monkeypatch seam for the dev-mode tests."""
+    return pathlib.Path(__file__).resolve().parent.parent
+
+
+def _is_dev_checkout() -> bool:
+    """True iff running from a git checkout (a ``.git`` entry at the repo
+    root — a directory for a main checkout, a file for a worktree) AND the
+    test/harness suppressor ``CCTALLY_DISABLE_DEV_AUTODETECT`` is unset.
+
+    Deliberately INDEPENDENT of ``CCTALLY_DATA_DIR``: this predicate gates
+    the ``setup`` guard (which protects WHICH BINARY gets wired into
+    ~/.claude/settings.json), not the data-dir relocation. The npm/brew
+    install copies ship without ``.git`` so they never read True."""
+    if os.environ.get("CCTALLY_DISABLE_DEV_AUTODETECT"):
+        return False
+    return (_repo_root() / ".git").exists()
+
+
 _init_paths_from_env()
 
 
@@ -494,6 +531,17 @@ def open_db() -> sqlite3.Connection:
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute("PRAGMA synchronous=NORMAL")
+    # Explicit for intent + symmetry with open_cache_db (bin/_cctally_cache.py).
+    # sqlite3.connect()'s default timeout=5.0 ALREADY maps to busy_timeout=5000,
+    # so this is not a behavior change — it makes the multi-writer retry window
+    # an explicit contract beside the WAL pragmas instead of an inherited
+    # default a reader has to know about. NOTE: busy_timeout does NOT absorb
+    # SQLITE_BUSY_SNAPSHOT (a WAL read-then-write transaction whose snapshot is
+    # invalidated by a competing commit raises "database is locked" instantly,
+    # bypassing the busy handler). The write paths defend against that by taking
+    # the write lock up front — BEGIN IMMEDIATE, or a write as the transaction's
+    # first DML. See cctally-dev#87.
+    conn.execute("PRAGMA busy_timeout=5000")
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS weekly_usage_snapshots (

package/bin/_cctally_db.py

@@ -62,6 +62,7 @@ from __future__ import annotations
 import argparse
 import datetime as dt
 import enum
+import fcntl
 import json
 import os
 import pathlib
@@ -2416,6 +2417,35 @@ def _001_banner_should_emit(conn: sqlite3.Connection) -> bool:
     return _recompute_banner_should_emit(data_present=row is not None)
 
 
+def _cache_db_lock_path_for_conn(conn: sqlite3.Connection) -> "pathlib.Path | None":
+    """Return the fcntl lock-file path for the cache.db a connection is
+    attached to — ``<main-db-file>.lock`` — or ``None`` for a path-less
+    (``:memory:`` / temp) connection.
+
+    Derived from the LIVE connection (``PRAGMA database_list``) rather than
+    the ``CACHE_LOCK_PATH`` constant so it tracks whatever cache.db the
+    handler was handed: production uses ``APP_DIR/cache.db`` whose sibling
+    is exactly ``CACHE_LOCK_PATH`` (the lock ``sync_cache`` opens — the
+    ``CACHE_LOCK_PATH == <CACHE_DB_PATH>.lock`` identity is asserted by
+    ``tests/test_migration_gate_concurrency.py``), while tests follow their
+    tmp cache.db so no real-home lock is ever touched. A path-less
+    connection has no sibling lock file and no cross-process concurrency to
+    guard, so the caller skips locking.
+    """
+    try:
+        rows = conn.execute("PRAGMA database_list").fetchall()
+    except sqlite3.DatabaseError:
+        return None
+    for row in rows:
+        # cache.db connection has no row_factory -> tuple (seq, name, file).
+        if row[1] == "main":
+            db_file = row[2]
+            if not db_file:
+                return None  # :memory: / temp -> no sibling lock file
+            return pathlib.Path(str(db_file) + ".lock")
+    return None
+
+
 @cache_migration("001_dedup_highest_wins")
 def _001_dedup_highest_wins(conn: sqlite3.Connection) -> None:
     """One-time re-ingest of session_entries with corrected msg_id+req_id dedup.
@@ -2464,6 +2494,55 @@ def _001_dedup_highest_wins(conn: sqlite3.Connection) -> None:
           handler time anyway. Interactive surfaces (``report``,
           ``weekly``, ``percent-breakdown``, etc.) still see it once.
     """
+    # #105 — mutual exclusion with ``sync_cache``. Acquire the SAME
+    # ``cache.db.lock`` fcntl flock ``sync_cache`` holds for its entire
+    # walk, BEFORE the ``BEGIN IMMEDIATE`` below. Both paths therefore
+    # acquire fcntl -> SQLite write lock in ONE consistent order, so there
+    # is no opposite-order deadlock (the hazard that deferred this fix:
+    # SQLite-then-fcntl in 001 vs fcntl-then-SQLite in sync_cache). With
+    # the lock held across the wipe, 001's destructive DELETEs can never
+    # interleave a ``sync_cache`` walk: a sync runs entirely before 001
+    # (then 001 wipes ``session_files`` so the next sync re-ingests from
+    # offset 0) or entirely after (reading an empty post-wipe baseline).
+    # That makes the compound straddle — a sync reading its ``existing``
+    # baseline pre-wipe, then committing a full-size ``session_files`` row
+    # whose pre-wipe prefix 001 just deleted — structurally impossible.
+    #
+    # On contention (a sync is mid-walk) we DEFER via ``MigrationGateNotMet``
+    # BEFORE touching any data: the cache stays fully consistent, the
+    # dispatcher records 001 as still-pending (no error log, no banner) and
+    # retries it on the next open — matching ``sync_cache``'s own
+    # non-blocking LOCK_NB-and-bail and the framework's "defer is the safe
+    # side" contract. 008/009/010 already defer while 001 is pending, so the
+    # system stays safe until a non-contended instant applies it.
+    lock_path = _cache_db_lock_path_for_conn(conn)
+    lock_fh = None
+    if lock_path is not None:
+        lock_fh = open(lock_path, "w")
+        try:
+            fcntl.flock(lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            lock_fh.close()
+            raise MigrationGateNotMet(
+                "cache.db.lock held by a concurrent sync_cache; deferring "
+                "cache 001 dedup wipe (#105)"
+            )
+    try:
+        _001_dedup_highest_wins_locked(conn)
+    finally:
+        if lock_fh is not None:
+            try:
+                fcntl.flock(lock_fh, fcntl.LOCK_UN)
+            except OSError:
+                pass
+            lock_fh.close()
+
+
+def _001_dedup_highest_wins_locked(conn: sqlite3.Connection) -> None:
+    """Body of cache 001, run with the ``cache.db.lock`` flock already held
+    (or skipped for a path-less connection). Split from the public handler
+    so the lock acquire/release wraps the whole wipe (#105); see
+    ``_001_dedup_highest_wins`` for the lock-ordering rationale."""
     if _001_banner_should_emit(conn):
         eprint(
             "[cctally] Re-ingesting Claude session history with "

package/bin/_cctally_record.py

@@ -799,7 +799,13 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
         # mid-sequence failure doesn't leave the prior block closed
         # without the current block opened/updated.
         now_iso = now_utc_iso()
-        conn.execute("BEGIN")
+        # BEGIN IMMEDIATE (not deferred): the first DML below is a write (the
+        # close-older UPDATE), so this transaction already takes the write lock
+        # up front today. Stating IMMEDIATE makes that the explicit contract —
+        # a future edit that slips a SELECT before the first write here cannot
+        # silently reintroduce a SQLITE_BUSY_SNAPSHOT crash (busy_timeout does
+        # not absorb that). See cctally-dev#87.
+        conn.execute("BEGIN IMMEDIATE")
         try:
             # Step 5: close any STRICTLY OLDER open block. `<` not `!=`
             # — record-usage runs in parallel via background hook-tick &

package/bin/_cctally_refresh.py

@@ -577,7 +577,12 @@ def _refresh_usage_inproc(timeout_seconds: float = 5.0) -> _RefreshUsageResult:
     five_resets_iso = None
     five_resets_epoch = None
     warnings: list = []
-    if five is not None and "utilization" in five and "resets_at" in five:
+    # An inactive 5h window arrives as `resets_at: null` (key present, value
+    # null). Require a string here — mirrors the seven_day guard in
+    # _fetch_oauth_usage — so _iso_to_epoch(None) can't raise AttributeError;
+    # a malformed (non-null) string still degrades via the except below.
+    if (five is not None and "utilization" in five
+            and isinstance(five.get("resets_at"), str)):
         try:
             five_pct = c._normalize_percent(float(five["utilization"]))
             five_resets_iso = five["resets_at"]
@@ -778,7 +783,12 @@ def _hook_tick_oauth_refresh(
     five = api.get("five_hour") if isinstance(api.get("five_hour"), dict) else None
     five_pct: float | None = None
     five_resets_epoch: int | None = None
-    if five is not None and "utilization" in five and "resets_at" in five:
+    # An inactive 5h window arrives as `resets_at: null` (key present, value
+    # null). Require a string here — mirrors the seven_day guard in
+    # _fetch_oauth_usage — so _iso_to_epoch(None) can't raise AttributeError;
+    # a malformed (non-null) string still degrades via the except below.
+    if (five is not None and "utilization" in five
+            and isinstance(five.get("resets_at"), str)):
         try:
             five_pct = c._normalize_percent(float(five["utilization"]))
             five_resets_epoch = _iso_to_epoch(five["resets_at"])

package/bin/_cctally_setup.py

@@ -77,6 +77,39 @@ from _cctally_core import (
 )
 
 
+# Dev-instance isolation (§3): refusal message when `cctally setup` is run
+# from a git checkout without --force-dev. {data_dir} is the resolved
+# APP_DIR for context (cctally-dev in plain dev mode, the override path if
+# CCTALLY_DATA_DIR was set — the guard keys on _is_dev_checkout(), not the
+# data dir, so the override still cannot rewrite prod's hooks).
+_DEV_SETUP_REFUSAL_MSG = (
+    "cctally setup: refusing to run from a dev checkout (data dir: {data_dir}).\n"
+    "This would rewrite the hooks in ~/.claude/settings.json that point at your\n"
+    "installed (prod) cctally. Run setup from the installed binary instead, or\n"
+    "pass --force-dev to override (e.g. to install dev-pointing hooks on purpose)."
+)
+
+
+# Dev-instance isolation (§3, P2): warning when `--force-dev` installs hooks
+# while CCTALLY_DATA_DIR is set. The hook command saved into settings.json is
+# just `<binary> hook-tick` — it does NOT carry the override env. A hook fire
+# that doesn't inherit the override (GUI-launched Claude, a different shell)
+# resolves APP_DIR via dev-checkout auto-detect ({autodetect_dir}), while
+# interactive runs in this shell use {override_dir} — silently splitting one
+# intended instance across two DBs. CCTALLY_DATA_DIR is an interactive-only
+# hatch (spec "Out of scope / accepted"); baking it into the global hook
+# command would persist a transient path machine-wide, so we warn instead.
+_DEV_SETUP_FORCE_DEV_OVERRIDE_WARNING = (
+    "cctally setup: warning: installing hooks with --force-dev while "
+    "CCTALLY_DATA_DIR is set.\n"
+    "  Interactive runs in this shell use: {override_dir}\n"
+    "  Background hook fires (no env inherited) will use: {autodetect_dir}\n"
+    "The hook command can't carry CCTALLY_DATA_DIR, so these two paths split "
+    "your\ndata across separate DBs. CCTALLY_DATA_DIR is an interactive-only "
+    "override."
+)
+
+
 # ── settings.json hook surgery ─────────────────────────────────────────
 
 
@@ -1818,6 +1851,53 @@ def _setup_install(args: argparse.Namespace) -> int:
 
 
 def cmd_setup(args: argparse.Namespace) -> int:
+    # Dev-instance isolation (§3): refuse the MUTATING modes (install +
+    # uninstall) when run from a git checkout, unless --force-dev. Those
+    # rewrite ~/.claude/settings.json (prod's hooks), which is NOT under
+    # APP_DIR — from the dev checkout this would repoint prod's hooks at the
+    # dev binary or remove them. --status / --dry-run are read-only previews
+    # (they never write settings.json) and stay usable from a checkout, so
+    # the guard is scoped to the write modes only. The three mode flags are a
+    # mutually-exclusive argparse group, so the write modes (uninstall +
+    # default install) are exactly the complement of {status, dry_run}.
+    # Keyed on _is_dev_checkout() (NOT DEV_MODE / the cctally-dev path
+    # string), so a per-branch CCTALLY_DATA_DIR override relocates the data
+    # dir but still cannot rewrite prod's hooks (the F1 fix). The test
+    # suppressor forces _is_dev_checkout() False, so the setup tests +
+    # golden harness behave exactly like prod.
+    mode_is_mutating = not (
+        getattr(args, "status", False) or getattr(args, "dry_run", False)
+    )
+    if (
+        mode_is_mutating
+        and _cctally_core._is_dev_checkout()
+        and not getattr(args, "force_dev", False)
+    ):
+        eprint(_DEV_SETUP_REFUSAL_MSG.format(data_dir=_cctally_core.APP_DIR))
+        return 2
+    # P2: --force-dev install on a checkout with CCTALLY_DATA_DIR set splits
+    # interactive runs (override dir) from background hook fires (auto-detect
+    # dir, since the saved hook command can't carry the override env). Only
+    # the install path writes hooks, so scope the warning to it (uninstall
+    # removes hooks; --status/--dry-run don't write). Fires only on the
+    # doubly-rare --force-dev + CCTALLY_DATA_DIR combination.
+    is_install = not (
+        getattr(args, "status", False)
+        or getattr(args, "dry_run", False)
+        or getattr(args, "uninstall", False)
+    )
+    override_dir = os.environ.get("CCTALLY_DATA_DIR", "").strip()
+    if (
+        is_install
+        and _cctally_core._is_dev_checkout()
+        and getattr(args, "force_dev", False)
+        and override_dir
+    ):
+        autodetect_dir = pathlib.Path.home() / ".local" / "share" / "cctally-dev"
+        eprint(_DEV_SETUP_FORCE_DEV_OVERRIDE_WARNING.format(
+            override_dir=pathlib.Path(override_dir).expanduser(),
+            autodetect_dir=autodetect_dir,
+        ))
     # Migration flags are install-mode-only. Reject combinations with
     # --status or --uninstall (per spec Section 2 mode×flag matrix). The
     # mutex group on the parser already prevents both flags being set

package/bin/_lib_aggregators.py

@@ -590,7 +590,13 @@ def _aggregate_codex_sessions(entries: list[CodexEntry]) -> list[CodexSessionUsa
             cached_input_tokens=s["cached_input"],
             output_tokens=s["output"],
             reasoning_output_tokens=s["reasoning"],
-            total_tokens=s["input"] + s["output"],  # derived, matches upstream
+            # Codex `input` is cache-inclusive (LiteLLM convention; see the
+            # "Codex token semantics" gotcha in CLAUDE.md) and `output`
+            # subsumes reasoning, so `input + output` already counts ALL
+            # tokens processed — the same "all tokens" semantic the Claude
+            # session roll-up reaches via input+output+cache (issue #104).
+            # Adding cache here would double-count. Matches upstream.
+            total_tokens=s["input"] + s["output"],
             cost_usd=s["cost"],
             models=list(s["models_order"]),
             model_breakdowns=model_breakdowns,
@@ -695,10 +701,17 @@ def _aggregate_claude_sessions(
             [sess["models"][m] for m in sess["models_order"]],
             key=lambda mb: -mb["cost"],
         )
-        # Spec A2.8 (design.md:422): Total Tokens = input + output only;
-        # cache tokens shown separately but not summed — parallels
-        # `codex-session` (see `_codex_sessions_to_json`, line ~3603).
-        total_tokens = sess["input"] + sess["output"]
+        # Issue #104: Total Tokens sums ALL four components (input + output
+        # + cache create + cache read), matching `daily`/`monthly` and
+        # upstream ccusage v20. (Supersedes the original Spec A2.8
+        # input+output-only convention.) The `codex-session` parallel is
+        # preserved at the SEMANTIC level — both report "all tokens
+        # processed" — even though its surface formula stays `input+output`
+        # (Codex `input_tokens` is already cache-inclusive; see line ~593).
+        total_tokens = (
+            sess["input"] + sess["output"]
+            + sess["cache_create"] + sess["cache_read"]
+        )
         results.append(ClaudeSessionUsage(
             session_id=sess["session_id"],
             project_path=sess["project_path"],

package/bin/_lib_diff_kernel.py

@@ -1234,11 +1234,18 @@ def _diff_render_section_table(
     used_pct_mode_a: str,
     used_pct_mode_b: str,
     threshold: "NoiseThreshold | None" = None,
+    compact: bool = False,
 ) -> str:
     """Render one bordered table for a section. The Total row sums all rows
     (visible + hidden) — the caller passes the unfiltered aggregate map as
-    total_a/total_b so hidden rows still contribute (spec §4 invariant)."""
+    total_a/total_b so hidden rows still contribute (spec §4 invariant).
+
+    ``compact`` (issue #91, Shape B) drops the 1-space cell padding to 0 on
+    this content-sized table, which has no proportional-width path to force.
+    ``pad == 1`` (the default) reproduces the prior output byte-for-byte."""
     boxes = _diff_box_chars()
+    pad = 0 if compact else 1
+    pad_s = " " * pad
     out: list = [_diff_section_heading(section.name, width), ""]
 
     header_cells: list = ["Model" if section.name == "models"
@@ -1318,7 +1325,7 @@ def _diff_render_section_table(
         fill = fill or boxes["h"]
         parts = [left]
         for i, w in enumerate(col_w):
-            parts.append(fill * (w + 2))
+            parts.append(fill * (w + 2 * pad))
             parts.append(right if i == n_cols - 1 else mid)
         return "".join(parts)
 
@@ -1340,7 +1347,7 @@ def _diff_render_section_table(
                 # result. Spaces stay outside the ANSI escape so column rules
                 # align identically with or without color.
                 styled = _style_ansi(padded, code, enabled=bool(code))
-                parts.append(f" {styled} ")
+                parts.append(f"{pad_s}{styled}{pad_s}")
                 parts.append(boxes["v"])
             out_lines.append("".join(parts))
         return "\n".join(out_lines)
@@ -1376,11 +1383,13 @@ def _diff_render_full_output(
     width: int,
     raw_aggregates: dict,
     tz: "ZoneInfo | None" = None,
+    compact: bool = False,
 ) -> str:
     """Compose banner + window header + each section's table.
 
     ``tz`` is forwarded to ``_diff_render_window_header`` for the date
-    labels; ``tz=None`` means host-local.
+    labels; ``tz=None`` means host-local. ``compact`` (issue #91, Shape B)
+    is forwarded to each section table's pad-reduction branch.
     """
     parts: list = [
         _diff_render_banner(), "",
@@ -1395,6 +1404,7 @@ def _diff_render_full_output(
             used_pct_mode_a=result.used_pct_mode_a,
             used_pct_mode_b=result.used_pct_mode_b,
             threshold=result.threshold,
+            compact=compact,
         ))
     return "\n".join(parts)
 

package/bin/_lib_doctor.py

@@ -94,6 +94,15 @@ class DoctorState:
     # Meta
     now_utc: dt.datetime
     cctally_version: str
+    # Dev-instance isolation (2026-05-26): which data dir this process
+    # resolved, and whether it was via dev-checkout auto-detect.
+    # `is_dev_checkout` is the binary-location fact (running from a git
+    # checkout), independent of `dev_mode` (which is False when an explicit
+    # CCTALLY_DATA_DIR override won at step 1). The override-on-checkout case
+    # is `is_dev_checkout=True, dev_mode=False` — distinct from installed.
+    dev_mode: bool
+    app_dir: str
+    is_dev_checkout: bool = False
 
 
 @dataclasses.dataclass(frozen=True)
@@ -212,6 +221,35 @@ def _check_install_legacy_bespoke(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_install_dev_mode(s: DoctorState) -> CheckResult:
+    """Always-present, always-ok: reports the resolved data dir and whether
+    this process is a dev-checkout or the installed binary.
+    Dev-instance isolation (§4, P3).
+
+    Three states, not two — `dev_mode` alone collapses the override case:
+      - dev_mode                       → auto-detected checkout (cctally-dev)
+      - is_dev_checkout, not dev_mode  → checkout + CCTALLY_DATA_DIR override
+      - neither                        → installed (prod)
+    Reporting the override case as "installed" was misleading exactly when a
+    user runs the per-branch hatch and wants to confirm which instance they
+    are on (the binary IS a checkout; setup still refuses it as one)."""
+    if s.dev_mode:
+        summary = "DEV (auto-detected git checkout)"
+    elif s.is_dev_checkout:
+        summary = "DEV (git checkout, custom data dir via CCTALLY_DATA_DIR)"
+    else:
+        summary = "installed"
+    return CheckResult(
+        id="install.mode", title="Mode",
+        severity="ok", summary=summary, remediation=None,
+        details={
+            "dev_mode": s.dev_mode,
+            "is_dev_checkout": s.is_dev_checkout,
+            "app_dir": s.app_dir,
+        },
+    )
+
+
 _REQUIRED_HOOK_EVENTS = ("PostToolBatch", "Stop", "SubagentStop")
 
 
@@ -840,6 +878,7 @@ def _check_safety_update_available(s: DoctorState) -> CheckResult:
 # success-vs-raise transitions.
 _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...] = (
     ("install", "Install", (
+        ("install.mode", "_check_install_dev_mode"),
         ("install.symlinks", "_check_install_symlinks"),
         ("install.path", "_check_install_path"),
         ("install.legacy_snippet", "_check_install_legacy_snippet"),