cctally 1.80.4 → 1.82.0

package/bin/_lib_journal.py

@@ -107,10 +107,19 @@ def evt_id(kind: str, *parts: object) -> str:
 # fully-formed line records
 # --------------------------------------------------------------------------
 
-def make_obs(at: str, src: str, provider: str, payload: dict) -> dict:
+def make_obs(at: str, src: str, provider: str, payload: dict,
+             account: str | None = None) -> dict:
     """Build a complete ``obs`` line record (raw capture; canonicalization is
-    derivation-time, never baked into the stored line — spec §4.2)."""
+    derivation-time, never baked into the stored line — spec §4.2).
+
+    ``account`` (#341) is the account_key stamp, a top-level sibling of
+    ``provider``. It is emitted ONLY when supplied, so a pre-epic / single-account
+    writer that passes nothing produces a byte-identical line (and a byte-stable
+    content id). When supplied it participates in the content id, so two obs that
+    differ only by account are distinct records."""
     core = {"t": "obs", "at": at, "src": src, "provider": provider, "payload": payload}
+    if account is not None:
+        core["account"] = account
     return {"v": LINE_VERSION, **core, "id": content_id(core)}
 
 
@@ -133,6 +142,60 @@ def make_evt(kind: str, id: str, at: str, payload: dict, rev: int = 0) -> dict:
             "at": at, "src": "ingest", "payload": body}
 
 
+# --------------------------------------------------------------------------
+# accounts-machinery records (#341): registered op kinds folded into the
+# `accounts` registry. These are NOT data-bearing account-stamped lines and are
+# NOT legacy — the classifier recognises them by their registered `kind`.
+# --------------------------------------------------------------------------
+
+def make_account_observe(
+    at: str,
+    account_key: str,
+    provider: str,
+    *,
+    natural_id: str | None = None,
+    email: str | None = None,
+    plan_type: str | None = None,
+    label: str | None = None,
+    label_source: str | None = None,
+) -> dict:
+    """Build an ``account_observe`` op line — appended on first sight of an
+    account or an identity change (NOT every tick). Folded into the ``accounts``
+    registry by ``_apply_op_account_observe`` (rebuild applier). ``last_seen_utc``
+    is NOT carried here — it derives at fold time from the max ``at`` of any
+    account-stamped line (spec §1)."""
+    payload = {"kind": "account_observe", "account_key": account_key,
+               "provider": provider}
+    if natural_id is not None:
+        payload["natural_id"] = natural_id
+    if email is not None:
+        payload["email"] = email
+    if plan_type is not None:
+        payload["plan_type"] = plan_type
+    if label is not None:
+        payload["label"] = label
+    if label_source is not None:
+        payload["label_source"] = label_source
+    return make_op(at=at, src="account-observe", payload=payload)
+
+
+def make_account_label(
+    at: str,
+    account_key: str,
+    label: str,
+    *,
+    provider: str | None = None,
+) -> dict:
+    """Build an ``account_label`` op line (a user rename). Folded by
+    ``_apply_op_account_label`` with ``label_source='user'`` — the top of the
+    label-precedence order (user > switcher > auto), so a later switcher/auto
+    enrichment never overrides it (spec §1)."""
+    payload = {"kind": "account_label", "account_key": account_key, "label": label}
+    if provider is not None:
+        payload["provider"] = provider
+    return make_op(at=at, src="account-label", payload=payload)
+
+
 # --------------------------------------------------------------------------
 # segment naming + canonical order
 # --------------------------------------------------------------------------

package/bin/_lib_pricing.py

@@ -53,7 +53,7 @@ def _chip_for_model(name: str) -> str:
 # Date the embedded pricing snapshots below were last verified against
 # vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
 # is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
-PRICING_SNAPSHOT_DATE = "2026-07-19"
+PRICING_SNAPSHOT_DATE = "2026-07-24"
 PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
 
 # Canonical machine-readable pricing source (Claude values + Codex values).
@@ -99,7 +99,7 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
 
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-07-19 (see PRICING_SNAPSHOT_DATE)
+# - Captured: 2026-07-24 (see PRICING_SNAPSHOT_DATE)
 # - Verified by maintainer against docs.claude.com/en/docs/about-claude/pricing;
 #   update in PRs touching this table.
 #   2026-06-10: added claude-fable-5 ($10/$50 per MTok; 1M context, no
@@ -114,6 +114,22 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = [
 #   value_drift on all four cost fields. Suppressed via PRICING_DRIFT_ALLOWLIST
 #   above (the non-vacuity guard forces removal once LiteLLM reverts to the
 #   standard rate after 2026-08-31).
+#   2026-07-24: added claude-opus-5 ($5/$25 per MTok — identical to Opus
+#   4.5/4.6/4.7/4.8; $6.25 5-minute cache write and $0.50 cache read at the
+#   standard 1.25x/0.1x multipliers). 1M context at standard pricing, so NO
+#   above-200k tier. Dateless pinned id with no dated twin (matches Anthropic's
+#   published ID/alias table). LiteLLM has no opus-5 entry yet, so this table is
+#   simply ahead of it — `ahead_of_litellm` is never a drift finding, so no
+#   PRICING_DRIFT_ALLOWLIST entry is needed.
+#
+# Known gap — Claude *fast mode* is not modelled. Anthropic bills fast mode at a
+# premium ($10/$50 per MTok on Opus 5 and Opus 4.8; $30/$150 on Opus 4.7), and
+# Claude Code records the tier per assistant entry at `message.usage.speed`
+# ("standard" | "fast"), so it IS derivable from the JSONL we already ingest —
+# but this table is one rate per model and `_calculate_entry_cost` ignores speed,
+# so a fast-mode entry is priced at the standard rate (2x undercount on Opus 5).
+# The Codex side already carries the shape for this
+# (`_calculate_codex_entry_cost(..., speed=...)` + its fast-tier multiplier).
 CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
     "claude-3-5-haiku-20241022": {
         "input_cost_per_token": 8e-07,
@@ -269,6 +285,12 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_creation_input_token_cost": 6.25e-06,
         "cache_read_input_token_cost": 5e-07,
     },
+    "claude-opus-5": {
+        "input_cost_per_token": 5e-06,
+        "output_cost_per_token": 2.5e-05,
+        "cache_creation_input_token_cost": 6.25e-06,
+        "cache_read_input_token_cost": 5e-07,
+    },
     "claude-sonnet-4-20250514": {
         "input_cost_per_token": 3e-06,
         "output_cost_per_token": 1.5e-05,
@@ -321,7 +343,9 @@ _unknown_model_warnings: set[str] = set()
 #
 # Codex (OpenAI) API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-07-19 (see PRICING_SNAPSHOT_DATE)
+# - Captured: 2026-07-19 — the last full Codex sync. PRICING_SNAPSHOT_DATE moved
+#   ahead to 2026-07-24 for the Claude-side opus-5 sync; these Codex values were
+#   NOT re-verified that day.
 # - As of the 2026-07-19 sync this carries every openai-provider
 #   gpt-5* model the LiteLLM snapshot lists, so `pricing-check`'s scope finds
 #   nothing missing. Models absent from this table still fall back to `gpt-5`

package/bin/_lib_quota.py

@@ -11,9 +11,11 @@ import datetime as dt
 import hashlib
 import json
 import math
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import Iterable, Literal
 
+import _lib_accounts
+
 
 FUTURE_CLOCK_SKEW_SECONDS = 300
 _SOURCE_PATH_KEY_PREFIX = b"cctally-source-path-v1\0"
@@ -52,11 +54,18 @@ class QuotaWindowIdentity:
     logical_limit_key: str
     observed_slot: str
     window_minutes: int
+    # account_key (#341) participates in equality/hashing so never-combine
+    # extends to accounts automatically: two accounts sharing one physical
+    # window key are distinct identities. It defaults to the reserved sentinel so
+    # a single-account / pre-#341 caller building an identity by keyword is
+    # byte-stable. limit_id/limit_name remain compare=False display metadata.
+    account_key: str = _lib_accounts.UNATTRIBUTED
     limit_id: str | None = field(default=None, compare=False)
     limit_name: str | None = field(default=None, compare=False)
 
     def __post_init__(self) -> None:
-        for name in ("source", "source_root_key", "logical_limit_key", "observed_slot"):
+        for name in ("source", "source_root_key", "logical_limit_key", "observed_slot",
+                     "account_key"):
             if not isinstance(getattr(self, name), str) or not getattr(self, name):
                 raise ValueError(f"{name} must be a non-empty string")
         if not isinstance(self.window_minutes, int) or isinstance(self.window_minutes, bool):
@@ -194,14 +203,20 @@ class QuotaThresholdDecision:
     threshold: int
 
 
-def identity_sort_key(identity: QuotaWindowIdentity) -> tuple[str, str, str, str, int]:
-    """Return the stable full logical identity ordering used by every selector."""
+def identity_sort_key(identity: QuotaWindowIdentity) -> tuple[str, str, str, str, int, str]:
+    """Return the stable full logical identity ordering used by every selector.
+
+    ``account_key`` (#341) is appended LAST so the existing 5-element ordering is
+    preserved byte-for-byte for a single-account install (the account is constant
+    there) and only ever breaks a genuine cross-account tie deterministically.
+    """
     return (
         identity.source,
         identity.source_root_key,
         identity.logical_limit_key,
         identity.observed_slot,
         identity.window_minutes,
+        identity.account_key,
     )
 
 
@@ -270,6 +285,68 @@ def build_history(observations: Iterable[QuotaObservation]) -> tuple[QuotaHistor
     return tuple(result)
 
 
+def _physical_window_key(observation: QuotaObservation) -> tuple[object, ...]:
+    """The account-INDEPENDENT physical window key used by the continuity fold.
+
+    Two observations share a physical window iff they agree on root, limit key,
+    slot, window minutes, and the exact (canonical UTC) reset boundary — the
+    account is deliberately EXCLUDED so unidentified observations can be adopted
+    by a same-window identified account (spec §2 window-account continuity).
+    """
+    identity = observation.identity
+    return (
+        identity.source,
+        identity.source_root_key,
+        identity.logical_limit_key,
+        identity.observed_slot,
+        identity.window_minutes,
+        observation.resets_at,
+    )
+
+
+def adopt_unidentified_observations(
+    observations: Iterable[QuotaObservation],
+) -> tuple[QuotaObservation, ...]:
+    """Apply the window-account continuity rule (#341 spec §2 rev 4).
+
+    Group observations by their physical window key (account EXCLUDED). Within a
+    group, identified observations (``account_key != unattributed``) are
+    AUTHORITATIVE and NEVER re-assigned — two identified accounts sharing an
+    identical physical window key stay separate windows (never-combine holds
+    unconditionally). Unidentified observations are adopted by the window's
+    account IFF exactly ONE identified account is ever observed for that key;
+    zero or ambiguous (>=2) identified accounts leave them ``unattributed``.
+
+    Pure and order-preserving: identified observations pass through untouched; an
+    adopted unidentified observation is returned with its identity re-stamped to
+    the single identified account. A single-account install (all observations
+    already carry one account, or all are unattributed with no identified peer)
+    is a byte-stable no-op.
+    """
+    values = tuple(observations)
+    identified_by_window: dict[tuple[object, ...], set[str]] = {}
+    for observation in values:
+        account = observation.identity.account_key
+        if account != _lib_accounts.UNATTRIBUTED:
+            identified_by_window.setdefault(
+                _physical_window_key(observation), set()
+            ).add(account)
+    result: list[QuotaObservation] = []
+    for observation in values:
+        if observation.identity.account_key != _lib_accounts.UNATTRIBUTED:
+            result.append(observation)
+            continue
+        accounts = identified_by_window.get(_physical_window_key(observation))
+        if accounts is not None and len(accounts) == 1:
+            adopted = next(iter(accounts))
+            result.append(replace(
+                observation, identity=replace(observation.identity, account_key=adopted),
+            ))
+        else:
+            result.append(observation)
+    return tuple(result)
+
+
 def latest_physical_observation(observations: Iterable[QuotaObservation]) -> QuotaObservation | None:
     """Select the latest local physical capture with deterministic tie breaking."""
     values = tuple(observations)

package/bin/_lib_render.py

@@ -811,6 +811,7 @@ def _bucket_to_json(
     *,
     list_key: str,
     date_key: str,
+    extra: "dict | None" = None,
 ) -> str:
     """Serialize bucket aggregates to JSON matching upstream ccusage's shape.
 
@@ -824,11 +825,15 @@ def _bucket_to_json(
     """
     bucket_list = [_daily_row_dict(d, date_key=date_key) for d in buckets]
     totals = _bucket_totals_dict(buckets)
-    payload = stamp_schema_version({list_key: bucket_list, "totals": totals})
+    body = {list_key: bucket_list, "totals": totals}
+    if extra:  # #341 R8 decoration (accountKey/accountLabel; empty unless --account)
+        body.update(extra)
+    payload = stamp_schema_version(body)
     return json.dumps(payload, indent=2)
 
 
-def _bucket_by_project_to_json(project_groups, *, date_key: str = "date") -> str:
+def _bucket_by_project_to_json(project_groups, *, date_key: str = "date",
+                               extra: "dict | None" = None) -> str:
     """Serialize ``[(label, [BucketUsage]), ...]`` to ``{projects:{label:[rows]},
     totals}`` (upstream ccusage daily --instances shape). Caller passes the
     disambiguated (unique, non-aliased) label per group; insertion order is
@@ -838,8 +843,10 @@ def _bucket_by_project_to_json(project_groups, *, date_key: str = "date") -> str
     for label, buckets in project_groups:
         projects[label] = [_daily_row_dict(b, date_key=date_key) for b in buckets]
         all_buckets.extend(buckets)
-    payload = stamp_schema_version(
-        {"projects": projects, "totals": _bucket_totals_dict(all_buckets)})
+    body = {"projects": projects, "totals": _bucket_totals_dict(all_buckets)}
+    if extra:  # #341 R8 decoration (accountKey/accountLabel; empty unless --account)
+        body.update(extra)
+    payload = stamp_schema_version(body)
     return json.dumps(payload, indent=2)
 
 
@@ -847,6 +854,8 @@ def _weekly_to_json(
     buckets: list[BucketUsage],
     weeks: list[SubWeek],
     week_pct_overlay: list[tuple[float | None, float | None]],
+    *,
+    extra: "dict | None" = None,
 ) -> str:
     """Serialize weekly rollup to JSON.
 
@@ -924,6 +933,8 @@ def _weekly_to_json(
             "totalCost": tot_cost,
         },
     }
+    if extra:  # #341 R8 decoration (accountKey/accountLabel; empty unless --account)
+        payload.update(extra)
     return json.dumps(stamp_schema_version(payload), indent=2)
 
 
@@ -1179,7 +1190,8 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
     return json.dumps(payload, indent=2)
 
 
-def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
+def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage], *,
+                             extra: "dict | None" = None) -> str:
     """Serialize Claude sessions to JSON (spec A2.8, amended by issue #104).
 
     Per-session: sessionId, projectPath, sourcePaths (list), firstActivity
@@ -1242,6 +1254,8 @@ def _claude_sessions_to_json(sessions: list[ClaudeSessionUsage]) -> str:
             "totalCost": tot_cost,
         },
     }
+    if extra:  # #341 R8 decoration (accountKey/accountLabel; empty unless --account)
+        payload.update(extra)
     return json.dumps(stamp_schema_version(payload), indent=2)
 
 

package/bin/_lib_share.py

@@ -920,6 +920,31 @@ def _build_anon_mapping(
     return mapping
 
 
+def anonymize_account_label(
+    label: str, index: int, *, reveal: bool,
+) -> str:
+    """Map an account label to ``Account A/B/C`` unless ``reveal`` (#341 Task 4).
+
+    Account labels are user data (spec §4 Privacy) — a share/export must never
+    leak them, exactly like project names. This is the fail-closed anonymization
+    chokepoint: ``reveal`` is the SAME toggle that governs project reveal
+    (``reveal_projects``), so anon-mode (the default) rewrites the label to a
+    positional ``Account <letter>`` keyed by the account's deterministic registry
+    ``index`` (0→A, 1→B, …); only an explicit reveal shows the real label. Emails
+    never enter a share at all — the ``data.accounts[]`` wire carries no email
+    field — so this covers the only account user-data a share can see.
+    """
+    if reveal:
+        return label
+    if index < 0:
+        index = 0
+    # A..Z then Account-27, Account-28, … (registries never approach 26 real
+    # accounts, but stay total rather than raise).
+    if index < 26:
+        return f"Account {chr(ord('A') + index)}"
+    return f"Account {index + 1}"
+
+
 def _apply_anon_mapping(
     snap: ShareSnapshot, mapping: dict[_ProjectAnonKey, str] | dict[str, str],
 ) -> ShareSnapshot:

package/bin/_lib_snapshot_cache.py

@@ -91,6 +91,12 @@ class SnapshotSignature(NamedTuple):
     # from the independently-committed quota/budget projection database.
     codex_physical_mutation_seq: int = 0
     codex_stats_digest: str = ""
+    # #341 finding 9: a digest of the account registry + the providers' on-disk
+    # identity-file/active-account state. Empty for every <=1-account install (no
+    # account ever observed), so it is byte-neutral there; otherwise it flips on
+    # an account SWITCH with zero new ingested rows, so the idle short-circuit is
+    # left and the `active` marker rebuilds on the next tick.
+    accounts_digest: str = ""
 
 
 def _max_id(conn: sqlite3.Connection, table: str) -> int:
@@ -179,6 +185,7 @@ def compute_signature(
     *,
     generation: int,
     codex_stats_digest: str = "",
+    accounts_digest: str = "",
 ) -> SnapshotSignature:
     """Composite data-version signature across cache.db + stats.db (spec §3).
 
@@ -199,6 +206,7 @@ def compute_signature(
         entry_mutation_seq=_entry_mutation_seq(cache_conn),
         codex_physical_mutation_seq=_codex_physical_mutation_seq(cache_conn),
         codex_stats_digest=str(codex_stats_digest),
+        accounts_digest=str(accounts_digest),
     )
 
 

package/bin/_lib_subscription_weeks.py

@@ -284,9 +284,18 @@ def _compute_subscription_weeks(
     range_start: dt.datetime,
     range_end: dt.datetime,
     config: "dict | None" = None,
+    *,
+    account_key: "str | None",
 ) -> list[SubWeek]:
     """Generate the ordered list of subscription weeks overlapping [range_start, range_end].
 
+    ``account_key`` (#341, review finding 11): MANDATORY account context — no
+    silent global fallback. A real key scopes the snapshot-derived reset anchors
+    to that account so two accounts with different reset cadences never
+    re-anchor each other's week walk; ``None`` is the explicit "all accounts"
+    (merged) read used by the analytics callers, byte-identical to today on a
+    single-account install.
+
     Prefers snapshot rows (authoritative reset boundaries from actual data)
     and extrapolates by 7-day multiples only for the range tail before the
     earliest snapshot. When no snapshots exist at all, falls back to
@@ -309,7 +318,10 @@ def _compute_subscription_weeks(
     dates that miss actual snapshot boundaries for middle weeks. Using
     snapshot rows directly for weeks they cover avoids that drift.
     """
-    # Case A: snapshots exist.
+    # Case A: snapshots exist. Account scoping (#341): a real key filters the
+    # reset anchors to that account; None is the merged (all-accounts) read.
+    acct_pred = "" if account_key is None else " AND account_key = ?"
+    acct_params: tuple = () if account_key is None else (account_key,)
     snap_rows = conn.execute(
         "SELECT "
         "    MIN(week_start_at) AS week_start_at, "
@@ -320,8 +332,10 @@ def _compute_subscription_weeks(
         "WHERE week_start_at IS NOT NULL "
         "  AND week_end_at   IS NOT NULL "
         "  AND week_start_date IS NOT NULL "
+        f"  {acct_pred} "
         "GROUP BY week_start_date "
-        "ORDER BY MIN(week_start_at) ASC"
+        "ORDER BY MIN(week_start_at) ASC",
+        acct_params,
     ).fetchall()
 
     weeks: list[SubWeek] = []

package/bin/_lib_view_models.py

@@ -572,7 +572,8 @@ class WeeklyView:
 
 
 def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
-                      as_of_utc=None, mode="auto", aggregated_override=None):
+                      as_of_utc=None, mode="auto", aggregated_override=None,
+                      account_key=None):
     """Build a ``WeeklyView`` from subscription-week boundaries
     (spec §5.3).
 
@@ -648,7 +649,8 @@ def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
             week_start_at=sw.start_ts,
             week_end_at=sw.end_ts,
         )
-        usage_row = get_usage(conn, ref, as_of_utc=as_of_utc)
+        usage_row = get_usage(conn, ref, as_of_utc=as_of_utc,
+                              account_key=account_key)
         used_pct = None
         if usage_row is not None and usage_row["weekly_percent"] is not None:
             used_pct = float(usage_row["weekly_percent"])
@@ -759,7 +761,7 @@ class TrendView:
 
 
 def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
-                     use_weekref_cost_cache=False):
+                     use_weekref_cost_cache=False, account_key=None):
     """Build a ``TrendView`` of the last ``n`` subscription weeks
     (spec §5.4).
 
@@ -799,7 +801,7 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
     get_usage = _cct_core.get_latest_usage_for_week
     c = _cctally()
 
-    week_refs = c.get_recent_weeks(conn, max(1, n))
+    week_refs = c.get_recent_weeks(conn, max(1, n), account_key=account_key)
     if not week_refs:
         return TrendView(
             rows=(), avg_dollars_per_pct=None,
@@ -809,10 +811,13 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
 
     # Determine current_key + current_week_start_at — same pattern as
     # _tui_build_trend / cmd_report's Bug D handling.
+    _acct_pred = "" if account_key is None else " WHERE account_key = ?"
+    _acct_p = () if account_key is None else (account_key,)
     latest_usage = conn.execute(
         "SELECT week_start_date, week_end_date "
-        "FROM weekly_usage_snapshots "
-        "ORDER BY captured_at_utc DESC, id DESC LIMIT 1"
+        "FROM weekly_usage_snapshots" + _acct_pred +
+        " ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+        _acct_p,
     ).fetchone()
     current_key = None
     current_week_start_at = None
@@ -858,6 +863,7 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
             as_of_utc=(
                 week_ref.week_end_at if week_ref.key in split_keys else None
             ),
+            account_key=account_key,
         )
         usage_captured_at = usage["captured_at_utc"] if usage else None
         if c._week_ref_has_reset_event(conn, week_ref):
@@ -881,12 +887,12 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
                     week_end_at=parse_iso(week_ref.week_end_at, "week_end_at"),
                     now_utc=now_utc,
                     compute=lambda: c._compute_cost_for_weekref(
-                        week_ref, skip_sync=True
+                        week_ref, skip_sync=True, account_key=account_key
                     ),
                 )
             else:
                 cost_usd = c._compute_cost_for_weekref(
-                    week_ref, skip_sync=skip_sync
+                    week_ref, skip_sync=skip_sync, account_key=account_key
                 )
             cost_captured_at = (
                 usage_captured_at if cost_usd is not None else None
@@ -894,7 +900,8 @@ def build_trend_view(conn, *, now_utc, n=8, display_tz=None, skip_sync=False,
             range_start_iso = week_ref.week_start_at
             range_end_iso = week_ref.week_end_at
         else:
-            cost = c.get_latest_cost_for_week(conn, week_ref)
+            cost = c.get_latest_cost_for_week(
+                conn, week_ref, account_key=account_key)
             cost_usd = float(cost["cost_usd"]) if cost else None
             cost_captured_at = cost["captured_at_utc"] if cost else None
             range_start_iso = (
@@ -1605,6 +1612,7 @@ def build_forecast_view(
     skip_sync: bool = False,
     display_tz=None,
     use_weekref_cost_cache: bool = False,
+    account_key=None,
 ):
     """Build a ``ForecastView`` (issue #57).
 
@@ -1626,6 +1634,7 @@ def build_forecast_view(
     inputs = c._load_forecast_inputs(
         conn, now_utc, skip_sync=skip_sync,
         use_weekref_cost_cache=use_weekref_cost_cache,
+        account_key=account_key,
     )
     if inputs is None:
         return ForecastView(

package/bin/cctally

@@ -876,6 +876,20 @@ _cmd_config_set = _cctally_config._cmd_config_set
 _cmd_config_unset = _cctally_config._cmd_config_unset
 _get_quota_alerts_config = _cctally_config._get_quota_alerts_config
 
+# Account subcommand + the R8 decoration helpers (#341 Task 3). Eager re-export
+# so the parser's `set_defaults(func=c.cmd_account)` binds and the alerts /
+# --account / doctor / dashboard consumers reach the shared registry helpers
+# through the cctally namespace.
+_cctally_account = _load_sibling("_cctally_account")
+cmd_account = _cctally_account.cmd_account
+load_accounts = _cctally_account.load_accounts
+real_account_count = _cctally_account.real_account_count
+provider_is_decorated = _cctally_account.provider_is_decorated
+account_label = _cctally_account.account_label
+resolve_active_account_keys = _cctally_account.resolve_active_account_keys
+resolve_account_filter = _cctally_account.resolve_account_filter
+account_json_fields = _cctally_account.account_json_fields
+
 
 # `cctally refresh-usage` + the OAuth-usage fetch/render/config surface,
 # the in-process refresh helper consumed by the dashboard `POST /api/sync`
@@ -1015,6 +1029,7 @@ _collect_codex_entries_direct = _cctally_cache._collect_codex_entries_direct
 get_codex_entries = _cctally_cache.get_codex_entries
 _sum_codex_cost_for_range = _cctally_cache._sum_codex_cost_for_range
 get_entries = _cctally_cache.get_entries
+AccountAttributionUnavailable = _cctally_cache.AccountAttributionUnavailable
 open_cache_db = _cctally_cache.open_cache_db
 open_conversations_db = _cctally_cache.open_conversations_db
 sync_claude_conversations = _cctally_cache.sync_claude_conversations
@@ -1772,14 +1787,21 @@ def _sum_cost_for_range(
     project: str | None = None,
     *,
     skip_sync: bool = False,
+    account_key: "str | None" = None,
 ) -> float:
     """Sum USD cost of all Claude Code usage entries in [start, end].
 
     Pass `skip_sync=True` to read only the cache-as-of-now without running
     a JSONL ingest pass (for forecast --no-sync).
+
+    ``account_key`` (#341, P2-CQ2) scopes the sum to one account's stamped
+    entries; ``None`` (default) sums all accounts (merged, byte-identical). Used
+    by the per-account ``sync-week`` cost materialization + per-account budget
+    ladders so a snapshot / budget carries genuinely per-account cost.
     """
     total = 0.0
-    for entry in get_entries(start, end, project=project, skip_sync=skip_sync):
+    for entry in get_entries(start, end, project=project, skip_sync=skip_sync,
+                             account_key=account_key):
         total += _calculate_entry_cost(
             entry.model,
             entry.usage,
@@ -2106,10 +2128,14 @@ def _load_claude_config_for_args(args: argparse.Namespace) -> "dict":
 
 
 def _resolve_primary_model_for_block(
-    conn: sqlite3.Connection, five_hour_window_key: int
+    conn: sqlite3.Connection, five_hour_window_key: int,
+    *, account_key: str = "unattributed",
 ) -> "str | None":
     """Return the highest-cost model active in this 5h block, or ``None``.
 
+    ``account_key`` (#341) scopes the child lookup so a shared physical window
+    reflects THIS account's models.
+
     Reads from ``five_hour_block_models`` (recompute-every-tick rollup-child;
     UNIQUE on ``(five_hour_window_key, model)``). Returns ``None`` when the
     child table has no row for this window (possible when the parent block
@@ -2124,9 +2150,9 @@ def _resolve_primary_model_for_block(
     """
     row = conn.execute(
         "SELECT model FROM five_hour_block_models "
-        "WHERE five_hour_window_key = ? "
+        "WHERE five_hour_window_key = ? AND account_key = ? "
         "ORDER BY cost_usd DESC, model ASC LIMIT 1",
-        (int(five_hour_window_key),),
+        (int(five_hour_window_key), account_key),
     ).fetchone()
     if row is None:
         return None
@@ -2881,6 +2907,13 @@ def _validate_source_args(args) -> None:
         return
     source = getattr(args, "source", "claude")
     speed = getattr(args, "speed", "auto")
+    # #341: `--account` on the source-aware analytics commands scopes the CLAUDE
+    # analytics only (the account dimension is provider-scoped; source `all` has
+    # no account selector, and Codex account filtering lives on `codex quota`).
+    # Reject `--account` with `--source {codex,all}` (spec §3 / handoff item d).
+    if getattr(args, "account", None) is not None and source in {"codex", "all"}:
+        raise ValueError(
+            f"--account is only valid with --source claude (got --source {source})")
     if source == "claude" and speed != "auto":
         raise ValueError("--speed is only valid for Codex or all-source requests")
     if command == "project" and source in {"codex", "all"} and getattr(args, "sort", None) == "used":
@@ -3267,6 +3300,12 @@ def main(argv: list[str] | None = None) -> int:
         # generic DatabaseError so it never renders as a raw traceback.
         eprint(f"cctally: {exc}")
         return 3
+    except AccountAttributionUnavailable as exc:
+        # #341: a `--account`-scoped entry read hit a query-time cache degrade
+        # (open failure / concurrent ingest) that would drop the account
+        # identity. Fail closed (exit 3) rather than emit a mislabeled render.
+        eprint(f"cctally: {exc}")
+        return 3
     except sqlite3.DatabaseError as exc:
         if _is_sqlite_corruption_error(exc):
             eprint(