cctally 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-05-28
+
+### Added
+- **`cctally statusline` (and `cctally claude statusline`) — a one-line status string for Claude Code's `statusLine` hook, drop-in for `ccusage statusline` with cctally-only extensions appended.** Reads the Claude Code hook stdin and emits five `|`-delimited segments: `🤖 <model>` (display name) · `💰 $X.XX session / $Y.YY today / $Z.ZZ block (Hh Mm left)` cost · `🔥 $X.XX/hr` burn rate with optional `🟢/🟡/🔴 (Normal/Moderate/High)` visual · `🧠 N%` context-window utilization · `5h X% (Hh Mm) · 7d Y% (Dd Hh)` cctally extension sourced from stdin `rate_limits` with the existing monotonic HWM clamp and DB-latest-row fallback. Flag surface mirrors ccusage's: `-B {off,emoji,text,emoji-text}`, `--cost-source {auto,cctally,cc,both}` (the `ccusage` value name is renamed; passing it errors with a one-line rename hint), `--context-low-threshold`/`--context-medium-threshold` (defaults 50/80, with `[0, 100]` range + `low < medium` ordering validation), `-z/--timezone`, `-d/--debug`, plus `--cache`/`--no-cache`/`--refresh-interval`/`-O/--offline`/`--single-thread` as documented no-op aliases and `--config PATH` honored as a real per-invocation override (parity with the 10 sibling Claude reporting commands). cctally adds `--cctally-extensions`/`--no-cctally-extensions` (default-on) to toggle segment 5 and persists three config keys (`statusline.{visual_burn_rate,cost_source,cctally_extensions}`) with CLI > config > built-in default precedence. Cost sources: `auto` uses the cctally JSONL-derived cost when the transcript is readable and the session exists in the cache, falling back to stdin `cost.total_cost_usd` otherwise; `cctally`/`cc`/`both` force one path or render side-by-side. Today's bucket honors `display.tz`; the active block segment reuses Session F's `_lib_blocks` kernel and burn-rate bands are `<$15/hr` green, `<$30/hr` yellow, `≥$30/hr` red. Context % is computed from a memory-safe tail-walk of the transcript JSONL (last assistant turn's usage block ÷ per-model context window — 200K default, 1M for `[1m]` variants); unknown models render `🧠 N/A` with a one-shot stderr warn. Stdin contract is deliberately graceful (an intentional ccusage divergence, documented in the spec): only malformed JSON or a non-object root exits 1; every other field absence — missing `model`, `transcript_path`, `session_id`, `cost`, even `rate_limits` — produces a degraded but non-broken line at exit 0, so the status line never fails the hook on a partial payload. Architecture: pure-function render kernel at `bin/_lib_statusline.py` (no I/O — every side-effecting dep dataclass-injected); I/O glue in `bin/cctally::cmd_statusline` wires DB + transcript reader + HWM clamp callables; built once and registered twice (flat + nested) per the Session B parser pattern, so `cctally statusline` and `cctally claude statusline` produce byte-identical output (only `--help` xref differs). Regression: `bin/cctally-statusline-test` (32 fixture scenarios — every cost-source value, every `-B` variant, every context color band + the unknown-model + 1M-window paths, extension HWM clamp + DB fallback + suppression, resumed-session merge, every graceful-degradation case, bad-stdin, tz buckets, config persistence + CLI override + `--config PATH`), `bin/cctally-reconcile-test` (+6 statusline invariants binding the segments to `cctally session`/`daily`/`blocks --active`/`weekly_usage_snapshots` within 1e-9 USD tolerance), `bin/cctally-subgroup-test` (new `compare_forms_stdin` proves flat≡`claude statusline` over a subgroup-parity fixture), and `tests/test_statusline.py` (66 kernel units). (#86)
+
+## [1.19.0] - 2026-05-28
+
+### Added
+- **`cctally blocks` (and `cctally claude blocks`) gain the ccusage drop-in flags `-a/--active`, `-r/--recent`, `-t/--token-limit N|max`, and `-n/--session-length N`.** `-a` filters to the single live block and renders it as a "Current Session Block Status" detail box — Block Started (+ "Xh Ym ago" / approximate-start `~` cue when the window has no recorded Anthropic reset), Time Remaining, Current Usage, Burn Rate and Projected Usage (when available), and — only when `-t` is passed explicitly — a Token Limit Status block whose `OK`/`WARNING`/`EXCEEDS LIMIT` color tracks the projected percent; with no active block it prints `No active session block found.` to stdout (JSON: `{"blocks": [], "message": "No active block"}`) and exits 0. `-r` keeps only blocks from the last 3 days plus the active block. `-t N` keys the table's `%`/REMAINING/PROJECTED surface (and the `-a` box's Token Limit Status) to an explicit limit even with no completed history, while `-t max` (the default) derives it from the largest completed block and prints `Using max tokens from previous sessions: N` to stdout (suppressed under `--json`); `--json` additionally gains an additive `tokenLimitStatus` key on active blocks under an explicit positive `-t`. `-n` is accepted for drop-in compatibility but is a no-op — cctally blocks follow Anthropic's real 5-hour resets and are not re-sizable — except `-n <= 0`, which errors (exit 1). cctally's block projection keeps its real-reset formula (a documented third intentional divergence from upstream's entry-span model). (#86)
+
 ## [1.18.0] - 2026-05-27
 
 ### Added

package/bin/_cctally_cache.py

@@ -11,8 +11,8 @@ pipeline.
 Holds:
 - ``ProjectKey`` (frozen dataclass) + ``_resolve_project_key`` —
   canonical project bucket identity for the ``project`` subcommand.
-- ``_get_codex_sessions_dir`` / ``_discover_codex_session_files`` —
-  Codex JSONL discovery primitives.
+- ``_discover_codex_session_files`` / ``_iter_codex_jsonl_paths`` —
+  Codex JSONL discovery primitives (multi-root $CODEX_HOME walk).
 - ``IngestStats`` / ``CodexIngestStats`` (dataclasses), ``_progress_stderr``
   / ``_progress_codex_stderr`` — ingest progress + per-call telemetry.
 - ``_ensure_session_files_row`` — idempotent backfill of
@@ -82,7 +82,7 @@ in the sibling graph):
 ``get_entries``, ``get_claude_session_entries``, ``get_codex_entries``,
 ``_resolve_project_key``, ``ProjectKey``, ``IngestStats``,
 ``CodexIngestStats``, ``_JoinedClaudeEntry``, ``_ensure_session_files_row``,
