cctally 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-05-26
+
+### Added
+- **`cctally claude <cmd>` and `cctally codex <cmd>` subgroup commands** let you paste ccusage's hierarchical syntax verbatim — `cctally claude {daily,monthly,weekly,session,blocks}` is a drop-in for `ccusage claude <cmd>`, and `cctally codex {daily,monthly,session,weekly}` for `ccusage codex <cmd>` (`codex weekly` is a cctally extension; upstream has none). Each subgroup leaf routes to the exact same engine as its flat form, so the table / `--json` / exit code are byte-identical — only `--help` adds a one-line alias/canonical cross-reference. The flat forms (`cctally daily`, `cctally codex-daily`, …) remain fully supported as back-compat aliases, with no deprecation warning. (#86)
+
+## [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

package/README.md

@@ -113,7 +113,7 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
 
 ## What cctally adds
 
-`cctally` started as a local-first replacement for [`ccusage`](https://github.com/ryoppippi/ccusage), and it stays compatible at the level of common CLI flows (`daily`, `monthly`, `weekly`, `session`, `blocks`). Beyond that, it adds:
+`cctally` started as a local-first replacement for [`ccusage`](https://github.com/ryoppippi/ccusage), and it stays compatible at the level of common CLI flows (`daily`, `monthly`, `weekly`, `session`, `blocks`). Paste from ccusage verbatim: `cctally claude <cmd>` is a drop-in for `ccusage claude <cmd>` (and `cctally codex <cmd>` for `ccusage codex <cmd>`), with the flat forms (`cctally daily`, `cctally codex-daily`, …) kept as aliases. Beyond that, it adds:
 
 - **Live web dashboard.** Nine-panel SSE-driven view at `localhost:8789` (current week, forecast, trend, sessions, weekly, monthly, blocks, daily, recent alerts), with per-panel modals, a mobile layout, threshold alerts, and a settings drawer.
 - **TUI live mode.** The same data inside your terminal (`cctally tui`; requires the optional `rich` package).
@@ -123,7 +123,7 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
 - **5-hour block analytics.** Per-block usage with model and project breakdowns (`cctally five-hour-blocks --breakdown=model`).
 - **Time-window diff.** Compare two windows with model and project decomposition (`cctally diff`).
 - **Project rollup.** Usage by Git project (`cctally project`).
-- **Codex parity.** Drop-in replacements for `ccusage-codex daily / monthly / session`, plus an added `cctally codex-weekly` rollup (upstream has no `codex weekly`).
+- **Codex parity.** `cctally codex daily / monthly / session` are drop-ins for `ccusage codex daily / monthly / session`; the flat `codex-*` forms (drop-ins for the standalone `ccusage-codex` binary) remain as aliases, plus an added `cctally codex weekly` / `cctally codex-weekly` rollup (upstream has no `codex weekly`).
 - **Persistent SQLite.** Week-over-week comparisons survive across runs.
 
 **On speed.** Pricing is embedded and computed at query time from a delta-tail SQLite cache (`~/.local/share/cctally/cache.db`), with no shell-outs. First-table latency on 30 days of session data: **~2.6s (cctally) vs ~31s (ccusage)**, about 12× faster. Measured by `bench/cctally-vs-ccusage.sh` on macOS arm64, 2026-05-05; your numbers will vary.[^bench]

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
@@ -2370,6 +2371,10 @@ def _recompute_banner_should_emit(
           confuses scripted pipelines. Banner still lands on the
           next interactive non-report command (``report``,
           ``weekly``, ``percent-breakdown``, etc.) once on upgrade.
+          Subgroup forms (``cctally claude/codex <cmd>``, issue #86
+          Session B) carry the source group in ``argv[1]`` and the
+          leaf in ``argv[2]``; we resolve the leaf so suppression is
+          byte-identical to the flat alias.
 
     Returns True iff the banner should be printed. Defensive: any
     error reading ``sys.argv`` falls back to "don't print" — silence
@@ -2387,6 +2392,14 @@ def _recompute_banner_should_emit(
         return False
     try:
         argv1 = sys.argv[1] if len(sys.argv) > 1 else None
+        # Subgroup forms (`cctally claude <cmd>` / `cctally codex <cmd>`) carry
+        # the source group in argv[1]; the suppression key is the leaf command
+        # in argv[2]. Resolve it so the recompute banner suppresses identically
+        # to the flat alias (issue #86 Session B; matches the args.command leaf
+        # resolution used by the error-sentinel banner). Purely additive — flat
+        # invocations (argv1 not in {claude,codex}) are byte-identical to before.
+        if argv1 in ("claude", "codex") and len(sys.argv) > 2:
+            argv1 = sys.argv[2]
     except Exception:
         argv1 = None
     if argv1 in _BANNER_SUPPRESSED_COMMANDS:
@@ -2416,6 +2429,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 +2506,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_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"),

package/bin/_lib_render.py

@@ -1006,13 +1006,18 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
 
 
 def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
-    """Serialize Claude sessions to JSON per spec A2.8.
+    """Serialize Claude sessions to JSON (spec A2.8, amended by issue #104).
 
     Per-session: sessionId, projectPath, sourcePaths (list), firstActivity
     / lastActivity ISO strings, modelsUsed, token counts
     (input/cacheCreation/cacheRead/output/total), totalCost, modelBreakdowns
     (camelCased token field names, cost).
 
+    `totalTokens` (per-session + totals) sums ALL four token components
+    (input + output + cacheCreation + cacheRead) per issue #104 — matching
+    `daily`/`monthly` and ccusage v20. (The field name/shape is unchanged;
+    only the value definition widened to include cache.)
+
     totals: same 6 numeric fields aggregated across sessions.
     """
     sess_list: list[dict[str, Any]] = []
@@ -2118,12 +2123,23 @@ def _render_codex_session_table(
     # auto-detect so the narrow layout renders regardless of terminal width.
     if force_compact or (sum(col_widths) + border_overhead > term_width):
         available = term_width - border_overhead
-        total_col = sum(col_widths)
-        scale = available / total_col if total_col > 0 else 1.0
-        col_widths = [max(int(w * scale), 8) for w in col_widths]
-        remainder = available - sum(col_widths)
-        if remainder > 0:
-            col_widths[3] += remainder  # grow Models column
+        # Issue #99 / #102: the prior bare-`8` floor could scale a column
+        # below its header label, and headers are padded (never truncated)
+        # in the header render — so the header row grew wider than the box
+        # border and the grid misaligned on narrow terminals. Mirror the
+        # sibling renderers (`_render_claude_session_table` + the project
+        # renderer) via the shared `_scale_down_col_widths` chokepoint:
+        # numeric columns are protected at their widest DATA value while
+        # text columns (incl. header labels) absorb the squeeze and may
+        # truncate, keeping every box line the same width. Grows the Models
+        # column (index 3) with any slack, preserving prior behavior.
+        data_widths = [0] * num_cols
+        for cells, _rt in raw_rows:
+            for i, (text, _c) in enumerate(cells):
+                data_widths[i] = max(data_widths[i], _max_line_width(text))
+        col_widths = _scale_down_col_widths(
+            col_widths, aligns, data_widths, available, grow_idx=3,
+        )
 
     def _split_cell(text: str) -> list[str]:
         return text.split("\n") if text else [""]
@@ -2165,13 +2181,17 @@ def _render_codex_session_table(
 
     out.append(_border_row(TL, T_DOWN, TR))
 
-    # Header
+    # Header — labels ellipsize like data cells so a column scaled below
+    # its header width stays box-aligned (issue #99 / #102 (a)). Previously
+    # the header padded without truncating, so a label wider than its
+    # scaled column overflowed the box border.
     header_cells = [_split_cell(h) for h in headers]
     max_h = max(len(c) for c in header_cells)
     for li in range(max_h):
         parts = [_dim(V)]
         for i, cell in enumerate(header_cells):
             content = cell[li] if li < len(cell) else ""
+            content = _ellipsize(content, col_widths[i], unicode_ok)
             parts.append(f" {_cyan(_pad_cell(content, col_widths[i], aligns[i]))} ")
             parts.append(_dim(V))
         out.append("".join(parts))
@@ -2187,11 +2207,14 @@ def _render_codex_session_table(
             parts = [_dim(V)]
             for i, (text, cfn) in enumerate(cells):
                 content = split_cells[i][li] if li < len(split_cells[i]) else ""
-                # Truncate with ellipsis if cell content exceeds column width
+                # Ellipsis-truncate only TEXT cells. Numeric (right-aligned)
+                # cells are NEVER truncated \u2014 a wrong number is worse than
+                # honest overflow (issue #102 (b)); _scale_down_col_widths
+                # floors numeric columns at their full number width so this
+                # normally never overflows. Mirrors the sibling renderers.
                 w = col_widths[i]
-                if len(content) > w:
-                    ell = "\u2026" if unicode_ok else "..."
-                    content = content[: max(0, w - len(ell))] + ell
+                if aligns[i] != "right":
+                    content = _ellipsize(content, w, unicode_ok)
                 padded = _pad_cell(content, w, aligns[i])
                 if cfn is not None:
                     padded = cfn(padded)
@@ -2281,9 +2304,10 @@ def _render_claude_session_table(
     for s in sessions:
         short_models = sorted({_short_model_name(m) for m in s.models})
         models_text = "\n".join(f"- {m}" for m in short_models) if short_models else ""
-        # Spec A2.8: Total Tokens = input + output (cache shown separately,
-        # not summed). Parallels `_render_codex_session_table` line ~4644.
-        session_total = s.input_tokens + s.output_tokens
+        # Issue #104: Total Tokens = all four components (input + output +
+        # cache), matching daily/monthly + ccusage v20. Read the single
+        # source of truth on the aggregate rather than recomputing.
+        session_total = s.total_tokens
         data_cells = [
             (_date_cell(s.last_activity), None),
             (s.project_path, None),
@@ -2306,8 +2330,8 @@ def _render_claude_session_table(
                 mb_cc = int(mb["cache_create"])
                 mb_cr = int(mb["cache_read"])
                 mb_output = int(mb["output"])
-                # Spec A2.8: Total Tokens = input + output only.
-                mb_total = mb_input + mb_output
+                # Issue #104: per-model Total Tokens sums all four components.
+                mb_total = mb_input + mb_output + mb_cc + mb_cr
                 mb_cost = float(mb["cost"])
                 bd_cells = [
                     (f"{arrow} {name}", _gray),
@@ -2328,8 +2352,8 @@ def _render_claude_session_table(
     tot_cc = sum(s.cache_creation_tokens for s in sessions)
     tot_cr = sum(s.cache_read_tokens for s in sessions)
     tot_output = sum(s.output_tokens for s in sessions)
-    # Spec A2.8: Total Tokens = input + output only.
-    tot_tokens = tot_input + tot_output
+    # Issue #104: Total Tokens footer sums all four components.
+    tot_tokens = sum(s.total_tokens for s in sessions)
     tot_cost = sum(s.cost_usd for s in sessions)
     footer_cells = [
         ("Total", _yellow),