cctally 1.17.0 → 1.19.0

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
@@ -368,6 +370,7 @@ CodexSessionUsage = _lib_aggregators.CodexSessionUsage
 ClaudeSessionUsage = _lib_aggregators.ClaudeSessionUsage
 _aggregate_buckets = _lib_aggregators._aggregate_buckets
 _aggregate_daily = _lib_aggregators._aggregate_daily
+_aggregate_daily_by_project = _lib_aggregators._aggregate_daily_by_project
 _aggregate_monthly = _lib_aggregators._aggregate_monthly
 _aggregate_weekly = _lib_aggregators._aggregate_weekly
 _aggregate_codex_buckets = _lib_aggregators._aggregate_codex_buckets
@@ -408,7 +411,11 @@ 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
+_bucket_by_project_to_json = _lib_render._bucket_by_project_to_json
 _weekly_to_json = _lib_render._weekly_to_json
 _daily_compact_split = _lib_render._daily_compact_split
 _monthly_compact_split = _lib_render._monthly_compact_split
@@ -614,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
@@ -871,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
@@ -1538,16 +1622,27 @@ def _usage_entry_from_joined(je) -> "UsageEntry":
     The joined-entry shape already carries ``source_path``, ``cost_usd``,
     and the per-token integers; this adapter is pure shape conversion
     with no cache re-read.
+
+    Non-token ``usage`` extras (``je.usage_extra``) — notably ``speed`` —
+    are merged AFTER the four token keys, mirroring ``iter_entries``'
+    ``usage.update(json.loads(...))``. Without this, the project-axis
+    ``daily`` path (and the diff/report joined-entry consumers) would
+    drop the fast-tier flag and render ``<model>`` where the normal path
+    renders ``<model>-fast``. The write-side strips the four token keys
+    from ``usage_extra_json`` so the merge never shadows the integers.
     """
+    usage = {
+        "input_tokens": je.input_tokens,
+        "output_tokens": je.output_tokens,
+        "cache_creation_input_tokens": je.cache_creation_tokens,
+        "cache_read_input_tokens": je.cache_read_tokens,
+    }
+    if je.usage_extra:
+        usage.update(je.usage_extra)
     return UsageEntry(
         timestamp=je.timestamp,
         model=je.model,
-        usage={
-            "input_tokens": je.input_tokens,
-            "output_tokens": je.output_tokens,
-            "cache_creation_input_tokens": je.cache_creation_tokens,
-            "cache_read_input_tokens": je.cache_read_tokens,
-        },
+        usage=usage,
         cost_usd=je.cost_usd,
         source_path=je.source_path,
     )
@@ -1586,6 +1681,42 @@ def _project_filter_matches(key, project_patterns):
     return any((p in dname) or (p in pname) for p in project_patterns)
 
 
+def _parse_project_aliases(raw):
+    """Parse a ``--project-aliases`` value into ``{key: label}``.
+
+    Form: comma-separated ``key=Label`` pairs. Whitespace around keys, labels,
+    and pairs is stripped; segments without ``=`` or with an empty key/label are
+    dropped (ported from ccusage's tolerant parser). ``None``/"" → ``{}``.
+    """
+    result: dict[str, str] = {}
+    if not raw:
+        return result
+    for pair in raw.split(","):
+        pair = pair.strip()
+        if not pair or "=" not in pair:
+            continue
+        k, _, v = pair.partition("=")
+        k = k.strip()
+        v = v.strip()
+        if k and v:
+            result[k] = v
+    return result
+
+
+def _alias_for(key, aliases):
+    """Return the alias label for a ProjectKey, or None.
+
+    Looks up ``aliases`` by ``display_key``, then ``git_root``, then
+    ``bucket_path`` (first hit). Display-only — never alters JSON keys.
+    """
+    if not aliases:
+        return None
+    for cand in (key.display_key, key.git_root, key.bucket_path):
+        if cand and cand in aliases:
+            return aliases[cand]
+    return None
+
+
 def _emit_diff_debug_samples(args, window_a, window_b) -> None:
     """Two-window diff report (spec §7.2.2 Pattern D).
 
@@ -4172,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)
@@ -4271,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
 
