cctally 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -5,6 +5,11 @@ 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

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/_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},
         )

package/bin/_lib_render.py

@@ -225,6 +225,124 @@ def _scale_down_col_widths(
 # Optional dependency: zoneinfo.ZoneInfo is referenced only as a string
 # annotation in moved code; no runtime import needed.
 
+
+def _render_title_banner(title: str, *, unicode_ok: bool, color: bool) -> str:
+    """ccusage-style rounded title banner (the box around a report title).
+
+    Returns the multi-line banner WITHOUT a trailing blank line; callers add
+    spacing. Shared by `_render_blocks_table` and `_render_active_block_box`.
+    """
+    def _bold(s: str) -> str:
+        return _style_ansi(s, "1", color)
+    title_padded = f"  {title}  "
+    tw = len(title_padded)
+    dash = "─" if unicode_ok else "-"
+    vb = "│" if unicode_ok else "|"
+    if unicode_ok:
+        top = f" ╭{dash * tw}╮"
+        bot = f" ╰{dash * tw}╯"
+    else:
+        top = f" +{'-' * tw}+"
+        bot = f" +{'-' * tw}+"
+    return "\n".join([
+        top,
+        f" {vb}" + " " * tw + vb,
+        f" {vb}" + _bold(title_padded) + vb,
+        f" {vb}" + " " * tw + vb,
+        bot,
+    ])
+
+
+def _fmt_block_time_local(ts: dt.datetime, tz: "ZoneInfo | None") -> str:
+    """Block-start timestamp in display tz, ccusage `toLocaleString`-style."""
+    local = ts.astimezone(tz)
+    hour_12 = local.hour % 12 or 12
+    ampm = "a.m." if local.hour < 12 else "p.m."
+    return (
+        f"{local.year}-{local.month:02d}-{local.day:02d}, "
+        f"{hour_12}:{local.minute:02d}:{local.second:02d} {ampm}"
+    )
+
+
+def _fmt_block_duration_hm(total_seconds: float) -> str:
+    total_minutes = int(total_seconds / 60)
+    return f"{total_minutes // 60}h {total_minutes % 60:02d}m"
+
+
+def _render_active_block_box(
+    block: "Block",
+    *,
+    now: dt.datetime,
+    tz: "ZoneInfo | None",
+    token_limit_explicit: int | None,
+    color: bool,
+    unicode_ok: bool,
+) -> str:
+    """ccusage `-a` 'Current Session Block Status' box (#86 Session F).
+
+    Token Limit Status sub-block appears only when `-t` was explicitly passed
+    (`token_limit_explicit` not None and > 0). Heuristic-anchored active blocks
+    get a `~`-prefixed start + approximate-start legend (Codex F2).
+    """
+    def _b(s: str) -> str:
+        return _style_ansi(s, "1", color)
+
+    lines: list[str] = [
+        _render_title_banner("Current Session Block Status",
+                             unicode_ok=unicode_ok, color=color),
+    ]
+    started = _fmt_block_time_local(block.start_time, tz)
+    approx = block.anchor == "heuristic"
+    if approx:
+        started = f"~{started}"
+    elapsed = max((now - block.start_time).total_seconds(), 0)
+    remaining = max((block.end_time - now).total_seconds(), 0)
+    lines.append(f"Block Started: {started} "
+                 f"({_fmt_block_duration_hm(elapsed)} ago)")
+    lines.append(f"Time Remaining: {_fmt_block_duration_hm(remaining)}")
+    if approx:
+        # Keep this wording in sync with the table footer legend below.
+        lines.append("~ = approximate start "
+                     "(no recorded Anthropic reset for this window)")
+
+    lines += ["", _b("Current Usage:"),
+              f"  Input Tokens:     {_fmt_num(block.input_tokens)}",
+              f"  Output Tokens:    {_fmt_num(block.output_tokens)}",
+              f"  Total Cost:       ${block.cost_usd:.2f}"]
+
+    if block.burn_rate:
+        lines += ["", _b("Burn Rate:"),
+                  f"  Tokens/minute:    "
+                  f"{_fmt_num(int(block.burn_rate['tokensPerMinute']))}",
+                  f"  Cost/hour:        ${block.burn_rate['costPerHour']:.2f}"]
+
+    if block.projection:
+        proj = block.projection
+        lines += ["", _b("Projected Usage (if current rate continues):"),
+                  f"  Total Tokens:     {_fmt_num(proj['totalTokens'])}",
+                  f"  Total Cost:       ${proj['totalCost']:.2f}"]
+        if token_limit_explicit is not None and token_limit_explicit > 0:
+            limit = token_limit_explicit
+            current = block.total_tokens
+            remaining_tokens = max(limit - current, 0)
+            pct_used = (proj["totalTokens"] / limit) * 100.0
+            cur_pct = (current / limit) * 100.0
+            # Keep the EXCEEDS/WARNING/OK thresholds (>100 / >80) in sync with
+            # the JSON status ladder in _lib_blocks._blocks_to_json.
+            if pct_used > 100:
+                status = _style_ansi("EXCEEDS LIMIT", "31", color)
+            elif pct_used > 80:
+                status = _style_ansi("WARNING", "33", color)
+            else:
+                status = _style_ansi("OK", "32", color)
+            lines += ["", _b("Token Limit Status:"),
+                      f"  Limit:            {_fmt_num(limit)} tokens",
+                      f"  Current Usage:    {_fmt_num(current)} ({cur_pct:.1f}%)",
+                      f"  Remaining:        {_fmt_num(remaining_tokens)} tokens",
+                      f"  Projected Usage:  {pct_used:.1f}% {status}"]
+    return "\n".join(lines)
+
+
 def _render_blocks_table(
     blocks: list[Block],
     breakdown: bool = False,
@@ -232,6 +350,7 @@ def _render_blocks_table(
     now: dt.datetime | None = None,
     tz: "ZoneInfo | None" = None,
     compact: bool = False,
+    token_limit: int | None = None,
 ) -> str:
     """Render blocks as a ccusage-style ANSI table with box-drawing borders.
 
@@ -268,9 +387,6 @@ def _render_blocks_table(
     def _cyan(s: str) -> str:
         return _style_ansi(s, "36", color)
 
-    def _bold(s: str) -> str:
-        return _style_ansi(s, "1", color)
-
     def _green(s: str) -> str:
         return _style_ansi(s, "32", color)
 
@@ -283,21 +399,10 @@ def _render_blocks_table(
     # ── time formatting ─────────────────────────────────────────────────
 
     def _fmt_time_local(ts: dt.datetime) -> str:
-        local = ts.astimezone(tz)
-        hour_12 = local.hour % 12
-        if hour_12 == 0:
-            hour_12 = 12
-        ampm = "a.m." if local.hour < 12 else "p.m."
-        return (
-            f"{local.year}-{local.month:02d}-{local.day:02d}, "
-            f"{hour_12}:{local.minute:02d}:{local.second:02d} {ampm}"
-        )
+        return _fmt_block_time_local(ts, tz)
 
     def _fmt_duration_hm(total_seconds: float) -> str:
-        total_minutes = int(total_seconds / 60)
-        h = total_minutes // 60
-        m = total_minutes % 60
-        return f"{h}h {m:02d}m"
+        return _fmt_block_duration_hm(total_seconds)
 
     def _fmt_gap_duration(total_seconds: float) -> str:
         total_minutes = int(total_seconds / 60)
@@ -307,19 +412,23 @@ def _render_blocks_table(
         return f"{h}h {m:02d}m gap" if m else f"{h}h gap"
 
     # ── determine if % column is needed ─────────────────────────────────
-    max_completed_tokens = 0
-    for b in blocks:
-        if not b.is_gap and not b.is_active and b.total_tokens > 0:
-            if b.total_tokens > max_completed_tokens:
-                max_completed_tokens = b.total_tokens
-    token_limit = 0
+    max_completed_tokens = _lib_blocks._max_completed_block_tokens(blocks)
     active_block: Block | None = None
     for b in blocks:
         if b.is_active and not b.is_gap:
             active_block = b
-    show_pct = max_completed_tokens > 0
-    if show_pct:
-        token_limit = max_completed_tokens
+    # ``token_limit`` param (#86 Session F): when caller passes an explicit
+    # limit, honor it directly (forces the %/REMAINING/PROJECTED surface even
+    # with no completed history, suppressed only when <= 0). When None, fall
+    # back to the internal auto-max recompute so the renderer stays
+    # standalone-callable and the default ``cmd_blocks`` path (which passes the
+    # resolved auto-max) is byte-identical.
+    if token_limit is not None:
+        show_pct = token_limit > 0
+        eff_limit = token_limit if token_limit > 0 else 0
+    else:
+        show_pct = max_completed_tokens > 0
+        eff_limit = max_completed_tokens if show_pct else 0
 
     # ── column layout ───────────────────────────────────────────────────
     headers = ["Block Start", "Duration/\u2026", "Models", "Tokens"]
@@ -405,8 +514,8 @@ def _render_blocks_table(
                 short_models = [""]
 
             pct_str = ""
-            if show_pct and token_limit > 0:
-                pct_val = (block.total_tokens / token_limit) * 100.0
+            if show_pct and eff_limit > 0:
+                pct_val = (block.total_tokens / eff_limit) * 100.0
                 pct_str = f"{pct_val:.1f}%"
 
             tokens_str = _fmt_num(block.total_tokens)
@@ -436,11 +545,11 @@ def _render_blocks_table(
 
     # Footer rows (REMAINING, PROJECTED)
     footer_rows: list[tuple[list[list[str]], str]] = []
-    if show_pct and token_limit > 0:
+    if show_pct and eff_limit > 0:
         active_tokens = active_block.total_tokens if active_block else 0
-        remaining_tokens = max(token_limit - active_tokens, 0)
-        remaining_pct = (remaining_tokens / token_limit) * 100.0
-        rem_label = f"(assuming {_fmt_num(token_limit)} token limit)"
+        remaining_tokens = max(eff_limit - active_tokens, 0)
+        remaining_pct = (remaining_tokens / eff_limit) * 100.0
+        rem_label = f"(assuming {_fmt_num(eff_limit)} token limit)"
 
         rem_cells = _empty_cells()
         rem_cells[0] = rem_label
@@ -456,7 +565,7 @@ def _render_blocks_table(
             proj = active_block.projection
             proj_tokens = proj.get("totalTokens", 0)
             proj_pct = (
-                (proj_tokens / token_limit) * 100.0 if token_limit > 0 else 0
+                (proj_tokens / eff_limit) * 100.0 if eff_limit > 0 else 0
             )
             proj_cost = proj.get("totalCost", 0.0)
 
@@ -600,23 +709,8 @@ def _render_blocks_table(
 
     # Title banner
     title = "Claude Code Token Usage Report - Session Blocks"
-    title_padded = f"  {title}  "
-    tw = len(title_padded)
-    dash = "\u2500" if unicode_ok else "-"
-    vb = "\u2502" if unicode_ok else "|"
-    if unicode_ok:
-        banner_top = f" \u256d{dash * tw}\u256e"
-        banner_bot = f" \u2570{dash * tw}\u256f"
-    else:
-        banner_top = f" +{'-' * tw}+"
-        banner_bot = f" +{'-' * tw}+"
-
     lines: list[str] = []
-    lines.append(banner_top)
-    lines.append(f" {vb}" + " " * tw + vb)
-    lines.append(f" {vb}" + _bold(title_padded) + vb)
-    lines.append(f" {vb}" + " " * tw + vb)
-    lines.append(banner_bot)
+    lines.append(_render_title_banner(title, unicode_ok=unicode_ok, color=color))
     lines.append("")
 
     # Header
@@ -979,6 +1073,57 @@ def _codex_bucket_to_json(
     return json.dumps({list_key: bucket_list, "totals": totals}, indent=2)
 
 
+def _codex_root_short_labels(roots: list[str]) -> list[str]:
+    """Given >=2 distinct root paths, return a short distinguishing label per
+    root: the first path segment after their longest common ancestor — e.g.
+    {".../rootA/.codex", ".../rootB/.codex"} -> ["rootA", "rootB"]. If a single
+    segment isn't unique, fall back to the full post-ancestor tail, then to the
+    whole path, so the returned labels are always pairwise distinct.
+
+    Order-preserving: labels[i] corresponds to roots[i].
+    """
+    parts = [pathlib.PurePosixPath(r).parts for r in roots]
+    common = 0
+    for seg in zip(*parts):
+        if len(set(seg)) == 1:
+            common += 1
+        else:
+            break
+    singles = [pr[common] if common < len(pr) else (pr[-1] if pr else "")
+               for pr in parts]
+    if len(set(singles)) == len(singles):
+        return singles
+    tails = ["/".join(pr[common:]) or (pr[-1] if pr else "") for pr in parts]
+    if len(set(tails)) == len(tails):
+        return tails
+    return list(roots)
+
+
+def _codex_session_disambiguate(sessions: list[CodexSessionUsage]) -> dict[int, str]:
+    """Return ``{row_index: " (label)"}`` for codex-session rows whose
+    ``session_id_path`` collides with another row's — a genuine
+    cross-$CODEX_HOME-root collision (issue #110). Non-colliding rows are absent
+    from the dict; callers render them byte-identically (single-root data never
+    collides, so this returns ``{}`` and output is unchanged).
+
+    ``label`` is a short distinguishing segment of the matched $CODEX_HOME root
+    (see ``_codex_root_short_labels``). Mirrors ``_project_disambiguate_labels``.
+    """
+    path_counts: dict[str, int] = {}
+    for s in sessions:
+        path_counts[s.session_id_path] = path_counts.get(s.session_id_path, 0) + 1
+    groups: dict[str, list[int]] = {}
+    for idx, s in enumerate(sessions):
+        if path_counts[s.session_id_path] > 1:
+            groups.setdefault(s.session_id_path, []).append(idx)
+    out: dict[int, str] = {}
+    for idxs in groups.values():
+        labels = _codex_root_short_labels([sessions[i].codex_root for i in idxs])
+        for i, label in zip(idxs, labels):
+            out[i] = f" ({label})"
+    return out
+
+
 def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
     """Serialize Codex session aggregates to JSON matching upstream exactly.
 
@@ -990,9 +1135,13 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
     session_list: list[dict[str, Any]] = []
     tot_input = tot_cached = tot_output = tot_reasoning = tot_tokens = 0
     tot_cost = 0.0
-    for s in sessions:
+    # Issue #110: only when two cross-root sessions share `sessionId` (the
+    # relative path) does this map a colliding row to a label; otherwise empty,
+    # so the per-session shape stays upstream-byte-identical (no `codexRoot`).
+    disambig = _codex_session_disambiguate(sessions)
+    for idx, s in enumerate(sessions):
         session_total = s.input_tokens + s.output_tokens
-        session_list.append({
+        entry = {
             "sessionId": s.session_id_path,
             "lastActivity": _codex_last_activity_iso(s.last_activity),
             "sessionFile": s.session_file,
@@ -1004,7 +1153,13 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
             "totalTokens": session_total,
             "costUSD": s.cost_usd,
             "models": _codex_models_dict(s.model_breakdowns),
-        })
+        }
+        if idx in disambig:
+            # Additive disambiguator — `sessionId` keeps its upstream-compatible
+            # relative-path value; consumers key off `codexRoot` to tell the
+            # (correctly separate) colliding rows apart.
+            entry["codexRoot"] = s.codex_root
+        session_list.append(entry)
         tot_input += s.input_tokens
         tot_cached += s.cached_input_tokens
         tot_output += s.output_tokens
@@ -2095,14 +2250,18 @@ def _render_codex_session_table(
     ROW_DATA, ROW_FOOTER = "data", "footer"
     raw_rows: list[tuple[list[tuple[str, Any]], str]] = []
 
-    for s in sessions:
+    # Issue #110: suffix the Session cell with the matched $CODEX_HOME root
+    # ONLY for cross-root collisions (two rows sharing session_id_path); empty
+    # for single-root data, so the table stays byte-identical.
+    disambig = _codex_session_disambiguate(sessions)
+    for idx, s in enumerate(sessions):
         models_text = "\n".join(f"- {m}" for m in s.models) if s.models else ""
         non_cached = max(0, s.input_tokens - s.cached_input_tokens)
         session_total = s.input_tokens + s.output_tokens
         data_cells = [
             (_date_cell(s.last_activity), None),
             (s.directory, None),
-            (_session_cell(s.session_id), None),
+            (_session_cell(s.session_id) + disambig.get(idx, ""), None),
             (models_text, None),
             (_fmt_num(non_cached), None),
             (_fmt_num(s.output_tokens), None),

package/bin/cctally

@@ -349,6 +349,8 @@ _group_entries_into_blocks = _lib_blocks._group_entries_into_blocks
 _aggregate_block = _lib_blocks._aggregate_block
 _build_activity_block = _lib_blocks._build_activity_block
 _blocks_to_json = _lib_blocks._blocks_to_json
+_max_completed_block_tokens = _lib_blocks._max_completed_block_tokens
+_parse_blocks_token_limit = _lib_blocks._parse_blocks_token_limit
 
 _lib_changelog = _load_sibling("_lib_changelog")
 # Backward-compat re-export: callers and tests reach the helper through
@@ -409,6 +411,7 @@ build_codex_session_view = _lib_view_models.build_codex_session_view
 _lib_render = _load_sibling("_lib_render")
 _CODEX_MONTHS = _lib_render._CODEX_MONTHS
 _render_blocks_table = _lib_render._render_blocks_table
+_render_active_block_box = _lib_render._render_active_block_box
 _daily_row_dict = _lib_render._daily_row_dict
 _bucket_totals_dict = _lib_render._bucket_totals_dict
 _bucket_to_json = _lib_render._bucket_to_json
@@ -618,7 +621,6 @@ cmd_db_unskip = _cctally_db.cmd_db_unskip
 _cctally_cache = _load_sibling("_cctally_cache")
 ProjectKey = _cctally_cache.ProjectKey
 _resolve_project_key = _cctally_cache._resolve_project_key
-_get_codex_sessions_dir = _cctally_cache._get_codex_sessions_dir
 _discover_codex_session_files = _cctally_cache._discover_codex_session_files
 IngestStats = _cctally_cache.IngestStats
 _progress_stderr = _cctally_cache._progress_stderr
@@ -875,6 +877,84 @@ LEGACY_STATUSLINE_NEEDLE = "cctally record-usage"
 
 CODEX_SESSIONS_DIR = pathlib.Path.home() / ".codex" / "sessions"
 
+
+def _codex_home_roots() -> list[pathlib.Path]:
+    """ALL raw $CODEX_HOME entries (comma-split), else [~/.codex].
+
+    These are the entries upstream calls "CODEX_HOME roots" — the full
+    comma-split list, BEFORE the sessions/-subdir rule decides home-vs-direct.
+    The config reader (_detect_codex_fast_service_tier) reads <entry>/config.toml
+    for EVERY entry returned here, including ones that turn out to be direct
+    JSONL dirs; only _codex_session_roots() applies the sessions/-subdir
+    narrowing. Blank/whitespace entries are dropped; each is expanduser'd
+    (literal '~'; the shell already expands $VAR before we see the value)
+    then made ABSOLUTE via .absolute() — a relative $CODEX_HOME (e.g.
+    `./codexA`) would otherwise glob and store relative source_paths, which
+    the cache-prune step cannot distinguish from synthetic relative-path
+    fixture rows (issue #108; see the prune guard in _cctally_cache.py).
+    Canonicalizing here makes every REAL ingested source_path absolute, so
+    the prune's `isabs` fixture carve-out is correct by construction.
+    Order is preserved (first-match-wins downstream).
+    """
+    raw = os.environ.get("CODEX_HOME", "").strip()
+    if not raw:
+        return [pathlib.Path.home() / ".codex"]
+    roots: list[pathlib.Path] = []
+    saw_part = False
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        saw_part = True
+        try:
+            # expanduser() raises RuntimeError on a malformed `~user` entry
+            # (e.g. `~nonexistentuser/x` — the user doesn't exist). Drop the
+            # bad entry rather than aborting the whole command, so valid
+            # roots beside it survive. .absolute() canonicalizes a relative
+            # entry (e.g. `./codexA`) against cwd so real ingested source_paths
+            # are always absolute (issue #108 — keeps the cache-prune correct).
+            roots.append(pathlib.Path(part).expanduser().absolute())
+        except (RuntimeError, OSError, ValueError):
+            continue
+    # Fall back to the default home ONLY when the variable is unset or carries
+    # no non-blank entry at all. An explicit-but-all-invalid value (e.g. a lone
+    # `~baduser` that expanduser() drops) yields [] — respect the override and
+    # read nothing rather than silently reading the default account (issue
+    # #108). A plain dead path like `/typo` already reaches [] via the is_dir()
+    # filter in _codex_session_roots(); this aligns the `~user` flavor with it.
+    if not saw_part:
+        return [pathlib.Path.home() / ".codex"]
+    return roots
+
+
+def _codex_session_roots() -> list[pathlib.Path]:
+    """Directories to walk for *.jsonl, applying the sessions/-subdir rule.
+
+    For each home root r (in $CODEX_HOME order):
+      (r / "sessions").is_dir()  -> r / "sessions"   (Codex home)
+      elif r.is_dir()            -> r                 (direct JSONL dir)
+      else                       -> skipped
+    Exact-duplicate roots are de-duped (first occurrence kept). File-level
+    de-dup for overlapping/prefix roots happens in the discovery walkers
+    (set of absolute paths); this function only collapses identical roots.
+    """
+    out: list[pathlib.Path] = []
+    seen: set[pathlib.Path] = set()
+    for r in _codex_home_roots():
+        sess = r / "sessions"
+        if sess.is_dir():
+            cand = sess
+        elif r.is_dir():
+            cand = r
+        else:
+            continue
+        if cand in seen:
+            continue
+        seen.add(cand)
+        out.append(cand)
+    return out
+
+
 # Note: `_cctally_db` reads its four path constants
 # (`LOG_DIR`/`MIGRATION_ERROR_LOG_PATH`/`DB_PATH`/`CACHE_DB_PATH`) via
 # `_cctally_core.X` at call time — the canonical sibling pattern after
@@ -4223,6 +4303,15 @@ def _load_recorded_five_hour_windows(
 
 def cmd_blocks(args: argparse.Namespace) -> int:
     """Show usage report grouped by 5-hour session blocks."""
+    # -n/--session-length guard (#86 Session F). The flag is a documented
+    # no-op (cctally blocks anchor to Anthropic's real 5h resets and are not
+    # re-sizable), but a non-positive value still errors for drop-in fidelity
+    # with ccusage's "Session length must be a positive number". Runs first,
+    # before any data load — matches ccusage's command-flow ordering.
+    if getattr(args, "session_length", 5.0) <= 0:
+        eprint("blocks: session length must be a positive number")
+        return 1
+
     config = _load_claude_config_for_args(args)
     _bridge_z_into_tz(args, config)
     tz = resolve_display_tz(args, config)
@@ -4322,16 +4411,60 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     # 20:50→01:50 with $45 cost vs the real $128).
     _maybe_swap_active_block_to_canonical(blocks, all_entries, now=now_utc, mode=args.mode)
 
+    # ── Session F (#86): resolve token limit, then filter ────────────────
+    # Auto-max baseline over ALL blocks (before --recent/--active filtering),
+    # matching ccusage's maxTokensFromAll.
+    max_completed = _max_completed_block_tokens(blocks)
+    token_limit = _parse_blocks_token_limit(
+        getattr(args, "token_limit", None), max_completed
+    )
+    # ``token_limit_explicit`` is the resolved limit ONLY when -t was passed
+    # (any value incl. "max"); the implicit default leaves it None so the
+    # box's Token Limit Status sub-block + the JSON tokenLimitStatus key are
+    # omitted (ccusage `if (tokenLimit != null)` gate).
+    token_limit_explicit = (
+        token_limit if getattr(args, "token_limit", None) is not None else None
+    )
+    auto_max = getattr(args, "token_limit", None) in (None, "", "max")
+    if auto_max and token_limit and not args.json:
+        # ccusage parity: logger.info → stdout (Codex F1). Suppressed under
+        # --json (ccusage sets logger.level=0), so --json goldens stay stable.
+        print(f"Using max tokens from previous sessions: {_fmt_num(token_limit)}")
+
+    if getattr(args, "recent", False):
+        cutoff = now_utc - dt.timedelta(days=3)
+        blocks = [b for b in blocks if b.start_time >= cutoff or b.is_active]
+
+    if getattr(args, "active", False):
+        blocks = [b for b in blocks if b.is_active and not b.is_gap]
+        if not blocks:
+            if args.json:
+                print('{\n  "blocks": [],\n  "message": "No active block"\n}')
+            else:
+                print("No active session block found.")
+            return 0
+
     if args.json:
-        print(_blocks_to_json(blocks))
+        print(_blocks_to_json(blocks, token_limit_status_limit=token_limit_explicit))
+        return 0
+
+    if getattr(args, "active", False) and len(blocks) == 1:
+        print(_render_active_block_box(
+            blocks[0], now=now_utc, tz=tz,
+            token_limit_explicit=token_limit_explicit,
+            color=_supports_color_stdout(), unicode_ok=_supports_unicode_stdout(),
+        ))
         return 0
 
     # Table output. Session A (spec §7.6.1; Review-A P2-B): thread
     # --compact through so the renderer's scale-down branch fires
-    # regardless of terminal width when the flag is set.
+    # regardless of terminal width when the flag is set. Session F: thread
+    # the resolved token_limit so an explicit -t keys the %/REMAINING/
+    # PROJECTED surface (the default path passes the same auto-max the
+    # renderer computed internally, so it stays byte-identical).
     print(_render_blocks_table(
         blocks, breakdown=args.breakdown, now=now_utc, tz=tz,
-        compact=getattr(args, "compact", False),
+        compact=getattr(args, "compact", False), token_limit=token_limit,
     ))
     return 0
 
@@ -4971,25 +5104,32 @@ def cmd_weekly(args: argparse.Namespace) -> int:
 
 
 def _detect_codex_fast_service_tier() -> bool:
-    """True iff ``~/.codex/config.toml`` requests the fast/priority tier.
-
-    Reads from ``~/.codex`` only (single root; ``$CODEX_HOME`` multi-root is
-    deferred — see #108). Tolerates an absent/unreadable config (→ False →
-    standard tier).
+    """True iff any $CODEX_HOME root's config.toml requests fast/priority tier.
+
+    Reads <root>/config.toml for EVERY entry in _codex_home_roots() (comma-
+    separated $CODEX_HOME, else ~/.codex) — including direct-JSONL entries,
+    which usually have no config.toml (read → absent → skipped) but DO count
+    if one is present. Returns on the first root that requests it (any-root
+    semantics, matching upstream ccusage). Tolerates absent/unreadable config
+    (→ that root contributes nothing).
     """
-    cfg = pathlib.Path.home() / ".codex" / "config.toml"
-    try:
-        content = cfg.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return False
-    return _codex_config_requests_fast_service_tier(content)
+    for root in _codex_home_roots():
+        cfg = root / "config.toml"
+        try:
+            content = cfg.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if _codex_config_requests_fast_service_tier(content):
+            return True
+    return False
 
 
 def _resolve_codex_speed(requested: str) -> str:
     """Resolve a ``--speed`` value to an effective tier.
 
-    ``auto`` → ``fast`` iff ``~/.codex/config.toml`` requests it, else
-    ``standard``. ``fast``/``standard`` pass through unchanged.
+    ``auto`` → ``fast`` iff any ``$CODEX_HOME`` root's ``config.toml``
+    requests it, else ``standard``. ``fast``/``standard`` pass through
+    unchanged.
     """
     if requested == "auto":
         return "fast" if _detect_codex_fast_service_tier() else "standard"
@@ -9830,11 +9970,16 @@ def doctor_gather_state(
     except Exception:
         pass
 
+    # Issue #109: probe every $CODEX_HOME session root (not the single
+    # hardcoded ~/.codex/sessions), matching the multi-root ingestion path
+    # from #108. _codex_session_roots() already applies the sessions/-subdir
+    # rule and filters to existing dirs, so a bare glob per root suffices.
     codex_jsonl_present = False
     try:
-        codex_dir = pathlib.Path.home() / ".codex" / "sessions"
-        if codex_dir.exists():
-            codex_jsonl_present = next(codex_dir.glob("**/*.jsonl"), None) is not None
+        for codex_dir in _codex_session_roots():
+            if next(codex_dir.glob("**/*.jsonl"), None) is not None:
+                codex_jsonl_present = True
+                break
     except Exception:
         pass
 
@@ -10601,6 +10746,29 @@ def _build_blocks_parser(subparsers, name, *, help_text, xref):
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    p.add_argument(
+        "-a", "--active", action="store_true",
+        help="Show only the active block, with burn-rate + projection "
+             "(ccusage drop-in).",
+    )
+    p.add_argument(
+        "-r", "--recent", action="store_true",
+        help="Show only blocks from the last 3 days (plus the active block).",
+    )
+    p.add_argument(
+        "-t", "--token-limit", dest="token_limit", default=None,
+        metavar="N|max",
+        help="Token limit for the quota %% column / projection warnings. "
+             "An integer, or 'max' (default) to derive from the largest "
+             "completed block.",
+    )
+    p.add_argument(
+        "-n", "--session-length", dest="session_length", type=float,
+        default=5.0, metavar="N",
+        help="Accepted for ccusage drop-in compat; no-op — cctally blocks "
+             "follow Anthropic's real 5-hour resets and are not re-sizable. "
+             "A value <= 0 is rejected.",
+    )
     _add_ccusage_alias_args(p, ansi_emit=False)
     _add_mode_arg(p)
     p.set_defaults(func=cmd_blocks)

package/package.json

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