-``_discover_codex_session_files``, ``_get_codex_sessions_dir``,
+``_discover_codex_session_files``,
 ``cmd_cache_sync``, ``_progress_stderr``, ``_progress_codex_stderr``,
 ``_collect_entries_direct``, ``_collect_codex_entries_direct``,
 ``_direct_parse_claude_session_entries``, ``iter_codex_entries``)
@@ -107,7 +107,7 @@ import pathlib
 import sqlite3
 import sys
 from dataclasses import dataclass, field
-from typing import Any, Callable
+from typing import Any, Callable, Iterator
 
 
 def _cctally():
@@ -265,27 +265,54 @@ def _resolve_project_key(
 # === Region 2: Codex sessions-dir helpers (was bin/cctally:2072-2099) ===
 
 
-def _get_codex_sessions_dir() -> pathlib.Path | None:
-    """Return the Codex sessions directory if present, else None."""
-    c = _cctally()
-    if c.CODEX_SESSIONS_DIR.is_dir():
-        return c.CODEX_SESSIONS_DIR
-    return None
+def _iter_codex_jsonl_paths(roots: list[pathlib.Path]) -> Iterator[pathlib.Path]:
+    """Yield each existing *.jsonl under the given roots, de-duped by RESOLVED
+    path (first occurrence wins — collapses overlapping/prefix roots and
+    symlink/`..` aliases of the same physical file).
+
+    Pure read: globs + is_file() only, no DB access. Shared by both Codex
+    walkers (_discover_codex_session_files and sync_codex_cache) so they stay
+    in lock-step on dedup + is_file() ordering.
+    """
+    seen: set[pathlib.Path] = set()
+    for root in roots:
+        for jp in root.glob("**/*.jsonl"):
+            # Dedup on the RESOLVED path, not the raw spelling. A symlinked
+            # $CODEX_HOME root or an alias entry (`.../.codex`,
+            # `.../sub/../.codex`) can glob the same physical file under
+            # different spellings; UNIQUE(source_path, line_offset) keys on the
+            # string, so distinct spellings would double-ingest (2-3x tokens /
+            # cost) on a fresh walk. resolve() collapses the aliases (issue
+            # #108). First spelling still wins for the yielded source_path.
+            try:
+                key = jp.resolve()
+            except OSError:
+                key = jp  # unresolvable (broken symlink, perms) — key on raw
+            if key in seen:
+                continue
+            seen.add(key)
+            if jp.is_file():
+                yield jp
 
 
 def _discover_codex_session_files(
     range_start: dt.datetime,
 ) -> list[pathlib.Path]:
-    """Glob ~/.codex/sessions/**/*.jsonl, filtering by mtime >= range_start."""
-    root = _get_codex_sessions_dir()
-    if root is None:
-        eprint("[codex] no ~/.codex/sessions directory found")
+    """Glob each $CODEX_HOME session root's **/*.jsonl, mtime >= range_start.
+
+    Iterates _cctally()._codex_session_roots() (multi-root). The "none found"
+    notice fires ONLY when there are zero session-root directories at all (the
+    multi-root analogue of the old single-dir-missing check) — NOT when roots
+    exist but the mtime filter leaves the set empty (that stays silent, as
+    today, so narrow-range queries gain no new stderr).
+    """
+    roots = _cctally()._codex_session_roots()
+    if not roots:
+        eprint("[codex] no Codex session directory found")
         return []
     start_ts = range_start.timestamp()
     result: list[pathlib.Path] = []
-    for jp in root.glob("**/*.jsonl"):
-        if not jp.is_file():
-            continue
+    for jp in _iter_codex_jsonl_paths(roots):
         try:
             mtime = jp.stat().st_mtime
         except OSError:
@@ -1190,6 +1217,9 @@ class CodexIngestStats:
     # ``IngestStats`` (Claude path) which carries an UPSERT and
     # therefore counts both new INSERTs and DO UPDATE replacements.
     rows_changed: int = 0
+    # Count of cached files dropped because they fall outside the CURRENT
+    # $CODEX_HOME root set (issue #108 — a prior-root purge, not a delta).
+    files_pruned: int = 0
     lock_contended: bool = False
 
 
@@ -1243,14 +1273,52 @@ def sync_codex_cache(
             conn.commit()
             eprint("[cache-sync] rebuild: cleared Codex cached entries")
 
-        root = _get_codex_sessions_dir()
-        paths: list[pathlib.Path] = []
-        if root is not None:
-            for jp in root.glob("**/*.jsonl"):
-                if jp.is_file():
-                    paths.append(jp)
+        roots = _cctally()._codex_session_roots()
+        # Pure read (glob + is_file only); safe to run before the SELECT and
+        # the per-file loop, where no cache.db write lock may be held.
+        paths: list[pathlib.Path] = list(_iter_codex_jsonl_paths(roots))
         stats.files_total = len(paths)
 
+        # Scope the cache to the CURRENT root set: drop rows ingested under a
+        # prior $CODEX_HOME (issue #108). iter_codex_entries() has NO root
+        # predicate — it reads every row in range — so without this, reusing
+        # the same cache.db across `CODEX_HOME=/A` then `CODEX_HOME=/B` runs
+        # returns A+B instead of just B. Prune every real (absolute) row
+        # outside the current set, even when that set is empty (an empty
+        # current root then prunes the cache to empty): the cache is fully
+        # re-derivable, so honoring the override beats retaining unreachable
+        # rows. Done INSIDE the lock and committed BEFORE the existing-SELECT
+        # + parse loop so no cache.db write lock is held across the read-heavy
+        # ingest (same invariant as the --rebuild clear above). Concurrent
+        # processes with different $CODEX_HOME would prune each other; the
+        # flock serializes them and that is a pathological configuration.
+        if not rebuild:  # --rebuild already cleared both tables above
+            current_paths = {str(p) for p in paths}
+            # Only prune ABSOLUTE source_paths. _codex_home_roots() makes
+            # every real root absolute (via .absolute()), so a real ingested
+            # row always stores an absolute str(jp) — INCLUDING a relative
+            # $CODEX_HOME like `./codexA`, which is canonicalized before the
+            # glob. A relative path here is therefore — by construction — a
+            # synthetic baked-cache fixture row (e.g. build-speed-fixtures.py)
+            # with no on-disk JSONL to scope against; pruning it would wipe a
+            # cache meant to be read as-is (issue #108).
+            orphan_paths = [
+                row[0]
+                for row in conn.execute("SELECT path FROM codex_session_files")
+                if row[0] not in current_paths and os.path.isabs(row[0])
+            ]
+            if orphan_paths:
+                conn.executemany(
+                    "DELETE FROM codex_session_entries WHERE source_path = ?",
+                    [(p,) for p in orphan_paths],
+                )
+                conn.executemany(
+                    "DELETE FROM codex_session_files WHERE path = ?",
+                    [(p,) for p in orphan_paths],
+                )
+                conn.commit()
+                stats.files_pruned = len(orphan_paths)
+
         # This SELECT does NOT open an implicit transaction (Python's
         # sqlite3 module only BEGINs on DML). Do NOT add any INSERT/
         # UPDATE/DELETE/REPLACE statement between here and the per-file

package/bin/_cctally_config.py

@@ -298,9 +298,71 @@ ALLOWED_CONFIG_KEYS = (
     "dashboard.bind",
     "update.check.enabled",
     "update.check.ttl_hours",
+    "statusline.visual_burn_rate",
+    "statusline.cost_source",
+    "statusline.cctally_extensions",
 )
 
 
+# === statusline config validators (issue #86 Session G) ===================
+
+_STATUSLINE_VBR_VALUES = ("off", "emoji", "text", "emoji-text")
+_STATUSLINE_COST_SOURCE_VALUES = ("auto", "cctally", "cc", "both")
+
+
+def _validate_statusline_visual_burn_rate(value):
+    """Validate ``statusline.visual_burn_rate``.
+
+    Accepts any of ``off`` / ``emoji`` / ``text`` / ``emoji-text``. Other
+    strings raise ``ValueError`` with a hint listing the valid values.
+    """
+    if isinstance(value, str) and value in _STATUSLINE_VBR_VALUES:
+        return value
+    raise ValueError(
+        f"statusline.visual_burn_rate must be one of "
+        f"{', '.join(_STATUSLINE_VBR_VALUES)} (got {value!r})"
+    )
+
+
+def _validate_statusline_cost_source(value):
+    """Validate ``statusline.cost_source``.
+
+    Accepts ``auto`` / ``cctally`` / ``cc`` / ``both``. The ``ccusage``
+    value name is rejected at config set time too — the rename hint
+    is surfaced both here AND at flag-parse time by the argparse choice
+    rejection inside ``cmd_statusline``.
+    """
+    if isinstance(value, str) and value in _STATUSLINE_COST_SOURCE_VALUES:
+        return value
+    if value == "ccusage":
+        raise ValueError(
+            "statusline.cost_source 'ccusage' was renamed; use 'cctally'"
+        )
+    raise ValueError(
+        f"statusline.cost_source must be one of "
+        f"{', '.join(_STATUSLINE_COST_SOURCE_VALUES)} (got {value!r})"
+    )
+
+
+def _validate_statusline_cctally_extensions(value):
+    """Validate ``statusline.cctally_extensions``.
+
+    Accepts booleans (preferred) or canonical truthy/falsy strings
+    (``true``/``false``/``yes``/``no``/``on``/``off``/``1``/``0``).
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lo = value.strip().lower()
+        if lo in ("true", "yes", "on", "1"):
+            return True
+        if lo in ("false", "no", "off", "0"):
+            return False
+    raise ValueError(
+        f"statusline.cctally_extensions must be boolean (got {value!r})"
+    )
+
+
 def cmd_config(args: argparse.Namespace) -> int:
     """Get/set/unset persisted user preferences in config.json.
 
@@ -374,6 +436,33 @@ def _config_known_value(config: dict, key: str) -> "object":
             return c._validate_update_check_ttl_hours_value(stored)
         except ValueError:
             return c.UPDATE_DEFAULT_TTL_HOURS
+    if key in (
+        "statusline.visual_burn_rate",
+        "statusline.cost_source",
+        "statusline.cctally_extensions",
+    ):
+        sl_block = config.get("statusline") if isinstance(config, dict) else None
+        if not isinstance(sl_block, dict):
+            sl_block = {}
+        inner = key.split(".", 1)[1]
+        stored = sl_block.get(inner)
+        defaults = {
+            "visual_burn_rate": "off",
+            "cost_source": "auto",
+            "cctally_extensions": True,
+        }
+        if stored is None:
+            return defaults[inner]
+        validator = {
+            "visual_burn_rate": _validate_statusline_visual_burn_rate,
+            "cost_source": _validate_statusline_cost_source,
+            "cctally_extensions": _validate_statusline_cctally_extensions,
+        }[inner]
+        try:
+            return validator(stored)
+        except ValueError:
+            # Hand-edited junk: surface the default — mirrors dashboard.bind.
+            return defaults[inner]
     return None
 
 
@@ -509,6 +598,44 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.bind={canonical}")
         return 0
+    if key in (
+        "statusline.visual_burn_rate",
+        "statusline.cost_source",
+        "statusline.cctally_extensions",
+    ):
+        inner_key = key.split(".", 1)[1]
+        validator = {
+            "visual_burn_rate": _validate_statusline_visual_burn_rate,
+            "cost_source": _validate_statusline_cost_source,
+            "cctally_extensions": _validate_statusline_cctally_extensions,
+        }[inner_key]
+        try:
+            normalized = validator(raw)
+        except ValueError as exc:
+            print(f"cctally: {exc}", file=sys.stderr)
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("statusline")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: statusline config error: statusline must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block[inner_key] = normalized
+            config["statusline"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"statusline": {inner_key: normalized}}, indent=2))
+        else:
+            if isinstance(normalized, bool):
+                rendered = "true" if normalized else "false"
+            else:
+                rendered = str(normalized)
+            print(f"{key}={rendered}")
+        return 0
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Validate first; rejection short-circuits before lock acquisition.
         if key == "update.check.enabled":
