cctally 1.80.3 → 1.81.0

package/bin/_cctally_tui.py

@@ -263,6 +263,8 @@ _ensure_sibling_loaded("_lib_dashboard_sources")
 _ensure_sibling_loaded("_cctally_dashboard_sources")
 from _cctally_dashboard_sources import (
     DashboardReadContext,
+    _claude_accounts_wire,
+    accounts_identity_digest,
     build_codex_source_state,
     refresh_codex_source_clock,
     resolve_dashboard_source_semantics,
@@ -2145,7 +2147,12 @@ def _snapshot_data_version(sig) -> str:
         getattr(sig, "codex_physical_mutation_seq", 0),
     ))
     digest = getattr(sig, "codex_stats_digest", "")
-    return numeric_legs if not digest else f"{numeric_legs}.{digest}"
+    out = numeric_legs if not digest else f"{numeric_legs}.{digest}"
+    # #341 finding 9: fold the account registry/active-identity digest so an
+    # account switch with zero new rows still flips the SSE change-signal. Empty
+    # for every <=1-account install (byte-neutral — never appended).
+    acct = getattr(sig, "accounts_digest", "")
+    return out if not acct else f"{out}.a{acct}"
 
 
 def _tui_source_copy(value: object) -> object:
@@ -2394,22 +2401,32 @@ def _tui_build_source_bundle(
             display_tz_name=display_tz_name,
         )
         stats_digest = codex_stats_digest(stats_conn)
+        # #341 finding 9: the account registry/active-identity digest. Empty for
+        # every <=1-account install (byte-neutral — appended only when non-empty),
+        # so single-account source versions stay byte-identical to today; a
+        # multi-account switch flips it -> the source rebuilds (re-resolving the
+        # `active` marker). Folded into BOTH providers' versions: a switch is a
+        # rare event and a rebuild is safe, so per-provider narrowing is not worth
+        # the split.
+        accounts_digest = accounts_identity_digest(stats_conn)
         signature = c.compute_signature(
             cache_conn,
             stats_conn,
             generation=c.current_generation(),
             codex_stats_digest=stats_digest,
+            accounts_digest=accounts_digest,
         )
+        _acct_suffix = f":a{accounts_digest}" if accounts_digest else ""
         codex_version = (
             f"codex:{signature.max_codex_id}:"
             f"{signature.codex_physical_mutation_seq}:{stats_digest}:"
-            f"{semantics.codex_identity}"
+            f"{semantics.codex_identity}{_acct_suffix}"
         )
         claude_version = (
             f"claude:{signature.max_entry_id}:{signature.entry_mutation_seq}:"
             f"{signature.max_wus_id}:{signature.max_wcs_id}:"
             f"{signature.reset_sig[0]}:{signature.reset_sig[1]}:"
-            f"{signature.generation}:{semantics.claude_identity}"
+            f"{signature.generation}:{semantics.claude_identity}{_acct_suffix}"
         )
         prior_claude = (
             prior_bundle.sources.get("claude")
@@ -2443,6 +2460,26 @@ def _tui_build_source_bundle(
             )
         if claude is None:
             claude_available = "ok" if (claude_cost_usd or claude_total_tokens) else "empty"
+            # #341 Task 4 (Ruling C): the conditional per-account Claude wire,
+            # symmetric with Codex. Built ONLY when the Claude provider has >1
+            # REAL account (R8) — a <=1-real-account install (every envelope
+            # golden) adds nothing, so its wire is byte-identical. The generic
+            # chip row / hero cards light up automatically for a decorated Claude
+            # source. A read failure degrades to the byte-stable undecorated shape.
+            claude_accounts: list[dict[str, object]] = []
+            try:
+                import _cctally_account
+                if _cctally_account.provider_is_decorated(stats_conn, "claude"):
+                    claude_accounts = _claude_accounts_wire(stats_conn, now_utc=now_utc)
+            except Exception:
+                # #341 Task 4 P3 — degrade to no-accounts-wire on ANY read
+                # failure, symmetric with the Codex path. Beyond sqlite, the wire
+                # reaches the identity read (file I/O on ~/.claude.json via
+                # resolve_active_account_keys) and the account registry/label
+                # lookups; a transient failure in this best-effort DECORATIVE
+                # wire must never fail the whole dashboard tick — it just falls
+                # back to the byte-stable undecorated shape.
+                claude_accounts = []
             claude = SourceDashboardState(
                 source="claude",
                 availability=claude_available,
@@ -2478,6 +2515,7 @@ def _tui_build_source_bundle(
                             "alerts": {"rows": ()},
                         }
                     ),
+                    **({"accounts": claude_accounts} if claude_accounts else {}),
                 },
             )
         if codex_ingest_failed:
