cctally 1.87.2 → 1.88.0

package/CHANGELOG.md

@@ -5,6 +5,12 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.88.0] - 2026-07-31
+
+### Fixed
+- The Codex hero's Snapshot chip no longer reports stale evidence while the dashboard's own freshness state for the same quota window reads fresh. One `/api/data` response could carry two different capture timestamps for a single quota window, and the chip aged off the older one: the initial build stamped the active row with the timestamp of the last reading whose VALUE changed, while that same row's freshness came from the last reading actually received — and because OpenAI repeats an unchanged percentage while you are idle, the two drift apart in exactly the common case. `active[].captured_at` now always means evidence recency, the same observation behind the row's freshness, and the percentage it reports is unchanged. The idle clock additionally refreshes every per-account view rather than only the merged one, so a focused account no longer reads freshness frozen at page load, and the hero's own copy of the quota summary is re-derived on each tick instead of keeping its build-time value. Retained quota windows and their live rows are now capped together, so an install tracking more than 250 windows can no longer publish a live row whose history was dropped or a summary percentage belonging to a window that was. The source envelope's `source_schema_version` moves to 2, because a published value changed meaning and a dashboard tab left open across an in-place upgrade does meet the new server over its existing event stream. That tab keeps working either way — nothing reads the version yet — so the bump is a correctness signal for future readers rather than the thing that preserves compatibility. (#429)
+- Codex sessions started outside the Desktop app — through the Codex MCP server, the CLI, `exec`, subagents, and older Desktop builds — now appear in the Conversation Viewer and resolve their project in Recent Sessions. Codex is part-way through rolling out the field cctally used to identify a conversation, and until now a session whose log omitted it was given no identity at all: its transcript was never indexed, and the sessions card could only report that project metadata was unavailable. cctally now infers the missing value, so those sessions are ordinary sessions with no visible difference from any other. On upgrade, existing history is re-read once in the background to repair it; a session's spend stays attributed to the account it was always attributed to, and a session whose log carries no usable identifier at all is left alone rather than guessed at. Because the repair re-reads the session logs themselves, totals are unchanged for every session still on disk — but a session whose log Codex has since deleted is no longer counted, so long-run totals can fall slightly. Sessions with no working directory recorded still appear, and still honestly report their project as unavailable. One visible consequence of that re-read: it briefly restores transcripts older than your configured retention window, so the ordinary retention sweep runs straight afterwards and those older conversations leave the Conversation Viewer on upgrade instead of lingering past their window.
+
 ## [1.87.2] - 2026-07-30
 
 ### Fixed

package/bin/_cctally_cache.py

@@ -511,6 +511,38 @@ _codex_conversation_fts_full_clear = _cctally_db_sib._codex_conversation_fts_ful
 # writes (#179) so the ON CONFLICT idiom lives in one place. Caller commits.
 _set_cache_meta = _cctally_db_sib._set_cache_meta
 
+# Byte-zero Codex replay markers (spec
+# docs/superpowers/specs/2026-07-30-codex-thread-source-inference-design.md
+# §4.3). Cache migration 035 / conversations migration 002 write them and clear
+# NO table; the sync functions consume them, because only the sync owns the
+# replay semantics that keep the repair safe:
+#
+#   * `sync_codex_cache` ORs the cache-side marker into its own `rebuild`, so
+#     the rebuild path captures `rebuild_known_identities` before clearing. A
+#     migration clearing `codex_session_files` directly would leave the next
+#     ordinary sync with an empty snapshot, sending every re-read rollout to the
+#     live-`auth.json` branch and re-attributing historical spend (§4.1).
+#   * `sync_codex_conversations` defers on the CONVERSATIONS marker until the
+#     cache-side one has cleared, because `_recompute_codex_rollups` reads the
+#     thread row from cache.db and a missing one stamps a materialized
+#     "(unassigned)" project the read path then prefers permanently (§4.2).
+#
+# The conversations key is deliberately DISTINCT from
+# `conversation_rebuild_codex_pending`: `_ensure_codex_conversation_contract`
+# consumes that one by replaying normalization over already-retained events —
+# which preserves their NULL conversation keys — and then deletes it, silently
+# discarding the repair.
+#
+# The keys themselves are defined in the pure kernel `_lib_codex_conversation`
+# and re-exported here, so the read-side authority probe and the doctor shell
+# bind the same names instead of repeating a SQL string literal.
+CODEX_REPLAY_FROM_ZERO_KEY = (
+    _lib_codex_conversation.CODEX_REPLAY_FROM_ZERO_KEY)
+CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY = (
+    _lib_codex_conversation.CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY)
+CODEX_REPLAY_BLOCKED_KEY = (
+    _lib_codex_conversation.CODEX_REPLAY_BLOCKED_KEY)
+
 
 # cache.db WAL hardening (#297). See
 # docs/superpowers/specs/2026-07-13-cache-db-wal-hardening-design.md.
@@ -4903,6 +4935,24 @@ def sync_codex_cache(
         # and bypasses every whole-tree operation (orphan prune, root prune,
         # global quota reconcile) — see the guards threaded through below.
         targeted = only_paths is not None
+
+        # A pending byte-zero replay is consumed HERE, not by the migration that
+        # armed it, so the rebuild path below captures `rebuild_known_identities`
+        # before clearing. A migration that cleared `codex_session_files`
+        # directly would leave the next ordinary sync with an empty snapshot,
+        # sending every re-read rollout to the live-auth branch and
+        # re-attributing historical spend to whoever is authenticated now.
+        replay_pending = conn.execute(
+            "SELECT 1 FROM cache_meta WHERE key=?",
+            (CODEX_REPLAY_FROM_ZERO_KEY,),
+        ).fetchone() is not None
+        if replay_pending and targeted:
+            # A live-tail tick must DEFER, never raise through the
+            # `targeted and rebuild` guard below.
+            stats.deferred_reason = "replay_pending"
+            return stats
+        rebuild = rebuild or replay_pending
+
         if targeted and rebuild:
             raise ValueError(
                 "sync_codex_cache: only_paths is incompatible with rebuild")
@@ -5742,6 +5792,35 @@ def sync_codex_cache(
             else:
                 conn.execute("DELETE FROM cache_meta WHERE key = ?",
                              ("codex_torn_auth_deferred",))
+            # Consume the byte-zero replay marker only after a clean full walk,
+            # and only when THIS call observed it. A contended call returned
+            # long before here, and a walk that failed or deferred a file leaves
+            # the marker standing — a surviving marker is what makes the repair
+            # retry on the next sync, and it is also what keeps
+            # `sync_codex_conversations` deferred until the cache side genuinely
+            # holds the replayed thread rows (§4.2). The `replay_pending` guard
+            # is defense in depth: `open_cache_db` and this walk share an
+            # exclusive lock today, so nothing can arm the marker in between —
+            # but the conversations side has no such exclusion, and the two
+            # clears must keep the same shape.
+            if stats.files_failed == 0 and stats.files_deferred_torn == 0:
+                if replay_pending:
+                    conn.execute("DELETE FROM cache_meta WHERE key = ?",
+                                 (CODEX_REPLAY_FROM_ZERO_KEY,))
+                conn.execute("DELETE FROM cache_meta WHERE key = ?",
+                             (CODEX_REPLAY_BLOCKED_KEY,))
+            elif replay_pending:
+                # A full walk ran and could NOT consume the marker, so the
+                # replay — and with it every Codex transcript ingest, which
+                # defers behind this marker — is stalled rather than merely
+                # not-yet-run. `doctor` reads this; the deferral itself stays,
+                # because running ahead is what stamps "(unassigned)" (§4.2).
+                _set_cache_meta(conn, CODEX_REPLAY_BLOCKED_KEY, json.dumps({
+                    "at": dt.datetime.now(dt.timezone.utc).isoformat(
+                        timespec="seconds").replace("+00:00", "Z"),
+                    "files_failed": stats.files_failed,
+                    "files_deferred_torn": stats.files_deferred_torn,
+                }, sort_keys=True))
             conn.commit()
         # Window-scoped spend adoption (spec
         # docs/superpowers/specs/2026-07-30-codex-window-scoped-spend-adoption.md).
@@ -7747,6 +7826,15 @@ def _ensure_codex_conversation_contract(conn: sqlite3.Connection) -> bool:
     JSONL. They still must remain usable after an upgrade, so replay only the
     already-retained physical events under the provider-local conversation lock.
     Empty stores keep their existing rebuild marker for the next real sync.
+
+    This must NEVER consume ``CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY`` (§4.3).
+    Do not merge the two keys during a tidy-up: this replay runs over
+    already-retained events, which preserves their NULL conversation keys, and
+    then deletes the flag it consumed — so a ``dashboard --no-sync`` or qualified
+    CLI read landing between the migration and the next real sync would silently
+    discard the byte-zero repair. Only a re-read from offset zero can mint the
+    missing identities, which is why that marker belongs to
+    ``sync_codex_conversations`` alone.
     """
     current = _lib_codex_conversation.CODEX_CONVERSATION_CONTRACT_VERSION
 
@@ -8145,6 +8233,24 @@ def sync_claude_conversations(
     return stats
 
 
+def _cache_side_replay_pending(conn: sqlite3.Connection) -> bool:
+    """Whether cache.db still has a byte-zero Codex replay pending (§4.3).
+
+    Read through the ``cache_db`` attachment conversation connections already
+    carry, and qualified: ``cache_meta`` exists in BOTH stores, so an unqualified
+    name would resolve to conversations.db's own table and never see the
+    cache-side marker. A bare or legacy connection without the attachment
+    reports False rather than raising, so it cannot wedge the conversations sync.
+    """
+    try:
+        return conn.execute(
+            "SELECT 1 FROM cache_db.cache_meta WHERE key=?",
+            (CODEX_REPLAY_FROM_ZERO_KEY,),
+        ).fetchone() is not None
+    except sqlite3.OperationalError:
+        return False
+
+
 def _clear_codex_conversation_store(conn: sqlite3.Connection) -> None:
     """Clear only the re-derivable Codex transcript families."""
     conn.execute("DELETE FROM codex_conversation_events")
@@ -8191,10 +8297,25 @@ def sync_codex_conversations(
                 != _lib_codex_conversation.CODEX_CONVERSATION_CONTRACT_VERSION
             )
         )
-        if (pending_rebuild or contract_rebuild) and targeted:
+        codex_replay_pending = conn.execute(
+            "SELECT 1 FROM cache_meta WHERE key=?",
+            (CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY,),
+        ).fetchone() is not None
+        # Ordering (§4.2): the cache replay must finish first.
+        # `_recompute_codex_rollups` reads `codex_conversation_threads` from
+        # cache.db, and a missing thread row does not yield NULL — it stamps a
+        # materialized "(unassigned)" project that the read path then PREFERS,
+        # permanently, for any conversation with no later activity. The two
+        # stores are synced by independent paths (the dashboard runs conversation
+        # sync in its own worker), so nothing else orders them.
+        if _cache_side_replay_pending(conn):
+            stats.deferred_reason = "cache_replay_pending"
+            return stats
+        if (pending_rebuild or contract_rebuild or codex_replay_pending) and targeted:
             stats.deferred_reason = "rebuild_pending"
             return stats
-        rebuild = rebuild or pending_rebuild or contract_rebuild
+        rebuild = (
+            rebuild or pending_rebuild or contract_rebuild or codex_replay_pending)
         if rebuild:
             conn.execute(
                 "INSERT OR REPLACE INTO cache_meta(key,value) VALUES(?,?)",
@@ -8494,6 +8615,17 @@ def sync_codex_conversations(
                 "DELETE FROM cache_meta "
                 "WHERE key='conversation_rebuild_codex_pending'"
             )
+            # Clear ONLY the marker this call observed. The dispatcher that
+            # arms it holds `CONVERSATIONS_LOCK_MAINTENANCE_PATH` shared while
+            # this walk serializes on `CONVERSATIONS_LOCK_CODEX_PATH`, so a
+            # marker armed after the read above belongs to a replay this walk
+            # never performed — and deleting it would strand the repair for
+            # good, since the migration is stamped and never re-arms.
+            if codex_replay_pending:
+                conn.execute(
+                    "DELETE FROM cache_meta WHERE key=?",
+                    (CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY,),
+                )
             conn.commit()
         _report_conversation_progress(progress, "checkpoint", stats)
         _harden_conversation_sidecars()

package/bin/_cctally_dashboard_envelope.py

@@ -53,6 +53,7 @@ from _cctally_core import (
     _get_budget_config,
 )
 from _lib_dashboard_sources import (
+    SOURCE_SCHEMA_VERSION,
     dashboard_resource_key as _dashboard_resource_key,
 )
 from _lib_display_tz import _compute_display_block, format_display_dt
@@ -720,7 +721,7 @@ def _source_bundle_to_envelope(bundle: object | None) -> dict:
     unavailable = {source: _unavailable_source_wire() for source in ("claude", "codex", "all")}
     if bundle is None:
         return {
-            "source_schema_version": 1,
+            "source_schema_version": SOURCE_SCHEMA_VERSION,
             "default_source": "claude",
             "source_order": ["claude", "codex", "all"],
             "sources": unavailable,
@@ -741,7 +742,7 @@ def _source_bundle_to_envelope(bundle: object | None) -> dict:
         }
     except Exception:  # Never turn an unexpected snapshot shape into request-thread I/O.
         return {
-            "source_schema_version": 1,
+            "source_schema_version": SOURCE_SCHEMA_VERSION,
             "default_source": "claude",
             "source_order": ["claude", "codex", "all"],
             "sources": unavailable,

package/bin/_cctally_dashboard_sources.py

@@ -183,6 +183,64 @@ def _codex_history_row_is_model_scoped(row: object) -> bool:
     return bool(isinstance(row, Mapping) and row.get("model_scoped"))
 
 
+def _active_row_from_history(
+    history_row: Mapping[str, object], *, now_utc: dt.datetime,
+) -> dict[str, object] | None:
+    """Project a serialized quota history row onto its ``summary.active[]`` row.
+
+    #429 §4.1. The ONE home for the active-window predicate and the active-row
+    shape, so the initial build and ``refresh_codex_source_clock`` cannot
+    disagree about what ``captured_at`` means — the defect this fixes. Callers
+    must keep no separate copy of any part of the predicate, including the #373
+    model-pool exclusion: a live Spark/foreign-pool window must never reach an
+    account-level aggregate.
+
+    Both call sites see the same serialized shape. The clock's forecast refresh
+    rewrites ``status``, ``remaining_seconds`` and ``projected_percent`` but
+    never ``current_percent`` or ``resets_at``, so the fields read here are
+    identical at build time and at every tick.
+
+    #428: the liveness predicate and the emitted ``resets_at`` are the SAME
+    ``forecast.resets_at``, which is ``baseline.canonical_resets_at``
+    (``_lib_quota.forecast_quota``). The client compares ``active[].resets_at``
+    against ``hero.cycle.resets_at`` (``activeWeeklyKeys``) to decide which
+    weekly history is the live one, so both must carry that one anchor.
+    """
+    if _codex_history_row_is_model_scoped(history_row):
+        return None
+    forecast = history_row.get("forecast")
+    if not isinstance(forecast, Mapping):
+        return None
+    current = forecast.get("current_percent")
+    if not isinstance(current, (int, float)) or isinstance(current, bool):
+        return None
+    resets_at = forecast.get("resets_at")
+    try:
+        reset = dt.datetime.fromisoformat(
+            str(resets_at).replace("Z", "+00:00")
+        ).astimezone(UTC)
+    except (TypeError, ValueError):
+        return None
+    if reset <= now_utc:
+        return None
+    row: dict[str, object] = {
+        "key": history_row.get("key"),
+        "current_percent": current,
+        # #429 §3: evidence recency — the newest PHYSICAL observation, the same
+        # one that produced this row's `freshness` and `stale_after_seconds`.
+        # Not the interpreted baseline, which is a value axis and belongs to
+        # `current_percent` alone.
+        "captured_at": history_row.get("captured_at"),
+        "resets_at": resets_at,
+        "freshness": history_row.get("freshness"),
+        "stale_after_seconds": history_row.get("stale_after_seconds"),
+    }
+    account_key = history_row.get("account_key")
+    if account_key:
+        row["account_key"] = account_key
+    return row
+
+
 def _resolve_codex_weekly_cycle(
     observations: Iterable[object],
     now_utc: dt.datetime,
@@ -1693,6 +1751,7 @@ def _quota_read_model(
     *,
     accounting_entries: Iterable[object] = (),
     account_key: str | None = None,
+    decorated: bool,
 ) -> dict[str, object]:
     """Use S2's pure history/block/forecast kernels over cache evidence.
 
@@ -1714,9 +1773,11 @@ def _quota_read_model(
     cost_entries = tuple(accounting_entries)
     histories = build_history(quota_observations)
     blocks = build_blocks(quota_observations)
-    history_rows: list[dict[str, object]] = []
     milestone_rows: list[dict[str, object]] = []
-    active_rows: list[dict[str, object]] = []
+    # #429 §4.2: one candidate unit per identity — (ordinal, history row, active
+    # projection or None) — so the cap retains PAIRS instead of capping the two
+    # lists independently and in different orders.
+    candidates: list[tuple[int, dict[str, object], dict[str, object] | None]] = []
     # 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
     # dashboard client can scope per-account quota rows instead of merging them.
@@ -1726,13 +1787,12 @@ def _quota_read_model(
     # 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
-        _codex_decorated = _cctally_account.provider_is_decorated(
-            context.stats_conn, "codex")
-    except Exception:
-        _codex_decorated = False
+    #
+    # #429 §4.4: the caller owns this gate. Re-querying here, per parent AND per
+    # child, let a transient failure emit decorated scopes whose quota rows were
+    # silently unstamped — and the active-row helper cannot project a field the
+    # history row never carried.
+    _codex_decorated = decorated
     for history in histories:
         identity = history.identity
         key_parts = (
@@ -1777,21 +1837,11 @@ def _quota_read_model(
                 "confidence": forecast.confidence,
             },
         }
-        history_rows.append(row)
-        if _codex_history_row_is_model_scoped(row):
-            continue
-        # #428: the client compares `active[].resets_at` against
-        # `hero.cycle.resets_at` (`activeWeeklyKeys`) to decide which weekly
-        # history is the live one, so both must carry the SAME anchor.
-        if baseline is not None and baseline.canonical_resets_at > context.now_utc:
-            active_rows.append({
-                "key": dashboard_resource_key("quota", "codex", *key_parts),
-                "current_percent": baseline.used_percent,
-                "captured_at": baseline.captured_at.astimezone(UTC).isoformat(),
-                "resets_at": baseline.canonical_resets_at.astimezone(UTC).isoformat(),
-                "freshness": freshness.state,
-                "stale_after_seconds": freshness.stale_after_seconds,
-            })
+        candidates.append((
+            len(candidates),
+            row,
+            _active_row_from_history(row, now_utc=context.now_utc),
+        ))
     for block in blocks:
         identity = block.identity
         block_parts = (
@@ -1899,20 +1949,21 @@ def _quota_read_model(
                 "marginal_usd": max(0.0, cumulative_usd - previous_cumulative),
             })
             previous_cumulative = cumulative_usd
-    latest_percent = max(
-        (float(row["current_percent"]) for row in active_rows), default=None,
-    )
-    active_freshness = (
-        "fresh" if active_rows and all(row["freshness"] == "fresh" for row in active_rows)
-        else ("unavailable" if not active_rows else "stale")
-    )
     # 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}
+    #
+    # #429 §4.2 — retention decides ONCE per (history, active) unit, then each
+    # list is emitted in its own established order: histories in retention
+    # order, actives in identity order. Emitting both in a single order would
+    # reorder active rows below the cap and move bytes for every install.
+    active_keys = {
+        str(active["key"]) for _, _, active in candidates if active is not None
+    }
 
-    def _history_retention_key(row):
+    def _history_retention_key(unit):
+        _, row, _ = unit
         key = str(row["key"])
         if key in active_keys:
             return (0, 0.0, key)
@@ -1927,11 +1978,22 @@ def _quota_read_model(
             return (1, -captured_epoch, key)
         return (2, 0.0, key)
 
-    history_rows.sort(key=_history_retention_key)
-    history_rows = history_rows[:SOURCE_HISTORY_LIMIT]
+    retained = sorted(candidates, key=_history_retention_key)[:SOURCE_HISTORY_LIMIT]
+    history_rows = [row for _, row, _ in retained]
+    active_rows = [
+        active
+        for _, _, active in sorted(retained, key=lambda unit: unit[0])
+        if active is not None
+    ]
+    latest_percent = max(
+        (float(row["current_percent"]) for row in active_rows), default=None,
+    )
+    active_freshness = (
+        "fresh" if active_rows and all(row["freshness"] == "fresh" for row in active_rows)
+        else ("unavailable" if not active_rows else "stale")
+    )
     milestone_rows.sort(key=lambda row: str(row["captured_at"]), reverse=True)
     milestone_rows = milestone_rows[:SOURCE_HISTORY_LIMIT]
-    active_rows = active_rows[:SOURCE_HISTORY_LIMIT]
     return {
         "summary": {
             "window_count": len(blocks),
@@ -2035,6 +2097,117 @@ def _refresh_budget_status_clock(
     }
 
 
+def _scoped_quota_identity(row: Mapping[str, object]) -> tuple[str, str]:
+    """#429 §3.1. `dashboard_resource_key` carries no account, and two accounts
+    sharing one $CODEX_HOME root emit the same key, so bare key is not an
+    identity under decoration. `"unattributed"` is a legitimate account here."""
+    return (str(row.get("account_key") or ""), str(row.get("key")))
+
+
+def _reclock_quota_domain(
+    quota: Mapping[str, object], *, now_utc: dt.datetime,
+) -> dict[str, object]:
+    """Re-evaluate a quota domain's row freshness and summary against ``now``.
+
+    #429 §4.3. Replaces ONLY `histories` and `summary`; `blocks`, `milestones`
+    and `cycle_index` are carried through untouched, because the per-account
+    scopes carry them and a scope that lost them would render empty.
+
+    Emits TUPLES, matching what `_quota_read_model` publishes. Publication
+    freezes lists into tuples anyway, so this is byte-identical on the wire —
+    but it is what lets the caller detect an unchanged domain by comparing the
+    result against the frozen original. A list would never compare equal to the
+    tuple it was frozen from (``[] != ()``), the caller would report a change on
+    every tick, and the retain/degrade paths that assert the EXACT prior ``data``
+    object is handed back would break.
+    """
+    refreshed = dict(quota)
+    refreshed_histories: list[dict[str, object]] = []
+    active_rows: list[dict[str, object]] = []
+    for raw_history in quota.get("histories", ()):
+        if not isinstance(raw_history, Mapping):
+            continue
+        history = dict(raw_history)
+        # #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"] = row_freshness
+        forecast = history.get("forecast")
+        if isinstance(forecast, Mapping):
+            forecast = dict(forecast)
+            resets_at = forecast.get("resets_at")
+            try:
+                reset = dt.datetime.fromisoformat(
+                    str(resets_at).replace("Z", "+00:00")
+                ).astimezone(UTC)
+            except (TypeError, ValueError):
+                reset = None
+            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 row_freshness == "future":
+                forecast["status"] = "future"
+            elif row_freshness == "stale":
+                forecast["status"] = "stale"
+            elif sample_count == 0:
+                forecast["status"] = "insufficient-history"
+            else:
+                forecast["status"] = "ok"
+            rate = forecast.get("rate_percent_per_hour")
+            current = forecast.get("current_percent")
+            if (
+                isinstance(rate, (int, float)) and not isinstance(rate, bool)
+                and isinstance(current, (int, float)) and not isinstance(current, bool)
+                and remaining is not None
+            ):
+                forecast["projected_percent"] = min(
+                    100.0, max(float(current), float(current) + float(rate) * remaining / 3600),
+                )
+            history["forecast"] = forecast
+        # Called unconditionally, exactly as the build calls it. The helper
+        # already returns None for a row without a usable forecast, and keeping
+        # a caller-side `isinstance(forecast, Mapping)` guard here would put a
+        # fragment of the predicate back on the caller — the split #429 exists
+        # to remove.
+        active = _active_row_from_history(history, now_utc=now_utc)
+        if active is not None:
+            active_rows.append(active)
+        refreshed_histories.append(history)
+    summary = dict(quota.get("summary") or {})
+    prior_active = summary.get("active")
+    if isinstance(prior_active, (tuple, list)):
+        # #429 §3.1: scoped identity, not bare key — two decorated rows can
+        # share one key and would collapse into a single map entry.
+        active_order = {
+            _scoped_quota_identity(row): index
+            for index, row in enumerate(prior_active)
+            if isinstance(row, Mapping)
+        }
+        active_rows.sort(
+            key=lambda row: active_order.get(
+                _scoped_quota_identity(row), len(active_order)),
+        )
+    summary.update({
+        "active_window_count": len(active_rows),
+        "latest_percent": max(
+            (float(row["current_percent"]) for row in active_rows), default=None),
+        "freshness": (
+            "fresh" if active_rows and all(row["freshness"] == "fresh" for row in active_rows)
+            else ("unavailable" if not active_rows else "stale")
+        ),
+        "active": tuple(active_rows),
+    })
+    refreshed["histories"] = tuple(refreshed_histories)
+    refreshed["summary"] = summary
+    return refreshed
+
+
 def refresh_codex_source_clock(
     state: SourceDashboardState,
     *,
@@ -2059,148 +2232,48 @@ def refresh_codex_source_clock(
     freshness = state.freshness
     domain_freshness = dict(state.domain_freshness or {})
     if isinstance(quota, Mapping):
-        quota = dict(quota)
-        refreshed_histories: list[dict[str, object]] = []
-        active_rows: list[dict[str, object]] = []
-        for raw_history in quota.get("histories", ()):
-            if not isinstance(raw_history, Mapping):
-                continue
-            history = dict(raw_history)
-            # #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"] = row_freshness
-            forecast = history.get("forecast")
-            if isinstance(forecast, Mapping):
-                forecast = dict(forecast)
-                resets_at = forecast.get("resets_at")
-                try:
-                    reset = dt.datetime.fromisoformat(
-                        str(resets_at).replace("Z", "+00:00")
-                    ).astimezone(UTC)
-                except (TypeError, ValueError):
-                    reset = None
-                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 row_freshness == "future":
-                    forecast["status"] = "future"
-                elif row_freshness == "stale":
-                    forecast["status"] = "stale"
-                elif sample_count == 0:
-                    forecast["status"] = "insufficient-history"
-                else:
-                    forecast["status"] = "ok"
-                rate = forecast.get("rate_percent_per_hour")
-                current = forecast.get("current_percent")
-                if (
-                    isinstance(rate, (int, float)) and not isinstance(rate, bool)
-                    and isinstance(current, (int, float)) and not isinstance(current, bool)
-                    and remaining is not None
-                ):
-                    forecast["projected_percent"] = min(
-                        100.0, max(float(current), float(current) + float(rate) * remaining / 3600),
-                    )
-                history["forecast"] = forecast
-                # #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": row_freshness,
-                        "stale_after_seconds": history.get("stale_after_seconds"),
-                    })
-            refreshed_histories.append(history)
-        quota["histories"] = refreshed_histories
-        latest_percent = max(
-            (float(row["current_percent"]) for row in active_rows), default=None,
-        )
-        summary = dict(quota.get("summary") or {})
-        prior_active = summary.get("active")
-        if isinstance(prior_active, (tuple, list)):
-            active_order = {
-                str(row.get("key")): index
-                for index, row in enumerate(prior_active)
-                if isinstance(row, Mapping)
-            }
-            active_rows.sort(
-                key=lambda row: active_order.get(str(row.get("key")), len(active_order)),
-            )
-        summary.update({
-            "active_window_count": len(active_rows),
-            "latest_percent": latest_percent,
-            "freshness": (
-                "fresh" if active_rows and all(row["freshness"] == "fresh" for row in active_rows)
-                else ("unavailable" if not active_rows else "stale")
-            ),
-            "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.
+        reclocked = _reclock_quota_domain(quota, now_utc=now_utc)
+        quota_changed = reclocked != quota
+        quota = reclocked
+        data["quota"] = quota
+        # Only account-level active histories reach the summary; the shared
+        # model-scoped predicate 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. #429 §4.3 keeps this
+        # deriving from the TOP-LEVEL summary only — the #350 §3.9 rule that a
+        # row-level freshness value never touches `state.freshness` extends to
+        # the per-account scopes clocked below.
         domain_freshness["quota"] = (
-            "stale" if summary["freshness"] == "stale" else "fresh"
+            "stale" if quota["summary"]["freshness"] == "stale" else "fresh"
         )
-        quota["summary"] = summary
-        data["quota"] = quota
-        quota_changed = bool(refreshed_histories)
-        hero = data.get("hero")
-        hero_capability = state.capabilities.get("hero")
-        if (
-            isinstance(hero, Mapping)
-            and isinstance(hero.get("cycle"), Mapping)
-            and hero_capability is not None
-            and hero_capability.status == "supported"
-        ):
-            # #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",
-                    "reasoning_output_tokens", "total_tokens", "cycle",
-                ):
-                    hero[field] = None
-                data["hero"] = hero
-                refreshed_capabilities = dict(state.capabilities)
-                refreshed_capabilities["hero"] = CapabilityRecord(
-                    "unavailable", "missing-or-conflicting-native-cycle",
-                )
-                capabilities = refreshed_capabilities
-                warnings = tuple(
-                    warning for warning in state.warnings
-                    if warning.code != "codex_cycle_unavailable"
-                ) + (SourceDashboardWarning(
-                    "codex_cycle_unavailable",
-                    "Codex native reset cycle is unavailable.",
-                    "hero",
-                ),)
-                availability = "partial"
-                cycle_changed = True
+    # #429 §4.3: the per-account scopes are independent evidence domains and
+    # were never clocked at all, so a focused account read frozen freshness
+    # forever. The published state is recursively frozen (`MappingProxyType`),
+    # so nothing may be mutated in place — copy outward: the scopes mapping,
+    # then the scope, then only that scope's `quota`.
+    scopes = data.get("account_scopes")
+    scopes_changed = False
+    if isinstance(scopes, Mapping):
+        rebuilt_scopes = dict(scopes)
+        for scope_key, scope in scopes.items():
+            if not isinstance(scope, Mapping):
+                continue
+            scope_quota = scope.get("quota")
+            if not isinstance(scope_quota, Mapping):
+                continue
+            reclocked_scope_quota = _reclock_quota_domain(
+                scope_quota, now_utc=now_utc)
+            if reclocked_scope_quota == scope_quota:
+                continue
+            rebuilt_scope = dict(scope)
+            rebuilt_scope["quota"] = reclocked_scope_quota
+            rebuilt_scopes[scope_key] = rebuilt_scope
+            scopes_changed = True
+        if scopes_changed:
+            data["account_scopes"] = rebuilt_scopes
     budget_domain = data.get("budget")
     budget_changed = False
+    refreshed_budget = None
     if isinstance(budget_domain, Mapping):
         budget_domain = dict(budget_domain)
         refreshed_budget = _refresh_budget_status_clock(
@@ -2214,13 +2287,62 @@ def refresh_codex_source_clock(
         if refreshed_budget is not None:
             budget_domain["status"] = refreshed_budget
             data["budget"] = budget_domain
-            hero = data.get("hero")
-            if isinstance(hero, Mapping):
-                hero = dict(hero)
-                hero["budget"] = refreshed_budget
-                data["hero"] = hero
             budget_changed = True
-    if not (quota_changed or budget_changed or cycle_changed):
+    # #429 §4.5: all three hero mutations compose on ONE copy, in a stated
+    # order. Three independent `dict(hero)` copies let the last write win, which
+    # is how `hero["quota"]` stayed frozen at its build-time value while
+    # `quota["summary"]` advanced.
+    hero = data.get("hero")
+    if isinstance(hero, Mapping):
+        hero = dict(hero)
+        # 1. quota first — `_clock_cycle_expired` reads `hero["cycle"]`, never
+        #    `hero["quota"]`, so replacing quota cannot affect the predicate.
+        if isinstance(quota, Mapping):
+            hero["quota"] = quota["summary"]
+        # 2. cycle expiry, with its capability/warning consequences.
+        #    #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.
+        hero_capability = state.capabilities.get("hero")
+        if (
+            isinstance(hero.get("cycle"), Mapping)
+            and hero_capability is not None
+            and hero_capability.status == "supported"
+            and _clock_cycle_expired(hero.get("cycle"), now_utc)
+        ):
+            for field in (
+                "cost_usd", "input_tokens", "cached_input_tokens", "output_tokens",
+                "reasoning_output_tokens", "total_tokens", "cycle",
+            ):
+                hero[field] = None
+            refreshed_capabilities = dict(state.capabilities)
+            refreshed_capabilities["hero"] = CapabilityRecord(
+                "unavailable", "missing-or-conflicting-native-cycle",
+            )
+            capabilities = refreshed_capabilities
+            warnings = tuple(
+                warning for warning in state.warnings
+                if warning.code != "codex_cycle_unavailable"
+            ) + (SourceDashboardWarning(
+                "codex_cycle_unavailable",
+                "Codex native reset cycle is unavailable.",
+                "hero",
+            ),)
+            availability = "partial"
+            cycle_changed = True
+        # 3. budget last
+        if refreshed_budget is not None:
+            hero["budget"] = refreshed_budget
+        data["hero"] = hero
+    if not (quota_changed or budget_changed or cycle_changed or scopes_changed):
         return state
     refreshed_state = SourceDashboardState(
         source=state.source,
@@ -2832,6 +2954,9 @@ def _codex_account_scopes_wire(
         quota = _quota_read_model(
             context, account_observations, accounting_entries=rows,
             account_key=key,
+            # #429 §4.4: this wire is only ever reached under decoration — the
+            # caller gates the whole `account_scopes` surface on it.
+            decorated=True,
         )
         # Each decorated child owns the only honest cycle index for that
         # account. Reusing a merged parent index here would render account A's
@@ -3228,6 +3353,7 @@ def build_codex_source_state(
         context,
         quota_observations,
         accounting_entries=visible_accounting_entries,
+        decorated=_codex_decorated,
     )
     # R8 gate, resolved ONCE and threaded (#341 Task 4 / #416 §5.8). Every
     # per-account decoration below — block/alert/budget `account_key`, the

package/bin/_cctally_db.py

@@ -3925,6 +3925,54 @@ def _conv_001_adopt_schema_version_marker(conn: sqlite3.Connection) -> None:
     conn.commit()
 
 
+@conversations_migration("002_codex_thread_source_inference_replay")
+def _conv_002_codex_thread_source_inference_replay(
+    conn: sqlite3.Connection,
+) -> None:
+    """Arm the conversations half of the byte-zero Codex replay.
+
+    Spec:
+    ``docs/superpowers/specs/2026-07-30-codex-thread-source-inference-design.md``
+    §4.3.
+
+    Writes a marker ONLY; it clears no table. ``sync_codex_conversations``
+    consumes it, and DEFERS while the cache-side marker is still pending —
+    ``_recompute_codex_rollups`` resolves project attribution from the cache-side
+    thread row, and a missing one stamps a materialized ``"(unassigned)"`` the
+    read path then prefers permanently.
+
+    The key is DISTINCT from ``conversation_rebuild_codex_pending`` on purpose.
+    ``_ensure_codex_conversation_contract`` consumes that one by replaying
+    normalization over already-retained events — which preserves their NULL
+    conversation keys — and then deletes it, so a ``dashboard --no-sync`` or
+    qualified CLI read between this migration and the next real sync would
+    silently discard the repair.
+
+    Takes the Codex conversations provider flock first, the way cache migration
+    ``028_split_conversation_store`` does, and DEFERS on contention. The
+    conversations dispatcher runs inside ``_conversations_open_guarded``, which
+    holds ``CONVERSATIONS_LOCK_MAINTENANCE_PATH`` only SHARED, while
+    ``sync_codex_conversations`` serializes on ``CONVERSATIONS_LOCK_CODEX_PATH``
+    — so without this lock the marker can be armed in the middle of a walk that
+    already read it as absent, and that walk's finalize would clear a replay it
+    never performed. Deferring leaves the migration pending, so it arms cleanly
+    at the next open.
+
+    Idempotent: re-running rewrites the same marker. NO self-stamp — the
+    dispatcher central-stamps on a clean return (#140).
+    """
+    import _cctally_cache
+
+    held = _acquire_conversations_db_codex_provider_flock(
+        conn, migration="conversations 002 thread_source replay")
+    try:
+        _set_cache_meta(
+            conn, _cctally_cache.CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY, "1")
+        conn.commit()
+    finally:
+        _release_cache_db_writer_flocks(held)
+
+
 # #177 S6: the consolidated multi-column external-content FTS5 table that
 # replaces the old conversation_fts(text) + conversation_fts_aux(search_aux)
 # pair. The three column names MUST match the conversation_messages columns BY
@@ -4683,6 +4731,44 @@ def _acquire_cache_db_codex_provider_flock(
     return held
 
 
+def _acquire_conversations_db_codex_provider_flock(
+    conn: sqlite3.Connection,
+    *,
+    migration: str,
+) -> list[int]:
+    """Take the ``<conversations.db>.codex.lock`` sibling, or DEFER.
+
+    The conversations dispatcher runs under a SHARED maintenance flock, so —
+    unlike the cache dispatcher — it does not exclude the provider sync that
+    owns the marker lifecycle. A conversations handler that writes a marker
+    ``sync_codex_conversations`` consumes must therefore hold the same
+    provider lock that sync holds, or it can arm mid-walk and have its marker
+    swallowed by a walk that already read it as absent.
+
+    Derived from the connection (the lock-path helper is store-agnostic: main DB
+    file + ``.codex.lock``), so a migration test never contends on the caller's
+    real conversations lock.
+    """
+    provider_path = _cache_db_codex_lock_path_for_conn(conn)
+    if provider_path is None:
+        return []
+
+    from _lib_cache_writer_lock import acquire_ordered_flocks
+
+    try:
+        held = acquire_ordered_flocks([(provider_path, fcntl.LOCK_EX)])
+    except OSError as exc:
+        raise MigrationGateNotMet(
+            f"conversations.db Codex lock unavailable; deferring {migration}"
+        ) from exc
+    if held is None:
+        raise MigrationGateNotMet(
+            f"conversations.db Codex lock held by a concurrent Codex "
+            f"conversation sync; deferring {migration}"
+        )
+    return held
+
+
 def _release_cache_db_writer_flocks(held: list[int]) -> None:
     from _lib_cache_writer_lock import release_cache_writer_flocks
 
@@ -6135,6 +6221,42 @@ def _034_codex_window_spend_adoption(conn: sqlite3.Connection) -> None:
         _release_cache_db_writer_flocks(held)
 
 
+@cache_migration("035_codex_thread_source_inference_replay")
+def _035_codex_thread_source_inference_replay(conn: sqlite3.Connection) -> None:
+    """Arm a byte-zero Codex replay so rollouts whose ``session_meta`` omits
+    ``thread_source`` gain a conversation identity.
+
+    Spec:
+    ``docs/superpowers/specs/2026-07-30-codex-thread-source-inference-design.md``
+    §4.3.
+
+    The repair must re-read the rollout bytes: the retained events carry NULL
+    conversation keys and the in-place normalization replay preserves them.
+
+    Writes a marker ONLY. ``sync_codex_cache`` consumes it and ORs it into its
+    own ``rebuild``, which is what makes the rebuild path capture
+    ``rebuild_known_identities`` BEFORE the clear. Clearing here instead would
+    delete ``codex_session_files`` out of band, leaving the next ordinary sync
+    with an empty snapshot — every re-read rollout would fall through to the
+    live-``auth.json`` branch and pre-mechanism Codex spend would be
+    re-attributed to whoever is authenticated now (#416 spec D1). Migrations 026
+    and 027 predate that snapshot and are already stamped, so this would be the
+    first migration to hit it live.
+
+    No provider flock: unlike handlers 024-027 and 034 this writes one
+    ``cache_meta`` row and touches no Codex-derived table, so a concurrent
+    ``sync_codex_cache`` has nothing to interleave with — and if one is mid-walk,
+    arming the marker simply defers the replay to the following sync.
+
+    Idempotent: re-running rewrites the same marker. NO self-stamp — the
+    dispatcher central-stamps on a clean return (#140).
+    """
+    import _cctally_cache
+
+    _set_cache_meta(conn, _cctally_cache.CODEX_REPLAY_FROM_ZERO_KEY, "1")
+    conn.commit()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")

package/bin/_cctally_doctor.py

@@ -1125,12 +1125,25 @@ def _doctor_gather_state_impl(
     # #416 review B4: the durable record that a torn Codex `auth.json` halted
     # ingest. Same cache_meta read, same degrade-to-None-on-anything contract.
     codex_torn_deferred = None
+    # The byte-zero Codex replay stall signal. The marker itself is a bare "1";
+    # the sibling `blocked` record is the JSON one, so it is read through the
+    # same loop while the marker gets a plain existence probe. Key names come
+    # from the kernel constants, never inline literals.
+    codex_replay_pending = None
+    codex_replay_blocked = None
+    try:
+        import _lib_codex_conversation as _codex_kern
+        _blocked_key = _codex_kern.CODEX_REPLAY_BLOCKED_KEY
+        _pending_key = _codex_kern.CODEX_REPLAY_FROM_ZERO_KEY
+    except Exception:
+        _blocked_key = "codex_replay_from_zero_blocked"
+        _pending_key = "codex_replay_from_zero_pending"
     try:
         if _cache_probe_allowed and _cctally_core.CACHE_DB_PATH.exists():
             conn = sqlite3.connect(str(_cctally_core.CACHE_DB_PATH))
             try:
                 for _key in ("parse_health_claude", "parse_health_codex",
-                             "codex_torn_auth_deferred"):
+                             "codex_torn_auth_deferred", _blocked_key):
                     try:
                         row = conn.execute(
                             "SELECT value FROM cache_meta WHERE key = ?",
@@ -1143,10 +1156,19 @@ def _doctor_gather_state_impl(
                                     parse_health_claude = _parsed
                                 elif _key == "parse_health_codex":
                                     parse_health_codex = _parsed
+                                elif _key == _blocked_key:
+                                    codex_replay_blocked = _parsed
                                 else:
                                     codex_torn_deferred = _parsed
                     except (sqlite3.OperationalError, ValueError):
                         pass
+                try:
+                    codex_replay_pending = conn.execute(
+                        "SELECT 1 FROM cache_meta WHERE key = ?",
+                        (_pending_key,),
+                    ).fetchone() is not None
+                except sqlite3.OperationalError:
+                    pass
             finally:
                 conn.close()
     except Exception:
@@ -1722,6 +1744,8 @@ def _doctor_gather_state_impl(
         parse_health_claude=parse_health_claude,
         parse_health_codex=parse_health_codex,
         codex_torn_deferred=codex_torn_deferred,
+        codex_replay_pending=codex_replay_pending,
+        codex_replay_blocked=codex_replay_blocked,
         stats_db_quick_check=stats_db_quick_check,
         cache_db_quick_check=cache_db_quick_check,
         conversations_db_quick_check=conversations_db_quick_check,

package/bin/_cctally_transcript.py

@@ -49,9 +49,13 @@ def cmd_transcript(args) -> int:
 # ---- export ----------------------------------------------------------------
 
 _SPEED_ONLY_CODEX_MSG = "transcript: --speed applies only to Codex conversations"
+# Deliberately generic about WHAT is pending. Three distinct conditions reach
+# this branch — a cache predating migration 025, a store with the contract
+# rebuild marker armed, and a store with a byte-zero Codex replay marker armed —
+# and naming the migration told users to wait for work applied long ago.
 _PENDING_EXPORT_MSG = (
     "transcript: Codex conversation is not yet normalized "
-    "(migration 025 runs on the next cache open) — retry shortly")
+    "(the pending work runs on the next cache open) — retry shortly")
 
 
 def _emit_export(md: str, output) -> None:
@@ -213,9 +217,10 @@ def _cmd_transcript_search_claude(args) -> int:
 
 # ---- search (Codex) --------------------------------------------------------
 
+# Same generic wording as `_PENDING_EXPORT_MSG`, for the same reason.
 _CODEX_SEARCH_PENDING_MSG = (
     "transcript: Codex conversations are not yet normalized "
-    "(migration 025 runs on the next cache open); no results yet")
+    "(the pending work runs on the next cache open); no results yet")
 
 
 def _cmd_transcript_search_codex(args) -> int:

package/bin/_cctally_tui.py

@@ -271,6 +271,7 @@ from _cctally_dashboard_sources import (
     resolve_dashboard_source_semantics,
 )
 from _lib_dashboard_sources import (
+    SOURCE_SCHEMA_VERSION,
     CapabilityRecord,
     SourceDashboardBundle,
     SourceDashboardState,
@@ -2803,7 +2804,7 @@ def _tui_build_source_bundle(
         codex = refresh_codex_source_clock(codex, now_utc=now_utc)
         combined = compose_all_state(claude, codex)
         bundle = SourceDashboardBundle(
-            source_schema_version=1,
+            source_schema_version=SOURCE_SCHEMA_VERSION,
             default_source="claude",
             source_order=("claude", "codex", "all"),
             sources={"claude": claude, "codex": codex, "all": combined},
@@ -2877,7 +2878,7 @@ def _tui_hydrating_source_bundle() -> SourceDashboardBundle:
         domain_freshness={"hero": "stale", "quota": "stale", "sessions": "stale"},
     )
     return SourceDashboardBundle(
-        source_schema_version=1,
+        source_schema_version=SOURCE_SCHEMA_VERSION,
         default_source="claude",
         source_order=("claude", "codex", "all"),
         sources={"claude": claude, "codex": codex, "all": compose_all_state(claude, codex)},

package/bin/_lib_codex_conversation.py

@@ -74,6 +74,23 @@ CODEX_TITLE_MAX = _TITLE_MAX
 # migration (the store is wholly re-derivable).
 CODEX_CONVERSATION_CONTRACT_VERSION = "5"
 
+# Byte-zero Codex replay markers (spec
+# docs/superpowers/specs/2026-07-30-codex-thread-source-inference-design.md
+# §4.3). One `cache_meta` key per store, armed by cache migration 035 /
+# conversations migration 002 and consumed inside the sync function that owns
+# the correct replay semantics. They live in this kernel because three layers
+# read them — the cache glue that consumes them, the read-side authority probe,
+# and the doctor I/O shell — and a SQL string literal in any one of them would
+# silently outlive a rename of the others.
+CODEX_REPLAY_FROM_ZERO_KEY = "codex_replay_from_zero_pending"
+CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY = (
+    "codex_conversation_replay_from_zero_pending"
+)
+# Written when a whole-tree Codex sync completed and still could NOT consume
+# `CODEX_REPLAY_FROM_ZERO_KEY` — the replay is stalled, not merely pending, and
+# Codex transcript ingest is deferred behind it. Read by `doctor`.
+CODEX_REPLAY_BLOCKED_KEY = "codex_replay_from_zero_blocked"
+
 # Structural wrapper prefixes skipped during title selection (§4.3), pinned from
 # the corpus (title-wrapper-window). Prefix-structural, never content heuristics.
 CODEX_TITLE_SKIP_PREFIXES: tuple[str, ...] = (

package/bin/_lib_codex_conversation_query.py

@@ -35,6 +35,13 @@ from _lib_pricing import _calculate_codex_entry_cost
 # authoritative; a held-lock deferral leaves it pending.
 CODEX_NORMALIZATION_MIGRATION = "025_codex_conversation_normalization"
 
+# The provider-local rebuild marker migration 028's byte-zero replay arms. Its
+# sibling — the thread_source-inference replay marker — is
+# ``kern.CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY``; both are named, never
+# inlined as SQL literals, so a rename cannot leave this probe testing a key
+# nothing writes any more.
+CODEX_CONTRACT_REBUILD_MARKER = "conversation_rebuild_codex_pending"
+
 # Domain separations for the opaque item-key encoding (§5.2). The source-path
 # fingerprint is a domain-separated hash, NEVER a raw path (privacy-safe).
 CODEX_ITEM_KEY_DOMAIN = b"cctally-codex-item-key-v1\0"
@@ -93,6 +100,12 @@ def codex_normalization_authoritative(conn: sqlite3.Connection) -> bool:
     Split stores use their provider-local rebuild marker: current schema alone
     is not authority while migration 028's byte-zero replay is pending. Legacy
     monolithic/bare connections retain the migration-025 stamp contract.
+
+    EITHER pending marker withholds authority. The thread_source-inference
+    replay (conversations migration 002) is armed by its own key precisely
+    because the contract replay must not consume it, so a probe that tested only
+    the contract marker would report a not-yet-repaired store as authoritative
+    to every ``--no-sync`` read.
     """
     try:
         split = conn.execute(
@@ -101,8 +114,9 @@ def codex_normalization_authoritative(conn: sqlite3.Connection) -> bool:
         ).fetchone() is not None
         if split:
             pending = conn.execute(
-                "SELECT 1 FROM cache_meta "
-                "WHERE key='conversation_rebuild_codex_pending'"
+                "SELECT 1 FROM cache_meta WHERE key IN (?,?) LIMIT 1",
+                (CODEX_CONTRACT_REBUILD_MARKER,
+                 kern.CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY),
             ).fetchone() is not None
             version = conn.execute(
                 "SELECT value FROM cache_meta "

package/bin/_lib_dashboard_sources.py

@@ -22,7 +22,14 @@ CapabilityStatus = Literal[
     "supported", "derived", "unavailable", "deferred", "not_applicable",
 ]
 
-SOURCE_SCHEMA_VERSION = 1
+# #429 §3.2 — bumped to 2 because `active[].captured_at` changed MEANING (the
+# newest physical observation, not the interpreted baseline). The in-place
+# update flow `execvp`s the server while the already-loaded client reconnects
+# over its existing EventSource without reloading its JS
+# (`UpdateRunningModal.tsx`, `store/sse.ts`), so an old client demonstrably
+# does meet a new server; `docs/cli-contract.md` calls changing a value's
+# meaning breaking. Version-aware client reaction is deliberately deferred.
+SOURCE_SCHEMA_VERSION = 2
 DEFAULT_SOURCE = "claude"
 SOURCE_ORDER = ("claude", "codex", "all")
 SOURCE_FRESHNESS_DOMAINS = ("hero", "quota", "sessions")

package/bin/_lib_doctor.py

@@ -189,6 +189,14 @@ class DoctorState:
     # by the next whole-tree sync that defers none. None = key absent (the
     # normal state) or cache unreadable — the check degrades OK.
     codex_torn_deferred: Optional[dict] = None
+    # The byte-zero Codex replay's stall signal. `codex_replay_pending` mirrors
+    # the `codex_replay_from_zero_pending` cache_meta marker; `codex_replay_blocked`
+    # is `{"at": iso, "files_failed": N, "files_deferred_torn": N}`, written by a
+    # whole-tree Codex sync that RAN and still could not consume it, and deleted
+    # by the next clean whole-tree sync. Both None = key absent (the normal
+    # state) or cache unreadable — the check degrades OK.
+    codex_replay_pending: Optional[bool] = None
+    codex_replay_blocked: Optional[dict] = None
     # #279 S2 (F5b): PRAGMA quick_check(1) results, gathered ONLY under
     # doctor_gather_state(deep=True) (CLI cmd_doctor) — the dashboard
     # rebuild loop calls the gather every rebuild and quick_check on a
@@ -1107,6 +1115,50 @@ def _check_data_codex_cache(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_data_codex_replay(s: DoctorState) -> CheckResult:
+    """WARN while a byte-zero Codex replay is STALLED rather than merely pending.
+
+    `sync_codex_conversations` defers on the cache-side replay marker, so as long
+    as that marker stands no Codex transcript is ingested at all. The deferral is
+    protective — running ahead of the replayed thread rows stamps a materialized
+    `"(unassigned)"` project the read path then prefers permanently — so the fix
+    is never to drop it. But a whole-tree sync that runs and still cannot consume
+    the marker (a persistently torn `auth.json`, a repeated per-file DB error)
+    holds that deferral open indefinitely, and `cache-sync` still exits 0. This
+    leg is the only standing signal that Codex transcript ingest has stopped.
+
+    A marker that is merely pending is NOT reported: it is the ordinary state
+    between the migration and the next sync, and it clears on its own. The WARN
+    needs the durable `blocked` record, which only a completed-but-unsuccessful
+    whole-tree walk writes.
+    """
+    blocked = s.codex_replay_blocked or {}
+    at = blocked.get("at")
+    details = {
+        "pending": bool(s.codex_replay_pending),
+        "blocked_at": at,
+        "files_failed": blocked.get("files_failed"),
+        "files_deferred_torn": blocked.get("files_deferred_torn"),
+    }
+    if s.codex_replay_pending and isinstance(at, str) and at:
+        return CheckResult(
+            id="data.codex_replay", title="Codex transcript replay",
+            severity="warn",
+            summary=(f"stalled since {at} — Codex transcript ingest is "
+                     "deferred until it completes"),
+            remediation=("Check the Codex auth.json (re-run `codex login` if it "
+                         "is truncated), then `cctally cache-sync --source codex`"),
+            details=details,
+        )
+    return CheckResult(
+        id="data.codex_replay", title="Codex transcript replay",
+        severity="ok",
+        summary="pending (clears on the next Codex sync)"
+                if s.codex_replay_pending else "none pending",
+        remediation=None, details=details,
+    )
+
+
 def _check_data_codex_project_metadata(s: DoctorState) -> CheckResult:
     """Report the identity-safe all-history Codex metadata partition."""
     if s.codex_project_metadata_error is not None:
@@ -2680,7 +2732,12 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("data.statusline_pipeline", "_check_statusline_pipeline"),
         ("data.cache_sync_state", "_check_data_cache_sync_state"),
         ("data.codex_cache", "_check_data_codex_cache"),
+        # `data.codex_project_metadata` must stay IMMEDIATELY after
+        # `data.codex_cache` (pinned by
+        # tests/test_doctor_codex_project_metadata.py), so the replay leg goes
+        # after the pair rather than between them.
         ("data.codex_project_metadata", "_check_data_codex_project_metadata"),
+        ("data.codex_replay", "_check_data_codex_replay"),
         ("data.codex_quota", "_check_data_codex_quota"),
         ("data.parse_health", "_check_data_parse_health"),
         ("data.forked_buckets", "_check_data_forked_buckets"),

package/bin/_lib_jsonl.py

@@ -549,15 +549,48 @@ def _canonical_container(value: object) -> str | None:
     return _codex_canonical_json(value)
 
 
+# Codex is mid-rollout on `thread_source`: Desktop 0.146.0-alpha.3.1 emits it,
+# the CLI 0.146.0 behind the MCP server does not. Abandoning the identity when
+# it is absent costs the rollout its thread row AND every normalized message,
+# so infer the category the provider would most likely emit instead. Inferring
+# rather than minting a null parent keeps one identity across the release that
+# starts emitting the field.
+_CODEX_DEFAULT_THREAD_SOURCE = "user"
+
+
+def _inferred_codex_thread_source(payload: dict[str, Any]) -> str:
+    """The thread-origin category for one ``session_meta`` payload.
+
+    Per-record and stateless: a later ``session_meta`` never inherits an earlier
+    one's category, so a file's key sequence is a function of its own bytes.
+    The string form of ``source`` is deliberately never used — ``source:
+    "vscode"`` co-occurs with ``thread_source: "user"``, so the client name and
+    the origin category are orthogonal vocabularies.
+    """
+    explicit = _codex_string(payload.get("thread_source"))
+    if explicit is not None:
+        return explicit
+    source = payload.get("source")
+    if isinstance(source, dict) and len(source) == 1:
+        # A single-key object is the shape Codex uses for `{"subagent": {...}}`.
+        # Guard every malformed variant: the identity encoder REJECTS an empty
+        # parent key, so an unguarded rule turns bad metadata into an ingest
+        # exception rather than a degraded-but-working ingest.
+        only_key = _codex_string(next(iter(source)))
+        if only_key is not None:
+            return only_key
+    return _CODEX_DEFAULT_THREAD_SOURCE
+
+
 def _thread_metadata_from_session_meta(
     payload: dict[str, Any], path_str: str, source_root_key: str | None,
 ) -> CodexThreadMetadata:
     accounting_id = _codex_string(payload.get("id"))
     native_thread_id = _codex_string(payload.get("session_id")) or accounting_id
-    root_thread_id = _codex_string(payload.get("thread_source"))
+    root_thread_id = _inferred_codex_thread_source(payload)
     parent_thread_id = _codex_string(payload.get("forked_from_id"))
     conversation_key = None
-    if native_thread_id is not None and root_thread_id is not None:
+    if native_thread_id is not None:
         conversation_key = canonical_identity_from_root_key(
             "codex", "conversation", source_root_key, native_thread_id, root_thread_id
         )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.87.2",
+  "version": "1.88.0",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {