cctally 1.109.0 → 1.111.0

package/bin/_cctally_db.py

@@ -2083,6 +2083,8 @@ def _run_pending_migrations(
                 db_label, db_version=cur_version, max_known=len(registry),
             )
     if cur_version == len(registry):
+        if db_label == "conversations.db":
+            _ensure_codex_session_meta_provenance_index(conn)
         # When the registry is currently empty (today's cache.db case),
         # still leave the schema_migrations table behind so a later
         # transition to len(registry) >= 1 can distinguish populated
@@ -2124,6 +2126,9 @@ def _run_pending_migrations(
             db_label, _first_pending_migration_name(conn, registry, cur_version)
         )
 
+    if db_label == "conversations.db":
+        _ensure_codex_session_meta_provenance_index(conn)
+
     # Track whether schema_migrations existed before this open so we can
     # detect the fresh-install path. After bootstrap, even a "first time
     # opened with framework code" DB might have rows from the legacy
@@ -5475,6 +5480,45 @@ def _apply_conversations_schema(conn: sqlite3.Connection) -> None:
     _apply_codex_conversation_source_identity(conn)
 
 
+def _ensure_codex_session_meta_provenance_index(
+    conn: sqlite3.Connection,
+) -> bool:
+    """Ensure the account-scoped anonymization provenance index exists.
+
+    ``codex_conversation_events`` is an append-only physical log and can be
+    much larger than the normalized transcript.  The scoped anonymizer reads
+    only ``session_meta`` payloads, so an index restricted to that record type
+    makes the read proportional to the retained provenance rows rather than
+    every event.  This is an idempotent, data-free schema ensure run by the
+    conversations dispatcher on both its fast and pending paths; keeping the
+    helper here also gives the schema migration layer one stable delivery
+    point for fresh and already-current stores.
+
+    A pre-conversations store may not have the event table yet.  That is a
+    valid no-op; the schema apply creates it before the dispatcher runs.
+    Other SQLite errors propagate so a damaged store cannot silently fall back
+    to a full physical-event scan.
+    """
+    if conn.execute(
+        "SELECT 1 FROM sqlite_master "
+        "WHERE type='table' AND name='codex_conversation_events'"
+    ).fetchone() is None:
+        return False
+    if conn.execute(
+        "SELECT 1 FROM sqlite_master "
+        "WHERE type='index' AND name='idx_codex_events_session_meta_provenance'"
+    ).fetchone() is not None:
+        return True
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_events_session_meta_provenance "
+        "ON codex_conversation_events("
+        "source_root_key, account_key, conversation_key, payload_json) "
+        "WHERE record_type='session_meta'"
+    )
+    conn.commit()
+    return True
+
+
 #: `cache_meta` keys the stamp backfill uses. The cursor is the durable resume
 #: point (the last source path whose rows are fully stamped); the completion
 #: marker is what a rebuild's publication gate reads. Both are values, not

package/bin/_cctally_diagnosis_sources.py

@@ -40,10 +40,12 @@ import json
 import os
 import pickle
 import re
+import signal
 import shlex
 import sqlite3
 import sys
 import threading
+import time
 from collections import defaultdict
 from dataclasses import dataclass, field
 from functools import cached_property
@@ -71,6 +73,14 @@ UTC = dt.timezone.utc
 # bounded wait rather than an immediate `database is locked`.
 READ_BUSY_TIMEOUT_MS = 4000
 
+# A provider read can lose its component-local coherence check to the writer
+# that is publishing the next generation. Retry the whole provider build a
+# small number of times while a monotonic admission budget remains. The
+# `_establish` retry remains deliberately narrower: it still rereads one
+# component once and refuses a second divergence within that build.
+DIAGNOSIS_RETRY_MAX_ATTEMPTS = 3
+DIAGNOSIS_RETRY_DEADLINE_SECONDS = 1.0
+
 _STORE_PATHS = {
     "cache": "CACHE_DB_PATH",
     "stats": "DB_PATH",
@@ -1045,28 +1055,22 @@ def _compiled_codex_pricer(model: str, speed: str):
                reasoning_output_tokens: int) -> float:
         del reasoning_output_tokens
         non_cached_input = max(0, input_tokens - cached_input_tokens)
