cctally 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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
+- **Project-axis flags on `cctally daily` (and `cctally claude daily`): `-i/--instances`, `-p/--project`, and `--project-aliases`** — a drop-in for `ccusage daily`. `-i/--instances` groups the daily report by project (git-root), rendering a `Project: <label>` section per project with one global Total (`--json` becomes `{projects: {...}, totals}`); `-p/--project PATTERN` filters to matching projects by case-insensitive substring of the project label or path, and is repeatable with OR semantics; `--project-aliases key=Label,...` overrides project display labels (table headers only — never the JSON keys). Two distinct git-roots that share a basename stay separate (`app (work)` / `app (personal)`), null-project entries collect under `(unknown)`, and under `--format` shareable output `-i` is a no-op while `-p` is honored (the filter survives into the artifact). (#86)
+
 ## [1.17.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:
@@ -937,6 +964,13 @@ class _JoinedClaudeEntry:
     # reconciles with daily/range-cost paths that already pass
     # `entry.cost_usd` into `_calculate_entry_cost`.
     cost_usd: float | None = None
+    # Non-token `usage` extras (parsed `usage_extra_json`) — notably
+    # `speed`, which `_aggregate_buckets` reads to render `<model>-fast`.
+    # `iter_entries` merges these into its `UsageEntry.usage`; the joined
+    # path must carry them too so `_usage_entry_from_joined` can restore
+    # them (else `daily -i`/`-p` lose fast-tier model labels). None when
+    # the row has no extras.
+    usage_extra: dict | None = None
 
 
 def get_claude_session_entries(
@@ -996,7 +1030,7 @@ def get_claude_session_entries(
         "  se.cache_create_tokens, se.cache_read_tokens, "
         "  se.source_path, "
         "  sf.session_id, sf.project_path, "
-        "  se.cost_usd_raw "
+        "  se.cost_usd_raw, se.usage_extra_json "
         "FROM session_entries se "
         "LEFT JOIN session_files sf ON sf.path = se.source_path "
         "WHERE se.timestamp_utc >= ? AND se.timestamp_utc <= ?"
@@ -1024,6 +1058,7 @@ def get_claude_session_entries(
             session_id=row[7],
             project_path=row[8],
             cost_usd=row[9],
+            usage_extra=(json.loads(row[10]) if row[10] else None),
         )
         for row in rows
     ]
@@ -1135,9 +1170,16 @@ def _direct_parse_claude_session_entries(
     results: list[_JoinedClaudeEntry] = []
     flat: list[tuple[UsageEntry, str]] = list(dedupe_map.values()) + no_key_with_meta
     flat.sort(key=lambda pair: pair[0].timestamp)
+    _token_keys = {
+        "input_tokens", "output_tokens",
+        "cache_creation_input_tokens", "cache_read_input_tokens",
+    }
     for entry, source_path in flat:
         usage = entry.usage
         sid, cwd = meta_by_path[source_path]
+        # Mirror the cache-backed path: carry non-token `usage` extras
+        # (e.g. `speed`) so `_usage_entry_from_joined` can restore them.
+        extras = {k: v for k, v in usage.items() if k not in _token_keys}
         results.append(_JoinedClaudeEntry(
             timestamp=entry.timestamp,
             model=entry.model,
@@ -1153,6 +1195,7 @@ def _direct_parse_claude_session_entries(
             session_id=sid,
             project_path=cwd,
             cost_usd=entry.cost_usd,
+            usage_extra=(extras or None),
         ))
 
     return results
@@ -1174,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
 
 
@@ -1227,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/_lib_aggregators.py

@@ -232,6 +232,41 @@ def _aggregate_monthly(
     )
 
 
+def _aggregate_daily_by_project(
+    keyed_entries: list[tuple[Any, UsageEntry]],
+    *,
+    tz: "Any | None" = None,
+    mode: str = "auto",
+) -> list[tuple[Any, list[BucketUsage]]]:
+    """Group ``(project_key, UsageEntry)`` pairs into per-project daily buckets.
+
+    Returns ``[(project_key, [BucketUsage date-asc]), ...]`` ordered by each
+    project's total cost descending, ties broken by ``project_key.display_key``
+    ascending. ``project_key`` is opaque/hashable (a ``ProjectKey``); resolution
+    happened in the caller, so this stays pure (no filesystem).
+
+    Reuses ``_aggregate_daily`` per group, so per-model breakdowns, token sums,
+    and ``mode``/``cost_usd`` threading are identical to the non-instances path.
+    """
+    grouped: dict[Any, list[UsageEntry]] = {}
+    order: list[Any] = []
+    for key, entry in keyed_entries:
+        bucket = grouped.get(key)
+        if bucket is None:
+            grouped[key] = bucket = []
+            order.append(key)
+        bucket.append(entry)
+
+    ranked: list[tuple[Any, list[BucketUsage], float]] = []
+    for key in order:
+        buckets = _aggregate_daily(grouped[key], mode=mode, tz=tz)  # date-asc
+        total = sum(b.cost_usd for b in buckets)
+        ranked.append((key, buckets, total))
+
+    ranked.sort(key=lambda t: (-t[2], t[0].display_key))
+    return [(key, buckets) for key, buckets, _ in ranked]
+
+
 def _aggregate_weekly(
     entries: list[UsageEntry],
     weeks: list[SubWeek],
@@ -340,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
@@ -496,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
@@ -525,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).
 
@@ -535,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,
@@ -571,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,
@@ -588,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"],
@@ -606,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},
         )