fix(compaction): render APPROX_ATTRIBUTION kept_tail/pre ratio truthfully (>100% basis artifact)

agent/conversation_compression.py

@@ -89,6 +89,26 @@
 _APPROX_GROSS_MAX_FRAC = 0.10
 
 
+def _fmt_gross_frac(gross_tok: int, pre_tok: int) -> str:
+    """Render the raw-kept-tail-vs-pre ratio TRUTHFULLY for the observability marker.
+
+    ``gross_tok`` (``raw_tail_tokens``) is a documented UPPER BOUND on the kept-tail
+    magnitude, estimated on the RAW (pre-sanitize) suffix; ``pre_tok`` is the
+    pre-compaction total counted on the SANITIZED/in-context basis. The two are on
+    DIFFERENT bases, so the raw bound can legitimately exceed ``pre`` — printing a bare
+    ``101.3%`` reads as an impossible "kept more than existed". Cap the displayed
+    fraction at 100% and mark it as a bound (``≥100%``) with a basis note when it
+    exceeds pre, so the marker is honest; the underlying comparison still uses the raw
+    ratio (a bound over threshold correctly triggers the two-line degrade)."""
+    if pre_tok <= 0:
+        return "n/a (pre=0)"
+    frac = gross_tok / pre_tok
+    if frac > 1.0:
+        # raw upper-bound exceeds the sanitized pre-total: bases differ, not a real >100%
+        return f"≥100% (raw-tail bound {gross_tok} ≥ pre {pre_tok}; raw vs sanitized basis)"
+    return f"{frac:.1%}"
+
+
 def _warn_compaction_stats_once(agent, message: str, *, exc_info: bool = False) -> None:
     """Emit a compaction-stats degrade ``warning`` at most once per (cause, session).
 
@@ -1515,7 +1535,8 @@ def _release_lock() -> None:
                                 agent,
                                 f"COMPACTION_STATS_APPROX_ATTRIBUTION in-turn "
                                 f"degraded (kept_tail {_gross_tok} / pre {_pre_tok} "
-                                f"= {_gross_frac:.1%} > {_APPROX_GROSS_MAX_FRAC:.0%}); two-line",
+                                f"= {_fmt_gross_frac(_gross_tok, _pre_tok)} "
+                                f"> {_APPROX_GROSS_MAX_FRAC:.0%}); two-line",
                             )
                             _inturn_stats = None
                         else:
@@ -1527,7 +1548,7 @@ def _release_lock() -> None:
                                 agent,
                                 f"COMPACTION_STATS_APPROX_ATTRIBUTION in-turn "
                                 f"(engine={_engine_name}; kept_tail {_gross_tok} / "
-                                f"pre {_pre_tok} = {_gross_frac:.1%})",
+                                f"pre {_pre_tok} = {_fmt_gross_frac(_gross_tok, _pre_tok)})",
                             )
                     else:
                         _inturn_stats = _cand

tests/agent/test_compaction_stats_degrade_observability.py

@@ -71,3 +71,34 @@ class _Frozen:
     with caplog.at_level(logging.WARNING):
         _warn_compaction_stats_once(_Frozen(), "COMPACTION_STATS_BUILD_FAILED in-turn")
     assert any("BUILD_FAILED" in r.message for r in caplog.records)
+
+
+# ── Truthful basis rendering for the APPROX_ATTRIBUTION marker (2026-07-01) ──
+# raw_tail_tokens is a documented UPPER BOUND estimated on the RAW (pre-sanitize)
+# suffix; pre_tokens is the sanitized/in-context total. The two are on different
+# bases, so the raw bound can exceed pre — a bare "101.3%" reads as an impossible
+# "kept more than existed". The marker must render that case as a bounded ≥100% with
+# a basis note, never a misleading >100% percentage.
+
+def test_gross_frac_over_100_renders_as_bounded_not_misleading():
+    from agent.conversation_compression import _fmt_gross_frac
+
+    # the REAL captured live case that produced the confusing "101.3%" (#logs 2026-07-01)
+    out = _fmt_gross_frac(75378, 74447)
+    assert "≥100%" in out, f"raw-bound>pre must render ≥100%, got {out!r}"
+    assert "101.3%" not in out and "101%" not in out, f"must not show misleading >100%, got {out!r}"
+    assert "basis" in out, f"must note the raw-vs-sanitized basis mismatch, got {out!r}"
+
+
+def test_gross_frac_within_bound_renders_plain_percent():
+    from agent.conversation_compression import _fmt_gross_frac
+
+    assert _fmt_gross_frac(7000, 100000) == "7.0%"
+    assert _fmt_gross_frac(100, 100) == "100.0%"   # exactly-at-pre is a real 100%, not a bound
+
+
+def test_gross_frac_pre_zero_is_safe():
+    from agent.conversation_compression import _fmt_gross_frac
+
+    out = _fmt_gross_frac(5, 0)
+    assert "n/a" in out and "%" not in out.replace("n/a", "")  # no divide-by-zero, no bogus percent