cctally 1.7.0 → 1.7.1

package/bin/_lib_display_tz.py

@@ -0,0 +1,361 @@
+"""Display-timezone primitives — the datetime render chokepoint.
+
+Pure-fn layer (no I/O at import time): holds every helper that resolves a
+display tz from CLI args / config, localizes a datetime through that
+resolution, and formats it for human display. `format_display_dt` is the
+chokepoint per CLAUDE.md — all human-displayed datetimes route through it.
+
+`bin/cctally` re-exports every symbol below so internal call sites resolve
+unchanged. Future pure layers (alerts payload, render, aggregators) import
+the chokepoint from here directly via `_load_sibling("_lib_display_tz")`,
+so they stay pure without back-importing `cctally`.
+
+Module-level flags `_DISPLAY_TZ_BAD_CONFIG_WARNED` and
+`_DISPLAY_TZ_RESOLVE_WARNED` move with their owning functions; the
+`global` declarations work fine in the new module. A private `_eprint`
+duplicates `bin/cctally:eprint` (two-line stderr helper) so this pure
+layer carries zero back-imports per the split design's §5.3 contract.
+
+Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import os
+import sys
+from typing import Any
+
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+def _eprint(*args: Any) -> None:
+    print(*args, file=sys.stderr)
+
+
+def _local_tz_name() -> str:
+    """Return an IANA timezone name if resolvable, else a best-effort fallback.
+
+    Used in Codex command title banners ("(Timezone: <name>)"). Upstream
+    uses IANA names (e.g. "Asia/Jerusalem"); we mirror when possible.
+    """
+    # Preferred: TZ env var if IANA-looking ("/" in the value).
+    tz = os.environ.get("TZ", "")
+    if tz and "/" in tz:
+        return tz
+    try:
+        tz_path = os.readlink("/etc/localtime")
+        if "zoneinfo/" in tz_path:
+            return tz_path.split("zoneinfo/", 1)[1]
+    except (OSError, ValueError):
+        pass
+    # Fallback: time.tzname[0] (e.g. "IST"); may be non-IANA.
+    try:
+        import time as _time
+        return _time.tzname[0] or ""
+    except Exception:
+        return ""
+
+
+def _resolve_tz(tz_name: str | None, *, strict_iana: bool = False, fallback: Any = None) -> Any:
+    """Return ZoneInfo(tz_name) or ``fallback``. Callers have already validated
+    the tz via _parse_cli_date_range; this is a defensive re-resolve that
+    falls back to ``fallback`` on any error so aggregators never crash.
+
+    With ``strict_iana=True``, names lacking a "/" (e.g. bare "UTC") are
+    rejected up-front and ``fallback`` is returned instead — mirrors
+    ``_local_tz_name``'s gating to avoid the bare-UTC gotcha (see CLAUDE.md).
+    Default behavior (strict_iana=False, fallback=None) preserves the prior
+    contract for existing callers.
+    """
+    if not tz_name:
+        return fallback
+    if strict_iana and "/" not in tz_name:
+        return fallback
+    try:
+        return ZoneInfo(tz_name)
+    except (ZoneInfoNotFoundError, ValueError, OSError):
+        return fallback
+
+
+DISPLAY_TZ_DEFAULT = "local"
+_DISPLAY_TZ_BAD_CONFIG_WARNED = False  # one-shot warning flag
+
+
+def normalize_display_tz_value(raw: "str | None") -> str:
+    """Canonicalize a display-tz value to "local" | "utc" | <IANA>.
+
+    - None / "" / case-insensitive "local" -> "local"
+    - case-insensitive "utc" -> "utc"
+    - anything else: must be a valid IANA name (validated via _resolve_tz
+      with strict_iana=True). Returns the trimmed value verbatim.
+    Raises ValueError on invalid input.
+    """
+    if raw is None:
+        return "local"
+    s = str(raw).strip()
+    if not s:
+        return "local"
+    low = s.lower()
+    if low == "local":
+        return "local"
+    if low == "utc":
+        return "utc"
+    sentinel = object()
+    if _resolve_tz(s, strict_iana=True, fallback=sentinel) is sentinel:
+        raise ValueError(f"invalid IANA zone: {s!r}")
+    return s
+
+
+def _config_has_explicit_display_tz(config: "dict | None") -> bool:
+    """Return True iff `config["display"]["tz"]` is present and non-None.
+
+    Used by codex command tz-name resolution (F2): we need to distinguish
+    "user pinned a display tz" from "default 'local' fallback because no
+    config block is set" so upstream's `--timezone` can still apply in the
+    drop-in-parity case where neither --tz nor display.tz was specified.
+    """
+    if not isinstance(config, dict):
+        return False
+    block = config.get("display")
+    return isinstance(block, dict) and block.get("tz") is not None
+
+
+def get_display_tz_pref(config: "dict | None") -> str:
+    """Read config['display']['tz']; default DISPLAY_TZ_DEFAULT.
+
+    Malformed value -> fall back to default with one-shot stderr warning.
+    Never raises.
+    """
+    global _DISPLAY_TZ_BAD_CONFIG_WARNED
+    if not isinstance(config, dict):
+        return DISPLAY_TZ_DEFAULT
+    block = config.get("display")
+    if not isinstance(block, dict):
+        return DISPLAY_TZ_DEFAULT
+    raw = block.get("tz")
+    if raw is None:
+        return DISPLAY_TZ_DEFAULT
+    try:
+        return normalize_display_tz_value(raw)
+    except ValueError:
+        if not _DISPLAY_TZ_BAD_CONFIG_WARNED:
+            _eprint(
+                f"warning: ignoring malformed display.tz {raw!r} in config; "
+                f"using {DISPLAY_TZ_DEFAULT!r}"
+            )
+            _DISPLAY_TZ_BAD_CONFIG_WARNED = True
+        return DISPLAY_TZ_DEFAULT
+
+
+def resolve_display_tz(args: argparse.Namespace,
+                       config: "dict | None") -> "ZoneInfo | None":
+    """Returns ZoneInfo for fixed zones, None for "local" (caller does
+    bare astimezone()). Precedence: --tz flag > config > default.
+    Invalid --tz values are normalized via normalize_display_tz_value
+    (which raises ValueError -- caller is responsible for catching at
+    argparse-time via the shared _argparse_tz type=callable).
+    """
+    flag = getattr(args, "tz", None)
+    if flag is not None and str(flag).strip() != "":
+        canonical = normalize_display_tz_value(flag)  # may raise
+    else:
+        canonical = get_display_tz_pref(config)
+    if canonical == "local":
+        return None
+    if canonical == "utc":
+        return ZoneInfo("Etc/UTC")
+    return ZoneInfo(canonical)
+
+
+def display_tz_label(localized: dt.datetime) -> str:
+    """Returns the suffix label for an already-localized datetime.
+
+    Prefer ``localized.tzname()`` if alphanumeric and len <= 5; otherwise
+    fall back to a numeric offset via ``%z`` trimmed to "+HH" or "+HHMM".
+    Works uniformly across local / utc / explicit IANA -- caller has
+    already done astimezone() before passing in.
+    """
+    if localized.tzinfo is None:
+        # Defensive: shouldn't happen because callers localize first
+        localized = localized.replace(tzinfo=dt.timezone.utc)
+    name = localized.tzname() or ""
+    if (name
+            and name.replace("+", "").replace("-", "").isalnum()
+            and len(name) <= 5
+            and any(c.isalpha() for c in name)):
+        return name
+    # Numeric fallback. %z gives "+HHMM"; trim trailing "00" -> "+HH".
+    raw = localized.strftime("%z")
+    if not raw:
+        return "UTC"
+    if raw.endswith("00") and len(raw) == 5:
+        return raw[:-2]   # "+0500" -> "+05"
+    # Insert colon for readability when minutes != 00: "+0530" -> "+05:30"
+    if len(raw) == 5:
+        return f"{raw[:3]}:{raw[3:]}"
+    return raw
+
+
+def _localize(d: dt.datetime, tz: "ZoneInfo | None") -> dt.datetime:
+    """Localize a tz-aware datetime through the resolved display tz.
+
+    Mirrors ``format_display_dt``'s tz handling for callers that need a
+    localized ``dt.datetime`` (not a formatted string) — e.g. when the
+    same instant is fed to multiple ``strftime`` formats. ``tz=None``
+    falls back to host local via bare ``astimezone()``.
+    """
+    return d.astimezone(tz) if tz is not None else d.astimezone()
+
+
+_DISPLAY_TZ_RESOLVE_WARNED = False  # one-shot host-zone-fallback warning
+
+
+def _resolve_display_tz_obj(config: dict) -> ZoneInfo:
+    """Resolve config.display.tz to a concrete ZoneInfo object.
+
+    Single source of truth used by ``_compute_display_block`` and the
+    dashboard snapshot builders (``_tui_build_snapshot``,
+    ``_handle_get_block_detail``). Local-fallback case emits a one-shot
+    warning via ``_DISPLAY_TZ_RESOLVE_WARNED``. Returns a ZoneInfo
+    (never None).
+    """
+    global _DISPLAY_TZ_RESOLVE_WARNED
+    pref = get_display_tz_pref(config)
+    if pref == "local":
+        host_iana = _local_tz_name()
+        if host_iana and "/" in host_iana:
+            return ZoneInfo(host_iana)
+        if not _DISPLAY_TZ_RESOLVE_WARNED:
+            _eprint(
+                "warning: display.tz='local' but host IANA zone could "
+                "not be resolved; using Etc/UTC. Set TZ to an IANA "
+                "name (e.g. America/New_York) to fix."
+            )
+            _DISPLAY_TZ_RESOLVE_WARNED = True
+        return ZoneInfo("Etc/UTC")
+    if pref == "utc":
+        return ZoneInfo("Etc/UTC")
+    try:
+        return ZoneInfo(pref)
+    except Exception:
+        # Defense in depth -- pref was already canonicalized via
+        # normalize_display_tz_value, but if a stale config slipped
+        # through, fall back rather than crash.
+        if not _DISPLAY_TZ_RESOLVE_WARNED:
+            _eprint(
+                f"warning: display.tz={pref!r} could not be loaded as "
+                f"a ZoneInfo; using Etc/UTC"
+            )
+            _DISPLAY_TZ_RESOLVE_WARNED = True
+        return ZoneInfo("Etc/UTC")
+
+
+def _apply_display_tz_override(
+    config: dict,
+    override: "str | None",
+) -> dict:
+    """Return a shallow-copied config with `display.tz` substituted from
+    the override (F3 fix).
+
+    `--tz` on `cctally dashboard` should win over the persisted
+    `config.display.tz` for the lifetime of the server. Plumbing the
+    canonicalized string here lets every reader that already calls
+    `load_config()` (envelope builder, snapshot builder, block-detail
+    handler) pick up the override by routing the loaded config through
+    this thin wrapper -- without changing their existing
+    `_resolve_display_tz_obj(load_config())` shape.
+
+    Override semantics: a canonical token from
+    ``normalize_display_tz_value`` (``"local"`` / ``"utc"`` / IANA
+    name). ``None`` means "no override; let config win" -- the input
+    config is returned unchanged. Always returns a fresh dict so callers
+    can't mutate the passed-in config via the result.
+    """
+    if override is None:
+        return config
+    out = dict(config)
+    out["display"] = dict(out.get("display") or {})
+    out["display"]["tz"] = override
+    out["display"]["pinned"] = True
+    return out
+
+
+def _compute_display_block(config: dict, generated_at: dt.datetime) -> dict:
+    """Compute the dashboard envelope's ``display`` block.
+
+    Resolves ``config.display.tz`` to a CONCRETE IANA name server-side
+    (F1 fix per spec) so the browser never has to guess "local". Also
+    computes the offset label and signed offset seconds at the snapshot
+    timestamp, so the client can label times consistently with the
+    server-rendered week_lbl / block labels.
+
+    Resolution flows through ``_resolve_display_tz_obj`` -- the same
+    helper that ``_tui_build_snapshot`` and ``_handle_get_block_detail``
+    use, so all three sites share warn-once stderr semantics.
+    """
+    pref = get_display_tz_pref(config)
+    resolved_obj = _resolve_display_tz_obj(config)
+    resolved_iana = resolved_obj.key
+
+    if generated_at.tzinfo is None:
+        generated_at = generated_at.replace(tzinfo=dt.timezone.utc)
+    localized = generated_at.astimezone(resolved_obj)
+    offset = localized.utcoffset()
+    offset_seconds = int(offset.total_seconds()) if offset is not None else 0
+    block: dict = {
+        "tz":              pref,
+        "resolved_tz":     resolved_iana,
+        "offset_label":    display_tz_label(localized),
+        "offset_seconds":  offset_seconds,
+    }
+    # F3: surface --tz-pin so the React client can render a read-only
+    # state for the Settings UI when the operator launched the server
+    # with an explicit --tz override. Override application leaves the
+    # `pinned` key on `config["display"]`; we forward it as a runtime
+    # signal (NOT persisted into config.json -- POST /api/settings is
+    # blocked under pin in this mode).
+    display_cfg = config.get("display") if isinstance(config, dict) else None
+    if isinstance(display_cfg, dict) and display_cfg.get("pinned"):
+        block["pinned"] = True
+    return block
+
+
+def format_display_dt(value: "str | dt.datetime",
+                      tz: "ZoneInfo | None",
+                      *, fmt: str, suffix: bool = True) -> str:
+    """Targeted-swap chokepoint. Naive value treated as UTC.
+
+    Output: "<strftime fmt> <suffix>" when suffix=True, else just the
+    strftime. Suffix is computed from the localized datetime via
+    display_tz_label.
+    """
+    if isinstance(value, str):
+        s = value.replace("Z", "+00:00")
+        parsed = dt.datetime.fromisoformat(s)
+    else:
+        parsed = value
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    localized = parsed.astimezone(tz) if tz is not None else parsed.astimezone()
+    body = localized.strftime(fmt)
+    if not suffix:
+        return body
+    return f"{body} {display_tz_label(localized)}"
+
+
+def _argparse_tz(value: str) -> str:
+    """argparse ``type=`` callable for ``--tz`` on any subcommand.
+
+    Canonicalizes via ``normalize_display_tz_value``: returns "local",
+    "utc", or a verbatim IANA name. Bad input raises
+    ``argparse.ArgumentTypeError`` so argparse formats a standard
+    ``error: argument --tz: ...`` message and exits 2.
+    """
+    try:
+        return normalize_display_tz_value(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"invalid timezone {value!r} -- expected 'local', 'utc', "
+            f"or an IANA name"
+        )

package/bin/_lib_doctor.py

@@ -49,6 +49,17 @@ class DoctorState:
     cache_entries_count: Optional[int]
     cache_last_entry_at: Optional[dt.datetime]
     claude_jsonl_present: bool
+    # Forked-bucket invariant counts (data.forked_buckets check).
+    # Keys: "usage", "cost", "milestones" — each maps to the count of
+    # rows in the respective table where ``week_start_at IS NOT NULL``
+    # AND ``week_start_date != substr(week_start_at, 1, 10)``. None
+    # means the stats.db couldn't be opened to check; the migration
+    # ``004_heal_forked_week_start_date_buckets`` auto-merges any
+    # detected rows on the next ``open_db()``, so a non-zero count
+    # here indicates either (a) the migration is gated as
+    # skipped/failed/pending or (b) a buggy writer slipped through
+    # after the migration ran.
+    forked_bucket_counts: Optional[dict]
     codex_entries_count: Optional[int]
     codex_last_entry_at: Optional[dt.datetime]
     codex_jsonl_present: bool
@@ -502,6 +513,52 @@ def _check_data_codex_cache(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_data_forked_buckets(s: DoctorState) -> CheckResult:
+    """Invariant: for every row with ``week_start_at IS NOT NULL``,
+    ``week_start_date == substr(week_start_at, 1, 10)``.
+
+    Pair with migration ``004_heal_forked_week_start_date_buckets``,
+    which auto-merges any detected rows on the next ``open_db()``. A
+    non-zero count here means either (a) the migration is gated as
+    skipped/failed/pending or (b) a buggy writer slipped through
+    after the migration ran. Either way the user has a fork that
+    needs attention.
+    """
+    counts = s.forked_bucket_counts
+    if counts is None:
+        return CheckResult(
+            id="data.forked_buckets", title="Forked week buckets",
+            severity="fail", summary="state unavailable",
+            remediation="Check stats.db opens (`cctally db status`)",
+            details={"reason": "gather returned None"},
+        )
+    total = sum(int(counts.get(k, 0)) for k in ("usage", "cost", "milestones"))
+    if total == 0:
+        return CheckResult(
+            id="data.forked_buckets", title="Forked week buckets",
+            severity="ok", summary="none",
+            remediation=None,
+            details=dict(counts),
+        )
+    parts = [
+        f"{counts.get(k, 0)} {k}"
+        for k in ("usage", "cost", "milestones")
+        if counts.get(k, 0)
+    ]
+    return CheckResult(
+        id="data.forked_buckets", title="Forked week buckets",
+        severity="fail",
+        summary=f"{total} forked row(s): {', '.join(parts)}",
+        remediation=(
+            "Run any cctally command to trigger the auto-heal migration "
+            "(`004_heal_forked_week_start_date_buckets`); if it's already "
+            "applied, see `cctally db status`."
+        ),
+        details=dict(counts),
+    )
+
+
+
 _LOOPBACK_HOSTS = frozenset({"loopback", "127.0.0.1", "::1", "localhost"})
 
 
@@ -728,6 +785,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("data.latest_snapshot_age", "_check_data_latest_snapshot_age"),
         ("data.cache_sync_state", "_check_data_cache_sync_state"),
         ("data.codex_cache", "_check_data_codex_cache"),
+        ("data.forked_buckets", "_check_data_forked_buckets"),
     )),
     ("safety", "Safety", (
         ("safety.dashboard_bind", "_check_safety_dashboard_bind"),

package/bin/_lib_five_hour.py

@@ -0,0 +1,82 @@
+"""5-hour window canonical-key primitives.
+
+Pure-fn layer (no I/O at import time): holds the two jitter-tolerant
+floors that route every 5h-window identity decision through a single
+granularity. `_canonical_5h_window_key` is the epoch-int chokepoint and
+`_floor_to_ten_minutes` the datetime equivalent — CLAUDE.md's "5h window
+key MUST go through `_canonical_5h_window_key`" invariant lives here.
+
+Both helpers share `_FIVE_HOUR_JITTER_FLOOR_SECONDS = 600` so neither can
+drift independently; the regression `bin/cctally-5h-canonical-test`
+pins the cross-shape equivalence (epoch-int → datetime → epoch round-trip
+matches the modulo floor on 600-aligned base epochs).
+
+`bin/cctally` re-exports every symbol below so internal call sites and
+SourceFileLoader-based tests/fixtures (`tests/test_blocks_recorded_anchor`,
+`tests/test_five_hour_block_selector`, `tests/test_five_hour_blocks_json`,
+`tests/test_five_hour_breakdown`, `bin/cctally-5h-canonical-test`,
+`bin/cctally-record-usage-selfheal-test`) resolve unchanged. No
+cross-sibling dependencies — this is a true leaf in the sibling graph.
+
+Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
+"""
+from __future__ import annotations
+
+import datetime as dt
+
+
+_FIVE_HOUR_JITTER_FLOOR_SECONDS = 600  # 10 minutes; tolerance band for resets_at jitter
+
+
+def _floor_to_ten_minutes(d: dt.datetime) -> dt.datetime:
+    """Floor a datetime to the previous 10-minute boundary.
+
+    Anthropic ``rate_limits.5h.resets_at`` arrives via the status line
+    with capture jitter and occasional transient bogus values that
+    differ from the real reset by tens of minutes (a brief mid-window
+    glitch sitting alongside the genuine reset). A 10-minute floor
+    collapses fine-grained jitter into shared buckets while leaving
+    truly distinct windows separable; structural conflicts that survive
+    the floor are resolved downstream by
+    ``_select_non_overlapping_recorded_windows``.
+    """
+    minute_bucket = _FIVE_HOUR_JITTER_FLOOR_SECONDS // 60
+    return d.replace(
+        minute=(d.minute // minute_bucket) * minute_bucket,
+        second=0, microsecond=0,
+    )
+
+
+def _canonical_5h_window_key(
+    resets_at_epoch: int,
+    prior_epoch: int | None = None,
+    prior_key: int | None = None,
+) -> int:
+    """Floor a 5h-window resets_at epoch to a jitter-tolerant canonical key.
+
+    Anthropic's status-line API jitters resets_at by ~seconds within the same
+    physical 5h window. Any code identifying 'this 5h window' across consecutive
+    fetches MUST derive its key via this function. Floor granularity matches
+    _floor_to_ten_minutes (the same tolerance already used for weekly_reset_events).
+
+    Required invariant: two ``record-usage`` calls with ``resets_at`` differing
+    by ≤ 599 seconds MUST resolve to the same window key. A pure modulo floor
+    cannot satisfy this when the two epochs straddle a 600-second bucket
+    boundary (e.g. 1746014999 → 1746014400 vs. 1746015000 → 1746015000, a
+    1-second delta producing different keys).
+
+    The optional ``prior_epoch`` / ``prior_key`` arguments close that gap: when
+    callers can supply the most-recent stored sample's raw ``five_hour_resets_at``
+    and its persisted ``five_hour_window_key``, the function reuses ``prior_key``
+    whenever ``|resets_at_epoch - prior_epoch| < _FIVE_HOUR_JITTER_FLOOR_SECONDS``
+    — boundary-straddling jitter then collapses to the first-seen anchor instead
+    of forking a new key. With no anchor (or with the anchor too far away to be
+    the same physical window), falls back to the pure floor.
+    """
+    if (
+        prior_epoch is not None
+        and prior_key is not None
+        and abs(resets_at_epoch - prior_epoch) < _FIVE_HOUR_JITTER_FLOOR_SECONDS
+    ):
+        return prior_key
+    return resets_at_epoch - (resets_at_epoch % _FIVE_HOUR_JITTER_FLOOR_SECONDS)