cctally 1.82.0 → 1.83.0

package/bin/_cctally_dashboard_sources.py

@@ -43,11 +43,19 @@ from _lib_quota import (
     build_blocks,
     build_history,
     forecast_quota,
+    latest_physical_observation,
     percent_milestones,
     quota_freshness,
     select_baseline,
+    stale_after_seconds,
 )
-from _lib_jsonl import CodexEntry, codex_model_scoped_quota_pool
+from _lib_jsonl import CodexEntry
+from _lib_codex_pools import (
+    codex_history_is_model_scoped,
+    codex_model_scoped_quota_pool,
+    is_model_scoped_codex_quota,
+)
+from _lib_codex_conversation import _display_title as _codex_display_title
 from _lib_fmt import stable_sum
 from _lib_aggregators import _aggregate_codex_buckets
 from _lib_five_hour import _FIVE_HOUR_JITTER_FLOOR_SECONDS
@@ -140,6 +148,10 @@ class CodexCycleBoundary:
     # Exact server-side quota identity selected for the hero. It is never
     # serialized; milestone-history keys hash it opaquely.
     quota_identity: QuotaWindowIdentity | None = None
+    # #350: whether this boundary won the §3.2 ranking on STALE evidence (no
+    # fresh boundary existed for the account). Backward-looking actuals stay
+    # bounded, but the hero discloses it through ``hero.cycle_freshness``.
+    evidence_stale: bool = False
 
 
 @dataclass(frozen=True)
@@ -152,19 +164,22 @@ class CodexWeeklyPeriod:
     used_percent: float | None = None
 
 
