cctally 1.85.1 → 1.87.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.87.0] - 2026-07-30
+
+### Fixed
+- A Codex cycle's per-percent milestone ladder no longer reports `$0.00` for a crossing whose spend is real. cctally already recognised which account a quota window belongs to even when individual samples arrived unlabelled, but the dollars behind those percentages were attributed separately, per rollout file — and for usage recorded before cctally began keeping durable per-file attribution there was no decision to apply, so that spend belonged to nobody. The crossing was confidently the account's while its cost read as zero, the cycle hero under-reported spend by the same amount, and roughly a seventh of one Pro account's weekly Codex spend sat in the `unattributed` bucket instead of on its own card. Codex spend recorded inside an account-level weekly window is now attributed to that window's account whenever the window names exactly one, so the ladder, the cycle hero, the per-account cards, the Codex budget and the CLI all agree. Nothing is guessed: spend that no window can name is left alone, so is spend claimed by two windows naming different accounts, and separate model pools such as GPT-5.3-Codex-Spark are never treated as account quota. Existing history is repaired once on upgrade, and no usage is ever counted twice.
+
+## [1.86.0] - 2026-07-30
+
+### Fixed
+- Each Claude, Codex, or future-provider logical model release now receives a distinct, accessible dashboard color that stays consistent across cards and modals, while dated and capacity-qualified variants of the same release share one color.
+- Codex quota windows whose reported reset drifts through a chain of nearby values now converge into one physical window. The original upgrade grouped each sample only against already-settled anchors, so real history could leave one connected window split across multiple percentages, forecasts, milestone ladders and alert identities even though every adjacent reset remained within the intended ten-minute tolerance. A follow-up cache migration repairs already-upgraded history without changing the raw provider evidence, live ingest applies the same transitive rule, and terminal alert evidence follows exact retained members even when an endpoint is more than ten minutes from the winning first observation. Release cuts now also refuse every newly registered migration until a dated real-production-copy verification is tracked; `--ack-migrations` cannot bypass that gate. (#425)
+- Pooled Codex weekly rows now name every account whose near-identical reset boundary contributed to the row. The Weekly and Trend panels and their expanded tables no longer show one account's maximum percentage without disclosing the other account blended into it; focused and single-account views remain unchanged. Three dashboard tests also now reject malformed trailing text instead of checking only a correct-looking prefix. (#424)
+- The dashboard now keeps account focus consistent across every account-sensitive surface. Claude's merged and All-provider headlines no longer borrow one account's quota, while a focused Claude account uses only the percentage, reset and spend fields its own card actually provides. Focused keyboard shortcuts open scoped sessions and blocks, merged Codex block rows always expose their account in visible and accessible text, and shared-root quota forecasts no longer join through the account-blind parent. Account selection announcements now name the selected state correctly, long account labels remain identifiable on 320px screens, and small non-zero dollar values retain their cents instead of rounding to `$0`. (#423)
+- A weekly percent milestone is no longer recorded carrying the cost of an earlier crossing. Recording a crossing first refreshes the week's cost, but when a concurrent cache ingest made that account-scoped refresh fail closed, cctally kept going and stamped the last stored cost onto the new percentage — so the Current Week per-percent ladder showed two consecutive percentages at an identical cumulative dollar figure, a `$0.00` marginal and a `$/1%` that never happened. Because milestone rows are written once, that was permanent. The crossing is now skipped instead and recorded by the next observation with its real cost, so nothing is lost; the same fail-closed condition on a reset-affected week also no longer aborts the whole ingest cycle over a transient lock.
+- Codex quota percentages now appear only for windows the server still marks live. The Current Cycle modal no longer turns a retained, already-reset history row into a current percentage or `$ / 1%`; the All-accounts cycle table derives each live percentage and reset from that account's own quota window, including a live unattributed bucket whose totals-only card intentionally blanks those fields. Decorated parent envelopes also stop exposing one representative account's cycle-history index, and Forecast panels now preserve the same one-decimal percentage shown by their expanded views. (#422)
+- Codex cache sync now stops before reading rollout files when its durable account-attribution decisions cannot be replayed, preventing a transient journal/cache failure from reassigning usage to the account currently signed in. Doctor also reports retained quota rows that lack their canonical reset anchor and points to the safe Codex cache rebuild. (#421)
+
 ## [1.85.1] - 2026-07-29
 
 ### Fixed

package/bin/_cctally_cache.py

@@ -192,6 +192,11 @@ _iter_message_rows = _lib_conversation.iter_message_rows
 # so it loads at module-load time alongside _lib_conversation.
 _lib_codex_conversation = _load_lib("_lib_codex_conversation")
 
+# Window-scoped spend adoption's decision kernel (2026-07-30 spec). Pure
+# stdlib leaf, same shape as `_lib_codex_pools`, so it loads here rather than
+# through a bare import that would depend on ``bin/`` being on ``sys.path``.
+_lib_codex_account_adoption = _load_lib("_lib_codex_account_adoption")
+
 # Opt-in backend phase-instrumentation collector (issue #276, Session A). Pure
 # stdlib leaf; near-noop when CCTALLY_PERF_TRACE is unset (phase() returns a
 # shared no-op singleton), so the sync_cache seam wraps below cost nothing on
@@ -1054,7 +1059,11 @@ class CodexResetAnchorResolver:
 
     def __init__(self, conn: sqlite3.Connection):
         self._conn = conn
-        self._groups: "dict[tuple[str, str, str, object], _lib_quota.ResetAnchorIndex]" = {}
+        self._groups: "dict[tuple[str, str, str, object], _lib_quota.ResetAnchorComponents]" = {}
+        self._pending_merges: list[
+            tuple[tuple[str, str, str, object], str, dt.datetime,
+                  tuple[dt.datetime, ...]]
+        ] = []
         self._seed_failed = False
 
     @staticmethod
@@ -1068,34 +1077,31 @@ class CodexResetAnchorResolver:
             _lib_jsonl.snap_codex_window_minutes(window_minutes),
         )
 
-    def _anchors_for(
+    def _components_for(
         self, group, logical_limit_key: str,
-    ) -> "_lib_quota.ResetAnchorIndex":
-        """The group's established anchors, as an O(1)-lookup index.
-
-        A bucketed index rather than a list because this seed is UNBOUNDED — it
-        is every distinct anchor the group ever carried — and the resolver is
-        driven over the whole table by cache migration 032 and over the whole
-        walk by `cache-sync --rebuild`. A linear scan per observation makes both
-        quadratic in the group's anchor count (~1,750 a year for a 5h window).
+    ) -> "_lib_quota.ResetAnchorComponents":
+        """The group's raw-reset components, ordered by deterministic ingest.
+
+        Raw values, not only stored anchors, are required to recover transitive
+        chain membership. Ordering by rollout byte identity preserves the
+        original first-sight winner while making a rebuild reproducible.
         """
-        anchors = self._groups.get(group)
-        if anchors is not None:
-            return anchors
-        anchors = _lib_quota.ResetAnchorIndex()
+        components = self._groups.get(group)
+        if components is not None:
+            return components
+        components = _lib_quota.ResetAnchorComponents()
         if not self._seed_failed:
             candidates = _lib_jsonl.codex_snap_equivalent_limit_keys(
                 str(logical_limit_key))
             placeholders = ",".join("?" for _ in candidates)
             try:
                 rows = self._conn.execute(
-                    "SELECT DISTINCT canonical_resets_at_utc "
+                    "SELECT source_path, line_offset, id, resets_at_utc "
                     "FROM quota_window_snapshots "
                     "WHERE source = 'codex' AND source_root_key = ? "
                     "  AND observed_slot = ? "
                     f"  AND logical_limit_key IN ({placeholders}) "
-                    "  AND canonical_resets_at_utc IS NOT NULL "
-                    "ORDER BY canonical_resets_at_utc",
+                    "ORDER BY source_path, line_offset, id",
                     (group[0], group[1], *candidates),
                 ).fetchall()
             except sqlite3.DatabaseError:
@@ -1105,15 +1111,66 @@ class CodexResetAnchorResolver:
                 self._seed_failed = True
                 rows = []
             for row in rows:
-                parsed = _parse_anchor_iso(row[0])
+                parsed = _parse_anchor_iso(row[3])
                 if parsed is not None:
-                    anchors.add(parsed)
-        self._groups[group] = anchors
-        return anchors
+                    components.add(
+                        parsed,
+                        order_key=(
+                            str(row[0]), int(row[1]), int(row[2])),
+                    )
+        self._groups[group] = components
+        return components
+
+    def _merge_stored_anchors(
+        self, group, logical_limit_key: str, winner: dt.datetime,
+        retired: tuple[dt.datetime, ...],
+    ) -> None:
+        if not retired:
+            return
+        self._pending_merges.append(
+            (group, str(logical_limit_key), winner, retired))
+
+    def apply_pending_merges(self) -> None:
+        """Apply queued component merges inside the caller's transaction.
+
+        Resolution happens while the direct walk is still buffering a file.
+        Deferring DML until `_write_codex_file_batch` keeps retired-anchor
+        updates atomic with that file's rows and cursor; its one rollback/retry
+        can safely reapply the unchanged queue.
+        """
+        for group, logical_limit_key, winner, retired in self._pending_merges:
+            candidates = _lib_jsonl.codex_snap_equivalent_limit_keys(
+                logical_limit_key)
+            key_placeholders = ",".join("?" for _ in candidates)
+            retired_text = tuple(
+                _codex_anchor_iso(value) for value in retired)
+            retired_placeholders = ",".join("?" for _ in retired_text)
+            self._conn.execute(
+                "UPDATE quota_window_snapshots "
+                "SET canonical_resets_at_utc = ? "
+                "WHERE source = 'codex' AND source_root_key = ? "
+                "  AND observed_slot = ? "
+                f"  AND logical_limit_key IN ({key_placeholders}) "
+                f"  AND canonical_resets_at_utc IN ({retired_placeholders})",
+                (
+                    _codex_anchor_iso(winner), group[0], group[1],
+                    *candidates, *retired_text,
+                ),
+            )
+
+    def mark_file_committed(self) -> None:
+        self._pending_merges.clear()
+
+    def discard_uncommitted_file(self) -> None:
+        """Forget buffered evidence after its file did not commit."""
+        self._groups.clear()
+        self._pending_merges.clear()
 
     def resolve(
         self, *, source_root_key: str, observed_slot: str,
         logical_limit_key: str, window_minutes: object, resets_at_utc: object,
+        source_path: "str | None" = None,
+        line_offset: "int | None" = None,
     ) -> "str | None":
         """The canonical anchor for one observation, as stored TEXT.
 
@@ -1126,10 +1183,17 @@ class CodexResetAnchorResolver:
             return None
         group = self.group_key(
             source_root_key, observed_slot, logical_limit_key, window_minutes)
-        anchors = self._anchors_for(group, logical_limit_key)
-        chosen = _lib_quota.resolve_reset_anchor(anchors, raw)
-        if chosen == raw:
-            anchors.add(raw)
+        components = self._components_for(group, logical_limit_key)
+        order_key = None
+        if (
+            isinstance(source_path, str)
+            and isinstance(line_offset, int)
+            and not isinstance(line_offset, bool)
+        ):
+            order_key = (source_path, line_offset, -1)
+        chosen, retired = components.add(raw, order_key=order_key)
+        self._merge_stored_anchors(
+            group, logical_limit_key, chosen, retired)
         # ALWAYS re-serialized through the canonical UTC form, established or
         # joined alike: two spellings of one instant ("…Z" vs "…+00:00") must
         # never mint two anchors for one cluster, and a row seeded by anything
@@ -1137,6 +1201,25 @@ class CodexResetAnchorResolver:
         # spell it either way.
         return _codex_anchor_iso(chosen)
 
+    def normalize_quota_rows(self, quota_rows: list[tuple[Any, ...]]) -> None:
+        """Converge buffered direct-walk rows after a later bridge observation.
+
+        The journal applier inserts one row immediately after resolution, so a
+        component merge can update earlier rows in SQLite. The direct rollout
+        walk buffers a whole file before its first DML; this final pass applies
+        the same union result to those not-yet-inserted tuples.
+        """
+        for index, row in enumerate(quota_rows):
+            raw = _parse_anchor_iso(row[11])
+            if raw is None:
+                continue
+            group = self.group_key(row[1], row[5], row[6], row[9])
+            components = self._groups.get(group)
+            if components is None:
+                continue
+            quota_rows[index] = row[:-1] + (
+                _codex_anchor_iso(components.canonical(raw)),)
+
 
 def _codex_anchor_iso(value: dt.datetime) -> str:
     return value.astimezone(dt.timezone.utc).isoformat().replace("+00:00", "Z")
@@ -1272,7 +1355,9 @@ def _discover_codex_files_with_roots() -> list[CodexDiscoveredFile]:
     discovered: list[CodexDiscoveredFile] = []
     seen: set[pathlib.Path] = set()
     for root in _codex_provider_roots():
-        for candidate in root.walk_root.glob("**/*.jsonl"):
+        for candidate in sorted(
+            root.walk_root.glob("**/*.jsonl"), key=lambda path: str(path)
+        ):
             if not candidate.is_file():
                 continue
             physical_path = _canonical_codex_path(candidate)
@@ -1905,6 +1990,7 @@ def _write_codex_file_batch(
     file_identity: "str | None" = None,
     incarnation: "int | None" = None,
     file_account_decision: "tuple[int, str | None] | None" = None,
+    anchor_resolver: "CodexResetAnchorResolver | None" = None,
 ) -> int:
     """Write one fully-buffered Codex file atomically and return entry changes.
 
@@ -1960,6 +2046,8 @@ def _write_codex_file_batch(
         )
         rows_changed = conn.total_changes - before
     if quota_rows:
+        if anchor_resolver is not None:
+            anchor_resolver.apply_pending_merges()
         conn.executemany(
             """INSERT OR IGNORE INTO quota_window_snapshots
                (source, source_root_key, source_path, line_offset,
@@ -2027,7 +2115,7 @@ def _iter_codex_jsonl_paths(roots: list[pathlib.Path]) -> Iterator[pathlib.Path]
     """
     seen: set[pathlib.Path] = set()
     for root in roots:
-        for jp in root.glob("**/*.jsonl"):
+        for jp in sorted(root.glob("**/*.jsonl"), key=lambda path: str(path)):
             # Dedup on the RESOLVED path, not the raw spelling. A symlinked
             # $CODEX_HOME root or an alias entry (`.../.codex`,
             # `.../sub/../.codex`) can glob the same physical file under
@@ -4729,6 +4817,22 @@ def _progress_codex_stderr(stats: CodexIngestStats, *, force: bool = False) -> N
     )
 
 
+def _extend_codex_touched_span(
+    spans: "dict[str, tuple[dt.datetime, dt.datetime]]",
+    source_root_key: object,
+    moment: "dt.datetime | None",
+) -> None:
+    """Widen one root's touched instant span in place."""
+    if not source_root_key or moment is None:
+        return
+    key = str(source_root_key)
+    current = spans.get(key)
+    if current is None:
+        spans[key] = (moment, moment)
+    else:
+        spans[key] = (min(current[0], moment), max(current[1], moment))
+
+
 def sync_codex_cache(
     conn: sqlite3.Connection,
     *,
@@ -4753,6 +4857,13 @@ def sync_codex_cache(
     """
     stats = CodexIngestStats()
     project_after_unlock = False
+    # Per-root instant span this sync wrote — accounting-row timestamps AND
+    # canonical window resets. It bounds the end-of-sync spend-adoption pass to
+    # the windows this sync could have changed; an unchanged tree leaves it empty
+    # and the pass does no SQL at all. A rebuild deliberately passes ``None``
+    # instead (full re-derivation restores the unattributed state, so the repair
+    # has to re-run over everything).
+    adoption_spans: "dict[str, tuple[dt.datetime, dt.datetime]]" = {}
     # #313 P1 review (F4/F1): when the CACHE certificate is current we cannot
     # yet decide whether to skip the reconcile — reconcile's own short-circuit
     # ALSO requires the stats-side quota_projection_state signatures to match
@@ -4845,10 +4956,13 @@ def sync_codex_cache(
             conn.commit()
             eprint("[cache-sync] rebuild: cleared Codex cached entries")
         # #416 spec §3.4: rehydrate the attribution map from the journal BEFORE
-        # the walk. The ordinary journal-to-cache replay lives inside
-        # `rebuild_stats_index`; this path clears (on --rebuild) and walks on its
-        # own with no applier in front of it, so a cache.db whose map cannot
-        # answer would send every file back to the live auth.json.
+        # the walk. This cursor is intentionally distinct from the stats ingest
+        # cursor that drives `_cache_applier`: a recreated/rebuilt cache.db may
+        # have an empty map while stats is already at journal high-water, and
+        # invoking stats ingest here would either reverse the total lock order
+        # (inside the cache flocks) or leave an append-before-lock race (outside
+        # them). The private cache-map cursor is therefore the only safe witness
+        # that every durable decision visible to this locked walk was replayed.
         #
         # Deliberately NOT rebuild-only. Every production Codex call site syncs
         # with rebuild=False, and the corruption auto-heal recreates the cache.db
@@ -4921,9 +5035,11 @@ def sync_codex_cache(
             _jr._report_file_account_conflicts(_declined)
         except Exception as exc:
             conn.rollback()
+            stats.deferred_reason = "attribution_rehydration"
             eprint(
                 "[cache-sync] could not rehydrate Codex attribution "
-                f"decisions: {exc}; undecided history stays unattributed")
+                f"decisions: {exc}; deferring the Codex walk")
+            return stats
 
         # Pure read (glob + is_file only); safe to run before the SELECT and
         # the per-file loop, where no cache.db write lock may be held. Targeted
@@ -5186,9 +5302,14 @@ def sync_codex_cache(
                 # The guard is the whole safety argument: `delta_append` means
                 # `start_offset` is this file's ingest watermark, and the second
                 # condition means the new range starts strictly beyond every
-                # decided range. So auth.json can only ever mint a range for
-                # bytes NOBODY has attributed yet; it can never re-decide bytes
-                # a decision already covers, which is the original defect.
+                # decided range. Today the term is algebraically redundant:
+                # every non-delta branch sets `start_offset = 0`, while every
+                # decided range starts at a non-negative offset, so the strict
+                # comparison alone implies a delta append. Keep the explicit
+                # term as belt-and-suspenders: it pins the semantic permission
+                # to consult auth.json if a future branch changes the offsets.
+                # Auth can therefore mint a range only for bytes NOBODY has
+                # attributed yet; it never re-decides covered bytes.
                 if delta_append and start_offset > account_ranges[-1][0]:
                     root_account = _live_root_account()
                     if root_account.status == "torn":
@@ -5345,6 +5466,8 @@ def sync_codex_cache(
                                     logical_limit_key=quota.logical_limit_key,
                                     window_minutes=quota.window_minutes,
                                     resets_at_utc=quota.resets_at_utc,
+                                    source_path=quota.source_path,
+                                    line_offset=quota.line_offset,
                                 ),
                             ))
                         if (thread := emission.thread) is not None and (
@@ -5394,6 +5517,7 @@ def sync_codex_cache(
                         stats.skip_reasons[_r] = stats.skip_reasons.get(_r, 0) + _n
             except OSError as exc:
                 eprint(f"[codex-cache] could not read {jp}: {exc}")
+                anchor_resolver.discard_uncommitted_file()
                 if targeted:
                     stats.files_failed += 1  # §5.1 I/O decline → call dirty
                 continue
@@ -5468,6 +5592,7 @@ def sync_codex_cache(
                         f"[codex-cache] attribution decision journal append "
                         f"failed for {jp}: {exc}; deferring the file")
                     stats.files_failed += 1
+                    anchor_resolver.discard_uncommitted_file()
                     continue
 
             # Task 7 Item 1: journal the Codex quota observations BEFORE the cache
@@ -5477,6 +5602,7 @@ def sync_codex_cache(
             # (idempotent at the QUOTA_APPLIER natural key) rather than losing the
             # observation. Appended once here, not inside the retry loop, so a DB
             # retry never double-journals.
+            anchor_resolver.normalize_quota_rows(quota_rows)
             _append_codex_quota_obs(quota_rows)
 
             # Every derived row above was buffered before the first DML. A
@@ -5514,6 +5640,7 @@ def sync_codex_cache(
                         file_identity=file_identity,
                         incarnation=incarnation,
                         file_account_decision=pending_decision,
+                        anchor_resolver=anchor_resolver,
                     )
                 except sqlite3.DatabaseError as exc:
                     conn.rollback()
@@ -5543,7 +5670,26 @@ def sync_codex_cache(
                 # walk count.  Targeted mode already depended on this signal;
                 # explicit rebuild now uses it to reject partial success too.
                 stats.files_failed += 1
+                anchor_resolver.discard_uncommitted_file()
                 continue
+            anchor_resolver.mark_file_committed()
+
+            if not rebuild:
+                # Accounting timestamps share one producer spelling, so the
+                # lexicographic extremes ARE the chronological ones and only two
+                # rows need parsing. Quota anchors are few per file, so they are
+                # parsed individually.
+                if accounting_rows:
+                    for _extreme in (
+                        min(_r[2] for _r in accounting_rows),
+                        max(_r[2] for _r in accounting_rows),
+                    ):
+                        _extend_codex_touched_span(
+                            adoption_spans, discovered.source_root_key,
+                            _parse_anchor_iso(_extreme))
+                for _qrow in quota_rows:
+                    _extend_codex_touched_span(
+                        adoption_spans, _qrow[1], _parse_anchor_iso(_qrow[17]))
 
             # Private test seam (§5.1 post-preflight late-shrink race): fires
             # after each file's successful commit, so a race test can shrink a
@@ -5597,6 +5743,31 @@ def sync_codex_cache(
                 conn.execute("DELETE FROM cache_meta WHERE key = ?",
                              ("codex_torn_auth_deferred",))
             conn.commit()
+        # Window-scoped spend adoption (spec
+        # docs/superpowers/specs/2026-07-30-codex-window-scoped-spend-adoption.md).
+        # Runs AFTER the walk committed and while both cache writer flocks are
+        # still held, so the observation evidence and the accounting rows it
+        # stamps are the same committed generation. Cache-only — no stats.db read
+        # — so the lock-order law is untouched. A failure here is never fatal:
+        # the stamp is fully re-derivable, so the next sync (or the migration)
+        # repeats it.
+        try:
+            adopted = apply_codex_window_spend_adoption(
+                conn, touched=None if rebuild else adoption_spans)
+            conn.commit()
+            # Terse, and silent on zero: a rebuild re-derives every row and so
+            # legitimately re-stamps the same population each time, which would
+            # otherwise read as a recurring anomaly rather than convergence.
+            if adopted:
+                eprint(f"[cache-sync] attributed {adopted} Codex row(s) "
+                       "from quota windows")
+        except sqlite3.DatabaseError as exc:
+            conn.rollback()
+            if _cctally_db_sib._is_sqlite_corruption_error(exc):
+                # Classified family corruption belongs to the shared recovery
+                # boundary, never to a best-effort local except.
+                raise
+            eprint(f"[cache-sync] could not adopt Codex window spend: {exc}")
         # Codex creates/extends cache.db sidecars independently of Claude's
         # sync path. Harden them while both cache flocks are still held and
         # after all Codex writes, before the optional checkpoint can rotate a
@@ -5693,6 +5864,188 @@ def sync_codex_cache(
     return stats
 
 
+_CODEX_ACCOUNT_WEEK = dt.timedelta(
+    minutes=_lib_codex_account_adoption.ACCOUNT_WEEKLY_WINDOW_MINUTES)
+
+
+def apply_codex_window_spend_adoption(
+    conn: sqlite3.Connection,
+    *,
+    touched: "dict[str, tuple[dt.datetime, dt.datetime]] | None" = None,
+) -> int:
+    """Stamp window-derived attribution onto unattributed Codex spend.
+
+    The I/O half of ``_lib_codex_account_adoption``: read the folded window
+    evidence and the candidate rows, hand both to the pure kernel, write back the
+    plan it returns.  Cache-only by construction — the window's identified
+    accounts come from ``load_codex_quota_observations`` (which already runs
+    ``adopt_unidentified_observations``) and the nominal range is derived from
+    the canonical reset, so no stats.db read is involved and the lock-order law
+    is untouched.  The caller owns the transaction and the commit.
+
+    ``touched`` maps ``source_root_key`` to the ``(low, high)`` instant span this
+    sync wrote — the timestamps of the accounting rows AND the canonical resets
+    of the quota rows.  ``None`` runs the pass over all history (``cache-sync
+    --rebuild`` and the one-time migration); an EMPTY map is a no-op that issues
+    NO SQL AT ALL, which is what keeps a quiescent hook tick free.
+
+    A bounded pass must reach the SAME verdict the unbounded one would, because
+    the stamp is one-way (``NULL`` -> key, never back) and an incremental sync
+    followed by a later rebuild would otherwise disagree.  That needs the loaded
+    window set to be a SUPERSET of the windows that can claim any candidate the
+    scan offers, so the two bounds are derived together: windows are loaded for
+    resets in ``[low - 7d, high + 7d]``, and candidates are clamped to
+    ``[low - 7d, high]``.  Every window claiming an instant ``t`` in that
+    candidate span has its reset in ``(t, t + 7d]``, which the window bound
+    contains — so no window can claim a scanned row unseen.  The candidate span
+    still covers everything this sync could have changed: the rows it wrote lie
+    in ``[low, high]``, and a window whose reset it wrote lies in ``[low, high]``
+    too, so that window's whole nominal range lies in ``[low - 7d, high)``.
+
+    Idempotent and re-runnable: ``codex_session_entries`` is fully re-derived on
+    every rebuild, so the pass must re-stamp afterwards, and re-running over an
+    already-stamped cache writes nothing because an identified row is never a
+    candidate.  Returns the number of rows actually stamped.
+    """
+    roots: "set[str] | None" = None
+    reset_bounds: "tuple[dt.datetime, dt.datetime] | None" = None
+    candidate_bounds: "tuple[dt.datetime, dt.datetime] | None" = None
+    if touched is not None:
+        spans = {
+            str(root): span for root, span in touched.items()
+            if root and span is not None
+        }
+        # Before any SQL: an unchanged tree must cost this pass nothing.
+        if not spans:
+            return 0
+        roots = set(spans)
+        low = min(span[0] for span in spans.values())
+        high = max(span[1] for span in spans.values())
+        reset_bounds = (low - _CODEX_ACCOUNT_WEEK, high + _CODEX_ACCOUNT_WEEK)
+        candidate_bounds = (low - _CODEX_ACCOUNT_WEEK, high)
+
+    from _cctally_quota import load_codex_quota_observations
+
+    # `_load_lib`, not a bare import: this module is loadable in isolation, where
+    # `bin/` may not be on `sys.path` (see the module docstring).
+    _lib_accounts = _load_lib("_lib_accounts")
+    is_model_scoped_codex_quota = _load_lib(
+        "_lib_codex_pools").is_model_scoped_codex_quota
+    adopt = _lib_codex_account_adoption
+    try:
+        columns = {
+            str(row[1]) for row in conn.execute(
+                "PRAGMA table_info(codex_session_entries)")
+        }
+    except sqlite3.DatabaseError:
+        return 0
+    if not {"account_key", "source_root_key", "timestamp_utc"} <= columns:
+        return 0
+
+    try:
+        observations = load_codex_quota_observations(
+            source_root_keys=roots, cache_conn=conn,
+            canonical_resets_between=reset_bounds,
+        )
+    except sqlite3.DatabaseError:
+        return 0
+
+    # Group on the SAME key the observation fold groups on
+    # (`_lib_quota._physical_window_key`) — the account is deliberately excluded
+    # from it, which is precisely what makes a window able to name an account for
+    # rows that carry none.
+    buckets: "dict[tuple, dict]" = {}
+    for observation in observations:
+        identity = observation.identity
+        bucket = buckets.get(key := _lib_quota._physical_window_key(observation))
+        if bucket is None:
+            bucket = buckets[key] = {
+                "root": identity.source_root_key,
+                "minutes": identity.window_minutes,
+                "reset": observation.canonical_resets_at,
+                "accounts": set(),
+                "model_scoped": False,
+            }
+        if identity.account_key != _lib_accounts.UNATTRIBUTED:
+            bucket["accounts"].add(identity.account_key)
+        # `limit_name` is compare=False on the identity, so the label can differ
+        # across one group's observations; ANY Spark evidence demotes the whole
+        # window out of account weekly quota (#373). That direction only ever
+        # withholds a stamp, never invents one.
+        if is_model_scoped_codex_quota(
+                identity.logical_limit_key, identity.limit_name):
+            bucket["model_scoped"] = True
+
+    windows: "list[object]" = []
+    root_ranges: "dict[str, list[tuple[dt.datetime, dt.datetime]]]" = {}
+    for bucket in buckets.values():
+        window = adopt.SpendAdoptionWindow(
+            source_root_key=bucket["root"],
+            window_minutes=bucket["minutes"],
+            canonical_resets_at=bucket["reset"],
+            identified_accounts=frozenset(bucket["accounts"]),
+            model_scoped=bucket["model_scoped"],
+        )
+        if not window.in_scope:
+            continue
+        windows.append(window)
+        root_ranges.setdefault(window.source_root_key, []).append(
+            (window.nominal_start_at, window.canonical_resets_at))
+    if not windows:
+        return 0
+
+    # SQL bounds the scan to a coarse per-root union of the candidate windows,
+    # clamped to the span the loaded window set provably covers (see the
+    # docstring); exact half-open containment stays in the kernel. `unixepoch`
+    # deliberately accepts both retained spellings (`Z` and `+00:00`) — the
+    # accounting rows are written with the offset form, the quota rows with `Z`.
+    # Both comparisons are INCLUSIVE on the truncated second: `unixepoch` drops
+    # any sub-second fraction, so an exclusive upper bound would discard rows in
+    # the reset's final second if a canonical anchor ever carried one. Admitting
+    # that second here is free — the kernel re-tests containment exactly.
+    candidates = []
+    for root, spans_for_root in root_ranges.items():
+        window_low = min(span[0] for span in spans_for_root)
+        window_high = max(span[1] for span in spans_for_root)
+        if candidate_bounds is not None:
+            window_low = max(window_low, candidate_bounds[0])
+            window_high = min(window_high, candidate_bounds[1])
+            if window_low > window_high:
+                continue
+        for row in conn.execute(
+            "SELECT id, timestamp_utc FROM codex_session_entries "
+            " WHERE source_root_key = ? "
+            "   AND (account_key IS NULL OR account_key = '' "
+            "        OR account_key = ?) "
+            "   AND unixepoch(timestamp_utc) >= unixepoch(?) "
+            "   AND unixepoch(timestamp_utc) <= unixepoch(?)",
+            (root, _lib_accounts.UNATTRIBUTED,
+             _codex_anchor_iso(window_low), _codex_anchor_iso(window_high)),
+        ):
+            timestamp = _parse_anchor_iso(row[1])
+            if timestamp is None:
+                continue
+            candidates.append(adopt.SpendAdoptionCandidate(
+                entry_id=int(row[0]), source_root_key=root,
+                timestamp=timestamp, account_key=None,
+            ))
+    if not candidates:
+        return 0
+
+    plan = adopt.build_spend_adoption_plan(windows, candidates)
+    if not plan:
+        return 0
+    before = conn.total_changes
+    conn.executemany(
+        "UPDATE codex_session_entries SET account_key = ? "
+        " WHERE id = ? AND (account_key IS NULL OR account_key = '' "
+        "                   OR account_key = ?)",
+        [(stamp.account_key, stamp.entry_id, _lib_accounts.UNATTRIBUTED)
+         for stamp in plan],
+    )
+    return conn.total_changes - before
+
+
 def iter_codex_entries(
     conn: sqlite3.Connection,
     range_start: dt.datetime,