@@ -4512,6 +4696,29 @@ def _parse_cli_date_range(
     return range_start, range_end
 
 
+def _emit_daily_view_table_or_json(view, args):
+    """Order + emit a DailyView as the flat daily table or {daily} JSON.
+
+    Shared by cmd_daily's default path and its -p-only (filter, no grouping)
+    path so the two cannot drift. Body is exactly the default path's order +
+    emit tail; callers keep their own --format share gate upstream of this.
+    """
+    days = list(reversed(view.aggregated))
+    if args.order == "desc":
+        days = list(reversed(days))
+    if args.json:
+        print(_bucket_to_json(days, list_key="daily", date_key="date"))
+        return
+    print(_render_bucket_table(
+        days,
+        first_col_name="Date",
+        title_suffix="Daily",
+        compact_split_fn=_daily_compact_split,
+        breakdown=args.breakdown,
+        compact=getattr(args, "compact", False),
+    ))
+
+
 def cmd_daily(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone date."""
     _share_validate_args(args)
@@ -4533,6 +4740,109 @@ def cmd_daily(args: argparse.Namespace) -> int:
         return range
     range_start, range_end = range
 
+    # ── Project-axis path (issue #86 Session E / T1.11) ────────────────────
+    # Gated by -i/--instances or -p/--project; the default path below is
+    # untouched/byte-stable. Mirrors cmd_project's I/O-layer git-root
+    # resolution + substring-OR-path filter.
+    aliases = _parse_project_aliases(getattr(args, "project_aliases", None))
+    project_patterns = [p.lower() for p in (getattr(args, "project", None) or [])]
+
+    if getattr(args, "instances", False) or project_patterns:
+        joined = list(get_claude_session_entries(range_start, range_end))
+        resolver_cache: dict = {}
+        keyed: list = []              # [(ProjectKey, UsageEntry)] — for -i grouping
+        filtered_uentries: list = []  # UsageEntry — for -p-only / --format / debug
+        for je in joined:
+            if je.model == "<synthetic>":
+                continue
+            key = _resolve_project_key(je.project_path, "git-root", resolver_cache)
+            if project_patterns and not _project_filter_matches(key, project_patterns):
+                continue
+            ue = _usage_entry_from_joined(je)
+            keyed.append((key, ue))
+            filtered_uentries.append(ue)
+
+        # Debug scope = the filtered entries (mirrors cmd_project).
+        _emit_debug_samples_if_set(args, filtered_uentries, command_label="daily")
+
+        # --format share gate: -i is a no-op (no project-section share render),
+        # but -p IS honored by building the snapshot from the filtered view.
+        if getattr(args, "format", None):
+            view = build_daily_view(filtered_uentries, now_utc=_command_as_of(),
+                                    display_tz=tz, mode=args.mode)
+            display_tz_str = _share_display_tz_label(tz)
+            snap = _build_daily_snapshot(
+                view, period_start=range_start, period_end=range_end,
+                display_tz=display_tz_str, version=_share_resolve_version(),
+                theme=args.theme, reveal_projects=args.reveal_projects,
+            )
+            if args.order == "desc":
+                snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
+            _share_render_and_emit(snap, args)
+            return 0
+
+        if getattr(args, "instances", False):
+            groups = _aggregate_daily_by_project(keyed, tz=tz, mode=args.mode)
+            aug = _project_disambiguate_labels(
+                [{"key": k, "cost_usd": sum(b.cost_usd for b in bl)}
+                 for k, bl in groups]
+            )
+            json_groups: list = []
+            table_groups: list = []
+            # `_project_disambiguate_labels` only suffixes the immediate
+            # parent-dir basename, so two distinct git-roots like
+            # `/a/x/app` + `/b/x/app` both resolve to `app (x)`. Guarantee
+            # per-group JSON-key uniqueness with a counter suffix on any
+            # residual collision — otherwise `_bucket_by_project_to_json`'s
+            # `projects[label] = ...` silently overwrites the earlier group
+            # (data loss in --json). The table_label derives from the now-
+            # unique json_label, so section headers stay distinct too.
+            # `json_label`s are unique by construction (the `(#N)` counter
+            # above). Table labels, however, can re-collide: `_alias_for`
+            # matches on `display_key` first, so a basename alias like
+            # `--project-aliases app=Alias` maps BOTH same-basename git-roots
+            # to "Alias" — re-merging the exact sections this feature
+            # disambiguates. Apply the SAME `(#N)` counter to table labels so
+            # the two distinct-total sections stay tellable apart (JSON keys
+            # are untouched — they use the non-aliased `json_label`).
+            seen_json_labels: dict[str, int] = {}
+            seen_table_labels: dict[str, int] = {}
+            for i, (k, bl) in enumerate(groups):
+                ordered = list(reversed(bl)) if args.order == "desc" else bl
+                base_json_label = aug.get(i, k.display_key)
+                n = seen_json_labels.get(base_json_label, 0) + 1
+                seen_json_labels[base_json_label] = n
+                json_label = (
+                    base_json_label if n == 1 else f"{base_json_label} (#{n})"
+                )
+                base_table_label = _alias_for(k, aliases) or json_label
+                nt = seen_table_labels.get(base_table_label, 0) + 1
+                seen_table_labels[base_table_label] = nt
+                table_label = (
+                    base_table_label if nt == 1
+                    else f"{base_table_label} (#{nt})"
+                )
+                json_groups.append((json_label, ordered))
+                table_groups.append((table_label, ordered))
+            if args.json:
+                print(_bucket_by_project_to_json(json_groups, date_key="date"))
+                return 0
+            print(_render_bucket_table(
+                [], first_col_name="Date", title_suffix="Daily",
+                compact_split_fn=_daily_compact_split,
+                breakdown=args.breakdown,
+                compact=getattr(args, "compact", False),
+                project_groups=table_groups,
+            ))
+            return 0
+
+        # -p only (no -i): filter-only → normal date-aggregated daily output.
+        view = build_daily_view(filtered_uentries, now_utc=_command_as_of(),
+                                display_tz=tz, mode=args.mode)
+        _emit_daily_view_table_or_json(view, args)
+        return 0
+
+    # ── Default path (UNCHANGED) ───────────────────────────────────────────
     # Collect entries.
     all_entries = get_entries(range_start, range_end)
 
@@ -4549,10 +4859,6 @@ def cmd_daily(args: argparse.Namespace) -> int:
     # `_aggregate_daily` call is the same one we used inline.
     view = build_daily_view(all_entries, now_utc=_command_as_of(),
                             display_tz=tz, mode=args.mode)
-    # `_aggregate_daily` returned ascending order; build_daily_view stores
-    # `aggregated` newest-first. CLI's default order is ascending, so
-    # re-reverse to match the prior on-the-wire shape.
-    days = list(reversed(view.aggregated))
 
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
@@ -4583,23 +4889,10 @@ def cmd_daily(args: argparse.Namespace) -> int:
         _share_render_and_emit(snap, args)
         return 0
 
-    # Apply sort order.
-    if args.order == "desc":
-        days = list(reversed(days))
-
-    if args.json:
-        print(_bucket_to_json(days, list_key="daily", date_key="date"))
-        return 0
-
-    # Table output.
-    print(_render_bucket_table(
-        days,
-        first_col_name="Date",
-        title_suffix="Daily",
-        compact_split_fn=_daily_compact_split,
-        breakdown=args.breakdown,
-        compact=getattr(args, "compact", False),
-    ))
+    # Order + emit the flat daily table / {daily} JSON. Extracted into
+    # `_emit_daily_view_table_or_json` so this default path and the
+    # -p-only (filter, no grouping) path above stay byte-identical.
+    _emit_daily_view_table_or_json(view, args)
     return 0
 
 
@@ -4811,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"
@@ -9670,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
 
@@ -10173,6 +10478,8 @@ def _build_daily_parser(subparsers, name, *, help_text, xref):
               cctally daily --since 20260414 --breakdown
               cctally daily --since 20260414 --json
               cctally daily --order desc
+              cctally daily --instances
+              cctally daily -i --project-aliases repos=Repos
         """),
     )
     p.add_argument(
@@ -10210,6 +10517,28 @@ def _build_daily_parser(subparsers, name, *, help_text, xref):
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    p.add_argument(
+        "-i", "--instances",
+        action="store_true",
+        default=False,
+        help="Group the report by project (git-root).",
+    )
+    p.add_argument(
+        "-p", "--project",
+        action="append",
+        default=None,
+        metavar="PATTERN",
+        help="Filter to projects matching PATTERN (substring of the project "
+             "label or path; repeatable, OR semantics).",
+    )
+    p.add_argument(
+        "--project-aliases",
+        dest="project_aliases",
+        default=None,
+        metavar="PAIRS",
+        help="Comma-separated key=Label pairs overriding project display "
+             "labels (e.g. cctally-dev=Tracker). Display-only.",
+    )
     _add_ccusage_alias_args(p, ansi_emit=False)
     _add_mode_arg(p)
     _add_share_args(p)
@@ -10417,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.17.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": {