-def _is_model_scoped_codex_quota(logical_limit_key: object) -> bool:
-    """Whether an interpreted native identity belongs outside standard quota."""
-    if not isinstance(logical_limit_key, str):
-        return False
-    try:
-        payload = json.loads(logical_limit_key)
-    except (json.JSONDecodeError, TypeError):
-        return False
-    return (
-        isinstance(payload, dict)
-        and isinstance(payload.get("modelPool"), str)
-        and bool(payload["modelPool"].strip())
-    )
+def _codex_history_row_is_model_scoped(row: object) -> bool:
+    """Whether a SERIALIZED Codex quota history row sits outside account quota.
+
+    The single predicate both the initial build (``_quota_read_model``) and the
+    idle refresh (``refresh_codex_source_clock``) consult, so the two paths
+    cannot drift apart: the build stamps ``model_scoped`` from
+    ``codex_history_is_model_scoped`` and then asks THIS function about the row
+    it just built, and the refresh — which only ever sees the serialized row —
+    asks the same function. Fixing one path and not the other is exactly how
+    the quota summary and its idle refresh would disagree (#373 spec §7.2).
+
+    The key is additive and OMITTED when false (spec §7.3), so a row without it
+    is standard account quota and every fixture that has no model-scoped window
+    serializes byte-identically.
+    """
+    return bool(isinstance(row, Mapping) and row.get("model_scoped"))
 
 
 def _resolve_codex_weekly_cycle(
@@ -180,34 +195,68 @@ def _resolve_codex_weekly_cycle(
     Raises ``CodexCycleUnavailable`` only when NO account yields a live cycle. A
     single-account install returns a 1-element list = today's boundary
     byte-for-byte (the hero path is unchanged, spec R8).
+
+    #350 — FRESH-FIRST ranking (spec §3.2). Codex has no background quota poll,
+    so ``stale_after_seconds(10_080) == 3600`` makes an idle weekly observation
+    stale after exactly one hour. Discarding a stale-but-FUTURE boundary blanked
+    the hero's backward-looking actuals even though the spend was never lost, so
+    each account's future weekly boundaries are now collected into a fresh set
+    and a stale set and ranked:
+
+    1. exactly one FRESH boundary -> valid, cycle fresh;
+    2. else, no fresh boundaries and exactly one STALE boundary -> valid, cycle
+       stale (``CodexCycleBoundary.evidence_stale``, surfaced as the additive
+       ``hero.cycle_freshness``);
+    3. else -> invalid, with today's ``conflicting``/``stale``/``missing`` reason.
+
+    Fresh-first ordering is load-bearing: a flat count over the union would
+    regress one-fresh-plus-one-stale, which resolves valid today. Only the EXACT
+    ``"stale"`` freshness state is eligible — ``"future"`` (a capture ahead of
+    ``now``) and ``"unavailable"`` stay invalid and keep today's reason.
     """
-    per_account: dict[str, dict[tuple[int, dt.datetime], list[tuple[object, object]]]] = {}
+    fresh_by_account: dict[str, dict[tuple[int, dt.datetime], list[tuple[object, object]]]] = {}
+    stale_by_account: dict[str, dict[tuple[int, dt.datetime], list[tuple[object, object]]]] = {}
     accounts_seen: set[str] = set()
-    stale_by_account: dict[str, bool] = {}
+    ineligible_by_account: dict[str, bool] = {}
     for history in build_history(tuple(observations)):
         if history.identity.window_minutes != 10_080:
             continue
-        if _is_model_scoped_codex_quota(history.identity.logical_limit_key):
+        # The baseline observation is the §7.1 label authority, so it is
+        # resolved BEFORE classification wherever the call site has one.
+        baseline = select_baseline(history.observations, now_utc)
+        if codex_history_is_model_scoped(history, baseline=baseline):
             continue
         account = history.identity.account_key
         accounts_seen.add(account)
-        baseline = select_baseline(history.observations, now_utc)
         if baseline is None or baseline.resets_at <= now_utc:
             continue
-        if quota_freshness(history.physical_observations, now_utc).state != "fresh":
-            stale_by_account[account] = True
-            continue
+        state = quota_freshness(history.physical_observations, now_utc).state
         boundary = (history.identity.window_minutes, baseline.resets_at)
-        per_account.setdefault(account, {}).setdefault(boundary, []).append((history, baseline))
+        if state == "fresh":
+            bucket = fresh_by_account
+        elif state == "stale":
+            bucket = stale_by_account
+        else:
+            # "future"/"unavailable" evidence is never a stale fallback; it keeps
+            # today's non-fresh reason so the envelope degrades exactly as before.
+            ineligible_by_account[account] = True
+            continue
+        bucket.setdefault(account, {}).setdefault(boundary, []).append((history, baseline))
     cycles: list[CodexCycleBoundary] = []
     reasons: list[str] = []
-    for account in sorted(accounts_seen | set(per_account)):
-        boundaries = per_account.get(account, {})
-        if len(boundaries) != 1:
-            # Within one account: 0 boundaries -> stale/missing; >=2 -> conflicting.
+    for account in sorted(accounts_seen | set(fresh_by_account) | set(stale_by_account)):
+        fresh_boundaries = fresh_by_account.get(account, {})
+        stale_boundaries = stale_by_account.get(account, {})
+        if len(fresh_boundaries) == 1:
+            boundaries, evidence_stale = fresh_boundaries, False
+        elif not fresh_boundaries and len(stale_boundaries) == 1:
+            boundaries, evidence_stale = stale_boundaries, True
+        else:
+            # Within one account: >=2 fresh, or no fresh and >=2 stale ->
+            # conflicting; nothing eligible -> today's stale/missing reason.
             reasons.append(
-                "conflicting" if boundaries
-                else ("stale" if stale_by_account.get(account) else "missing")
+                "conflicting" if (fresh_boundaries or stale_boundaries)
+                else ("stale" if ineligible_by_account.get(account) else "missing")
             )
             continue
         (window_minutes, resets_at), candidates = next(iter(boundaries.items()))
@@ -232,6 +281,7 @@ def _resolve_codex_weekly_cycle(
             source_root_keys=(selected_identity.source_root_key,),
             used_percent=float(baseline.used_percent),
             quota_identity=selected_identity,
+            evidence_stale=evidence_stale,
         ))
     if not cycles:
         # Aggregate reason: for a single account this is exactly the old reason
@@ -244,6 +294,157 @@ def _resolve_codex_weekly_cycle(
     return cycles
 
 
+def resolve_codex_cycle_detail_identity(
+    cache_conn,
+    *,
+    source_root_keys: Iterable[str],
+    now_utc: dt.datetime,
+):
+    """The live-cycle identity for a per-request Codex cycle-DETAIL read (#373).
+
+    The cycle INDEX is built with the hero's live ``CodexCycleBoundary``; the
+    detail route runs outside the snapshot build and has no envelope, so it used
+    to pass a stub carrying no ``resets_at``. The former future-reset proxy then
+    reported ``is_current: true`` for every future-ending cycle — including a
+    historic one that an early re-anchor had already closed. Resolving the same
+    boundary here is what makes one cycle key describe one cycle on both routes.
+
+    ``source_root_keys`` scopes the returned identity's cycle LOOKUP (the caller
+    passes every retained Codex root, so a just-closed cycle stays fetchable);
+    the live boundary itself is resolved from the active roots' observations,
+    exactly as the source build does.
+
+    Degrades to a bare-roots identity — today's behaviour — whenever no live
+    cycle resolves. The clip guard stays unarmed on that identity by design
+    (``_boundary_has_live_reset``), so the detail keeps clipping as it did
+    before #373 rather than trusting the proxy.
+    """
+    identity = SimpleNamespace(
+        source_root_keys=tuple(source_root_keys),
+        resets_at=None,
+        quota_identity=None,
+    )
+    if cache_conn is None:
+        return identity
+    try:
+        active_roots = tuple(sorted(
+            str(row[0]) for row in cache_conn.execute(
+                "SELECT source_root_key FROM codex_source_roots"
+            )
+        ))
+        if not active_roots:
+            return identity
+        observations = load_codex_quota_observations(
+            source_root_keys=active_roots,
+            cache_conn=cache_conn,
+            captured_at_or_after=(
+                now_utc - dt.timedelta(days=DASHBOARD_QUOTA_RECENT_DAYS)
+            ),
+            active_at=now_utc,
+            max_rows=DASHBOARD_QUOTA_OBSERVATION_LIMIT,
+        )
+        cycles = _resolve_codex_weekly_cycle(observations, now_utc)
+    except (sqlite3.Error, CodexCycleUnavailable, ValueError):
+        return identity
+    if not cycles:
+        return identity
+    boundary = cycles[0]
+    identity.resets_at = boundary.resets_at
+    identity.quota_identity = boundary.quota_identity
+    return identity
+
+
+def _codex_next_decision_at(
+    observations: Iterable[object],
+    cycles: Iterable[CodexCycleBoundary],
+    now_utc: dt.datetime,
+) -> dt.datetime | None:
+    """The earliest future instant at which weekly-cycle resolution can change.
+
+    #350 spec §3.3. Cycle validity is time-dependent even on FROZEN evidence:
+    ``_resolve_codex_weekly_cycle`` passes ``now_utc`` to both ``select_baseline``
+    (a future-dated capture becomes baseline-eligible purely because time passed,
+    which can switch the selected reset) and ``quota_freshness`` (fresh flips to
+    stale as age crosses ``stale_after_seconds``). One fresh plus one stale
+    boundary resolves FRESH today and ``conflicting`` an hour later on the very
+    same rows. The idle clock cannot re-resolve that itself — the public
+    histories it sees are capped at ``SOURCE_HISTORY_LIMIT`` and omit
+    ``logical_limit_key`` (§2.3) — so build time instead records WHEN the clock
+    must stop trusting its verdict, and the tick rebuilds authoritatively at the
+    crossing. That is one rebuild per deadline (a handful per weekly cycle), not
+    one per tick.
+
+    The deadline is the ``min`` of three candidate kinds, dropping any candidate
+    at or before ``now_utc``:
+
+    1. every selected cycle's ``resets_at`` (expiry — including the
+       #341 multi-account case where account A expires while B stays live);
+    2. ``latest_physical_capture + stale_after_seconds(window)`` for every weekly
+       history with a live baseline (fresh -> stale). This is a deliberate
+       SUPERSET of the §3.2 ranking participants — it also covers histories whose
+       freshness is ``"future"``/``"unavailable"`` and so never enter the ranking
+       — because an extra candidate can only pull the deadline EARLIER, and an
+       earlier deadline is always the conservative direction;
+    3. the ``captured_at`` of any future-dated weekly observation
+       (future -> fresh / baseline eligibility).
+
+    Returns ``None`` when nothing can flip. Server-only: it rides ``clock_data``
+    and never reaches the public source envelope.
+    """
+    candidates: list[dt.datetime] = []
+    for cycle in cycles:
+        candidates.append(cycle.resets_at.astimezone(UTC))
+    for history in build_history(tuple(observations)):
+        if history.identity.window_minutes != 10_080:
+            continue
+        baseline = select_baseline(history.observations, now_utc)
+        if codex_history_is_model_scoped(history, baseline=baseline):
+            continue
+        if baseline is not None and baseline.resets_at > now_utc:
+            latest = latest_physical_observation(history.physical_observations)
+            if latest is not None:
+                candidates.append(
+                    latest.captured_at.astimezone(UTC)
+                    + dt.timedelta(
+                        seconds=stale_after_seconds(history.identity.window_minutes),
+                    )
+                )
+        # A capture ahead of ``now`` is not baseline-eligible yet, so this runs
+        # even for a history with no live baseline at all.
+        for observation in (
+            *history.observations, *history.physical_observations,
+        ):
+            captured_at = observation.captured_at.astimezone(UTC)
+            if captured_at > now_utc:
+                candidates.append(captured_at)
+    live = [candidate for candidate in candidates if candidate > now_utc]
+    return min(live) if live else None
+
+
+def codex_decision_deadline_passed(
+    state: object,
+    now_utc: dt.datetime,
+) -> bool:
+    """Whether a published Codex state's cycle decision deadline has elapsed.
+
+    #350 spec §3.3. When this holds the tick MUST rebuild Codex authoritatively
+    via ``build_codex_source_state`` — bypassing both the idle clock and
+    ``reuse_coherent_source_state`` — because the frozen evidence would now
+    resolve to a different cycle (or to none). A state with no recorded deadline
+    (``None``, or an older generation that predates the field) never forces a
+    rebuild; the clock's expiry guard remains its safety net.
+    """
+    clock_data = getattr(state, "clock_data", None)
+    if not isinstance(clock_data, Mapping):
+        return False
+    deadline = clock_data.get("codex_next_decision_at")
+    if not isinstance(deadline, dt.datetime):
+        return False
+    if deadline.tzinfo is None or deadline.utcoffset() is None:
+        return False
+    return now_utc.astimezone(UTC) >= deadline.astimezone(UTC)
+
+
 def _codex_weekly_periods(
     stats_conn: sqlite3.Connection,
     *,
@@ -265,7 +466,7 @@ def _codex_weekly_periods(
     placeholders = ",".join("?" for _ in roots)
     try:
         rows = stats_conn.execute(
-            "SELECT source_root_key, logical_limit_key, resets_at_utc, "
+            "SELECT source_root_key, logical_limit_key, limit_name, resets_at_utc, "
             "nominal_start_at_utc, current_percent "
             "FROM quota_window_blocks "
             "WHERE source='codex' AND window_minutes=10080 "
@@ -277,10 +478,18 @@ def _codex_weekly_periods(
     except sqlite3.Error:
         rows = ()
 
-    raw_boundaries: list[tuple[dt.datetime, dt.datetime, set[str], list[float]]] = []
-
-    for root_key, logical_limit_key, resets_at_raw, start_at_raw, current_percent in rows:
-        if _is_model_scoped_codex_quota(logical_limit_key):
+    # #373 §7.4: the fifth element marks the LIVE boundary, which is never
+    # clipped by a successor. Durable rows are never live on their own — only
+    # the caller's `active_cycle` is — but the jitter-merge below folds the
+    # live boundary together with its own durable row, so the flag is OR-ed on
+    # merge rather than taken from either side.
+    raw_boundaries: list[
+        tuple[dt.datetime, dt.datetime, set[str], list[float], bool]
+    ] = []
+
+    for (root_key, logical_limit_key, limit_name, resets_at_raw,
+         start_at_raw, current_percent) in rows:
+        if is_model_scoped_codex_quota(logical_limit_key, limit_name):
             continue
         try:
             start_at = dt.datetime.fromisoformat(str(start_at_raw).replace("Z", "+00:00"))
@@ -296,18 +505,23 @@ def _codex_weekly_periods(
         used_values = []
         if isinstance(current_percent, (int, float)) and not isinstance(current_percent, bool):
             used_values.append(float(current_percent))
-        raw_boundaries.append((start_at, resets_at, {str(root_key)}, used_values))
+        raw_boundaries.append((start_at, resets_at, {str(root_key)}, used_values, False))
 
+    # `active_cycle is None` is the case §7.4 calls out explicitly: no boundary
+    # is live, so nothing is exempt and every period clips exactly as before.
     if active_cycle is not None:
         raw_boundaries.append((
             active_cycle.start_at.astimezone(UTC),
             active_cycle.resets_at.astimezone(UTC),
             set(active_cycle.source_root_keys),
             [active_cycle.used_percent] if active_cycle.used_percent is not None else [],
+            True,
         ))
 
-    ordered: list[tuple[dt.datetime, dt.datetime, set[str], list[float]]] = []
-    for start_at, resets_at, period_roots, used_values in sorted(
+    ordered: list[
+        tuple[dt.datetime, dt.datetime, set[str], list[float], bool]
+    ] = []
+    for start_at, resets_at, period_roots, used_values, is_live in sorted(
         raw_boundaries, key=lambda item: (item[0], item[1]),
     ):
         if (
@@ -315,17 +529,23 @@ def _codex_weekly_periods(
             and (start_at - ordered[-1][0]).total_seconds()
             < _FIVE_HOUR_JITTER_FLOOR_SECONDS
         ):
-            first_start, latest_reset, existing_roots, existing_used = ordered[-1]
+            first_start, latest_reset, existing_roots, existing_used, existing_live = ordered[-1]
             existing_roots.update(period_roots)
             existing_used.extend(used_values)
             ordered[-1] = (
                 first_start, max(latest_reset, resets_at), existing_roots, existing_used,
+                existing_live or is_live,
             )
         else:
-            ordered.append((start_at, resets_at, set(period_roots), list(used_values)))
+            ordered.append((
+                start_at, resets_at, set(period_roots), list(used_values), is_live,
+            ))
     periods: list[CodexWeeklyPeriod] = []
-    for index, (start_at, resets_at, period_roots, used_values) in enumerate(ordered):
+    for index, (start_at, resets_at, period_roots, used_values, is_live) in enumerate(ordered):
         next_start = ordered[index + 1][0] if index + 1 < len(ordered) else None
+        # The live cycle always ends at its own reset (#373 §7.4).
+        if is_live:
+            next_start = None
         end_at = min(resets_at, next_start) if next_start is not None else resets_at
         if end_at <= start_at:
             continue
@@ -928,7 +1148,9 @@ def _codex_conversation_metadata(
                         f"SELECT id, title FROM threads WHERE id IN ({placeholders})",
                         batch,
                     ):
-                        clean_title = " ".join(str(title or "").split())
+                        clean_title = _codex_display_title(
+                            str(title) if title is not None else None
+                        )
                         if clean_title:
                             short_names[str(thread_id)] = clean_title
             except (OSError, sqlite3.Error):
@@ -993,6 +1215,7 @@ def _session_wire(
     view: Any,
     *,
     metadata: Mapping[tuple[str, str], Mapping[str, object]] | None = None,
+    private_labels: dict[str, str] | None = None,
 ) -> dict[str, object]:
     rows = []
     for row in view.rows:
@@ -1018,7 +1241,11 @@ def _session_wire(
                     )
                 )
             ), None)
-        title = str(row_metadata.get("title") or "").strip() if row_metadata else ""
+        title = _codex_display_title(
+            str(row_metadata.get("title"))
+            if row_metadata and row_metadata.get("title") is not None
+            else None
+        )
         project = str(row_metadata.get("project_label") or "").strip() if row_metadata else ""
         started_at = row_metadata.get("started_at") if row_metadata else None
         duration_min = None
@@ -1028,12 +1255,14 @@ def _session_wire(
                 duration_min = max(0, round((row.last_activity.astimezone(UTC) - started_dt.astimezone(UTC)).total_seconds() / 60))
             except (TypeError, ValueError):
                 started_at = None
+        key = dashboard_resource_key(
+            "session", "codex", root_identity, row.session_id_path,
+        )
+        if title and private_labels is not None:
+            private_labels[key] = title
         rows.append({
-            "key": dashboard_resource_key(
-                "session", "codex", root_identity, row.session_id_path,
-            ),
+            "key": key,
             "source": "codex",
-            "label": title or None,
             "project": project or None,
             "project_key": row_metadata.get("project_key") if row_metadata else None,
             "started_at": started_at,
@@ -1298,10 +1527,14 @@ def _quota_read_model(
     milestone_rows: list[dict[str, object]] = []
     active_rows: list[dict[str, object]] = []
     # R8 (#341 Task 4): the per-account `account_key` is serialized onto each
-    # history row ONLY when the Codex provider has >1 REAL account, so the idle
-    # clock (`_clock_cycle_validity`) can scope weekly-cycle validity per account
-    # instead of degrading a genuine multi-account state to `conflicting`. A
-    # <=1-real-account install (all fixtures) stays byte-identical (no key added).
+    # history row ONLY when the Codex provider has >1 REAL account, so the
+    # dashboard client can scope per-account quota rows instead of merging them.
+    # A <=1-real-account install (all fixtures) stays byte-identical (no key
+    # added). #350 removed the original consumer, `_clock_cycle_validity`: the
+    # idle clock no longer re-derives weekly-cycle validity at all, because this
+    # public history view is LOSSY — capped at `SOURCE_HISTORY_LIMIT` and without
+    # `logical_limit_key` — so it cannot resolve the cycle authoritatively. Build
+    # time owns resolution; a `clock_data` decision deadline forces the rebuild.
     _codex_decorated = False
     try:
         import _cctally_account
@@ -1320,9 +1553,16 @@ def _quota_read_model(
         baseline = select_baseline(history.observations, context.now_utc)
         freshness = quota_freshness(history.physical_observations, context.now_utc)
         forecast = forecast_quota(history.physical_observations, context.now_utc)
-        history_rows.append({
+        # #373: a window outside account-level standard quota (a separate model
+        # pool such as GPT-5.3-Codex-Spark) stays LISTED — a legitimate
+        # independent pool must remain visible — but is excluded from every
+        # account-level aggregate below. `baseline` is the label authority when
+        # one exists (spec §7.1).
+        model_scoped = codex_history_is_model_scoped(history, baseline=baseline)
+        row = {
             "key": dashboard_resource_key("quota", "codex", *key_parts),
             "source": "codex",
+            **({"model_scoped": True} if model_scoped else {}),
             **({"account_key": identity.account_key} if _codex_decorated else {}),
             "label": _native_limit_label(identity.limit_name, identity.window_minutes),
             "observed_slot": identity.observed_slot,
@@ -1345,7 +1585,10 @@ def _quota_read_model(
                 "sample_span_seconds": forecast.sample_span_seconds,
                 "confidence": forecast.confidence,
             },
-        })
+        }
+        history_rows.append(row)
+        if _codex_history_row_is_model_scoped(row):
+            continue
         if baseline is not None and baseline.resets_at > context.now_utc:
             active_rows.append({
                 "key": dashboard_resource_key("quota", "codex", *key_parts),
@@ -1463,10 +1706,28 @@ def _quota_read_model(
         "fresh" if active_rows and all(row["freshness"] == "fresh" for row in active_rows)
         else ("unavailable" if not active_rows else "stale")
     )
-    # Active identities are presentation-critical.  Keep them ahead of
-    # inactive retained history before enforcing the public cardinality cap.
+    # Active account identities are presentation-critical. Independent
+    # model-scoped pools are also legitimate provider facts, so reserve the
+    # remaining cap space for their newest captures before inactive account
+    # history. Opaque resource-key order is only a stable tie-breaker.
     active_keys = {str(row["key"]) for row in active_rows}
-    history_rows.sort(key=lambda row: (str(row["key"]) not in active_keys, str(row["key"])))
+
+    def _history_retention_key(row):
+        key = str(row["key"])
+        if key in active_keys:
+            return (0, 0.0, key)
+        if _codex_history_row_is_model_scoped(row):
+            captured_at = row.get("captured_at")
+            try:
+                captured_epoch = dt.datetime.fromisoformat(
+                    str(captured_at).replace("Z", "+00:00")
+                ).timestamp()
+            except (TypeError, ValueError):
+                captured_epoch = float("-inf")
+            return (1, -captured_epoch, key)
+        return (2, 0.0, key)
+
+    history_rows.sort(key=_history_retention_key)
     history_rows = history_rows[:SOURCE_HISTORY_LIMIT]
     milestone_rows.sort(key=lambda row: str(row["captured_at"]), reverse=True)
     milestone_rows = milestone_rows[:SOURCE_HISTORY_LIMIT]
@@ -1501,67 +1762,25 @@ def _clock_freshness(
     return "stale" if age_seconds > stale_after else "fresh"
 
 
-def _clock_cycle_validity(
-    histories: Iterable[object],
-    now_utc: dt.datetime,
-) -> tuple[bool, str]:
-    """Re-evaluate frozen weekly evidence without touching cache or rollouts.
-
-    Per-account (#341 Task 4): boundaries are grouped by the history row's
-    ``account_key`` (serialized only when the Codex provider is DECORATED, i.e.
-    >1 real account — R8). The idle clock mirrors the build-time
-    ``_resolve_codex_weekly_cycle`` resolution: an account yields a live cycle iff
-    it has EXACTLY ONE fresh future boundary, and the hero is valid iff AT LEAST
-    ONE account does (raising the aggregate ``conflicting > stale > missing``
-    reason only when NO account yields one). When ``account_key`` is absent
-    (<=1-real-account install — no decoration) every row falls into one global
-    bucket, so this reduces EXACTLY to the prior single-boundary logic
-    (byte-stable). This removes the documented placeholder degrade where two real
-    accounts with distinct weekly cycles collapsed the whole hero to
-    ``conflicting`` on the idle clock.
+def _clock_cycle_expired(cycle: object, now_utc: dt.datetime) -> bool:
+    """Whether a retained hero cycle has already reset (#350 spec §3.3).
+
+    The one invariant the idle clock still enforces on frozen evidence: a cycle
+    whose ``resets_at`` is at or before ``now_utc`` cannot bound current
+    accounting. Fails CLOSED on an unparseable or absent boundary, matching the
+    prior behavior where malformed evidence yielded no valid boundary.
     """
-    per_account: dict[str, set[dt.datetime]] = {}
-    stale_by_account: dict[str, bool] = {}
-    for raw_history in histories:
-        if not isinstance(raw_history, Mapping):
-            continue
-        if raw_history.get("window_minutes") != 10_080:
-            continue
-        current = raw_history.get("current_percent")
-        forecast = raw_history.get("forecast")
-        if current is None or not isinstance(forecast, Mapping):
-            continue
-        try:
-            resets_at = dt.datetime.fromisoformat(
-                str(forecast.get("resets_at")).replace("Z", "+00:00")
-            ).astimezone(UTC)
-        except (TypeError, ValueError):
-            continue
-        if resets_at <= now_utc:
-            continue
-        # None account_key (undecorated / <=1 real account) -> one global bucket
-        # == today's behavior. A real key buckets per account.
-        acct = raw_history.get("account_key")
-        bucket = acct if acct is not None else "__all__"
-        if raw_history.get("freshness") != "fresh":
-            stale_by_account[bucket] = True
-            continue
-        per_account.setdefault(bucket, set()).add(resets_at)
-    accounts = set(per_account) | set(stale_by_account)
-    reasons: list[str] = []
-    for acct in accounts:
-        boundaries = per_account.get(acct, set())
-        if len(boundaries) == 1:
-            return True, "ok"  # at least one account yields a live cycle
-        reasons.append(
-            "conflicting" if boundaries
-            else ("stale" if stale_by_account.get(acct) else "missing")
+    if not isinstance(cycle, Mapping):
+        return True
+    try:
+        resets_at = dt.datetime.fromisoformat(
+            str(cycle.get("resets_at")).replace("Z", "+00:00")
         )
-    if "conflicting" in reasons:
-        return False, "conflicting"
-    if "stale" in reasons:
-        return False, "stale"
-    return False, "missing"
+    except (TypeError, ValueError):
+        return True
+    if resets_at.tzinfo is None or resets_at.utcoffset() is None:
+        return True
+    return resets_at.astimezone(UTC) <= now_utc
 
 
 def _refresh_budget_status_clock(
@@ -1638,6 +1857,7 @@ def refresh_codex_source_clock(
     warnings = state.warnings
     availability = state.availability
     freshness = state.freshness
+    domain_freshness = dict(state.domain_freshness or {})
     if isinstance(quota, Mapping):
         quota = dict(quota)
         refreshed_histories: list[dict[str, object]] = []
@@ -1646,10 +1866,16 @@ def refresh_codex_source_clock(
             if not isinstance(raw_history, Mapping):
                 continue
             history = dict(raw_history)
-            freshness = _clock_freshness(
+            # #350 spec §3.9: this is a PER-ROW value and must never shadow the
+            # envelope-level `freshness`. It used to, so after the loop the
+            # envelope held the LAST retained history row's freshness — often an
+            # inactive row, and with a single weekly history the active weekly
+            # one, which silently marked the whole provider stale on an idle
+            # stale crossing and tripped idle eligibility on its own.
+            row_freshness = _clock_freshness(
                 history.get("captured_at"), history.get("stale_after_seconds"), now_utc,
             )
-            history["freshness"] = freshness
+            history["freshness"] = row_freshness
             forecast = history.get("forecast")
             if isinstance(forecast, Mapping):
                 forecast = dict(forecast)
@@ -1663,9 +1889,9 @@ def refresh_codex_source_clock(
                 remaining = max(0, int((reset - now_utc).total_seconds())) if reset else None
                 forecast["remaining_seconds"] = remaining
                 sample_count = int(forecast.get("sample_count") or 0)
-                if freshness == "future":
+                if row_freshness == "future":
                     forecast["status"] = "future"
-                elif freshness == "stale":
+                elif row_freshness == "stale":
                     forecast["status"] = "stale"
                 elif sample_count == 0:
                     forecast["status"] = "insufficient-history"
@@ -1682,13 +1908,18 @@ def refresh_codex_source_clock(
                         100.0, max(float(current), float(current) + float(rate) * remaining / 3600),
                     )
                 history["forecast"] = forecast
-                if reset is not None and reset > now_utc and current is not None:
+                # #373: same rule as the initial build, through the same
+                # predicate, so the two paths cannot drift.
+                if (
+                    not _codex_history_row_is_model_scoped(history)
+                    and reset is not None and reset > now_utc and current is not None
+                ):
                     active_rows.append({
                         "key": history.get("key"),
                         "current_percent": current,
                         "captured_at": history.get("captured_at"),
                         "resets_at": resets_at,
-                        "freshness": freshness,
+                        "freshness": row_freshness,
                         "stale_after_seconds": history.get("stale_after_seconds"),
                     })
             refreshed_histories.append(history)
@@ -1716,6 +1947,13 @@ def refresh_codex_source_clock(
             ),
             "active": active_rows,
         })
+        # Only account-level active histories reach ``active_rows``; the shared
+        # model-scoped predicate above excludes foreign pools. An unavailable
+        # active set is a capability/data-availability fact, not invented
+        # staleness, so only the exact stale verdict moves this axis.
+        domain_freshness["quota"] = (
+            "stale" if summary["freshness"] == "stale" else "fresh"
+        )
         quota["summary"] = summary
         data["quota"] = quota
         quota_changed = bool(refreshed_histories)
@@ -1727,8 +1965,18 @@ def refresh_codex_source_clock(
             and hero_capability is not None
             and hero_capability.status == "supported"
         ):
-            cycle_valid, cycle_reason = _clock_cycle_validity(refreshed_histories, now_utc)
-            if not cycle_valid:
+            # #350 spec §3.3: the clock no longer RE-DERIVES cycle validity.
+            # Its public-history view is lossy (capped, no `logical_limit_key`,
+            # no `quota_identity`), so it cannot resolve the cycle correctly —
+            # and per §2.2 it cannot simply trust the old verdict forever either,
+            # because resolution is time-dependent on frozen evidence. Build time
+            # owns resolution and records a decision deadline in `clock_data`; the
+            # tick rebuilds authoritatively at the crossing. All the clock keeps
+            # is this cheap invariant guard: a cycle that has already RESET cannot
+            # bound current accounting, so it degrades exactly as before.
+            # Expiry is also deadline candidate #1, so the two paths are disjoint
+            # belt-and-suspenders rather than a single mechanism.
+            if _clock_cycle_expired(hero.get("cycle"), now_utc):
                 hero = dict(hero)
                 for field in (
                     "cost_usd", "input_tokens", "cached_input_tokens", "output_tokens",
@@ -1750,8 +1998,6 @@ def refresh_codex_source_clock(
                     "hero",
                 ),)
                 availability = "partial"
-                if cycle_reason == "stale":
-                    freshness = "stale"
                 cycle_changed = True
     budget_domain = data.get("budget")
     budget_changed = False
@@ -1785,9 +2031,11 @@ def refresh_codex_source_clock(
         last_success_at=state.last_success_at,
         capabilities=capabilities,
         data=data,
+        domain_freshness=domain_freshness,
         clock_data=state.clock_data,
+        private_session_labels=state.private_session_labels,
     )
-    return state if refreshed_state.data == state.data else refreshed_state
+    return state if refreshed_state == state else refreshed_state
 
 
 def _alerts_wire(stats_conn: sqlite3.Connection) -> tuple[dict[str, object], ...]:
@@ -1937,7 +2185,10 @@ def _partial_projects_wire(
             "reasoning_output_tokens": 0, "total_tokens": 0,
         })
         session_totals = group["session_rows"].setdefault(identity, {
-            "label": str(row_metadata.get("title") or "Session"),
+            # A persisted Codex task title is transcript-derived content. The
+            # partial project projection is shared across every dashboard
+            # client, so retain only a non-sensitive generic label here.
+            "label": "Session",
             "last_activity": timestamp.astimezone(UTC).isoformat(),
             "cost_usd": 0.0, "input_tokens": 0, "cached_input_tokens": 0,
             "output_tokens": 0, "reasoning_output_tokens": 0, "total_tokens": 0,
@@ -2105,7 +2356,12 @@ def _codex_account_five_hour_percent(
     for history in build_history(tuple(observations)):
         if history.identity.window_minutes != 300:
             continue
+        # #373: the retained `codex_bengalfox` 5h rows are on the PRIMARY slot —
+        # the same slot this account aggregate reads — so a foreign pool at 95%
+        # would win the max outright over the real account window.
         baseline = select_baseline(history.observations, now_utc)
+        if codex_history_is_model_scoped(history, baseline=baseline):
+            continue
         if baseline is None or baseline.resets_at <= now_utc:
             continue
         acct = history.identity.account_key
@@ -2560,10 +2816,13 @@ def build_codex_source_state(
             # degrade to the byte-stable undecorated shape.
             accounts_wire = []
             hero_cycles_wire = []
+    private_session_labels: dict[str, str] = {}
     return SourceDashboardState(
         source="codex",
         availability=availability,
-        freshness=("stale" if cycle_reason == "stale" else "fresh"),
+        # A successful source build is one coherent provider generation. Quota
+        # observation age and weekly-cycle evidence live on their own axes.
+        freshness="fresh",
         warnings=tuple(warnings),
         data_version=data_version,
         last_success_at=context.now_utc,
@@ -2609,6 +2868,15 @@ def build_codex_source_state(
                     }
                     if cycle is not None and not hero_failure else None
                 ),
+                # #350 (spec §3.4): additive, hero-local staleness disclosure.
+                # OMITTED when the cycle is fresh — never emitted as "fresh" —
+                # for the legacy client transition. Provider metadata remains
+                # coherent; ``domain_freshness.hero`` owns the shared axis.
+                **(
+                    {"cycle_freshness": "stale"}
+                    if cycle is not None and not hero_failure and cycle.evidence_stale
+                    else {}
+                ),
                 "quota": quota["summary"],
                 "budget": configured_budget,
                 "alerts": {"count": len(alerts)},
@@ -2620,7 +2888,11 @@ def build_codex_source_state(
                 "monthly": _period_wire(monthly),
                 "weekly": _period_wire(weekly),
             },
-            "sessions": _session_wire(sessions, metadata=conversation_metadata),
+            "sessions": _session_wire(
+                sessions,
+                metadata=conversation_metadata,
+                private_labels=private_session_labels,
+            ),
             "quota": quota,
             "budget": {
                 "status": configured_budget,
@@ -2635,5 +2907,32 @@ def build_codex_source_state(
             },
             "cache_report": cache_report,
         },
-        clock_data={"codex_budget_cost_events": budget_cost_events},
+        domain_freshness={
+            "hero": (
+                "stale"
+                if cycle_reason == "stale"
+                or (
+                    cycle is not None
+                    and not hero_failure
+                    and cycle.evidence_stale
+                )
+                else "fresh"
+            ),
+            "quota": (
+                "stale"
+                if quota["summary"]["freshness"] == "stale"
+                else "fresh"
+            ),
+            "sessions": "fresh",
+        },
+        clock_data={
+            "codex_budget_cost_events": budget_cost_events,
+            # #350 spec §3.3: when the tick passes this instant it must rebuild
+            # Codex authoritatively instead of idle-clocking or reusing, because
+            # weekly-cycle resolution can change on identical frozen evidence.
+            "codex_next_decision_at": _codex_next_decision_at(
+                quota_observations, cycles_all, context.now_utc,
+            ),
+        },
+        private_session_labels=private_session_labels,
     )