@@ -607,6 +734,22 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key in (
+        "statusline.visual_burn_rate",
+        "statusline.cost_source",
+        "statusline.cctally_extensions",
+    ):
+        inner_key = key.split(".", 1)[1]
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("statusline")
+            if isinstance(block, dict) and inner_key in block:
+                del block[inner_key]
+                if not block:
+                    config.pop("statusline", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Mirror the dashboard.bind branch: drop the leaf, then prune
         # empty `check` and empty `update` so config.json stays tidy.

package/bin/_lib_aggregators.py

@@ -375,6 +375,14 @@ class CodexSessionUsage:
     models: list[str]
     model_breakdowns: list[dict[str, Any]]
     last_activity: dt.datetime
+    # Issue #110: the matched $CODEX_HOME root in home-root form
+    # (e.g. "<root>/.codex", or "<root>" for a direct-JSONL root). Used ONLY
+    # to disambiguate the displayed / JSON label when two cross-root sessions
+    # share the same relative `session_id_path`. "" for the bare-relative
+    # fixture form (which cannot collide cross-root). Single-root data leaves
+    # every row's `codex_root` constant, so the renderers' collision check
+    # never fires and output stays byte-identical.
+    codex_root: str = ""
 
 
 @dataclass
@@ -531,24 +539,30 @@ def _aggregate_codex_weekly(
 def _session_path_parts(source_path: str) -> tuple[str, str, str]:
     """Return (session_id_path, session_file, directory) from a full path.
 
-    session_id_path = relative path under CODEX_SESSIONS_DIR with .jsonl
-                      stripped (e.g. "2025/12/25/rollout-...").
+    session_id_path = relative path under the matched $CODEX_HOME session
+                      root with .jsonl stripped (e.g. "2025/12/25/rollout-...").
     session_file    = basename without .jsonl extension.
-    directory       = relative parent path under CODEX_SESSIONS_DIR.
-
-    Accepts three input shapes:
-      1. Absolute path under CODEX_SESSIONS_DIR (the runtime sync path).
-      2. Bare-relative path starting with ".codex/sessions/..." — the form
-         emitted by build-codex-fixtures.py so committed fixture cache.db
-         files stay free of maintainer absolute paths (public-mirror safe).
-      3. Anything else — falls back to basename-only.
+    directory       = relative parent path under the matched root.
+
+    Tries each root in _codex_session_roots() order (the same list/order the
+    discovery walkers use, so overlapping/prefix roots resolve to the FIRST
+    matching root deterministically); first relative_to() that succeeds wins.
+    Falls back to the bare-relative ".codex/sessions/<rest>" fixture form (the
+    shape emitted by build-codex-fixtures.py so committed fixture cache.db
+    files stay free of maintainer absolute paths), then basename. Direct-JSONL
+    roots yield an id relative to <entry> itself (no sessions/ prefix).
     """
-    CODEX_SESSIONS_DIR = _cctally().CODEX_SESSIONS_DIR
+    roots = _cctally()._codex_session_roots()
     p = pathlib.Path(source_path)
-    try:
-        rel = p.relative_to(CODEX_SESSIONS_DIR)
-    except ValueError:
-        # Try bare-relative ".codex/sessions/<rest>" before basename fallback.
+    rel: pathlib.PurePath | None = None
+    for root in roots:
+        try:
+            rel = p.relative_to(root)
+            break
+        except ValueError:
+            continue
+    if rel is None:
+        # Bare-relative ".codex/sessions/<rest>" (fixture form), else basename.
         # Use PurePosixPath to avoid Windows-style drive parsing on unusual
         # inputs; fixture-emitted paths are always POSIX.
         parts = pathlib.PurePosixPath(source_path).parts
@@ -560,6 +574,22 @@ def _session_path_parts(source_path: str) -> tuple[str, str, str]:
     return str(stem), stem.name, str(stem.parent)
 
 
+def _codex_home_root_from_prefix(root_prefix: str) -> str:
+    """Normalize the aggregator's `root_prefix` to the matched $CODEX_HOME entry.
+
+    `root_prefix` is `source_path` with the relative `id_path` tail removed, so a
+    Codex-home match looks like "<root>/.codex/sessions/" and a direct-JSONL
+    match like "<root>/". Strip the trailing slash and any "/sessions" tail to
+    recover the home root the user configured — the unit the issue #110
+    disambiguator labels by. The bare-relative fixture prefix ".codex/sessions/"
+    normalizes to ".codex" (constant across fixtures, so it never collides).
+    """
+    s = root_prefix.rstrip("/")
+    if s.endswith("/sessions"):
+        s = s[: -len("/sessions")]
+    return s
+
+
 def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard") -> list[CodexSessionUsage]:
     """Group by session file path (upstream-compatible).
 
@@ -570,13 +600,31 @@ def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard"
     Per-model breakdowns include `isFallback: bool` — true when the model is
     absent from CODEX_MODEL_PRICING.
     """
-    by_session: dict[str, dict[str, Any]] = {}
+    by_session: dict[tuple[str, str], dict[str, Any]] = {}
     for entry in entries:
         id_path, file_name, directory = _session_path_parts(entry.source_path)
-        sess = by_session.setdefault(id_path, {
+        # Disambiguate identical relative paths under DIFFERENT $CODEX_HOME
+        # roots (issue #108). _session_path_parts strips the matched root, so
+        # <rootA>/sessions/2026/04/17/rollout-x.jsonl and the same relative
+        # path under <rootB> both yield id_path "2026/04/17/rollout-x";
+        # grouping on id_path alone would silently merge two distinct sessions
+        # (summed tokens, one UUID). Key on (root_prefix, id_path), where
+        # root_prefix is source_path with the id_path tail removed. Single-root
+        # data — and the bare-relative fixture form — has a constant prefix, so
+        # the grouping, insertion order, and every golden stay byte-identical;
+        # only a genuine cross-root collision splits into separate rows.
+        suffix = id_path + ".jsonl"
+        sp = entry.source_path
+        root_prefix = sp[: -len(suffix)] if sp.endswith(suffix) else sp
+        sess = by_session.setdefault((root_prefix, id_path), {
             "session_id_uuid": entry.session_id,
+            "session_id_path": id_path,
             "session_file": file_name,
             "directory": directory,
+            # Matched $CODEX_HOME root (home-root form) — issue #110 display
+            # disambiguator. Derived from the same root_prefix that keys the
+            # group, so it's constant per group.
+            "codex_root": _codex_home_root_from_prefix(root_prefix),
             "input": 0, "cached_input": 0, "output": 0, "reasoning": 0,
             "cost": 0.0, "models": {}, "models_order": [],
             "last": entry.timestamp,
@@ -606,7 +654,7 @@ def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard"
             sess["last"] = entry.timestamp
 
     result: list[CodexSessionUsage] = []
-    for id_path, s in by_session.items():
+    for _group_key, s in by_session.items():
         model_breakdowns = [
             {
                 "modelName": model,
@@ -623,7 +671,7 @@ def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard"
         model_breakdowns.sort(key=lambda m: m["cost"], reverse=True)
         result.append(CodexSessionUsage(
             session_id=s["session_id_uuid"],
-            session_id_path=id_path,
+            session_id_path=s["session_id_path"],
             session_file=s["session_file"],
             directory=s["directory"],
             input_tokens=s["input"],
@@ -641,6 +689,7 @@ def _aggregate_codex_sessions(entries: list[CodexEntry], speed: str = "standard"
             models=list(s["models_order"]),
             model_breakdowns=model_breakdowns,
             last_activity=s["last"],
+            codex_root=s["codex_root"],
         ))
     result.sort(key=lambda x: x.last_activity, reverse=True)
     return result

package/bin/_lib_blocks.py

@@ -36,6 +36,7 @@ import bisect
 import datetime as dt
 import json
 import pathlib
+import re
 import sys
 from dataclasses import dataclass
 from typing import Any
@@ -432,7 +433,42 @@ def _build_activity_block(
     )
 
 
-def _blocks_to_json(blocks: list[Block]) -> str:
+def _max_completed_block_tokens(blocks: list["Block"]) -> int:
+    """Largest total_tokens among completed (non-gap, non-active) blocks.
+
+    The auto-derived token-limit baseline for the `%`/REMAINING/PROJECTED
+    surface — matches ccusage's `maxTokensFromAll` (computed over all blocks
+    before any --recent/--active filtering). Returns 0 when there is no
+    completed block with tokens.
+    """
+    best = 0
+    for b in blocks:
+        if not b.is_gap and not b.is_active and b.total_tokens > best:
+            best = b.total_tokens
+    return best
+
+
+def _parse_blocks_token_limit(
+    raw: "str | None", max_from_completed: int
+) -> "int | None":
+    """Resolve the `-t/--token-limit` value to an int limit or None.
+
+    Mirrors ccusage `parseTokenLimit`: `None`/`""`/`"max"` → the auto-derived
+    `max_from_completed` (or None when it is 0); otherwise replicate JS
+    `Number.parseInt(raw, 10)` — leading optional sign + run of digits, stop at
+    the first non-digit (`"123abc"`→123, `"12.5"`→12, `"abc"`/`""`→None). A
+    non-positive result still returns the int; the caller's `limit > 0` gate
+    suppresses the `%` column (same observable result as upstream).
+    """
+    if raw is None or raw in ("", "max"):
+        return max_from_completed if max_from_completed > 0 else None
+    m = re.match(r"\s*([+-]?\d+)", raw)
+    return int(m.group(1)) if m else None
+
+
+def _blocks_to_json(
+    blocks: list[Block], *, token_limit_status_limit: int | None = None
+) -> str:
     """Serialize blocks to JSON matching upstream ccusage's output structure."""
 
     def _iso_utc(ts: dt.datetime) -> str:
@@ -470,6 +506,24 @@ def _blocks_to_json(blocks: list[Block]) -> str:
             "burnRate": block.burn_rate,
             "projection": block.projection,
         })
+        if (token_limit_status_limit is not None
+                and token_limit_status_limit > 0
+                and not block.is_gap
+                and block.is_active and block.projection):
+            limit = token_limit_status_limit
+            proj_tokens = block.projection["totalTokens"]
+            pct = (proj_tokens / limit) * 100.0
+            # Keep the exceeds/warning/ok thresholds (>100% / >80%) in sync with
+            # the box status ladder in _lib_render._render_active_block_box.
+            status = ("exceeds" if proj_tokens > limit
+                      else "warning" if proj_tokens > limit * 0.8
+                      else "ok")
+            obj["tokenLimitStatus"] = {
+                "limit": limit,
+                "projectedUsage": proj_tokens,
+                "percentUsed": pct,
+                "status": status,
+            }
         result.append(obj)
 
     return json.dumps({"blocks": result}, indent=2)

package/bin/_lib_doctor.py

@@ -530,7 +530,7 @@ def _check_data_codex_cache(s: DoctorState) -> CheckResult:
     if count == 0 and not s.codex_jsonl_present:
         return CheckResult(
             id="data.codex_cache", title="Codex cache",
-            severity="ok", summary="none (no ~/.codex/sessions/)",
+            severity="ok", summary="none (no Codex session JSONL found)",
             remediation=None,
             details={"entries": 0, "codex_jsonl_present": False},
         )