@@ -2566,6 +2604,7 @@ def _tui_build_source_bundle(
             stats_conn,
             generation=c.current_generation(),
             codex_stats_digest=post_stats_digest,
+            accounts_digest=accounts_identity_digest(stats_conn),
         )
         if post_signature != signature:
             if prior_bundle is not None:
@@ -2749,24 +2788,58 @@ def _tui_build_snapshot(
             if do_ingest:
                 try:
                     cache_conn = _cctally().open_cache_db()
+                    cache_mod = _cctally()._load_sibling("_cctally_cache")
                     try:
-                        try:
-                            claude_ingest = sync_cache(cache_conn)
+                        def _claude_leg(active_conn):
+                            try:
+                                return sync_cache(active_conn), None
+                            except sqlite3.DatabaseError as exc:
+                                if cache_mod._cctally_db_sib._is_sqlite_corruption_error(
+                                    exc
+                                ):
+                                    raise
+                                return None, exc
+                            except Exception as exc:
+                                return None, exc
+
+                        operations = [_claude_leg]
+                        if precompute_envelope:
+                            def _codex_leg(active_conn):
+                                try:
+                                    return sync_codex_cache(active_conn), None
+                                except sqlite3.DatabaseError as exc:
+                                    if cache_mod._cctally_db_sib._is_sqlite_corruption_error(
+                                        exc
+                                    ):
+                                        raise
+                                    return None, exc
+                                except Exception as exc:
+                                    return None, exc
+
+                            operations.append(_codex_leg)
+
+                        results, cache_conn = (
+                            cache_mod._run_cache_plan_with_recovery(
+                                cache_conn, tuple(operations)
+                            )
+                        )
+                        claude_ingest, claude_error = results[0]
+                        if claude_error is None:
                             claude_ingest_contended = bool(
                                 getattr(claude_ingest, "lock_contended", False)
                             )
-                        except Exception as exc:
+                        else:
                             claude_ingest_failed = True
-                            errors.append(f"sync-cache: {exc}")
+                            errors.append(f"sync-cache: {claude_error}")
                         if precompute_envelope:
-                            try:
-                                codex_ingest = sync_codex_cache(cache_conn)
+                            codex_ingest, codex_error = results[1]
+                            if codex_error is None:
                                 codex_ingest_contended = bool(
                                     getattr(codex_ingest, "lock_contended", False)
                                 )
-                            except Exception as exc:
+                            else:
                                 codex_ingest_failed = True
-                                errors.append(f"sync-codex-cache: {exc}")
+                                errors.append(f"sync-codex-cache: {codex_error}")
                     finally:
                         cache_conn.close()
                 except Exception as exc:
@@ -3589,6 +3662,7 @@ def _tui_compute_dispatch_signature(stats_conn):
             stats_conn,
             generation=sc.current_generation(),
             codex_stats_digest=codex_stats_digest(stats_conn),
+            accounts_digest=accounts_identity_digest(stats_conn),
         )
     finally:
         cache_conn.close()
@@ -6092,6 +6166,7 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
                     throttle=throttle, monotonic=_time.monotonic,
                 )
                 cache_conn = _cctally().open_cache_db()