+        long_context = input_tokens > threshold
         if non_cached_input <= 0 or not input_rate:
             input_cost = 0.0
-        elif non_cached_input > threshold and input_tier is not None:
-            input_cost = (threshold * input_rate
-                          + (non_cached_input - threshold) * input_tier)
         else:
-            input_cost = non_cached_input * input_rate
+            input_cost = non_cached_input * (
+                input_tier if long_context and input_tier is not None else input_rate)
         if cached_input_tokens <= 0 or not cache_rate:
             cached_input_cost = 0.0
-        elif cached_input_tokens > threshold and cache_tier is not None:
-            cached_input_cost = (
-                threshold * cache_rate
-                + (cached_input_tokens - threshold) * cache_tier)
         else:
-            cached_input_cost = cached_input_tokens * cache_rate
+            cached_input_cost = cached_input_tokens * (
+                cache_tier if long_context and cache_tier is not None else cache_rate)
         if output_tokens <= 0 or not output_rate:
             output_cost = 0.0
-        elif output_tokens > threshold and output_tier is not None:
-            output_cost = (threshold * output_rate
-                           + (output_tokens - threshold) * output_tier)
         else:
-            output_cost = output_tokens * output_rate
+            output_cost = output_tokens * (
+                output_tier if long_context and output_tier is not None else output_rate)
         base = input_cost + cached_input_cost + output_cost
         if speed == "fast":
             base *= multiplier
@@ -4345,11 +4349,43 @@ def build_provider_diagnosis(scope: DiagnosisScope, *,
         )
 
 
+def _build_provider_with_retry(scope: DiagnosisScope, *,
+                               transcripts_visible: bool
+                               ) -> kernel.ProviderResult:
+    """Build one provider, admitting only bounded fresh retries.
+
+    A `generation_incoherent` result means the provider's read crossed two
+    writes during one attempt. Restarting the provider build is safe because
+    every attempt owns fresh read-only connections and facts. Other typed
+    establishment failures and unexpected exceptions retain their existing
+    handling at the caller; they are never converted into retries.
+    """
+    deadline = time.monotonic() + DIAGNOSIS_RETRY_DEADLINE_SECONDS
+    for attempt in range(DIAGNOSIS_RETRY_MAX_ATTEMPTS):
+        try:
+            return build_provider_diagnosis(
+                scope, transcripts_visible=transcripts_visible)
+        except EstablishmentFailure as exc:
+            if exc.code != EstablishmentError.GENERATION_INCOHERENT.value:
+                raise
+            if attempt + 1 >= DIAGNOSIS_RETRY_MAX_ATTEMPTS:
+                raise
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise
+            # Give an in-flight writer a chance to finish before reopening
+            # every store. Normal coherent reads pay no delay.
+            time.sleep(min(0.1 * (attempt + 1), remaining))
+            if time.monotonic() >= deadline:
+                raise
+    raise AssertionError("provider diagnosis retry loop did not return")
+
+
 def _build_provider_task(args) -> kernel.ProviderResult:
     """Pickle-safe provider build for the independent `all` branches."""
     scope, transcripts_visible = args
     try:
