cctally 1.18.0 → 1.20.0

package/bin/cctally

@@ -150,6 +150,7 @@ SETUP_SYMLINK_NAMES = (
     "cctally-forecast",
     "cctally-project",
     "cctally-refresh-usage",
+    "cctally-statusline",
     "cctally-sync-week",
     "cctally-tui",
     "cctally-update",
@@ -274,6 +275,26 @@ CODEX_FAST_MULTIPLIER_FALLBACK = _lib_pricing.CODEX_FAST_MULTIPLIER_FALLBACK
 _codex_config_requests_fast_service_tier = _lib_pricing._codex_config_requests_fast_service_tier
 _short_model_name = _lib_pricing._short_model_name
 
+# Per-model context window (used by `cctally statusline` segment 4).
+# Keep in sync with Anthropic's docs:
+#   https://docs.anthropic.com/en/docs/about-claude/models
+# Unknown model id → segment renders `🧠 N/A` + one-shot stderr warn.
+CLAUDE_MODEL_CONTEXT_WINDOWS = {
+    # 1M-token variants (explicit IDs override the family default).
+    "claude-opus-4-7[1m]": 1_000_000,
+    "claude-sonnet-4-5[1m]": 1_000_000,
+    # Default 200K for every other Sonnet/Opus/Haiku family member.
+    # The resolver does a substring match on the family token if the
+    # exact id is missing — see _resolve_context_window.
+}
+
+CLAUDE_MODEL_CONTEXT_WINDOW_DEFAULT_FAMILY = {
+    # Substring (case-insensitive) → window. Order matters; first hit wins.
+    "sonnet": 200_000,
+    "opus":   200_000,
+    "haiku":  200_000,
+}
+
 _lib_display_tz = _load_sibling("_lib_display_tz")
 DISPLAY_TZ_DEFAULT = _lib_display_tz.DISPLAY_TZ_DEFAULT
 _DISPLAY_TZ_BAD_CONFIG_WARNED = _lib_display_tz._DISPLAY_TZ_BAD_CONFIG_WARNED
@@ -349,6 +370,11 @@ _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_statusline = _load_sibling("_lib_statusline")
+STATUSLINE_BURN_RATE_BANDS = _lib_statusline.STATUSLINE_BURN_RATE_BANDS
 
 _lib_changelog = _load_sibling("_lib_changelog")
 # Backward-compat re-export: callers and tests reach the helper through
@@ -409,6 +435,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 +645,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 +901,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 +4327,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,20 +4435,567 @@ 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
 
 
+def cmd_statusline(args: argparse.Namespace) -> int:
+    """`cctally statusline` — one-line status summary for CC hooks.
+
+    See docs/superpowers/specs/2026-05-28-issue-86-session-g-statusline-design.md
+    for the full design.
+
+    Exit codes:
+        0  success (every absent stdin field degrades gracefully)
+        1  stdin is not parseable JSON OR root is not a JSON object
+        2  argparse rejected a flag (e.g. --cost-source ccusage), OR
+           --config PATH unreadable
+    """
+    # NOTE: `--cost-source ccusage` is rejected at argparse-time by
+    # `_CostSourceAction` in `_build_statusline_parser`; it exits 2 with
+    # the rename hint before we get here, so no explicit re-check is
+    # needed in this function.
+
+    # Validate `--context-{low,medium}-threshold` BEFORE reading stdin
+    # so a misconfigured invocation fails fast without consuming the
+    # CC hook's stdin payload.
+    low = args.context_low_threshold
+    med = args.context_medium_threshold
+    if not isinstance(low, int) or low < 0 or low > 100:
+        eprint(
+            "cctally statusline: --context-low-threshold must be in [0, 100]"
+        )
+        return 2
+    if not isinstance(med, int) or med < 0 or med > 100:
+        eprint(
+            "cctally statusline: --context-medium-threshold must be in [0, 100]"
+        )
+        return 2
+    if low >= med:
+        eprint(
+            "cctally statusline: --context-low-threshold must be < "
+            "--context-medium-threshold"
+        )
+        return 2
+
+    # Silently clamp `--refresh-interval` to [0, 600]. The flag is a
+    # no-op alias for ccusage drop-in compat; users never observe the
+    # effect, but the spec mandates the clamp for forward-compat (when
+    # we promote it to a real flag, the clamped value should be the one
+    # propagated downstream).
+    try:
+        args.refresh_interval = max(0, min(600, int(args.refresh_interval)))
+    except (TypeError, ValueError):
+        args.refresh_interval = 1
+
+    # Read stdin once.
+    raw = sys.stdin.buffer.read()
+    parse_result = _lib_statusline.parse_statusline_stdin(raw)
+    if isinstance(parse_result, _lib_statusline.ParseError):
+        eprint(f"cctally statusline: {parse_result.message}")
+        return 1
+    inp = parse_result
+
+    # Resolve effective config: CLI > config.json > built-in default.
+    # `_load_claude_config_for_args` honors `--config PATH` (issue #88
+    # plumbing); a missing/invalid PATH raises SystemExit(2) inside
+    # `_load_config_from_explicit_path` so this call already enforces
+    # exit-2 on a bad --config.
+    cfg = _load_claude_config_for_args(args)
+    sl_cfg = (cfg.get("statusline") or {}) if isinstance(cfg, dict) else {}
+    if not isinstance(sl_cfg, dict):
+        sl_cfg = {}
+
+    # Validate config values; on invalid, one-shot stderr warn + use default.
+    _warned: set = set()
+
+    def warn_once(msg: str) -> None:
+        if msg in _warned:
+            return
+        _warned.add(msg)
+        eprint(msg)
+
+    def _resolve(cli_val, cfg_key, default):
+        if cli_val is not None:
+            return cli_val
+        cv = sl_cfg.get(cfg_key)
+        if cv is None:
+            return default
+        return cv
+
+    vbr = _resolve(args.visual_burn_rate, "visual_burn_rate", "off")
+    if vbr not in ("off", "emoji", "text", "emoji-text"):
+        warn_once(
+            f"cctally statusline: invalid statusline.visual_burn_rate={vbr!r}; "
+            f"using 'off'"
+        )
+        vbr = "off"
+
+    cs = _resolve(args.cost_source, "cost_source", "auto")
+    if cs not in ("auto", "cctally", "cc", "both"):
+        warn_once(
+            f"cctally statusline: invalid statusline.cost_source={cs!r}; "
+            f"using 'auto'"
+        )
+        cs = "auto"
+
+    ext_on = _resolve(args.cctally_extensions, "cctally_extensions", True)
+    if not isinstance(ext_on, bool):
+        warn_once(
+            f"cctally statusline: invalid statusline.cctally_extensions="
+            f"{ext_on!r}; using True"
+        )
+        ext_on = True
+
+    # Display tz: CLI -z/--timezone > display.tz config > "UTC".
+    tz_name = getattr(args, "timezone", None)
+    if not tz_name:
+        display_block = cfg.get("display") if isinstance(cfg, dict) else None
+        if isinstance(display_block, dict):
+            tz_name = display_block.get("tz")
+    if not tz_name:
+        tz_name = "UTC"
+    if tz_name in ("local", "LOCAL"):
+        try:
+            tz_name = _local_tz_name() or "UTC"
+        except Exception:
+            tz_name = "UTC"
+    # Validate the IANA name; fall back to UTC with a one-shot warning.
+    try:
+        ZoneInfo(tz_name)
+    except (ZoneInfoNotFoundError, Exception):
+        warn_once(
+            f"cctally statusline: invalid timezone {tz_name!r}; using 'UTC'"
+        )
+        tz_name = "UTC"
+
+    # Color: explicit CLI > NO_COLOR env > TTY detect.
+    if args.color is True or args.color is False:
+        color = args.color
+    else:
+        color = (os.environ.get("NO_COLOR", "") == "") and sys.stdout.isatty()
+
+    sargs = _lib_statusline.StatuslineArgs(
+        visual_burn_rate=vbr,
+        cost_source=cs,
+        context_low_threshold=int(args.context_low_threshold),
+        context_medium_threshold=int(args.context_medium_threshold),
+        cctally_extensions=bool(ext_on),
+        color=bool(color),
+        display_tz_name=tz_name,
+        debug=bool(args.debug),
+    )
+
+    # Build injections (DB + transcript file IO).
+    inj = _build_statusline_injections(warn_once)
+
+    # `_command_as_of()` honors the `CCTALLY_AS_OF` testing hook so the
+    # golden harness can pin "now" for deterministic block-remaining and
+    # 5h/7d countdown numbers. Falls back to wall-clock UTC otherwise.
+    now = _command_as_of()
+    try:
+        line = _lib_statusline.render_statusline(inp, sargs, inj, now)
+    except Exception as exc:  # pragma: no cover — defensive
+        eprint(f"cctally statusline: render failed: {exc}")
+        return 1
+    print(line)
+    return 0
+
+
+def _resolve_context_window(model_id, warn_once) -> "int | None":
+    """Look up ``model_id`` in ``CLAUDE_MODEL_CONTEXT_WINDOWS``; fall back
+    to a family-substring match against
+    ``CLAUDE_MODEL_CONTEXT_WINDOW_DEFAULT_FAMILY``. Unknown id → ``None`` +
+    one-shot stderr warning.
+    """
+    if not model_id:
+        return None
+    if model_id in CLAUDE_MODEL_CONTEXT_WINDOWS:
+        return CLAUDE_MODEL_CONTEXT_WINDOWS[model_id]
+    mid_lower = model_id.lower()
+    for family, window in CLAUDE_MODEL_CONTEXT_WINDOW_DEFAULT_FAMILY.items():
+        if family in mid_lower:
+            return window
+    warn_once(
+        f"cctally statusline: unknown model {model_id!r}; context % unavailable"
+    )
+    return None
+
+
+def _read_last_assistant_usage(transcript_path):
+    """Tail-walk the transcript JSONL backwards to the most recent
+    ``type=assistant`` line carrying ``message.usage``. Returns the usage
+    dict or ``None``.
+
+    Reads in 64 KB chunks from the end so multi-MB transcripts don't
+    block the hot statusline path with a full-file parse.
+    """
+    if not transcript_path:
+        return None
+    path = pathlib.Path(transcript_path)
+    if not path.exists():
+        return None
+    try:
+        with path.open("rb") as fh:
+            fh.seek(0, 2)
+            size = fh.tell()
+            tail = b""
+            chunk = 65536
+            # Read backwards in chunks until we have at least one full line
+            # and the tail starts with a newline (so the first line is whole).
+            while size > 0 and tail.count(b"\n") < 2:
+                read_at = max(0, size - chunk)
+                fh.seek(read_at)
+                tail = fh.read(size - read_at) + tail
+                size = read_at
+            lines = tail.split(b"\n")
+    except OSError:
+        return None
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(obj, dict):
+            continue
+        if obj.get("type") != "assistant":
+            continue
+        msg = obj.get("message") or {}
+        usage = msg.get("usage") if isinstance(msg, dict) else None
+        if isinstance(usage, dict):
+            return usage
+    return None
+
+
+def _build_statusline_injections(warn_once):
+    """Wire DB- and FS-backed implementations for the kernel's injection ports.
+
+    See ``_lib_statusline.StatuslineInjections`` for the contract. All
+    callables fast-fail to "no data" on any exception — statusline must
+    NEVER block the Claude Code hook tick.
+    """
+    def _cctally_session_cost(sid):
+        if not sid:
+            return None
+        try:
+            conn = open_cache_db()
+        except Exception:
+            return None
+        try:
+            # Walk all entries via session_files join; sum costs whose
+            # session_id matches. Stays read-only — does NOT call
+            # sync_cache (too heavy for the hot statusline path; the
+            # record-usage + hook-tick paths keep the cache warm).
+            sql = (
+                "SELECT se.timestamp_utc, se.model, "
+                "  se.input_tokens, se.output_tokens, "
+                "  se.cache_create_tokens, se.cache_read_tokens, "
+                "  se.cost_usd_raw, se.usage_extra_json "
+                "FROM session_entries se "
+                "LEFT JOIN session_files sf ON sf.path = se.source_path "
+                "WHERE sf.session_id = ?"
+            )
+            rows = list(conn.execute(sql, (sid,)))
+        except Exception:
+            return None
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                pass
+        if not rows:
+            return None
+        total = 0.0
+        for r in rows:
+            usage = {
+                "input_tokens":                r[2] or 0,
+                "output_tokens":               r[3] or 0,
+                "cache_creation_input_tokens": r[4] or 0,
+                "cache_read_input_tokens":     r[5] or 0,
+            }
+            try:
+                if r[7]:
+                    extras = json.loads(r[7])
+                    if isinstance(extras, dict):
+                        usage.update(extras)
+            except Exception:
+                pass
+            try:
+                total += _calculate_entry_cost(
+                    r[1], usage, mode="auto", cost_usd=r[6],
+                )
+            except Exception:
+                continue
+        return total
+
+    def _today_cost(tz_name, now):
+        try:
+            tz = ZoneInfo(tz_name) if tz_name and tz_name != "UTC" else dt.timezone.utc
+        except Exception:
+            tz = dt.timezone.utc
+        local_now = now.astimezone(tz)
+        day_start_local = local_now.replace(
+            hour=0, minute=0, second=0, microsecond=0
+        )
+        day_end_local = day_start_local + dt.timedelta(days=1)
+        range_start = day_start_local.astimezone(dt.timezone.utc)
+        range_end = day_end_local.astimezone(dt.timezone.utc)
+        # Two-filter pattern (UTC half-open + display-tz date check):
+        # the UTC range fetches the candidate window cheaply via the
+        # cache's indexed `timestamp` column; the display-tz date check
+        # then trims any entries that fall outside today's local
+        # calendar day (the UTC window straddles two local dates when
+        # the display tz has any UTC offset, so the SQL range alone is
+        # slightly wider than the local day).
+        try:
+            entries = get_entries(range_start, range_end, skip_sync=True)
+        except Exception:
+            return 0.0
+        total = 0.0
+        for e in entries:
+            try:
+                # Filter to today in display tz (second-pass trim).
+                ts_local = e.timestamp.astimezone(tz)
+                if ts_local.date() != local_now.date():
+                    continue
+                total += _calculate_entry_cost(
+                    e.model, e.usage, mode="auto", cost_usd=e.cost_usd,
+                )
+            except Exception:
+                continue
+        return total
+
+    def _active_block(now):
+        try:
+            # Look at last 24h — captures the full active 5h window.
+            range_start = now - dt.timedelta(hours=24)
+            entries = get_entries(range_start, now, skip_sync=True)
+        except Exception:
+            return None
+        if not entries:
+            return None
+        try:
+            recorded_windows, block_start_overrides, canonical_intervals = (
+                _load_recorded_five_hour_windows(
+                    range_start - BLOCK_DURATION, now + BLOCK_DURATION,
+                )
+            )
+        except Exception:
+            recorded_windows, block_start_overrides, canonical_intervals = (
+                [], {}, {},
+            )
+        try:
+            blocks = _group_entries_into_blocks(
+                entries,
+                mode="auto",
+                recorded_windows=recorded_windows,
+                block_start_overrides=block_start_overrides,
+                canonical_intervals=canonical_intervals,
+                now=now,
+            )
+        except Exception:
+            return None
+        for b in blocks:
+            if not b.is_gap and b.is_active:
+                remaining_s = int((b.end_time - now).total_seconds())
+                elapsed_s = int((now - b.start_time).total_seconds())
+                return (float(b.cost_usd or 0.0), remaining_s, elapsed_s)
+        return None
+
+    def _hwm_clamp(five_resets, seven_resets):
+        five_hwm = None
+        seven_hwm = None
+        try:
+            conn = open_db()
+        except Exception:
+            return (None, None)
+        try:
+            if five_resets is not None:
+                try:
+                    key = _canonical_5h_window_key(int(five_resets))
+                    row = conn.execute(
+                        "SELECT MAX(five_hour_percent) "
+                        "FROM weekly_usage_snapshots "
+                        "WHERE five_hour_window_key = ?",
+                        (key,),
+                    ).fetchone()
+                    if row and row[0] is not None:
+                        five_hwm = float(row[0])
+                except Exception:
+                    pass
+            if seven_resets is not None:
+                try:
+                    # Seven-day window: derive week_start_date from the
+                    # resets_at epoch (reset - 7 days, UTC date).
+                    week_start_date = dt.datetime.fromtimestamp(
+                        int(seven_resets) - 7 * 86400, tz=dt.timezone.utc,
+                    ).date().isoformat()
+                    row = conn.execute(
+                        "SELECT MAX(weekly_percent) "
+                        "FROM weekly_usage_snapshots "
+                        "WHERE week_start_date = ?",
+                        (week_start_date,),
+                    ).fetchone()
+                    if row and row[0] is not None:
+                        seven_hwm = float(row[0])
+                except Exception:
+                    pass
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                pass
+        return (five_hwm, seven_hwm)
+
+    def _db_latest_rate_limits():
+        try:
+            conn = open_db()
+        except Exception:
+            return None
+        try:
+            # Prefer `week_end_at` (ISO timestamp; sub-day precision) over
+            # `week_end_date` (date-only; UTC-midnight). Older snapshots
+            # may have `week_end_at` NULL — fall back to the date column
+            # in that case. See the neighbor query in `pick_week_selection`
+            # (bin/cctally:3849) for the precedent.
+            row = conn.execute(
+                "SELECT five_hour_percent, five_hour_window_key, "
+                "  weekly_percent, week_end_at, week_end_date "
+                "FROM weekly_usage_snapshots "
+                "ORDER BY captured_at_utc DESC, id DESC LIMIT 1"
+            ).fetchone()
+            if not row:
+                return None
+            five_pct = float(row[0]) if row[0] is not None else None
+            five_resets = int(row[1]) if row[1] is not None else None
+            seven_pct = float(row[2]) if row[2] is not None else None
+            seven_resets = None
+            week_end_at = row[3]
+            week_end_date = row[4]
+            if week_end_at:
+                try:
+                    # `datetime.fromisoformat` accepts the trailing `Z`
+                    # only on Python 3.11+; normalize to `+00:00` so 3.10
+                    # checkouts (and any odd Z-suffixed snapshot) parse.
+                    raw_iso = str(week_end_at)
+                    if raw_iso.endswith("Z"):
+                        raw_iso = raw_iso[:-1] + "+00:00"
+                    end_dt = dt.datetime.fromisoformat(raw_iso)
+                    if end_dt.tzinfo is None:
+                        end_dt = end_dt.replace(tzinfo=dt.timezone.utc)
+                    seven_resets = int(end_dt.timestamp())
+                except Exception:
+                    seven_resets = None
+            if seven_resets is None and week_end_date:
+                try:
+                    end_dt = dt.datetime.fromisoformat(str(week_end_date))
+                    if end_dt.tzinfo is None:
+                        end_dt = end_dt.replace(tzinfo=dt.timezone.utc)
+                    # week_end_date is exclusive — that's the reset moment.
+                    seven_resets = int(end_dt.timestamp())
+                except Exception:
+                    seven_resets = None
+            return (five_pct, five_resets, seven_pct, seven_resets)
+        except Exception:
+            return None
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+    def _context_pct(transcript_path, model_id):
+        if not transcript_path or not model_id:
+            return None
+        window = _resolve_context_window(model_id, warn_once)
+        if window is None:
+            return None
+        try:
+            usage = _read_last_assistant_usage(transcript_path)
+        except Exception:
+            return None
+        if not isinstance(usage, dict):
+            return None
+        try:
+            ctx_tokens = (
+                int(usage.get("input_tokens", 0) or 0)
+                + int(usage.get("cache_read_input_tokens", 0) or 0)
+                + int(usage.get("cache_creation_input_tokens", 0) or 0)
+            )
+        except (TypeError, ValueError):
+            return None
+        if window <= 0:
+            return None
+        return ctx_tokens / window * 100.0
+
+    return _lib_statusline.StatuslineInjections(
+        cctally_session_cost=_cctally_session_cost,
+        today_cost=_today_cost,
+        active_block=_active_block,
+        hwm_clamp=_hwm_clamp,
+        db_latest_rate_limits=_db_latest_rate_limits,
+        context_pct=_context_pct,
+        warn_once=warn_once,
+    )
+
+
 def _maybe_swap_active_block_to_canonical(
     blocks: list[Any],
     all_entries: list[Any],
@@ -4971,25 +5631,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 +10497,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,12 +11273,213 @@ 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)
     return p
 
 
+def _build_statusline_parser(subparsers, name, *, help_text, xref):
+    """Build the `statusline` (or `claude statusline`) leaf parser.
+
+    Registered TWICE per the Session B build-once register-twice pattern:
+    once on the flat ``cctally statusline`` subparser, once under the
+    nested ``cctally claude statusline`` subgroup. Output is byte-identical
+    between the two forms; only ``--help`` text differs (the ``xref``
+    paragraph appended to ``description``).
+    """
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description=(
+            "Display a compact one-line status for Claude Code hooks "
+            "(ccusage drop-in + cctally extensions).\n\n" + xref
+        ),
+    )
+    # ccusage-shape flags
+    p.add_argument(
+        "-B", "--visual-burn-rate",
+        dest="visual_burn_rate",
+        default=None,
+        choices=["off", "emoji", "text", "emoji-text"],
+        help="Burn-rate visualization (default: off; config key "
+             "statusline.visual_burn_rate).",
+    )
+    # NOTE: `ccusage` is intentionally NOT in `choices=` so it doesn't
+    # appear in `--help` advertised options. Argparse runs the `choices`
+    # check BEFORE the action's `__call__`, so we cannot list `ccusage`
+    # in `choices=` AND catch it in the action. Instead we omit `choices=`
+    # entirely, manually validate inside the action, and re-raise the
+    # spec's rename hint via `parser.error` for `ccusage` specifically.
+    # Help text below hardcodes the legal set so users still see it in
+    # `--help`. A typo like `ccussage` falls through to a standard
+    # argparse-style "invalid choice" error from `parser.error`.
+    class _CostSourceAction(argparse.Action):
+        _ACCEPTED = ("auto", "cctally", "cc", "both")
+        _RENAMED = "ccusage"
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            if values == self._RENAMED:
+                parser.error(
+                    f"argument {option_string}: invalid choice: "
+                    f"{values!r} — cctally renamed it; try "
+                    f"--cost-source cctally"
+                )
+            if values not in self._ACCEPTED:
+                parser.error(
+                    f"argument {option_string}: invalid choice: "
+                    f"{values!r} (choose from "
+                    + ", ".join(repr(c) for c in self._ACCEPTED)
+                    + ")"
+                )
+            setattr(namespace, self.dest, values)
+
+    p.add_argument(
+        "--cost-source",
+        dest="cost_source",
+        default=None,
+        action=_CostSourceAction,
+        metavar="{auto,cctally,cc,both}",
+        help="Session cost source (default: auto; config key "
+             "statusline.cost_source). Note: 'ccusage' errors with a "
+             "rename hint — use 'cctally' instead.",
+    )
+    p.add_argument(
+        "--cache",
+        dest="cache",
+        action="store_true",
+        default=None,
+        help="Accepted for ccusage drop-in compat; cctally renders from "
+             "cache.db directly without an extra output cache.",
+    )
+    p.add_argument(
+        "--no-cache",
+        dest="cache",
+        action="store_false",
+        help="(no-op alias)",
+    )
+    p.add_argument(
+        "--refresh-interval",
+        dest="refresh_interval",
+        default=1,
+        type=int,
+        metavar="N",
+        help="(no-op alias) Accepted for ccusage drop-in compat.",
+    )
+    p.add_argument(
+        "--context-low-threshold",
+        dest="context_low_threshold",
+        default=50,
+        type=int,
+        metavar="N",
+        help="Below this %% → segment 4 green (default: 50, 0-100).",
+    )
+    p.add_argument(
+        "--context-medium-threshold",
+        dest="context_medium_threshold",
+        default=80,
+        type=int,
+        metavar="N",
+        help="Below this %% → segment 4 yellow; else red (default: 80, 0-100).",
+    )
+    p.add_argument(
+        "-z", "--timezone",
+        dest="timezone",
+        default=None,
+        metavar="TZ",
+        help="Display tz (IANA) for `today` calendar day. Overrides "
+             "display.tz config.",
+    )
+    p.add_argument(
+        "-O", "--offline",
+        dest="offline",
+        action="store_true",
+        default=True,
+        help="(no-op alias) cctally is always offline.",
+    )
+    p.add_argument(
+        "--no-offline",
+        dest="offline",
+        action="store_false",
+        help="(no-op alias)",
+    )
+    p.add_argument(
+        "--color",
+        dest="color",
+        action="store_true",
+        default=None,
+        help="Force ANSI colors on (default: auto via NO_COLOR + TTY).",
+    )
+    p.add_argument(
+        "--no-color",
+        dest="color",
+        action="store_false",
+        help="Force ANSI colors off.",
+    )
+    p.add_argument(
+        "--cctally-extensions",
+        dest="cctally_extensions",
+        action="store_true",
+        default=None,
+        help="Append cctally 5h%%/7d%% segment (default: on; config key "
+             "statusline.cctally_extensions).",
+    )
+    p.add_argument(
+        "--no-cctally-extensions",
+        dest="cctally_extensions",
+        action="store_false",
+        help="Suppress cctally 5h%%/7d%% segment.",
+    )
+    p.add_argument(
+        "--config",
+        dest="config",
+        default=None,
+        metavar="PATH",
+        help="Read config from PATH for this invocation only (no "
+             "mutation of the default config). Missing/invalid PATH "
+             "exits 2.",
+    )
+    p.add_argument(
+        "--single-thread",
+        dest="single_thread",
+        action="store_true",
+        help="(no-op alias) cctally is always single-threaded via the "
+             "session-entry cache.",
+    )
+    p.add_argument(
+        "-d", "--debug",
+        dest="debug",
+        action="store_true",
+        help="Emit pricing-mismatch / config diagnostics on stderr.",
+    )
+    p.set_defaults(func=cmd_statusline, command=name)
+    return p
+
+
 def _build_codex_daily_parser(subparsers, name, *, help_text, xref):
     """Build the `codex-daily` leaf parser (issue #86 Session B; routes to cmd_codex_daily)."""
     p = subparsers.add_parser(
@@ -11467,6 +12340,12 @@ def build_parser() -> argparse.ArgumentParser:
         help_text="Show usage report grouped by 5-hour session blocks",
         xref="Alias of `cctally claude blocks` (the canonical form).")
 
+    # -- statusline --
+    _build_statusline_parser(
+        sub, "statusline",
+        help_text="Compact one-line status for Claude Code hooks",
+        xref="Alias of `cctally claude statusline` (the canonical form).")
+
     # -- five-hour-blocks --
     fhb = sub.add_parser(
         "five-hour-blocks",
@@ -11722,6 +12601,10 @@ def build_parser() -> argparse.ArgumentParser:
     _build_blocks_parser(claude_sub, "blocks",
         help_text="Show usage grouped by 5-hour session blocks",
         xref="Drop-in for `ccusage claude blocks`. Same engine as `cctally blocks`.")
+    _build_statusline_parser(claude_sub, "statusline",
+        help_text="Compact one-line status for Claude Code hooks",
+        xref="Canonical `cctally claude statusline` (flat alias: `cctally statusline`). "
+             "Drop-in for `ccusage statusline` plus cctally extension segments.")
 
     # --- `codex` subgroup (drop-in for `ccusage codex …`); issue #86 Session B ---
     codex_p = sub.add_parser(