cctally 1.80.4 → 1.82.0

package/bin/_lib_alerts_payload.py

@@ -54,6 +54,15 @@ def _load_lib(name: str):
 _lib_display_tz = _load_lib("_lib_display_tz")
 format_display_dt = _lib_display_tz.format_display_dt
 
+# Account dimension (#341): every alert payload carries the account_key it wrote
+# under as a TOP-LEVEL field (never in `context`, to avoid touching any
+# context-serialized golden). Real-account families default to the sentinel;
+# vendor-wide families default to `*`. `_dispatch_alert_notification` reads it for
+# the unconditional 8th `alerts.log` field + the R8 `[label]` title prefix.
+_lib_accounts = _load_lib("_lib_accounts")
+_UNATTRIBUTED = _lib_accounts.UNATTRIBUTED
+_VENDOR_WIDE = _lib_accounts.VENDOR_WIDE
+
 
 def _alert_text_weekly(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
     """Build (title, subtitle, body) for a weekly threshold alert.
@@ -137,6 +146,7 @@ def _build_alert_payload_weekly(
     week_start_date: str,
     cumulative_cost_usd: float,
     dollars_per_percent: "float | None",
+    account_key: str = _UNATTRIBUTED,
 ) -> dict:
     """Build the alert payload for a weekly threshold crossing.
 
@@ -144,14 +154,15 @@ def _build_alert_payload_weekly(
     sets the DB ``alerted_at`` BEFORE invoking ``_dispatch_alert_notification``
     (set-then-dispatch invariant, spec §3.2). Consumers (envelope builders,
     test inspectors) read the ``alerted_at`` field as the authoritative
-    "alert was attempted" timestamp.
-    """
+    "alert was attempted" timestamp. ``account_key`` (#341) is the real account
+    the crossing wrote under (per-account family)."""
     return {
         "id": f"weekly:{week_start_date}:{threshold}",
         "axis": "weekly",
         "threshold": int(threshold),
         "crossed_at": crossed_at_utc,
         "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "account_key": str(account_key),
         "context": {
             "week_start_date": week_start_date,
             "cumulative_cost_usd": float(cumulative_cost_usd),
@@ -170,6 +181,7 @@ def _build_alert_payload_five_hour(
     block_start_at: str,
     block_cost_usd: float,
     primary_model: "str | None",
+    account_key: str = _UNATTRIBUTED,
 ) -> dict:
     """Build the alert payload for a 5h-block threshold crossing.
 
@@ -177,14 +189,15 @@ def _build_alert_payload_five_hour(
     rationale. ``primary_model`` is the highest-cost model active in the
     block (resolved via ``_resolve_primary_model_for_block``); ``None`` when
     the rollup-children child table is empty (e.g., direct-JSONL-fallback
-    path before lazy backfill).
-    """
+    path before lazy backfill). ``account_key`` (#341) is the block's account
+    (per-account family)."""
     return {
         "id": f"five_hour:{five_hour_window_key}:{threshold}",
         "axis": "five_hour",
         "threshold": int(threshold),
         "crossed_at": crossed_at_utc,
         "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "account_key": str(account_key),
         "context": {
             "five_hour_window_key": int(five_hour_window_key),
             "block_start_at": block_start_at,
@@ -223,6 +236,7 @@ def _build_alert_payload_budget(
     spent_usd: float,
     consumption_pct: float,
     period: str = "subscription-week",
+    account_key: str = _VENDOR_WIDE,
 ) -> dict:
     """Build the alert payload for an equiv-$ budget threshold crossing.
 
@@ -245,6 +259,7 @@ def _build_alert_payload_budget(
         "threshold": int(threshold),
         "crossed_at": crossed_at_utc,
         "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "account_key": str(account_key),
         "context": {
             "week_start_at": week_start_at,
             "period": str(period),
@@ -296,6 +311,7 @@ def _build_alert_payload_project_budget(
     budget_usd: float,
     spent_usd: float,
     consumption_pct: float,
+    account_key: str = _VENDOR_WIDE,
 ) -> dict:
     """Build the alert payload for a PER-PROJECT equiv-$ budget threshold
     crossing (axis ``project_budget``, the fifth alert axis; spec §5.3).
@@ -315,6 +331,7 @@ def _build_alert_payload_project_budget(
         "threshold": int(threshold),
         "crossed_at": crossed_at_utc,
         "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "account_key": str(account_key),
         "context": {
             "week_start_at": week_start_at,
             "project": project,
@@ -369,6 +386,7 @@ def _build_alert_payload_codex_budget(
     budget_usd: float,
     spent_usd: float,
     consumption_pct: float,
+    account_key: str = _VENDOR_WIDE,
 ) -> dict:
     """Build the alert payload for a Codex budget threshold crossing (axis
     ``codex_budget``, the sixth alert axis; spec §6).
@@ -388,6 +406,7 @@ def _build_alert_payload_codex_budget(
         "threshold": int(threshold),
         "crossed_at": crossed_at_utc,
         "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "account_key": str(account_key),
         "context": {
             "period": str(period),
             "period_start_at": period_start_at,
@@ -442,6 +461,7 @@ def _build_alert_payload_projected(
     projected_value: float,
     denominator: float,
     week_start_at: str,
+    account_key: str = _VENDOR_WIDE,
 ) -> dict:
     """Build the alert payload for a projected-pace threshold crossing (#121).
 
@@ -464,6 +484,7 @@ def _build_alert_payload_projected(
         "threshold": int(threshold),
         "projected_value": float(projected_value),
         "denominator": float(denominator),
+        "account_key": str(account_key),
         "context": {
             "week_start_at": week_start_at,
             "metric": str(metric),

package/bin/_lib_cache_writer_lock.py

@@ -0,0 +1,77 @@
+"""Ordered cross-process writer locks for the shared cache.db family.
+
+Every cache.db mutator takes the global writer lock first. Codex mutators then
+take the provider lock before opening a SQLite write transaction. A single
+deadline covers the complete lock set so adding the provider lock cannot double
+the caller's bounded-wait contract.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import time
+from pathlib import Path
+
+
+def acquire_ordered_flocks(
+    locks: list[tuple[Path, int]],
+    *,
+    timeout: float | None = None,
+) -> list[int] | None:
+    """Acquire ``(path, LOCK_SH|LOCK_EX)`` entries in caller-supplied order."""
+    deadline = None if timeout is None else time.monotonic() + max(timeout, 0.0)
+    held: list[int] = []
+    try:
+        for path, mode in locks:
+            fd = os.open(str(path), os.O_RDWR | os.O_CREAT, 0o600)
+            os.fchmod(fd, 0o600)
+            held.append(fd)
+            while True:
+                try:
+                    fcntl.flock(fd, mode | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    if deadline is None or time.monotonic() >= deadline:
+                        release_cache_writer_flocks(held)
+                        return None
+                    time.sleep(min(0.2, max(0.0, deadline - time.monotonic())))
+        return held
+    except BaseException:
+        release_cache_writer_flocks(held)
+        raise
+
+
+def acquire_cache_writer_flocks(
+    writer_path: Path,
+    provider_path: Path | None = None,
+    *,
+    timeout: float | None = None,
+) -> list[int] | None:
+    """Acquire global then optional provider flock, or return ``None``.
+
+    ``timeout=None`` performs one non-blocking attempt for the entire set.
+    A non-negative timeout bounds the complete acquisition, not each lock.
+    Returned descriptors must be released with
+    :func:`release_cache_writer_flocks`.
+    """
+    paths = [writer_path]
+    if provider_path is not None and provider_path != writer_path:
+        paths.append(provider_path)
+    return acquire_ordered_flocks(
+        [(path, fcntl.LOCK_EX) for path in paths],
+        timeout=timeout,
+    )
+
+
+def release_cache_writer_flocks(held: list[int]) -> None:
+    """Release an acquired lock set in reverse order."""
+    for fd in reversed(held):
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        try:
+            os.close(fd)
+        except OSError:
+            pass

package/bin/_lib_codex_hooks.py

@@ -301,12 +301,43 @@ def codex_hook_roots(paths: list[pathlib.Path]) -> list[CodexHookRoot]:
     return [roots[key] for key in sorted(roots)]
 
 
+def _resolve_codex_hook_account(root: CodexHookRoot) -> str:
+    """Resolve one hook root's active account_key from ``<home>/auth.json`` via
+    the stable-read protocol (#341, spec §1). identified -> the real key;
+    stably-absent (no auth / api-key mode) OR torn -> the ``unattributed``
+    sentinel (so the throttle marker keeps its byte-stable name). Read-only."""
+    import _lib_accounts
+
+    def _reader(data: bytes):
+        try:
+            obj = json.loads(data)
+        except (ValueError, TypeError):
+            raise _lib_accounts.TornRead()
+        if not isinstance(obj, dict):
+            raise _lib_accounts.TornRead()
+        tokens = obj.get("tokens")
+        id_token = (tokens.get("id_token") if isinstance(tokens, dict)
+                    else obj.get("id_token"))
+        payload = _lib_accounts.decode_id_token_payload(id_token)
+        nat = _lib_accounts.codex_natural_id(payload)
+        if nat is None:
+            return None
+        return _lib_accounts.account_key("codex", nat)
+
+    result = _lib_accounts.stable_read_identity(
+        str(root.codex_home / "auth.json"), _reader)
+    if result.status == "identified":
+        return str(result.value)
+    return _lib_accounts.UNATTRIBUTED
+
+
 def acquire_due_lifecycle_locks(
     app_dir: pathlib.Path,
     roots: list[CodexHookRoot],
     *,
     now: float,
     throttle_seconds: float = CODEX_HOOK_THROTTLE_SECONDS,
+    account_resolver: "Callable[[CodexHookRoot], str] | None" = None,
 ) -> list[CodexLifecycleLock]:
     base = app_dir / "codex-hook-tick"
     base.mkdir(parents=True, exist_ok=True, mode=0o700)
@@ -314,10 +345,18 @@ def acquire_due_lifecycle_locks(
         os.chmod(base, 0o700)
     except OSError:
         pass
+    resolve_account = account_resolver or _resolve_codex_hook_account
     held: list[CodexLifecycleLock] = []
     for root in sorted(roots, key=lambda item: item.source_root_key):
         lock_path = base / f"{root.source_root_key}.lock"
-        marker_path = base / f"{root.source_root_key}.last-success"
+        # Throttle marker keys by (source_root_key, account_key) so a mid-interval
+        # account switch bypasses the PRIOR account's throttle (spec §1). The
+        # ``unattributed`` sentinel keeps the byte-stable legacy marker name (no
+        # account suffix) — single-account / no-auth installs are unchanged.
+        import _lib_accounts
+        account = resolve_account(root)
+        suffix = "" if account == _lib_accounts.UNATTRIBUTED else f".{account}"
+        marker_path = base / f"{root.source_root_key}{suffix}.last-success"
         fd = -1
         try:
             fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)

package/bin/_lib_diff_kernel.py

@@ -470,7 +470,8 @@ def _humanize_tokens(n: "int | None") -> str:
     return f"{sign}{a / 1_000_000_000:.1f}B"
 
 
-def _diff_iter_claude_entries(window: ParsedWindow, *, skip_sync: bool):
+def _diff_iter_claude_entries(window: ParsedWindow, *, skip_sync: bool,
+                             account_key=None):
     """Honor ParsedWindow's half-open semantics by trimming end_utc by 1 µs
     before passing into the inclusive-end shared cache helper.
 
@@ -479,10 +480,14 @@ def _diff_iter_claude_entries(window: ParsedWindow, *, skip_sync: bool):
     end-of-day semantics for date-only inputs — so we cannot tighten the
     helper's SQL. `ParsedWindow.end_utc` is documented exclusive, so trim
     by one microsecond locally to bridge the convention gap.
+
+    ``account_key`` (#341 --account) scopes the read to one account's stamped
+    entries; ``None`` = merged (byte-identical).
     """
     end_exclusive = window.end_utc - dt.timedelta(microseconds=1)
     return get_claude_session_entries(
-        window.start_utc, end_exclusive, skip_sync=skip_sync
+        window.start_utc, end_exclusive, skip_sync=skip_sync,
+        account_key=account_key,
     )
 
 
@@ -490,6 +495,7 @@ def _diff_aggregate_overall(
     window: ParsedWindow,
     *,
     skip_sync: bool = False,
+    account_key=None,
 ) -> MetricBundle:
     """Sum cost, tokens, and cache stats across all entries in `window`.
 
@@ -500,7 +506,8 @@ def _diff_aggregate_overall(
     """
     cost = 0.0
     ti = to = tcr = tcw = 0
-    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync):
+    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync,
+                                       account_key=account_key):
         if e.model == "<synthetic>":
             continue
         cost += _calculate_entry_cost(
@@ -532,10 +539,12 @@ def _diff_aggregate_models(
     window: ParsedWindow,
     *,
     skip_sync: bool = False,
+    account_key=None,
 ) -> dict:
     """Group entries by model id, aggregate to per-model MetricBundle."""
     buckets: dict = {}
-    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync):
+    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync,
+                                       account_key=account_key):
         if e.model == "<synthetic>":
             continue
         b = buckets.setdefault(e.model, {
@@ -568,12 +577,14 @@ def _diff_aggregate_projects(
     window: ParsedWindow,
     *,
     skip_sync: bool = False,
+    account_key=None,
     group_mode: str = "git-root",
 ) -> dict:
     """Group entries by ProjectKey.display_key (git-root resolved)."""
     resolver_cache: dict = {}
     buckets: dict = {}
-    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync):
+    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync,
+                                       account_key=account_key):
         if e.model == "<synthetic>":
             continue
         key = _resolve_project_key(e.project_path, group_mode, resolver_cache)
@@ -607,6 +618,7 @@ def _diff_aggregate_cache(
     window: ParsedWindow,
     *,
     skip_sync: bool = False,
+    account_key=None,
 ) -> dict:
     """Cache-active-entries scope: only entries that touched the cache.
 
@@ -619,7 +631,8 @@ def _diff_aggregate_cache(
     """
     cost = 0.0
     tcr = tcw = ti = 0
-    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync):
+    for e in _diff_iter_claude_entries(window, skip_sync=skip_sync,
+                                       account_key=account_key):
         if e.model == "<synthetic>":
             continue
         if e.cache_creation_tokens == 0 and e.cache_read_tokens == 0:
@@ -891,6 +904,7 @@ def _build_diff_result(
     sort: str,
     allow_mismatch: bool = False,
     skip_sync: bool = False,
+    account_key=None,
     top: "int | None" = None,
 ) -> DiffResult:
     """Top-level diff builder: wire window_a vs window_b through every
@@ -936,8 +950,8 @@ def _build_diff_result(
     raw_totals: "dict[str, tuple[MetricBundle | None, MetricBundle | None]]" = {}
 
     if "overall" in sections_requested:
-        a_overall_raw = _norm_a(_diff_aggregate_overall(window_a, skip_sync=skip_sync))
-        b_overall_raw = _norm_b(_diff_aggregate_overall(window_b, skip_sync=skip_sync))
+        a_overall_raw = _norm_a(_diff_aggregate_overall(window_a, skip_sync=skip_sync, account_key=account_key))
+        b_overall_raw = _norm_b(_diff_aggregate_overall(window_b, skip_sync=skip_sync, account_key=account_key))
         # Splice in the resolved Used% AFTER normalization — Used % is
         # never per-day-normalized (it's a weekly ceiling ratio).
         a_overall = dataclasses.replace(a_overall_raw, used_pct=used_a)
@@ -954,9 +968,9 @@ def _build_diff_result(
 
     if "models" in sections_requested:
         a_map = {k: _norm_a(v) for k, v in
-                 _diff_aggregate_models(window_a, skip_sync=skip_sync).items()}
+                 _diff_aggregate_models(window_a, skip_sync=skip_sync, account_key=account_key).items()}
         b_map = {k: _norm_b(v) for k, v in
-                 _diff_aggregate_models(window_b, skip_sync=skip_sync).items()}
+                 _diff_aggregate_models(window_b, skip_sync=skip_sync, account_key=account_key).items()}
         sections.append(_diff_build_section(
             "models", "all", a_map, b_map,
             _DIFF_DEFAULT_COLUMNS_MODELS, threshold, sort,
@@ -969,9 +983,9 @@ def _build_diff_result(
 
     if "projects" in sections_requested:
         a_map = {k: _norm_a(v) for k, v in
-                 _diff_aggregate_projects(window_a, skip_sync=skip_sync).items()}
+                 _diff_aggregate_projects(window_a, skip_sync=skip_sync, account_key=account_key).items()}
         b_map = {k: _norm_b(v) for k, v in
-                 _diff_aggregate_projects(window_b, skip_sync=skip_sync).items()}
+                 _diff_aggregate_projects(window_b, skip_sync=skip_sync, account_key=account_key).items()}
         sections.append(_diff_build_section(
             "projects", "all", a_map, b_map,
             _DIFF_DEFAULT_COLUMNS_PROJECTS, threshold, sort,
@@ -984,9 +998,9 @@ def _build_diff_result(
 
     if "cache" in sections_requested:
         a_map = {k: _norm_a(v) for k, v in
-                 _diff_aggregate_cache(window_a, skip_sync=skip_sync).items()}
+                 _diff_aggregate_cache(window_a, skip_sync=skip_sync, account_key=account_key).items()}
         b_map = {k: _norm_b(v) for k, v in
-                 _diff_aggregate_cache(window_b, skip_sync=skip_sync).items()}
+                 _diff_aggregate_cache(window_b, skip_sync=skip_sync, account_key=account_key).items()}
         sections.append(_diff_build_section(
             "cache", "cache-active-entries", a_map, b_map,
             _DIFF_DEFAULT_COLUMNS_CACHE,

package/bin/_lib_doctor.py

@@ -272,6 +272,20 @@ class DoctorState:
     journal_hw_segment: Optional[str] = None
     journal_cursor_segment: Optional[str] = None
     journal_heal_incidents: Optional[list] = None
+    # Multi-account attribution (#341). A dict (None when unavailable) with:
+    #   * claude_identity_status — "identified" | "stably_absent" | "torn"
+    #   * claude_email — the active Claude email (or None)
+    #   * real_account_count — # real accounts across providers (excludes the
+    #     unattributed sentinel); by_provider — {provider: count}
+    #   * missing_provider — # registry rows lacking a provider (corrupt)
+    #   * freshest_last_seen_age_s — age of the newest last_seen_utc (or None)
+    #   * recent_attributed / recent_unattributed — last-7-day Claude usage
+    #     snapshot counts stamped to a real account vs the sentinel.
+    accounts_state: Optional[dict] = None
+    # Issue #344 Task B: read-only repair-owner classification for
+    # cache.db.repairing. {exists, live, reason}; None only when gather itself
+    # could not inspect the marker. Doctor never reclaims or deletes it.
+    cache_repair_marker: Optional[dict] = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -692,6 +706,25 @@ def _check_db_stats_file(s: DoctorState) -> CheckResult:
 
 
 def _check_db_cache_file(s: DoctorState) -> CheckResult:
+    marker = s.cache_repair_marker
+    if marker and marker.get("exists"):
+        if marker.get("live") is True:
+            return CheckResult(
+                id="db.cache.file",
+                title="cache.db",
+                severity="warn",
+                summary="repair in progress",
+                remediation="Wait for the active cache repair to finish.",
+                details={"repair_marker": marker},
+            )
+        return CheckResult(
+            id="db.cache.file",
+            title="cache.db",
+            severity="warn",
+            summary="stale repair owner",
+            remediation="Run `cctally cache-sync --rebuild`",
+            details={"repair_marker": marker},
+        )
     return _db_file_check("db.cache.file", "cache.db", s.cache_db_status,
                           "Run `cctally cache-sync --rebuild`")
 
@@ -2055,6 +2088,127 @@ def _check_journal_auto_heal(s: DoctorState) -> CheckResult:
 # `_evaluate_one` uses this id — not the function name — so the synthesized
 # FAIL CheckResult retains the contract id and fingerprint stays stable across
 # success-vs-raise transitions.
+def _check_accounts_identity(s: DoctorState) -> CheckResult:
+    """Is the active-account identity source (`~/.claude.json`) readable? A torn
+    mid-write read WARNs (transient); identified / stably-absent are OK (a legacy
+    / non-Claude-Code install has no file — that is a resolved state, not a
+    fault)."""
+    st = s.accounts_state or {}
+    status = st.get("claude_identity_status")
+    if status == "torn":
+        return CheckResult(
+            id="accounts.identity", title="Account identity source",
+            severity="warn",
+            summary="~/.claude.json is being rewritten (torn read); attribution deferred",
+            remediation="Transient — re-run once Claude Code finishes writing",
+            details={"claude_identity_status": status},
+        )
+    if status == "identified":
+        summary = f"active Claude account readable ({st.get('claude_email') or 'no email'})"
+    else:
+        summary = "no active Claude identity on disk (single-account / api-key mode)"
+    return CheckResult(
+        id="accounts.identity", title="Account identity source",
+        severity="ok", summary=summary, remediation=None,
+        details={"claude_identity_status": status},
+    )
+
+
+def _check_accounts_registry(s: DoctorState) -> CheckResult:
+    """Is the accounts registry consistent? A row lacking a provider is corrupt
+    (WARN → rebuild)."""
+    st = s.accounts_state
+    if st is None:
+        return CheckResult(
+            id="accounts.registry", title="Account registry",
+            severity="ok", summary="no registry (fresh install)",
+            remediation=None, details={},
+        )
+    missing = int(st.get("missing_provider") or 0)
+    count = int(st.get("real_account_count") or 0)
+    by_provider = st.get("by_provider") or {}
+    details = {"real_account_count": count, "by_provider": by_provider,
+               "missing_provider": missing}
+    if missing:
+        return CheckResult(
+            id="accounts.registry", title="Account registry",
+            severity="warn",
+            summary=f"{missing} account row(s) missing a provider",
+            remediation="Run `cctally db rebuild --db stats` to re-derive the registry",
+            details=details,
+        )
+    return CheckResult(
+        id="accounts.registry", title="Account registry",
+        severity="ok",
+        summary=(f"{count} account(s) known" if count
+                 else "no accounts observed yet"),
+        remediation=None, details=details,
+    )
+
+
+def _check_accounts_freshness(s: DoctorState) -> CheckResult:
+    """Attribution freshness — how recently any account was last seen. Purely
+    informational (always OK); a stale value just reports the age."""
+    st = s.accounts_state or {}
+    age = st.get("freshest_last_seen_age_s")
+    if age is None:
+        summary = "no attribution activity recorded"
+    else:
+        a = int(age)
+        if a >= 86400:
+            human = f"{a // 86400}d"
+        elif a >= 3600:
+            human = f"{a // 3600}h"
+        elif a >= 60:
+            human = f"{a // 60}m"
+        else:
+            human = f"{a}s"
+        summary = f"most recent account activity {human} ago"
+    return CheckResult(
+        id="accounts.freshness", title="Account attribution freshness",
+        severity="ok", summary=summary, remediation=None,
+        details={"freshest_last_seen_age_s": age},
+    )
+
+
+def _check_accounts_attribution(s: DoctorState) -> CheckResult:
+    """WARN when Claude usage is flowing but landing in `unattributed` despite a
+    resolved active account (the stamping pipeline is broken), or while the
+    identity is torn. This is the runtime complement to the structural
+    writer-audit backstop for the account_key DEFAULT."""
+    st = s.accounts_state or {}
+    recent_unattr = int(st.get("recent_unattributed") or 0)
+    recent_attr = int(st.get("recent_attributed") or 0)
+    status = st.get("claude_identity_status")
+    details = {"recent_attributed": recent_attr,
+               "recent_unattributed": recent_unattr,
+               "claude_identity_status": status}
+    # A real active account, recent usage, yet all of it unattributed -> the
+    # write-path stamp is not landing.
+    if status == "identified" and recent_unattr > 0 and recent_attr == 0:
+        return CheckResult(
+            id="accounts.attribution", title="Account attribution",
+            severity="warn",
+            summary="recent Claude usage is landing in 'unattributed' despite an active account",
+            remediation="Run `cctally db rebuild --db stats`; if it persists, file an issue",
+            details=details,
+        )
+    if status == "torn" and recent_unattr > 0:
+        return CheckResult(
+            id="accounts.attribution", title="Account attribution",
+            severity="warn",
+            summary="recent usage attributed to 'unattributed' while identity is torn",
+            remediation="Transient — the next clean read re-attributes new usage",
+            details=details,
+        )
+    return CheckResult(
+        id="accounts.attribution", title="Account attribution",
+        severity="ok",
+        summary="usage attribution healthy",
+        remediation=None, details=details,
+    )
+
+
 _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...] = (
     ("install", "Install", (
         ("install.mode", "_check_install_dev_mode"),
@@ -2106,6 +2260,12 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("data.conversation_sessions_rollup",
          "_check_data_conversation_sessions_rollup"),
     )),
+    ("accounts", "Accounts", (
+        ("accounts.identity", "_check_accounts_identity"),
+        ("accounts.registry", "_check_accounts_registry"),
+        ("accounts.freshness", "_check_accounts_freshness"),
+        ("accounts.attribution", "_check_accounts_attribution"),
+    )),
     ("pricing", "Pricing", (
         ("pricing.coverage", "_check_pricing_coverage"),
     )),