cctally 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,11 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-05-28
+
+### Added
+- **`cctally statusline` (and `cctally claude statusline`) — a one-line status string for Claude Code's `statusLine` hook, drop-in for `ccusage statusline` with cctally-only extensions appended.** Reads the Claude Code hook stdin and emits five `|`-delimited segments: `🤖 <model>` (display name) · `💰 $X.XX session / $Y.YY today / $Z.ZZ block (Hh Mm left)` cost · `🔥 $X.XX/hr` burn rate with optional `🟢/🟡/🔴 (Normal/Moderate/High)` visual · `🧠 N%` context-window utilization · `5h X% (Hh Mm) · 7d Y% (Dd Hh)` cctally extension sourced from stdin `rate_limits` with the existing monotonic HWM clamp and DB-latest-row fallback. Flag surface mirrors ccusage's: `-B {off,emoji,text,emoji-text}`, `--cost-source {auto,cctally,cc,both}` (the `ccusage` value name is renamed; passing it errors with a one-line rename hint), `--context-low-threshold`/`--context-medium-threshold` (defaults 50/80, with `[0, 100]` range + `low < medium` ordering validation), `-z/--timezone`, `-d/--debug`, plus `--cache`/`--no-cache`/`--refresh-interval`/`-O/--offline`/`--single-thread` as documented no-op aliases and `--config PATH` honored as a real per-invocation override (parity with the 10 sibling Claude reporting commands). cctally adds `--cctally-extensions`/`--no-cctally-extensions` (default-on) to toggle segment 5 and persists three config keys (`statusline.{visual_burn_rate,cost_source,cctally_extensions}`) with CLI > config > built-in default precedence. Cost sources: `auto` uses the cctally JSONL-derived cost when the transcript is readable and the session exists in the cache, falling back to stdin `cost.total_cost_usd` otherwise; `cctally`/`cc`/`both` force one path or render side-by-side. Today's bucket honors `display.tz`; the active block segment reuses Session F's `_lib_blocks` kernel and burn-rate bands are `<$15/hr` green, `<$30/hr` yellow, `≥$30/hr` red. Context % is computed from a memory-safe tail-walk of the transcript JSONL (last assistant turn's usage block ÷ per-model context window — 200K default, 1M for `[1m]` variants); unknown models render `🧠 N/A` with a one-shot stderr warn. Stdin contract is deliberately graceful (an intentional ccusage divergence, documented in the spec): only malformed JSON or a non-object root exits 1; every other field absence — missing `model`, `transcript_path`, `session_id`, `cost`, even `rate_limits` — produces a degraded but non-broken line at exit 0, so the status line never fails the hook on a partial payload. Architecture: pure-function render kernel at `bin/_lib_statusline.py` (no I/O — every side-effecting dep dataclass-injected); I/O glue in `bin/cctally::cmd_statusline` wires DB + transcript reader + HWM clamp callables; built once and registered twice (flat + nested) per the Session B parser pattern, so `cctally statusline` and `cctally claude statusline` produce byte-identical output (only `--help` xref differs). Regression: `bin/cctally-statusline-test` (32 fixture scenarios — every cost-source value, every `-B` variant, every context color band + the unknown-model + 1M-window paths, extension HWM clamp + DB fallback + suppression, resumed-session merge, every graceful-degradation case, bad-stdin, tz buckets, config persistence + CLI override + `--config PATH`), `bin/cctally-reconcile-test` (+6 statusline invariants binding the segments to `cctally session`/`daily`/`blocks --active`/`weekly_usage_snapshots` within 1e-9 USD tolerance), `bin/cctally-subgroup-test` (new `compare_forms_stdin` proves flat≡`claude statusline` over a subgroup-parity fixture), and `tests/test_statusline.py` (66 kernel units). (#86)
+
 ## [1.19.0] - 2026-05-28
 
 ### Added

package/bin/_cctally_config.py

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

package/bin/_lib_statusline.py

@@ -0,0 +1,499 @@
+"""Pure-function render kernel for ``cctally statusline``.
+
+No I/O — every side-effecting dependency is dataclass-injected (cache.db
+query fns, HWM-clamp fn, transcript-reader fn, ``now``). Keeps unit tests
+injection-driven and golden tests reproducible.
+
+See docs/superpowers/specs/2026-05-28-issue-86-session-g-statusline-design.md
+for the full design.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+
+# ---- Stdin payload (subset we care about) ----------------------------------
+
+
+@dataclass(frozen=True)
+class StatuslineInput:
+    """Parsed Claude Code hook stdin. Every field is optional — see §3.1 of
+    the spec for the graceful-degradation contract. The two exit-1 paths
+    (parse failure, non-object root) are handled BEFORE this dataclass is
+    constructed; if you have a ``StatuslineInput`` instance, the payload
+    was at least a valid JSON object.
+    """
+    session_id: Optional[str] = None
+    model_id: Optional[str] = None
+    model_display_name: Optional[str] = None
+    transcript_path: Optional[str] = None
+    workspace_current_dir: Optional[str] = None
+    cost_total_usd: Optional[float] = None
+    rate_limits_5h_pct: Optional[float] = None
+    rate_limits_5h_resets_at: Optional[int] = None  # unix epoch
+    rate_limits_7d_pct: Optional[float] = None
+    rate_limits_7d_resets_at: Optional[int] = None  # unix epoch
+    raw: dict = field(default_factory=dict)  # full parsed JSON for diagnostics
+
+
+# ---- CLI args (post-config-resolution) -------------------------------------
+
+
+@dataclass(frozen=True)
+class StatuslineArgs:
+    """Effective configuration AFTER CLI > config.json > built-in default
+    precedence has been resolved by the I/O layer. The kernel sees a fully
+    resolved view.
+    """
+    visual_burn_rate: str  # "off" | "emoji" | "text" | "emoji-text"
+    cost_source: str  # "auto" | "cctally" | "cc" | "both"
+    context_low_threshold: int
+    context_medium_threshold: int
+    cctally_extensions: bool
+    color: bool  # ANSI on/off after auto-detect resolved
+    display_tz_name: str  # IANA name; "UTC" if config absent
+    debug: bool
+
+
+# ---- Injection-ports (no defaults — every field MUST be supplied) ----------
+
+
+@dataclass(frozen=True)
+class StatuslineInjections:
+    """Side-effecting callables. Unit tests pass simple lambdas; the I/O
+    layer in ``cmd_statusline`` passes DB- and filesystem-backed
+    implementations.
+    """
+    # Sum of session_entries.cost WHERE session_id = ? (merged-resumed).
+    # Returns None if session_id unknown or cache miss.
+    cctally_session_cost: Callable[[Optional[str]], Optional[float]]
+    # Sum of session_entries.cost WHERE date(timestamp, tz) == today.
+    today_cost: Callable[[str, datetime], float]
+    # Active 5h block: returns (cost_usd, time_remaining_seconds, elapsed_seconds)
+    # or None if no active block.
+    active_block: Callable[[datetime], "Optional[tuple[float, int, int]]"]
+    # Returns (5h_hwm_pct, 7d_hwm_pct), both may be None.
+    hwm_clamp: Callable[
+        [Optional[int], Optional[int]],  # five_resets, seven_resets epochs
+        "tuple[Optional[float], Optional[float]]",
+    ]
+    # Latest weekly_usage_snapshots row as (five_pct, five_resets, seven_pct, seven_resets)
+    # or None.
+    db_latest_rate_limits: Callable[
+        [],
+        "Optional[tuple[Optional[float], Optional[int], Optional[float], Optional[int]]]",
+    ]
+    # transcript_path → context % (0.0..100.0) or None if unreadable/unknown.
+    context_pct: Callable[[Optional[str], Optional[str]], Optional[float]]
+    # Emits one-shot stderr warnings (deduped by message — caller maintains set).
+    warn_once: Callable[[str], None]
+
+
+# ---- ParseError sentinel ---------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ParseError:
+    """Returned by parse_statusline_stdin on JSON parse failure or
+    non-object root. The I/O layer maps this to exit 1 with a stderr
+    message and empty stdout.
+    """
+    message: str
+
+
+def parse_statusline_stdin(raw: "bytes | str") -> "StatuslineInput | ParseError":
+    """Parse the Claude Code hook stdin payload.
+
+    Returns ``StatuslineInput`` on success (every field optional), or
+    ``ParseError`` if stdin is not parseable JSON OR not an object root.
+    Field-level absences are NOT errors — they degrade gracefully per
+    spec §3.1.
+    """
+    try:
+        text = raw.decode("utf-8") if isinstance(raw, (bytes, bytearray)) else raw
+        parsed = json.loads(text)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return ParseError(f"invalid JSON: {exc}")
+    if not isinstance(parsed, dict):
+        typ = type(parsed).__name__
+        return ParseError(f"expected JSON object, got {typ}")
+
+    def _get(d, *path):
+        cur = d
+        for k in path:
+            if not isinstance(cur, dict):
+                return None
+            cur = cur.get(k)
+        return cur
+
+    def _to_epoch(v) -> Optional[int]:
+        if v is None:
+            return None
+        if isinstance(v, bool):  # bool is an int subclass — exclude
+            return None
+        if isinstance(v, (int, float)):
+            return int(v)
+        if isinstance(v, str):
+            try:
+                # iso8601 with Z or offset
+                s = v.replace("Z", "+00:00")
+                dt_obj = datetime.fromisoformat(s)
+                if dt_obj.tzinfo is None:
+                    dt_obj = dt_obj.replace(tzinfo=timezone.utc)
+                return int(dt_obj.timestamp())
+            except ValueError:
+                return None
+        return None
+
+    def _to_float(v) -> Optional[float]:
+        if v is None:
+            return None
+        if isinstance(v, bool):
+            return None
+        try:
+            return float(v)
+        except (TypeError, ValueError):
+            return None
+
+    def _to_str(v) -> Optional[str]:
+        return v if isinstance(v, str) and v else None
+
+    return StatuslineInput(
+        session_id=_to_str(parsed.get("session_id")),
+        model_id=_to_str(_get(parsed, "model", "id")),
+        model_display_name=_to_str(_get(parsed, "model", "display_name")),
+        transcript_path=_to_str(parsed.get("transcript_path")),
+        workspace_current_dir=_to_str(_get(parsed, "workspace", "current_dir")),
+        cost_total_usd=_to_float(_get(parsed, "cost", "total_cost_usd")),
+        rate_limits_5h_pct=_to_float(
+            _get(parsed, "rate_limits", "five_hour", "used_percentage")
+        ),
+        rate_limits_5h_resets_at=_to_epoch(
+            _get(parsed, "rate_limits", "five_hour", "resets_at")
+        ),
+        rate_limits_7d_pct=_to_float(
+            _get(parsed, "rate_limits", "seven_day", "used_percentage")
+        ),
+        rate_limits_7d_resets_at=_to_epoch(
+            _get(parsed, "rate_limits", "seven_day", "resets_at")
+        ),
+        raw=parsed,
+    )
+
+
+# ---- Segment 1: model -----------------------------------------------------
+
+
+def resolve_model_segment(inp: StatuslineInput) -> str:
+    """Segment 1: `🤖 <model>`. display_name > id > 'Unknown model'."""
+    name = inp.model_display_name or inp.model_id or "Unknown model"
+    return f"🤖 {name}"
+
+
+# ---- Segment 2 components -------------------------------------------------
+
+
+def _fmt_usd(v: float) -> str:
+    return f"${v:.2f}"
+
+
+def resolve_session_cost(
+    inp: StatuslineInput,
+    cost_source: str,
+    inj: StatuslineInjections,
+) -> str:
+    """Segment 2 prefix — the `session` slot.
+
+    `cctally`/`auto` (when transcript+session_id available and cache hit):
+        sum session_entries WHERE session_id = ?
+    `auto` falls through to `cc` when:
+        - session_id absent, OR
+        - transcript_path absent, OR
+        - cache miss (cctally_session_cost returns None)
+    `cc`: stdin cost.total_cost_usd (absent → $0.00)
+    `both`: side-by-side `($X cc / $Y cctally) session`
+    """
+    def _cctally_usable() -> Optional[float]:
+        # We require BOTH session_id (for the cache lookup key) AND
+        # transcript_path (proxy for "we trust the local cache" — its
+        # presence means CC believes a local transcript exists, so the
+        # session-entry cache should have ingested it). Future readers:
+        # don't drop the transcript guard without re-thinking that
+        # invariant.
+        if not inp.session_id or not inp.transcript_path:
+            return None
+        return inj.cctally_session_cost(inp.session_id)
+
+    cc = float(inp.cost_total_usd) if inp.cost_total_usd is not None else 0.0
+
+    if cost_source == "cctally":
+        v = _cctally_usable()
+        return f"{_fmt_usd(v if v is not None else 0.0)} session"
+    if cost_source == "cc":
+        return f"{_fmt_usd(cc)} session"
+    if cost_source == "both":
+        cct = _cctally_usable()
+        cct_val = cct if cct is not None else 0.0
+        return f"({_fmt_usd(cc)} cc / {_fmt_usd(cct_val)} cctally) session"
+    # auto (and any other value falls into auto behavior)
+    cct = _cctally_usable()
+    if cct is not None:
+        return f"{_fmt_usd(cct)} session"
+    return f"{_fmt_usd(cc)} session"
+
+
+def resolve_today_cost(
+    inp: StatuslineInput,
+    display_tz_name: str,
+    now: datetime,
+    inj: StatuslineInjections,
+) -> str:
+    """Segment 2 middle slot — `today`. Always cctally-source."""
+    cost = inj.today_cost(display_tz_name, now)
+    return f"{_fmt_usd(cost)} today"
+
+
+def _fmt_block_remaining(seconds: int) -> str:
+    s = max(seconds, 0)
+    h = s // 3600
+    m = (s % 3600) // 60
+    return f"{h}h {m}m left"
+
+
+def resolve_block_segment(
+    inp: StatuslineInput,
+    now: datetime,
+    inj: StatuslineInjections,
+) -> "tuple[str, tuple[float, int]]":
+    """Segment 2 tail slot — `block (Xh Ym left)`.
+
+    Returns the formatted segment string AND a tuple
+    ``(block_cost, elapsed_seconds)`` for the downstream burn-rate
+    resolver.
+    """
+    blk = inj.active_block(now)
+    if blk is None:
+        # No active block — clamp to 5h0m left, $0.00.
+        return ("$0.00 block (5h 0m left)", (0.0, 1))
+    cost, remaining_s, elapsed_s = blk
+    seg = f"{_fmt_usd(cost)} block ({_fmt_block_remaining(remaining_s)})"
+    return (seg, (cost, max(elapsed_s, 1)))
+
+
+# ---- Segment 3: burn rate -------------------------------------------------
+
+
+# Burn rate bands (mirrors ccusage at the time of writing). A future
+# bump-to-match-ccusage PR is a one-tuple edit.
+STATUSLINE_BURN_RATE_BANDS = (
+    # (upper_bound_exclusive_usd_per_hr, emoji, text)
+    (15.00, "🟢", "Normal"),
+    (30.00, "🟡", "Moderate"),
+    (float("inf"), "🔴", "High"),
+)
+
+
+def resolve_burn_rate(
+    block_cost: float,
+    elapsed_seconds: int,
+    visual: str,
+    color: bool,  # color injection deferred to render_statusline; passthrough here
+) -> str:
+    """Segment 3 — `🔥 $X.XX/hr [visual]`.
+
+    ``visual`` ∈ {off, emoji, text, emoji-text}.
+    """
+    rate = block_cost / max(elapsed_seconds, 1) * 3600.0
+    base = f"🔥 {_fmt_usd(rate)}/hr"
+    if visual == "off":
+        return base
+    # Find band.
+    emoji = text = ""
+    for upper, e, t in STATUSLINE_BURN_RATE_BANDS:
+        if rate < upper:
+            emoji, text = e, t
+            break
+    if visual == "emoji":
+        return f"{base} {emoji}"
+    if visual == "text":
+        return f"{base} ({text})"
+    # emoji-text
+    return f"{base} {emoji} ({text})"
+
+
+# ---- Segment 4: context % -------------------------------------------------
+
+
+def resolve_context_pct(
+    inp: StatuslineInput,
+    args: StatuslineArgs,
+    inj: StatuslineInjections,
+) -> str:
+    """Segment 4 — `🧠 X%` or `🧠 N/A`.
+
+    Color band selection is the render kernel's job, not this resolver —
+    this function only returns the plain `🧠 X%` form. ``render_statusline``
+    wraps the result in ANSI color codes per ``args.color``.
+    """
+    pct = inj.context_pct(inp.transcript_path, inp.model_id)
+    if pct is None:
+        return "🧠 N/A"
+    return f"🧠 {int(round(pct))}%"
+
+
+# ---- Segment 5: cctally extensions ----------------------------------------
+
+
+def _fmt_countdown(seconds: int) -> str:
+    """Human-friendly countdown — same shape as the user's bash
+    statusline-command.sh: `Xd Yh`, `Xh Ym`, or `Xm`.
+    """
+    s = max(seconds, 0)
+    days = s // 86400
+    hours = (s % 86400) // 3600
+    minutes = (s % 3600) // 60
+    if days > 0:
+        return f"{days}d {hours}h"
+    if hours > 0:
+        return f"{hours}h {minutes}m"
+    return f"{minutes}m"
+
+
+def resolve_cctally_extensions(
+    inp: StatuslineInput,
+    now: datetime,
+    inj: StatuslineInjections,
+) -> Optional[str]:
+    """Segment 5 — cctally-only `5h X% (...) · 7d Y% (...)`.
+
+    Source priority chain (spec §3.5):
+        1. stdin rate_limits (preferred — freshest)
+        2. DB latest weekly_usage_snapshots row (if stdin EMPTY)
+        3. HWM monotonic clamp (within window only)
+        4. If all empty → return None (segment 5 suppressed)
+    """
+    five_pct = inp.rate_limits_5h_pct
+    five_resets = inp.rate_limits_5h_resets_at
+    seven_pct = inp.rate_limits_7d_pct
+    seven_resets = inp.rate_limits_7d_resets_at
+
+    # If stdin entirely empty, try DB fallback.
+    stdin_empty = (
+        five_pct is None and five_resets is None
+        and seven_pct is None and seven_resets is None
+    )
+    if stdin_empty:
+        db = inj.db_latest_rate_limits()
+        if db is not None:
+            five_pct, five_resets, seven_pct, seven_resets = db
+
+    # HWM clamp — monotonic UP only.
+    hwm_5h, hwm_7d = inj.hwm_clamp(five_resets, seven_resets)
+    if five_pct is not None and hwm_5h is not None and hwm_5h > five_pct:
+        five_pct = hwm_5h
+    if seven_pct is not None and hwm_7d is not None and hwm_7d > seven_pct:
+        seven_pct = hwm_7d
+
+    # Suppress segment 5 if nothing to render.
+    if five_pct is None and seven_pct is None:
+        return None
+
+    now_epoch = int(now.timestamp())
+    parts = []
+    if five_pct is not None:
+        s = f"5h {int(round(five_pct))}%"
+        if five_resets is not None:
+            s += f" ({_fmt_countdown(five_resets - now_epoch)})"
+        parts.append(s)
+    if seven_pct is not None:
+        s = f"7d {int(round(seven_pct))}%"
+        if seven_resets is not None:
+            s += f" ({_fmt_countdown(seven_resets - now_epoch)})"
+        parts.append(s)
+    return " · ".join(parts)
+
+
+# ---- Top-level render -----------------------------------------------------
+
+
+# ANSI color codes (only emitted when args.color is True).
+_ANSI = {
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "red": "\033[31m",
+    "reset": "\033[0m",
+}
+
+
+def _wrap_color(text: str, color: Optional[str], enable: bool) -> str:
+    if not enable or color is None:
+        return text
+    return f"{_ANSI[color]}{text}{_ANSI['reset']}"
+
+
+_PERCENT_INT_RE = re.compile(r"(\d+)%")
+
+
+def render_statusline(
+    inp: StatuslineInput,
+    args: StatuslineArgs,
+    inj: StatuslineInjections,
+    now: datetime,
+) -> str:
+    """Top-level render chokepoint. Joins segments with ` | `; suppresses
+    None segments (currently only segment 5). See spec §1 for the exact
+    layout and §3 for the data flow.
+    """
+    seg1 = resolve_model_segment(inp)
+
+    # Segment 2: 💰 ... session / ... today / ... block (Xh Ym left)
+    session = resolve_session_cost(inp, args.cost_source, inj)
+    today = resolve_today_cost(inp, args.display_tz_name, now, inj)
+    block, burn_kwargs = resolve_block_segment(inp, now, inj)
+    seg2 = f"💰 {session} / {today} / {block}"
+
+    # Segment 3: 🔥 $X.XX/hr [visual]
+    seg3 = resolve_burn_rate(
+        burn_kwargs[0], burn_kwargs[1], args.visual_burn_rate, args.color
+    )
+
+    # Segment 4: 🧠 X% with color band
+    pct_text = resolve_context_pct(inp, args, inj)
+    if pct_text == "🧠 N/A":
+        seg4 = pct_text
+    else:
+        m = _PERCENT_INT_RE.search(pct_text)
+        n = int(m.group(1)) if m else 0
+        if n < args.context_low_threshold:
+            color = "green"
+        elif n < args.context_medium_threshold:
+            color = "yellow"
+        else:
+            color = "red"
+        seg4 = _wrap_color(pct_text, color, args.color)
+
+    # Segment 5: cctally extension (may be None)
+    seg5 = None
+    if args.cctally_extensions:
+        ext = resolve_cctally_extensions(inp, now, inj)
+        if ext is not None:
+            # Color by the higher of (5h%, 7d%) using cctally bands:
+            # <60 green, <85 yellow, >=85 red.
+            nums = [int(x) for x in _PERCENT_INT_RE.findall(ext)]
+            mx = max(nums) if nums else 0
+            if mx < 60:
+                color = "green"
+            elif mx < 85:
+                color = "yellow"
+            else:
+                color = "red"
+            seg5 = _wrap_color(ext, color, args.color)
+
+    segs = [seg1, seg2, seg3, seg4]
+    if seg5 is not None:
+        segs.append(seg5)
+    return " | ".join(segs)