+                cache_mod = _cctally()._load_sibling("_cctally_cache")
                 try:
                     # Under CCTALLY_PERF_TRACE the phase tree this standalone
                     # sync_cache builds is intentionally NOT surfaced in the live
@@ -6100,13 +6175,19 @@ def _make_run_sync_now_locked(*, ref, hub, pinned_now, display_tz_pref_override,
                     # these phases never reach an emitter. §0's trace-attribution
                     # target is `cctally-bench --trace`, which builds directly
                     # (no decoupled standalone ingest) and keeps its phase tree.
-                    sync_cache(cache_conn, progress=cb)
-                    # Dashboard S4's physical identity includes Codex.  Keep
-                    # the decoupled path's ingest set identical to the direct
-                    # dashboard snapshot path before its final pure read, or
-                    # it can publish a legacy data version from a different
-                    # provider generation.
-                    sync_codex_cache(cache_conn)
+                    # Dashboard S4's physical identity includes both providers.
+                    # They are one recovery plan because quarantine replaces
+                    # the shared physical family: corruption in the second leg
+                    # must restart the first leg too.
+                    _, cache_conn = cache_mod._run_cache_plan_with_recovery(
+                        cache_conn,
+                        (
+                            lambda active_conn: sync_cache(
+                                active_conn, progress=cb
+                            ),
+                            lambda active_conn: sync_codex_cache(active_conn),
+                        ),
+                    )
                 except Exception as exc:  # noqa: BLE001 — surfaced on the snap
                     sync_error = f"sync-cache: {exc}"
                 finally:

package/bin/_cctally_weekrefs.py

@@ -72,24 +72,34 @@ def _get_canonical_boundary_for_date(
     return None, None
 
 
-def get_recent_weeks(conn: sqlite3.Connection, limit: "int | None") -> list[WeekRef]:
+def get_recent_weeks(
+    conn: sqlite3.Connection, limit: "int | None", *,
+    account_key: "str | None" = None,
+) -> list[WeekRef]:
     # ``limit=None`` → SQL ``LIMIT -1`` (unbounded): the milestone-history
     # index (#hero-milestone-history) enumerates EVERY navigable week with no
     # depth cap. Existing callers pass a concrete int and are unaffected.
+    #
+    # ``account_key`` (#341, spec §3): ``None`` = the account-blind merged read
+    # (today's byte-identical behavior); a real key / ``unattributed`` scopes both
+    # snapshot legs to that account's weeks (the ``--account`` render consumers —
+    # ``report`` — pass it explicitly).
     limit_sql = -1 if limit is None else int(limit)
+    acct_pred = "" if account_key is None else " WHERE account_key = ?"
+    acct_p: tuple = () if account_key is None else (account_key,)
     rows = conn.execute(
-        """
+        f"""
         SELECT week_start_date, MAX(week_end_date) AS week_end_date
         FROM (
-          SELECT week_start_date, week_end_date FROM weekly_usage_snapshots
+          SELECT week_start_date, week_end_date FROM weekly_usage_snapshots{acct_pred}
           UNION ALL
-          SELECT week_start_date, week_end_date FROM weekly_cost_snapshots
+          SELECT week_start_date, week_end_date FROM weekly_cost_snapshots{acct_pred}
         )
         GROUP BY week_start_date
         ORDER BY week_start_date DESC
         LIMIT ?
         """,
-        (limit_sql,),
+        acct_p + acct_p + (limit_sql,),
     ).fetchall()
 
     refs: list[WeekRef] = []
@@ -333,21 +343,31 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
                 return
     try:
         rows = conn.execute(
-            "SELECT captured_at_utc, week_end_at, weekly_percent "
+            "SELECT captured_at_utc, week_end_at, weekly_percent, account_key "
             "FROM weekly_usage_snapshots "
             "WHERE week_end_at IS NOT NULL "
-            "ORDER BY captured_at_utc ASC, id ASC"
+            "ORDER BY account_key ASC, captured_at_utc ASC, id ASC"
         ).fetchall()
     except sqlite3.DatabaseError:
         return
     # Canonicalized (hour-rounded) previous end; stored canonical form is
     # what WeekRef.week_end_at carries after make_week_ref, so maps in
     # _apply_reset_events_to_weekrefs stay joinable without extra parsing.
+    # #341: the scan is PARTITIONED by account_key (ORDER BY account_key first)
+    # so one account's boundary shift never derives a phantom reset off another
+    # account's consecutive snapshot; prior state resets at each account boundary.
     prior_end = None
     prior_pct: float | None = None
+    prior_account = None
     for row in rows:
         cur_end_raw = row["week_end_at"]
         cur_pct = row["weekly_percent"]
+        cur_account = row["account_key"]
+        if cur_account != prior_account:
+            # New account partition — do not compare across the boundary.
+            prior_end = None
+            prior_pct = None
+            prior_account = cur_account
         if not cur_end_raw:
             continue
         try:
@@ -385,8 +405,9 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
                 conn.execute(
                     "INSERT OR IGNORE INTO week_reset_events "
                     "(detected_at_utc, old_week_end_at, new_week_end_at, "
-                    " effective_reset_at_utc) VALUES (?, ?, ?, ?)",
-                    (row["captured_at_utc"], prior_end, cur_end, effective_iso),
+                    " effective_reset_at_utc, account_key) VALUES (?, ?, ?, ?, ?)",
+                    (row["captured_at_utc"], prior_end, cur_end, effective_iso,
+                     cur_account),
                 )
         elif prior_end and cur_end == prior_end:
             # In-place credit branch (v1.7.2). Mirrors the live detection
@@ -418,8 +439,8 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
                 # upgrade. (See round-2 review Bug 1.)
                 already = conn.execute(
                     "SELECT 1 FROM week_reset_events "
-                    "WHERE new_week_end_at = ? LIMIT 1",
-                    (cur_end,),
+                    "WHERE new_week_end_at = ? AND account_key = ? LIMIT 1",
+                    (cur_end, cur_account),
                 ).fetchone()
                 if already is not None:
                     prior_end = cur_end
@@ -450,8 +471,9 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
                 conn.execute(
                     "INSERT OR IGNORE INTO week_reset_events "
                     "(detected_at_utc, old_week_end_at, new_week_end_at, "
-                    " effective_reset_at_utc) VALUES (?, ?, ?, ?)",
-                    (row["captured_at_utc"], effective_iso, cur_end, effective_iso),
+                    " effective_reset_at_utc, account_key) VALUES (?, ?, ?, ?, ?)",
+                    (row["captured_at_utc"], effective_iso, cur_end, effective_iso,
+                     cur_account),
                 )
         prior_end = cur_end
         prior_pct = cur_pct
@@ -553,7 +575,7 @@ def _week_ref_has_reset_event(
 
 
 def _compute_cost_for_weekref(
-    ref: WeekRef, *, skip_sync: bool = False
+    ref: WeekRef, *, skip_sync: bool = False, account_key: "str | None" = None,
 ) -> float | None:
     """Live-compute USD cost over `ref`'s (possibly reset-adjusted) range
     straight from session_entries. Mirrors what cmd_sync_week writes into
@@ -577,7 +599,8 @@ def _compute_cost_for_weekref(
         return None
     if end <= start:
         return 0.0
-    return c._sum_cost_for_range(start, end, mode="auto", skip_sync=skip_sync)
+    return c._sum_cost_for_range(
+        start, end, mode="auto", skip_sync=skip_sync, account_key=account_key)
 
 
 def _apply_overlap_clamp_to_weekrefs(refs: list[WeekRef]) -> list[WeekRef]:

package/bin/_lib_accounts.py

@@ -0,0 +1,325 @@
+"""Pure account-identity kernel for the multi-account epic (#341).
+
+Mirrors ``bin/_lib_source_identity.py``: an opaque, non-reversible per-account
+key plus the small set of pure helpers that derive an account identity from the
+provider's own on-disk credential state. I/O-free by construction beyond the
+stat-read-stat protocol (stdlib ``os`` only) and read-only SQLite lookups for
+ref resolution — no ``_cctally_*`` imports, no locks, no writes.
+
+Identity model (design spec §1):
+  - ``account_key = sha256("cctally-account-v1\\0" + provider + "\\0" + natural_id)[:32]``
+    (opaque, domain-separated, mirroring ``source_root_key``).
+  - Natural ids: Claude -> ``oauthAccount.accountUuid``; Codex ->
+    ``chatgpt_account_id + "\\0" + email`` (the pair, since neither is unique
+    alone), decoded from the ``~/.codex/auth.json`` id_token JWT payload (plain
+    base64 body decode; NO signature verification — we read our own disk state,
+    not authenticate).
+  - Reserved sentinel ``UNATTRIBUTED = "unattributed"`` means "account could not
+    be determined" (pre-feature history and any stably-unreadable ingest).
+  - ``VENDOR_WIDE = "*"`` is the vendor-wide budget sentinel (used by later
+    tasks; defined here as the single home for the constant).
+
+Stable-read protocol (review finding 7): identity files are rewritten in place
+by other programs, so every read is stat-read-stat on ``(st_ino, st_size,
+st_mtime_ns)`` with bounded retries. Three-valued outcome: *identified* (stamp
+the account), *stably_absent* (missing file / api-key mode -> stamp
+``unattributed``), or *torn* (stats never stabilised, or content unparseable
+mid-write -> defer, never stamp a guess).
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Callable, Optional, TypeVar
+
+
+ACCOUNT_KEY_VERSION = 1
+UNATTRIBUTED = "unattributed"
+VENDOR_WIDE = "*"
+
+# The namespaced OpenAI OIDC claim carrying the ChatGPT account identity.
+_OPENAI_AUTH_CLAIM = "https://api.openai.com/auth"
+
+T = TypeVar("T")
+
+
+def _required_string(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+# --------------------------------------------------------------------------
+# key derivation
+# --------------------------------------------------------------------------
+
+def account_key(provider: str, natural_id: str) -> str:
+    """Opaque, non-reversible 32-hex key for one account.
+
+    ``sha256("cctally-account-v1\\0" + provider + "\\0" + natural_id)[:32]``.
+    Stable across processes; distinct per provider and per natural id."""
+    prov = _required_string(provider, "provider")
+    nat = _required_string(natural_id, "natural_id")
+    digest = hashlib.sha256(
+        b"cctally-account-v1\0" + prov.encode("utf-8") + b"\0" + nat.encode("utf-8")
+    )
+    return digest.hexdigest()[:32]
+
+
+# --------------------------------------------------------------------------
+# natural-id extraction (pure; operate on already-decoded dicts)
+# --------------------------------------------------------------------------
+
+def claude_natural_id(oauth_account: object) -> Optional[str]:
+    """Claude natural id = ``oauthAccount.accountUuid`` (or None if absent)."""
+    if not isinstance(oauth_account, dict):
+        return None
+    uuid = oauth_account.get("accountUuid")
+    if isinstance(uuid, str) and uuid:
+        return uuid
+    return None
+
+
+def claude_email(oauth_account: object) -> Optional[str]:
+    """Best-effort Claude email (``oauthAccount.emailAddress``) for display."""
+    if not isinstance(oauth_account, dict):
+        return None
+    email = oauth_account.get("emailAddress")
+    if isinstance(email, str) and email:
+        return email
+    return None
+
+
+def _codex_auth_claim(payload: dict) -> dict:
+    """Return the OpenAI auth claim object, tolerating the flat dotted form."""
+    claim = payload.get(_OPENAI_AUTH_CLAIM)
+    if isinstance(claim, dict):
+        return claim
+    return {}
+
+
+def codex_natural_id(id_token_payload: object) -> Optional[str]:
+    """Codex natural id = ``chatgpt_account_id + "\\0" + email`` (the pair).
+
+    Returns None when either component is missing — e.g. ``OPENAI_API_KEY``
+    mode, which has no ChatGPT identity at all."""
+    if not isinstance(id_token_payload, dict):
+        return None
+    email = id_token_payload.get("email")
+    claim = _codex_auth_claim(id_token_payload)
+    account_id = claim.get("chatgpt_account_id")
+    # Flat fallback: a token that hoisted the id to the top level.
+    if not isinstance(account_id, str):
+        account_id = id_token_payload.get("chatgpt_account_id")
+    if not isinstance(email, str) or not email:
+        return None
+    if not isinstance(account_id, str) or not account_id:
+        return None
+    return account_id + "\0" + email
+
+
+def codex_email(id_token_payload: object) -> Optional[str]:
+    if not isinstance(id_token_payload, dict):
+        return None
+    email = id_token_payload.get("email")
+    return email if isinstance(email, str) and email else None
+
+
+def codex_plan_type(id_token_payload: object) -> Optional[str]:
+    """Best-effort ChatGPT plan type for registry enrichment."""
+    if not isinstance(id_token_payload, dict):
+        return None
+    claim = _codex_auth_claim(id_token_payload)
+    plan = claim.get("chatgpt_plan_type")
+    if not isinstance(plan, str):
+        plan = id_token_payload.get("chatgpt_plan_type")
+    return plan if isinstance(plan, str) and plan else None
+
+
+# --------------------------------------------------------------------------
+# JWT id_token decode (base64 body, NO signature verification)
+# --------------------------------------------------------------------------
+
+def decode_id_token_payload(id_token: object) -> Optional[dict]:
+    """Decode the payload segment of a JWT ``id_token``.
+
+    Returns the payload dict, or None on ANY failure. We are reading our own
+    disk state, not authenticating, so the signature is neither present-checked
+    nor verified — only the base64url body is decoded and JSON-parsed."""
+    if not isinstance(id_token, str) or not id_token:
+        return None
+    parts = id_token.split(".")
+    if len(parts) < 2:
+        return None
+    body = parts[1]
+    padded = body + "=" * (-len(body) % 4)
+    try:
+        raw = base64.urlsafe_b64decode(padded.encode("ascii"))
+    except (binascii.Error, ValueError):
+        return None
+    try:
+        obj = json.loads(raw)
+    except (ValueError, TypeError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+# --------------------------------------------------------------------------
+# stat-read-stat stable-read protocol
+# --------------------------------------------------------------------------
+
+class TornRead(Exception):
+    """Raised by a stable-read reader when the bytes are unparseable mid-write.
+
+    The stable-read machinery treats it as a *torn* outcome (defer), distinct
+    from a reader that returns None (parsed cleanly, but carries no identity ->
+    stably_absent)."""
+
+
+@dataclass
+class StableRead:
+    """Outcome of :func:`stable_read_identity`.
+
+    ``status`` is one of ``"identified"`` / ``"stably_absent"`` / ``"torn"``;
+    ``value`` is the reader's result only when ``identified``."""
+
+    status: str
+    value: object = None
+
+
+def _stat_signature(st) -> tuple:
+    return (st.st_ino, st.st_size, st.st_mtime_ns)
+
+
+def stable_read_identity(
+    path: str,
+    reader: Callable[[bytes], T],
+    *,
+    max_retries: int = 3,
+    _stat=None,
+    _open=None,
+) -> StableRead:
+    """stat -> read -> stat an identity file, retrying on a changed signature.
+
+    Outcomes:
+      * ``stably_absent`` — the file is missing (any attempt), or ``reader``
+        returns None over a stat-stable read (content present, no identity).
+      * ``torn`` — the ``(inode, size, mtime_ns)`` signature never stabilised
+        across ``max_retries`` attempts, or ``reader`` raised :class:`TornRead`.
+      * ``identified`` — a stat-stable read whose ``reader`` returned a value.
+
+    The private ``_stat``/``_open`` hooks exist only for deterministic torn-read
+    testing; production always uses ``os.stat`` / ``open``."""
+    stat = _stat or os.stat
+    opener = _open or open
+    for _ in range(max_retries + 1):
+        try:
+            st1 = stat(path)
+        except (FileNotFoundError, NotADirectoryError):
+            return StableRead("stably_absent")
+        except OSError:
+            continue
+        sig1 = _stat_signature(st1)
+        try:
+            with opener(path, "rb") as fh:
+                data = fh.read()
+        except (FileNotFoundError, NotADirectoryError):
+            return StableRead("stably_absent")
+        except OSError:
+            continue
+        try:
+            st2 = stat(path)
+        except (FileNotFoundError, NotADirectoryError):
+            return StableRead("stably_absent")
+        except OSError:
+            continue
+        if sig1 != _stat_signature(st2):
+            continue  # file changed during the read window -> retry
+        try:
+            value = reader(data)
+        except TornRead:
+            return StableRead("torn")
+        if value is None:
+            return StableRead("stably_absent")
+        return StableRead("identified", value)
+    return StableRead("torn")
+
+
+# --------------------------------------------------------------------------
+# account-ref resolution (read-only over the accounts registry)
+# --------------------------------------------------------------------------
+
+class AccountRefError(Exception):
+    """Raised when an account ref is ambiguous or unknown.
+
+    ``candidates`` is the list of ``account_key``s that the caller can print on
+    stderr (the tied matches for an ambiguous ref; every known account for an
+    unknown ref)."""
+
+    def __init__(self, ref: str, candidates):
+        self.ref = ref
+        self.candidates = list(candidates)
+        super().__init__(f"account ref {ref!r} is ambiguous or unknown")
+
+
+@dataclass
+class _AccountRow:
+    account_key: str
+    provider: str
+    label: Optional[str] = None
+    email: Optional[str] = None
+
+
+def _load_account_rows(conn, provider: Optional[str]):
+    sql = "SELECT account_key, provider, label, email FROM accounts"
+    params: tuple = ()
+    if provider is not None:
+        sql += " WHERE provider = ?"
+        params = (provider,)
+    rows = []
+    for account_key_, prov, label, email in conn.execute(sql, params).fetchall():
+        rows.append(_AccountRow(account_key_, prov, label, email))
+    return rows
+
+
+def resolve_account_ref(conn, ref: str, provider: Optional[str] = None) -> str:
+    """Resolve a user-supplied account ref to an ``account_key``.
+
+    Precedence: case-insensitive label -> case-insensitive email -> unique
+    ``account_key`` prefix. The literal ``"unattributed"`` sentinel is accepted
+    directly. Ambiguity within a tier, or no match in any tier, raises
+    :class:`AccountRefError` (candidates = the tied matches, or every known
+    account when unknown)."""
+    if not isinstance(ref, str) or not ref:
+        raise AccountRefError(ref, [])
+    if ref == UNATTRIBUTED:
+        return UNATTRIBUTED
+    rows = _load_account_rows(conn, provider)
+    needle = ref.strip().lower()
+
+    # Tier 1: exact case-insensitive label.
+    label_matches = [r for r in rows if (r.label or "").lower() == needle]
+    if len(label_matches) == 1:
+        return label_matches[0].account_key
+    if len(label_matches) > 1:
+        raise AccountRefError(ref, [r.account_key for r in label_matches])
+
+    # Tier 2: exact case-insensitive email.
+    email_matches = [r for r in rows if (r.email or "").lower() == needle]
+    if len(email_matches) == 1:
+        return email_matches[0].account_key
+    if len(email_matches) > 1:
+        raise AccountRefError(ref, [r.account_key for r in email_matches])
+
+    # Tier 3: account_key prefix (case-sensitive hex).
+    prefix_matches = [r for r in rows if r.account_key.startswith(ref)]
+    if len(prefix_matches) == 1:
+        return prefix_matches[0].account_key
+    if len(prefix_matches) > 1:
+        raise AccountRefError(ref, [r.account_key for r in prefix_matches])
+
+    raise AccountRefError(ref, [r.account_key for r in rows])