cctally 1.90.1 → 1.92.0

package/bin/_lib_dashboard_sources.py

@@ -33,7 +33,10 @@ CapabilityStatus = Literal[
 # field. Additive and omitted-when-zero, so the normal payload is byte-identical
 # — but the same `execvp` transition applies, so the bump ships as the signal it
 # has always been rather than as a mechanism the client branches on.
-SOURCE_SCHEMA_VERSION = 3
+# 3 -> 4 (#465): the Codex cache report retired its transitional
+# `cache_hit_percent` alias and changed structurally inapplicable figures from
+# numeric placeholders to null.
+SOURCE_SCHEMA_VERSION = 4
 DEFAULT_SOURCE = "claude"
 SOURCE_ORDER = ("claude", "codex", "all")
 SOURCE_FRESHNESS_DOMAINS = ("hero", "quota", "sessions")
@@ -392,13 +395,11 @@ def _combined_metrics(
 ) -> Mapping[str, object] | None:
     if not (_coherent_provider(claude) and _coherent_provider(codex)):
         return None
-    # #350 spec §3.5: a stale-cycle hero is NOT combinable. Retaining it would
-    # let a sum over stale evidence be published while `compose_all_state` marks
-    # the result fresh — and the All hero carries no Snapshot row or staleness
-    # marker at all, so the staleness would be silently undisclosed. The
-    # combined NUMBER therefore behaves exactly as it does today.
-    if _stale_cycle_providers(claude, codex):
-        return None
+    # #359: the hero counters are backward-looking accounting actuals. A stale
+    # but still-live quota boundary pauses projections; it does not invalidate
+    # the retained cost/token sums that each provider already keeps visible.
+    # Composition therefore retains the compatible number and discloses the
+    # stale boundary through All's hero-domain freshness + local warning.
     for state in (claude, codex):
         hero_capability = state.capabilities.get("hero")
         if hero_capability is None or hero_capability.status not in {"supported", "derived"}:
@@ -462,33 +463,33 @@ def compose_all_state(
         raise ValueError("all composition requires Claude and Codex provider states")
     combined = _combined_metrics(claude, codex)
     providers_coherent = _coherent_provider(claude) and _coherent_provider(codex)
-    # #350 spec §3.5: "All behaves exactly as today" is true only of the combined
-    # NUMBER. Under §3.4 both providers stay coherent, so All now publishes
-    # partial/fresh with no provider warning to explain it — the status chip
-    # would fall through to a generic `degraded` and the All hero fallback would
-    # claim a provider is degraded while both provider envelopes say otherwise.
-    # This All-LOCAL warning states the real reason without touching either
-    # provider envelope. It is emitted only when the providers are otherwise
-    # coherent; an incoherent provider already publishes its own reason.
+    stale_cycle_providers = (
+        _stale_cycle_providers(claude, codex) if providers_coherent else ()
+    )
+    # #359: the warning qualifies a retained combined actual. It stays
+    # All-local and keeps the composed source partial so the header status also
+    # names the caveat; provider envelopes remain independently coherent.
     all_local_warnings: tuple[SourceDashboardWarning, ...] = ()
+    if stale_cycle_providers:
+        all_local_warnings = (SourceDashboardWarning(
+            "combined_totals_stale",
+            f"{' and '.join(stale_cycle_providers)} quota evidence is stale; "
+            "combined totals use retained actuals.",
+            "hero",
+        ),)
     if providers_coherent:
-        stale_cycle_providers = _stale_cycle_providers(claude, codex)
         if stale_cycle_providers:
-            all_local_warnings = (SourceDashboardWarning(
-                "combined_totals_withheld",
-                f"{' and '.join(stale_cycle_providers)} quota evidence is stale, "
-                "so combined totals are withheld.",
-                "hero",
-            ),)
-        availability: Availability = (
-            "partial"
-            if combined is None or "partial" in (claude.availability, codex.availability)
-            else (
-                "empty"
-                if claude.availability == "empty" and codex.availability == "empty"
-                else "ok"
+            availability: Availability = "partial"
+        else:
+            availability = (
+                "partial"
+                if combined is None or "partial" in (claude.availability, codex.availability)
+                else (
+                    "empty"
+                    if claude.availability == "empty" and codex.availability == "empty"
+                    else "ok"
+                )
             )
-        )
         freshness: Freshness = "fresh"
     else:
         availability = "partial"
@@ -519,7 +520,7 @@ def compose_all_state(
         # All-LOCAL warnings lead: `warningForSource` on the client falls back to
         # the FIRST warning, so a merely-partial provider warning (e.g.
         # `codex_metadata_incomplete`) would otherwise pre-empt the chip label
-        # and hide the real reason combined totals are withheld.
+        # and hide the stale qualification on the combined actual.
         warnings=tuple((*all_local_warnings, *claude.warnings, *codex.warnings)),
         data_version=data_version,
         last_success_at=last_success_at,

package/bin/_lib_doctor.py

@@ -210,6 +210,11 @@ class DoctorState:
     # walk, so `files_failed`/`files_deferred_torn` are both zero, no `blocked`
     # record is ever written, and the ingest-backlog leg reads a drained store.
     codex_replay_deferred: Optional[dict] = None
+    # #485: privacy-safe durable records written when cache.db and/or
+    # conversations.db refused to treat an invalid Codex root as deletion
+    # evidence. None is the normal state; each record contains counts/reasons
+    # but never configured paths or provider identifiers.
+    codex_prune_refusals: Optional[list[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
@@ -1236,6 +1241,64 @@ def _check_data_codex_replay(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_data_codex_prune_safety(s: DoctorState) -> CheckResult:
+    """Surface a fail-closed orphan-prune decision instead of silent loss."""
+    records = [
+        record for record in (s.codex_prune_refusals or [])
+        if isinstance(record, dict)
+    ]
+    if not records:
+        return CheckResult(
+            id="data.codex_prune_safety",
+            title="Codex orphan pruning",
+            severity="ok",
+            summary="no refused prune",
+            remediation=None,
+            details={"refusalCount": 0, "stores": []},
+        )
+    stores = sorted({
+        str(record.get("store"))
+        for record in records
+        if record.get("store") in {"cache", "conversations"}
+    })
+    preserved_files = max(
+        (int(record.get("preservedFileCount") or 0) for record in records),
+        default=0,
+    )
+    since_values = sorted({
+        str(record["since"])
+        for record in records
+        if isinstance(record.get("since"), str) and record["since"]
+    })
+    reasons = sorted({
+        str(reason)
+        for record in records
+        for reason in (
+            record.get("reasons") if isinstance(record.get("reasons"), list) else []
+        )
+        if isinstance(reason, str)
+    })
+    return CheckResult(
+        id="data.codex_prune_safety",
+        title="Codex orphan pruning",
+        severity="warn",
+        summary=(
+            f"refused unsafe prune; preserved {preserved_files} tracked file(s)"
+        ),
+        remediation=(
+            "Check that every $CODEX_HOME root is mounted and contains Codex "
+            "rollout JSONL, then run `cctally cache-sync --source codex`"
+        ),
+        details={
+            "refusalCount": len(records),
+            "stores": stores,
+            "since": since_values[0] if since_values else None,
+            "reasons": reasons,
+            "preservedFileCount": preserved_files,
+        },
+    )
+
+
 def _check_data_codex_quota_verification(s: DoctorState) -> CheckResult:
     """WARN when the detached Codex quota verification is not landing.
 
@@ -2935,6 +2998,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         # 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_prune_safety", "_check_data_codex_prune_safety"),
         ("data.codex_replay", "_check_data_codex_replay"),
         ("data.codex_ingest_backlog", "_check_data_codex_ingest_backlog"),
         ("data.codex_quota", "_check_data_codex_quota"),

package/bin/_lib_quota_alert_axes.py

@@ -23,9 +23,10 @@ in ``quota_window_snapshots`` moving at all:
    and becomes eligible when wall time passes it with no mutation to observe.
    Persisting that boundary and treating ``now >= boundary`` as dirty is what
    closes it. Unlike axes 2 and 3 this one fires on WALL CLOCK rather than on a
-   configuration change, which is why the hook path defers it
-   (``defer_scheduled``) instead of paying an unannounced whole-history pass on
-   a blocking tick.
+   configuration change. An ownership schedule lets the hook evaluate only the
+   complete roots whose deadlines matured; scalar-only legacy state still
+   defers rather than paying an unannounced whole-history pass on a blocking
+   tick.
 5. **Durable lifecycle state** — the existing arming rows and terminal events,
    unchanged. Represented here only as the fingerprints axis 2 compares.
 
@@ -80,6 +81,7 @@ def alert_dirty_scope(
     gate_after: bool,
     now: dt.datetime,
     next_evaluation_at: "dt.datetime | None",
+    scheduled_roots: "Iterable[str] | None" = None,
     defer_scheduled: bool = False,
 ) -> AlertDirtyScope:
     """Resolve the five axes into one decision.
@@ -89,14 +91,11 @@ def alert_dirty_scope(
     observed_slot, window_minutes)``; the ROOT is element 1, which is what an
     exact-rule change is scoped to.
 
-    ``defer_scheduled`` is the hook path's (``full_pass="defer"``). Axes 2 and 3
-    are driven by a configuration change the user just made, so widening for
-    them is bounded and expected; axis 4 is driven by WALL CLOCK, which makes it
-    the one route into a whole-history pass that can land on a blocking hook
-    tick with nothing to have predicted it. Under this flag it is recorded as
-    ``REASON_SCHEDULED_DEFERRED`` and does NOT strengthen the scope — and the
-    caller owes the stored boundary a carry-through, because a deferral that
-    lets the boundary be recomputed is a silent drop.
+    ``scheduled_roots`` is the validated ownership retained with axis 4. When
+    present, a matured instant scopes to those roots even on the hook path.
+    ``None`` is the legacy/unavailable-ownership shape; only that shape needs
+    ``defer_scheduled`` to avoid an unannounced whole-history hook pass, and the
+    caller then owes the scalar boundary a carry-through.
     """
     reasons: list[str] = []
     if not gate_after:
@@ -132,11 +131,19 @@ def alert_dirty_scope(
         reasons.append("rule_changed")
 
     if next_evaluation_at is not None and now >= next_evaluation_at:
-        # A future-clocked observation just became eligible. Which identity it
-        # belongs to is not recorded — only the instant — so the honest scope is
-        # everything, and on the hook path "everything" is precisely what may
-        # not run.
-        if defer_scheduled:
+        # Epoch 1007 records the roots owning each scheduled instant. A complete
+        # semantic pass over those roots is bounded enough for the hook path and
+        # is all axis 4 needs. ``None`` means legacy/unavailable ownership, where
+        # the only honest scope remains everything (and therefore deferral on a
+        # hook tick). An empty known set means the owning roots are not lifecycle
+        # eligible on this tick; the stored axis remains due for a later tick.
+        if scheduled_roots is not None:
+            due_roots = {str(root) for root in scheduled_roots if str(root)}
+            if due_roots:
+                scope = _strongest(scope, SCOPE_ROOTS)
+                roots |= due_roots
+                reasons.append("scheduled")
+        elif defer_scheduled:
             reasons.append(REASON_SCHEDULED_DEFERRED)
         else:
             scope = _strongest(scope, SCOPE_ALL)
@@ -154,12 +161,12 @@ def next_evaluation_boundary(
 ) -> "dt.datetime | None":
     """The earliest still-future capture the projector must come back for.
 
-    A bounded pass only sees the dirty windows, so the STORED boundary is
+    This is the legacy scalar helper. A bounded pass only sees dirty windows, so
+    the STORED boundary is
     retained whenever it is still in the future: dropping it would forget a
     future-clocked observation sitting in a window this pass never loaded. Once
-    wall time passes it the axis fires, the pass widens to everything, and the
-    boundary is recomputed from complete evidence — so a retained value can only
-    ever cost one extra pass, never a missed one.
+    wall time passes it the axis fires and the caller decides whether it has
+    enough ownership to scope the pass.
 
     ``retain_due`` keeps a boundary that is ALREADY due, which is the case where
     "recomputed from complete evidence" is a lie: a reporting-only pass never
@@ -167,20 +174,10 @@ def next_evaluation_boundary(
     the widening deliberately did not look. Either would otherwise retire the
     axis on behalf of an evaluation nobody performed.
 
-    A due value sorts before every future candidate, so it stays until a pass
-    that genuinely looked at everything retires it — in practice a hook tick
-    that widened to whole-history for axis 2 or 3, since carrying alert
-    eligibility is what separates such a pass from a reporting-only one and the
-    hook is the only production caller that carries it.
-
-    It does NOT stay "until a pass that can act on it does", and that gap is
-    open rather than closed: on a hook-only install with a steady enabled gate,
-    unchanged rules and a quiet ledger, no qualifying pass ever runs and the
-    instant is retained indefinitely. The cost is bounded — the tick stays
-    bounded and fast, and the window is re-evaluated as soon as it goes
-    ledger-dirty again, which for a live window is continuous — so the exposure
-    is a future-clocked capture in a window that then goes permanently quiet
-    never qualifying a threshold. Under-alerting, never a stall or a burst.
+    Epoch 1007's per-root map is maintained by the projector rather than this
+    helper. It closes the quiet-window gap by letting a hook tick replace only
+    the roots it evaluated; scalar-only legacy state still uses ``retain_due``
+    and the conservative full/deferred path.
     """
     candidates = [value for value in capture_times if value > now]
     if stored is not None and (retain_due or stored > now):