-        result = build_provider_diagnosis(
+        result = _build_provider_with_retry(
             scope, transcripts_visible=transcripts_visible)
     except EstablishmentFailure as exc:
         if exc.code != EstablishmentError.STORE_UNAVAILABLE.value:
@@ -4419,6 +4455,136 @@ def _spawn_worker_init(cctally_path: str,
         setattr(_cctally_core, name, pathlib.Path(raw))
 
 
+_DIAGNOSIS_PROCESS_TERMINATE_GRACE_SECONDS = 0.5
+
+
+def _bounded_process_entry(result_path: str, task, args,
+                           initializer, initargs) -> None:
+    """Run one pickle-safe task in its own killable process group."""
+    if hasattr(os, "setsid"):
+        try:
+            os.setsid()
+        except OSError:
+            # The parent still terminates this process directly if the group
+            # was not established. No descendants exist before this point.
+            pass
+    try:
+        if initializer is not None:
+            initializer(*initargs)
+        payload = ("ok", task(*args))
+    except EstablishmentFailure as exc:
+        payload = ("establishment", exc.code, exc.message)
+    except BaseException as exc:
+        payload = ("unexpected", type(exc).__name__, str(exc))
+    with open(result_path, "wb") as stream:
+        pickle.dump(payload, stream, protocol=5)
+
+
+def _terminate_process_group(process) -> None:
+    """Terminate and reap one bounded worker plus any provider descendants."""
+    grouped = False
+    if process.pid is not None and hasattr(os, "killpg"):
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+            grouped = True
+        except ProcessLookupError:
+            pass
+        except OSError:
+            pass
+    if process.is_alive() and not grouped:
+        process.terminate()
+    process.join(_DIAGNOSIS_PROCESS_TERMINATE_GRACE_SECONDS)
+    if grouped and process.pid is not None:
+        try:
+            # The leader may have exited on SIGTERM while a provider child
+            # ignored it. The process group remains addressable until every
+            # descendant is gone, so always finish the group with SIGKILL.
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        except OSError:
+            pass
+    elif process.is_alive():
+        process.kill()
+    process.join(_DIAGNOSIS_PROCESS_TERMINATE_GRACE_SECONDS)
+
+
+def _run_process_with_deadline(task, args, *, timeout_seconds: float,
+                               initializer=None, initargs=()):
+    """Run TASK in a one-shot process and forcibly retire it at the deadline."""
+    import multiprocessing
+    import tempfile
+
+    if timeout_seconds <= 0:
+        raise TimeoutError("diagnosis process deadline expired")
+    methods = multiprocessing.get_all_start_methods()
+    method = "forkserver" if "forkserver" in methods else "spawn"
+    context = multiprocessing.get_context(method)
+    fd, result_path = tempfile.mkstemp(prefix="cctally-diagnosis-")
+    os.close(fd)
+    process = context.Process(
+        target=_bounded_process_entry,
+        args=(result_path, task, args, initializer, initargs),
+        name="cctally-diagnosis-process",
+    )
+    try:
+        process.start()
+        process.join(timeout_seconds)
+        if process.is_alive():
+            _terminate_process_group(process)
+            raise TimeoutError("diagnosis process deadline expired")
+        if process.exitcode != 0:
+            raise RuntimeError(
+                f"diagnosis process exited {process.exitcode}")
+        try:
+            with open(result_path, "rb") as stream:
+                payload = pickle.load(stream)
+        except (EOFError, OSError, pickle.PickleError) as exc:
+            raise RuntimeError("diagnosis process returned no result") from exc
+    finally:
+        if process.is_alive():
+            _terminate_process_group(process)
+        try:
+            os.unlink(result_path)
+        except FileNotFoundError:
+            pass
+        process.close()
+    if payload[0] == "ok":
+        return payload[1]
+    if payload[0] == "establishment":
+        raise EstablishmentFailure(payload[1], payload[2])
+    raise RuntimeError(f"{payload[1]}: {payload[2]}")
+
+
+def _build_diagnosis_process_task(scope: DiagnosisScope,
+                                  measured_at: dt.datetime | None,
+                                  transcripts_visible: bool):
+    return build_diagnosis(
+        scope, measured_at=measured_at,
+        transcripts_visible=transcripts_visible,
+    )
+
+
+def build_diagnosis_bounded(scope: DiagnosisScope, *,
+                            measured_at: dt.datetime | None = None,
+                            transcripts_visible: bool,
+                            timeout_seconds: float) -> kernel.DiagnosisReport:
+    """Build one dashboard diagnosis in a process retired at TIMEOUT_SECONDS."""
+    c = _cctally()
+    paths = {
+        name: str(getattr(_cctally_core, name))
+        for name in ("CACHE_DB_PATH", "DB_PATH",
+                     "CONVERSATIONS_DB_PATH", "CONFIG_PATH")
+    }
+    return _run_process_with_deadline(
+        _build_diagnosis_process_task,
+        (scope, measured_at, transcripts_visible),
+        timeout_seconds=timeout_seconds,
+        initializer=_spawn_worker_init,
+        initargs=(str(c.__file__), paths),
+    )
+
+
 def _build_isolated_provider(args):
     """Run one provider in a portable, one-shot safe process worker."""
     import concurrent.futures
@@ -4467,7 +4633,7 @@ def build_diagnosis(scope: DiagnosisScope,
             label=scope.label,
         )
         try:
-            return build_provider_diagnosis(
+            return _build_provider_with_retry(
                 provider_scope, transcripts_visible=transcripts_visible)
         except EstablishmentFailure as exc:
             # A store that cannot be OPENED withholds its provider rather than

package/bin/_cctally_doctor.py

@@ -1810,9 +1810,15 @@ def _doctor_gather_state_impl(
                     if row:
                         codex_entries_count = int(row[0]) if row[0] is not None else 0
                         if row[1]:
-                            codex_last_entry_at = parse_iso_datetime(
-                                row[1], "codex_session_entries.timestamp_utc",
-                            ).astimezone(dt.timezone.utc)
+                            try:
+                                codex_last_entry_at = parse_iso_datetime(
+                                    row[1], "codex_session_entries.timestamp_utc",
+                                ).astimezone(dt.timezone.utc)
+                            except ValueError:
+                                # A malformed newest row cannot establish cache
+                                # freshness. Continue to the all-history health
+                                # partition so doctor can count the bad row.
+                                codex_last_entry_at = None
                     try:
                         row = conn.execute(
                             "SELECT COUNT(*) FROM quota_window_snapshots "
@@ -1839,7 +1845,13 @@ def _doctor_gather_state_impl(
                             "qualified_rows": health.qualified_rows,
                             "missing_conversation_key_rows": health.missing_conversation_key_rows,
                             "missing_thread_join_rows": health.missing_thread_join_rows,
+                            "undecodable_metadata_rows": (
+                                health.undecodable_metadata_rows),
                         }
+                        if health.malformed_accounting_rows:
+                            codex_project_metadata_health[
+                                "malformed_accounting_rows"] = (
+                                    health.malformed_accounting_rows)
                     except Exception as exc:
                         codex_project_metadata_error = type(exc).__name__
                 except sqlite3.OperationalError as exc:

package/bin/_cctally_forecast.py

@@ -127,16 +127,16 @@ def _resolve_forecast_now(as_of: str | None) -> dt.datetime:
     return _command_as_of()
 
 
-def _shape_week_samples(rows, *, include_held: bool) -> list:
+def _shape_week_samples(rows, *, include_held: bool,
+                        include_account: bool = False) -> list:
     """Turn snapshot rows into the sample tuples `_fetch_current_week_snapshots`
     returns. Both of that function's row-fetch legs go through here so the two
     cannot drift on the tuple width.
 
     `rows` are `(captured_at_utc, weekly_percent, five_hour_percent,
-    weekly_observation_held)`. The held flag is appended to the sample only
-    when the caller asked for held rows, because a caller that excluded them
-    has nothing to tell apart and the three-element shape is what every
-    existing consumer unpacks.
+    weekly_observation_held[, account_key])`. The held flag is appended only
+    for a held-inclusive read, and the account only for an explicit identity
+    read. Existing consumers keep the historical three- or four-field shape.
     """
     out = []
     for row in rows:
@@ -147,13 +147,16 @@ def _shape_week_samples(rows, *, include_held: bool) -> list:
         )
         if include_held:
             sample = sample + (int(row[3] or 0),)
+        if include_account:
+            sample = sample + (row[4],)
         out.append(sample)
     return out
 
 
 def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime,
                                   *, account_key: "str | None" = None,
-                                  include_held: bool = False):
+                                  include_held: bool = False,
+                                  include_account: bool = False):
     """Return (week_start_at, week_end_at, list[(captured_at, percent, five_hr)])
     for the subscription week containing `now_utc`, or None if no snapshot
     exists for the current week.
@@ -199,6 +202,10 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
         five-hour axis takes the newest sample, a caller reading the weekly
         axis takes the newest sample whose flag is 0, and neither can mistake
         a carried-forward weekly value for an observed one.
+
+    ``include_account`` appends the physical account key after the held flag
+    for the multi-account Current Week card only. The default wire-independent
+    sample shape and merged forecast/cost reads remain unchanged.
     """
     # #341: optional account scoping — same predicate on every leg so the whole
     # window resolution stays consistent (a real key or the `unattributed`
@@ -209,6 +216,10 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
     # `include_held=True` is a pure superset of the default read rather than a
     # read that can also resolve a different week.
     _held_pred = "" if include_held else " AND weekly_observation_held = 0"
+    # The TUI's multi-account card needs the physical owner of the sample it
+    # actually displays. Keep the historical sample shape for every other read.
+    _owner_column = ", account_key" if include_account else ""
+    _sample_order = " ASC, id ASC" if include_account else " ASC"
     candidates = conn.execute(
         "SELECT week_start_at, week_end_at, week_start_date, MAX(captured_at_utc) AS latest_cap "
         "FROM weekly_usage_snapshots "
@@ -255,13 +266,14 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
         week_end_at = dt.datetime.combine(we_date + dt.timedelta(days=1), dt.time(0, 0), local_tz).astimezone(dt.timezone.utc)
         rows = conn.execute(
             "SELECT captured_at_utc, weekly_percent, five_hour_percent, "
-            "       weekly_observation_held "
+            "       weekly_observation_held" + _owner_column + " "
             "FROM weekly_usage_snapshots "
             "WHERE week_start_date = ?" + _acct_pred + _held_pred +
-            " ORDER BY captured_at_utc ASC",
+            " ORDER BY captured_at_utc" + _sample_order,
             (drow[0],) + _acct_p,
         ).fetchall()
-        samples = _shape_week_samples(rows, include_held=include_held)
+        samples = _shape_week_samples(rows, include_held=include_held,
+                                      include_account=include_account)
         samples = [s for s in samples if s[0] <= now_utc]
         return week_start_at, week_end_at, samples
     row = chosen
@@ -283,15 +295,16 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
     placeholders = ",".join("?" * len(matching_texts))
     rows = conn.execute(
         f"SELECT captured_at_utc, weekly_percent, five_hour_percent, "
-        f"       weekly_observation_held "
+        f"       weekly_observation_held{_owner_column} "
         f"FROM weekly_usage_snapshots "
         f"WHERE (week_start_at IN ({placeholders}) "
         f"       OR (week_start_at IS NULL AND week_start_date = ?))"
         f"{_acct_pred}{_held_pred} "
-        f"ORDER BY captured_at_utc ASC",
+        f"ORDER BY captured_at_utc{_sample_order}",
         tuple(matching_texts) + (chosen_date,) + _acct_p,
     ).fetchall()
-    samples = _shape_week_samples(rows, include_held=include_held)
+    samples = _shape_week_samples(rows, include_held=include_held,
+                                  include_account=include_account)
     samples = [s for s in samples if s[0] <= now_utc]
     return week_start_at, week_end_at, samples
 

package/bin/_cctally_journal.py

@@ -1415,6 +1415,9 @@ class IngestContext:
     # writes while still exercising the same SQLite derivation/fold code.
     event_sink: "list | None" = None
     projection_writes: bool = True
+    # Operator-reviewed scratch replay only. Normal ingest leaves this empty.
+    held_weekly_observation_ids: frozenset[str] = field(default_factory=frozenset)
+    reviewed_weekly_basis_by_account: dict = field(default_factory=dict)
     # #374 write boundary: emissions WITHHELD this cycle because they would have
     # violated the same-revision rule. Each entry is a `DroppedConflict`; the row
     # was converged from the already-journaled effective event instead.
@@ -3424,7 +3427,8 @@ def _now_iso() -> str:
 #: the reset-aware in-window maximum, so it IS the week's evidence.
 #: ``WEEKLY_HELD_CLAMP`` — it is strictly below that maximum, so the weekly axis
 #: is held at the maximum and the incoming value is recorded only as the raw
-#: reading. A held weekly value is never fresh weekly evidence.
+#: reading. On reviewed scratch replay, an exact observation id can also hold
+#: a reading above the basis; either way it is not fresh weekly evidence.
 WEEKLY_OBSERVED = "observed"
 WEEKLY_HELD_CLAMP = "held_clamp"
 
@@ -3469,6 +3473,30 @@ class WeeklyBasis:
     week_end_at: "str | None"
 
 
+def _latest_weekly_basis(conn, account_key, *, week_start_date=None):
+    """Return accepted weekly evidence before a later axis may delete rows."""
+    sql = (
+        "SELECT id, captured_at_utc, weekly_percent, week_start_date, "
+        "       week_end_date, week_start_at, week_end_at "
+        "FROM weekly_usage_snapshots "
+        "WHERE account_key = ? AND weekly_observation_held = 0 "
+    )
+    args = (account_key,)
+    if week_start_date is not None:
+        sql += "AND week_start_date = ? "
+        args += (week_start_date,)
+    row = conn.execute(
+        sql + "ORDER BY captured_at_utc DESC, id DESC LIMIT 1", args,
+    ).fetchone()
+    if row is None:
+        return None
+    return WeeklyBasis(
+        snapshot_id=int(row[0]), captured_at_utc=str(row[1]),
+        weekly_percent=float(row[2]), week_start_date=row[3],
+        week_end_date=row[4], week_start_at=row[5], week_end_at=row[6],
+    )
+
+
 @dataclass(frozen=True)
 class WeeklyFold:
     """The weekly axis of one fold decision."""
@@ -3514,7 +3542,9 @@ class UsageSnapshotFoldResult:
     snapshot_action: str
 
 
-def _usage_snapshot_fold_decision(conn, payload) -> UsageSnapshotFoldResult:
+def _usage_snapshot_fold_decision(
+    conn, payload, *, force_weekly_hold=False, reviewed_weekly_basis=None,
+) -> UsageSnapshotFoldResult:
     """The apply-time accept/hold/skip decision for a Claude rate-limit obs —
     the predicate ported from `cmd_record_usage`'s insert guard
     (bin/_cctally_record.py), made at fold time (spec §4.5 / §5.3).
@@ -3535,9 +3565,9 @@ def _usage_snapshot_fold_decision(conn, payload) -> UsageSnapshotFoldResult:
     The clamp/hold distinction is what `_pipeline_claude_usage` gates the weekly
     milestone on, and the reason it must survive: a dedup skip AGREES with the
     stored row, so re-running the derivation chokepoints against it heals a
-    killed tick; a clamp CONTRADICTS it, so deriving a weekly milestone from the
-    higher stored value fabricates a crossing (the 2026-09-01 incident, a
-    fabricated 13% milestone, and milestones are forward-only within an epoch).
+    killed tick; a hold CONTRADICTS it, so deriving a weekly milestone from the
+    carried value fabricates a crossing (the 2026-09-01 incident, a fabricated
+    13% milestone, and milestones are forward-only within an epoch).
 
     Every value returned is derived from the same `conn` state and payload, so
     the whole result is exactly as replay-deterministic as the boolean it
@@ -3573,30 +3603,24 @@ def _usage_snapshot_fold_decision(conn, payload) -> UsageSnapshotFoldResult:
         (week_start_date, account_key, clamp_floor_iso),
     ).fetchone()
     max_v = max_row[0] if max_row else None
-    weekly_held = _lib_record.hwm_clamp_applies(weekly_percent, max_v)
-    weekly_effective = float(max_v) if weekly_held else weekly_percent
+    weekly_held = force_weekly_hold or _lib_record.hwm_clamp_applies(
+        weekly_percent, max_v)
 
     basis = None
     if weekly_held:
-        basis_row = conn.execute(
-            "SELECT id, captured_at_utc, weekly_percent, week_start_date, "
-            "       week_end_date, week_start_at, week_end_at "
-            "FROM weekly_usage_snapshots "
-            "WHERE week_start_date = ? AND account_key = ? "
-            "  AND weekly_observation_held = 0 "
-            "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
-            (week_start_date, account_key),
-        ).fetchone()
-        if basis_row is not None:
-            basis = WeeklyBasis(
-                snapshot_id=int(basis_row[0]),
-                captured_at_utc=str(basis_row[1]),
-                weekly_percent=float(basis_row[2]),
-                week_start_date=basis_row[3],
-                week_end_date=basis_row[4],
-                week_start_at=basis_row[5],
-                week_end_at=basis_row[6],
-            )
+        # A reviewed hold may carry an old raw boundary. Its basis is selected
+        # before reset/credit detection because five-hour credit can delete
+        # that very row while preserving the held observation's 5h effect.
+        basis = (
+            reviewed_weekly_basis if force_weekly_hold
+            else _latest_weekly_basis(
+                conn, account_key, week_start_date=week_start_date)
+        )
+    weekly_effective = (
+        basis.weekly_percent if force_weekly_hold and basis is not None
+        else float(max_v) if weekly_held and max_v is not None
+        else weekly_percent
+    )
 
     weekly = WeeklyFold(
         raw_pct=weekly_percent,
@@ -3636,12 +3660,16 @@ def _usage_snapshot_fold_decision(conn, payload) -> UsageSnapshotFoldResult:
     # it would make the next held tick look like new five-hour evidence and
     # write a duplicate row every tick. Its weekly value is by construction a
     # copy of the basis's, so including it changes no weekly comparison.
+    last_week_start_date = (
+        basis.week_start_date if force_weekly_hold and basis is not None
+        else week_start_date
+    )
     last = conn.execute(
         "SELECT weekly_percent, five_hour_percent, five_hour_window_key "
         "FROM weekly_usage_snapshots "
         "WHERE week_start_date = ? AND account_key = ? "
         "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
-        (week_start_date, account_key),
+        (last_week_start_date, account_key),
     ).fetchone()
     last_5h = last[1] if last is not None else None
     last_window_key = last[2] if last is not None else None
@@ -3673,11 +3701,9 @@ def _usage_snapshot_fold_decision(conn, payload) -> UsageSnapshotFoldResult:
 
     # ── The materialized outcome ───────────────────────────────────────────
     if weekly_held:
-        # The weekly axis carries nothing new by definition — its value is the
-        # stored maximum. Only the five-hour axis can justify a row, and it can
-        # only justify a HELD one. A clamp with no basis cannot be materialized
-        # at all (no boundary to copy), so it degrades to a skip rather than
-        # writing a row with a fabricated week.
+        # The weekly axis carries nothing new. An ordinary clamp writes only
+        # for five-hour evidence, including on an explicit reviewed hold.
+        # A held row also needs an accepted basis boundary to carry forward.
         if five_hour_unchanged or basis is None:
             action = SNAPSHOT_SKIP_NO_CHANGE
         else:
@@ -3913,6 +3939,7 @@ _EVT_KIND_PROVIDER = {
 # planner raises `RederiveConflict` on every run.
 _ACCOUNTS_MACHINERY_KINDS = frozenset(
     ("account_observe", "account_label", "accounts_cutover",
+     "claude_weekly_observation_decision",
      "codex_file_account",
      "codex_window_attribution", "codex_window_attribution_retract"))