Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(cache): keep cached-prefix replay after background recompression (#3380)

gglucassaebe98954ee3
diff --git a/headroom/cache/prefix_tracker.py b/headroom/cache/prefix_tracker.py
index ea47417e3..c9907bb4c 100644
--- a/headroom/cache/prefix_tracker.py
+++ b/headroom/cache/prefix_tracker.py
@@ -448,6 +448,8 @@ def overlay_cached_prefix(
current_original_messages: list[dict[str, Any]],
previous_original_messages: list[dict[str, Any]] | None,
previous_forwarded_messages: list[dict[str, Any]] | None,
+ *,
+ confirmed_frozen_count: int | None = None,
) -> list[dict[str, Any]]:
"""Replay a positional, non-inflating cached prefix when it is safe.
@@ -471,6 +473,20 @@ def overlay_cached_prefix(
compact UTF-8 JSON for the replayed result must not exceed the optimized
candidate. These bounds prefer a cache miss to corrupting or inflating a
client's live history.
+
+ ``confirmed_frozen_count`` bounds UNCONDITIONAL replay. Leading positions
+ the provider has already confirmed cached (a message count derived from
+ ``cache_read_input_tokens``) are always replayed byte-identical: the
+ replay source there is exactly what the provider hashed, so changing
+ those bytes can only bust the cache. Beyond the floor the size bound
+ still arbitrates each turn: a shrinking replay (the pipeline emitted
+ original bytes for a frozen message) is repaired, while an inflating one
+ (fresh compression improved on the forwarded form) is declined so the
+ improvement reaches the wire. When the provider count collapses (cold
+ cache, TTL lapse) the floor collapses with it and every accumulated
+ improvement lands at once - the natural re-baselining that keeps
+ long-session growth bounded (#3026). Callers with no provider-confirmed
+ count pass None and keep the fully size-bounded behavior.
"""
prev_orig = previous_original_messages
prev_fwd = previous_forwarded_messages
@@ -548,15 +564,16 @@ def overlay_cached_prefix(
+ [merged]
+ list(optimized_messages[message_index + 1 :])
)
- replayed_bytes = _compact_json_bytes(replayed)
- optimized_bytes = _compact_json_bytes(optimized_messages)
- if (
- replayed_bytes is None
- or optimized_bytes is None
- or len(replayed_bytes) > len(optimized_bytes)
- ):
- logger.debug("overlay: block replay inflated compact JSON — skipping")
- return optimized_messages
+ if message_index >= max(confirmed_frozen_count or 0, 0):
+ replayed_bytes = _compact_json_bytes(replayed)
+ optimized_bytes = _compact_json_bytes(optimized_messages)
+ if (
+ replayed_bytes is None
+ or optimized_bytes is None
+ or len(replayed_bytes) > len(optimized_bytes)
+ ):
+ logger.debug("overlay: block replay inflated compact JSON — skipping")
+ return optimized_messages
return replayed
# Append-only guard on CONTENT ONLY, message-by-message. Replay the
# previously-forwarded (cached, compressed) bytes for the longest LEADING
@@ -611,8 +628,24 @@ def overlay_cached_prefix(
or optimized_bytes is None
or len(replayed_bytes) > len(optimized_bytes)
):
- logger.debug("overlay: replay inflated compact JSON — skipping cached-prefix replay")
- return optimized_messages
+ # Something in the replay is byte-larger than this turn's fresh form:
+ # fresh compression improved on already-forwarded bytes. Landing the
+ # improvement is only safe OUTSIDE the provider-confirmed prefix -
+ # inside it, the improvement would change bytes the provider has
+ # already cached and bust the whole suffix. Split at the confirmed
+ # floor: replay the confirmed region unconditionally, forward
+ # everything beyond it fresh so the improvement reaches the wire.
+ floor = min(k, max(confirmed_frozen_count or 0, 0))
+ if floor <= 0:
+ logger.debug("overlay: replay inflated compact JSON — skipping cached-prefix replay")
+ return optimized_messages
+ logger.debug(
+ "overlay: replay inflated beyond the confirmed floor — replaying %d/%d "
+ "confirmed messages, forwarding the rest fresh",
+ floor,
+ k,
+ )
+ return list(prev_fwd[:floor]) + list(optimized_messages[floor:])
return replayed
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 6fdeb3ed8..0b3cbb190 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -1691,6 +1691,14 @@ class AnthropicHandlerMixin:
compressor.close()
_compression_failed = False
+ # Provider-confirmed frozen count, stashed BEFORE prepare_turn
+ # clamps it against the local byte-replay cache: the overlay's
+ # unconditional-replay floor must cover everything the provider
+ # has cached, not just what local state can byte-replay (the
+ # replay source is the positional prev_fwd snapshot, which does
+ # not depend on the CompressionCache). Stays 0 on paths that
+ # never compute a tracker count (backpressure, cache mode).
+ _confirmed_frozen = 0
original_messages = messages # Preserve for 400-retry fallback
_decision = CompressionDecision.decide(
headers=request.headers,
@@ -1766,6 +1774,7 @@ class AnthropicHandlerMixin:
prepare_turn,
)
+ _confirmed_frozen = max(int(frozen_message_count or 0), 0)
_prep = prepare_turn(
comp_cache,
messages,
@@ -2150,6 +2159,17 @@ class AnthropicHandlerMixin:
previous_original_messages,
previous_forwarded_messages,
count_tokens=tokenizer.count_messages,
+ # The provider-confirmed prefix is replayed
+ # unconditionally: those bytes are exactly what the
+ # provider cached, so declining a byte-larger replay
+ # there re-forwards freshly recompressed history at
+ # the full input rate and busts the cache every time
+ # background compression improves on an
+ # already-forwarded message. Beyond the confirmed
+ # floor the size bound still lets improvements
+ # through, and a collapsed floor (cold cache) lets
+ # every accumulated improvement land at once.
+ confirmed_frozen_count=_confirmed_frozen,
)
_overlay_replayed = _final.replayed
if _overlay_replayed:
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 740f3e47c..e7eeba01e 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -3738,6 +3738,18 @@ class OpenAIHandlerMixin:
)
openai_frozen_count = 0
+ # Provider-confirmed floor for the cross-turn overlay at the end of this
+ # function. This is the count derived from OpenAI's own
+ # `prompt_tokens_details.cached_tokens` (via the shared tracker),
+ # snapshotted HERE rather than read at the call site: the token path's
+ # `prepare_turn` below runs FREEZE_POLICY_REPLAYABLE, whose count is
+ # `max(cache_count, explicit)` over the LOCAL byte-replay cache and can
+ # therefore exceed what the provider actually confirmed. Replaying past
+ # the confirmed point unconditionally would pin content the provider
+ # never cached. A cold prefix zeroes this above, which collapses the
+ # floor and lets every accumulated improvement land - same as Anthropic.
+ _openai_confirmed_frozen = max(int(openai_frozen_count or 0), 0)
+
_compression_failed = False
original_messages = messages # Preserve for 400-retry fallback
# Cross-turn dedup rewrites repeated tool-output spans to bare
@@ -3918,6 +3930,18 @@ class OpenAIHandlerMixin:
openai_prefix_tracker.get_last_original_messages(),
openai_prefix_tracker.get_last_forwarded_messages(),
count_tokens=tokenizer.count_messages,
+ # Same reasoning as the Anthropic call site: inside the
+ # provider-confirmed prefix the replay source IS what OpenAI
+ # hashed, so declining a byte-larger replay there re-forwards
+ # recompressed history and busts the prompt cache from the first
+ # changed byte. Beyond the floor the size bound still arbitrates.
+ # Exposure here is narrower than Anthropic's - the token path's
+ # REPLAYABLE freeze already stops most recompression of
+ # already-forwarded messages - but it is not zero: an entry
+ # evicted from the local byte-replay cache falls out of that
+ # freeze and can be recompressed, and cache mode freezes from the
+ # tracker only.
+ confirmed_frozen_count=_openai_confirmed_frozen,
)
if _final.replayed:
optimized_messages = _final.messages
diff --git a/headroom/proxy/session_engine.py b/headroom/proxy/session_engine.py
index 4864ae08a..9aac7f844 100644
--- a/headroom/proxy/session_engine.py
+++ b/headroom/proxy/session_engine.py
@@ -152,6 +152,7 @@ def finalize_turn(
prev_returned: list[dict[str, Any]] | None,
*,
count_tokens: Callable[[list[dict[str, Any]]], int] | None = None,
+ confirmed_frozen_count: int | None = None,
) -> TurnFinal:
"""Replay last turn's exact forwarded/returned prefix over pipeline drift.
@@ -159,11 +160,25 @@ def finalize_turn(
shape, non-inflation), so calling this is always safe: when replay is not
provably correct it returns the pipeline's own output unchanged.
+ ``confirmed_frozen_count`` is forwarded to ``overlay_cached_prefix`` as
+ the unconditional-replay floor: positions the provider has confirmed
+ cached are always replayed byte-identical, while beyond the floor the
+ size bound decides between drift repair (a shrinking replay) and letting
+ a fresh improvement through (an inflating one). Callers with no
+ provider-confirmed count pass None and keep the fully size-bounded
+ behavior.
+
``count_tokens`` is invoked only when the overlay actually replaced
bytes — the pipeline's own token count is still accurate otherwise. A
failing hook falls back to "no recount" rather than failing the turn.
"""
- final = overlay_cached_prefix(result_messages, original_messages, prev_original, prev_returned)
+ final = overlay_cached_prefix(
+ result_messages,
+ original_messages,
+ prev_original,
+ prev_returned,
+ confirmed_frozen_count=confirmed_frozen_count,
+ )
replayed = final != result_messages
tokens: int | None = None
if replayed and count_tokens is not None:
diff --git a/tests/test_cache_prefix_overlay.py b/tests/test_cache_prefix_overlay.py
index 45791ec1d..e65ca0798 100644
--- a/tests/test_cache_prefix_overlay.py
+++ b/tests/test_cache_prefix_overlay.py
@@ -145,6 +145,91 @@ def test_block_append_overlay_never_inflates_forwarded_payload():
assert overlay_cached_prefix(optimized, current, previous, forwarded) == optimized
+def test_confirmed_floor_replays_recompressed_confirmed_prefix():
+ # Background recompression produced a SMALLER form of already-forwarded,
+ # provider-CONFIRMED history. The floor replays the confirmed bytes
+ # unconditionally; without a floor the size bound declines the replay and
+ # the cache busts the moment compression improves.
+ recompressed = [
+ M("user", "READ foo.py:\n<tiny>"),
+ M("assistant", "ok"),
+ M("user", "grep result:\n<compressed>"),
+ ]
+ out = overlay_cached_prefix(
+ recompressed, CUR_ORIG, PREV_ORIG, PREV_FWD, confirmed_frozen_count=2
+ )
+ assert out[:2] == PREV_FWD # confirmed bytes win over the smaller fresh form
+ assert out[2] == recompressed[2] # this turn's tail is preserved
+ # No floor: the same replay is declined as inflating (sidecar posture).
+ assert overlay_cached_prefix(recompressed, CUR_ORIG, PREV_ORIG, PREV_FWD) == recompressed
+
+
+def test_confirmed_floor_keeps_alignment_guards():
+ # The floor relaxes ONLY the size bound; every alignment guard still bails.
+ changed = [M("user", "TOTALLY DIFFERENT"), PREV_ORIG[1], M("user", "x")]
+ assert (
+ overlay_cached_prefix(
+ OPTIMIZED_BUGGY, changed, PREV_ORIG, PREV_FWD, confirmed_frozen_count=2
+ )
+ == OPTIMIZED_BUGGY
+ )
+ assert (
+ overlay_cached_prefix(
+ OPTIMIZED_BUGGY, CUR_ORIG, PREV_ORIG, PREV_FWD[:1], confirmed_frozen_count=2
+ )
+ == OPTIMIZED_BUGGY
+ )
+
+
+def test_improvement_beyond_floor_lands_while_confirmed_region_replays():
+ # Three previously-forwarded messages; only the first is provider-confirmed.
+ prev_orig = [
+ M("user", "old tool output " * 20),
+ M("user", "newer output"),
+ M("assistant", "ok"),
+ ]
+ prev_fwd = [M("user", "[fwd-old-form-larger]"), M("user", "[fwd-newer]"), M("assistant", "ok")]
+ current = prev_orig + [M("user", "next")]
+ # Fresh compression improved BOTH forwarded forms. Only the beyond-floor
+ # improvement may land; the confirmed one would change provider bytes.
+ optimized = [
+ M("user", "[t0]"),
+ M("user", "[t1]"),
+ M("assistant", "ok"),
+ M("user", "next"),
+ ]
+ out = overlay_cached_prefix(optimized, current, prev_orig, prev_fwd, confirmed_frozen_count=1)
+ assert out[0] == prev_fwd[0] # confirmed region: replayed unconditionally
+ assert out[1] == optimized[1] # improvement beyond the floor reaches the wire
+ assert out[3] == optimized[3]
+
+
+def test_originals_drift_beyond_floor_still_repaired_when_replay_shrinks():
+ # The pipeline emitted the agent's ORIGINAL bytes beyond the floor (the
+ # #1850 freeze-drift case). The replay shrinks, the size bound passes, and
+ # the repair still covers the WHOLE prefix - the floor only decides the
+ # split when the bound would otherwise decline.
+ out = overlay_cached_prefix(
+ OPTIMIZED_BUGGY, CUR_ORIG, PREV_ORIG, PREV_FWD, confirmed_frozen_count=1
+ )
+ assert out[:2] == PREV_FWD
+
+
+def test_block_append_within_confirmed_floor_replays_forwarded_blocks():
+ previous = [{"role": "user", "content": [{"type": "text", "text": "stable"}]}]
+ forwarded = [{"role": "user", "content": [{"type": "text", "text": "x" * 500}]}]
+ current = [
+ {
+ "role": "user",
+ "content": [{"type": "text", "text": "stable"}, {"type": "text", "text": "new"}],
+ }
+ ]
+ optimized = copy.deepcopy(current)
+ out = overlay_cached_prefix(optimized, current, previous, forwarded, confirmed_frozen_count=1)
+ assert out[0]["content"][0]["text"] == "x" * 500
+ assert out[0]["content"][1]["text"] == "new"
+
+
def test_cache_hit_property_prefix_matches_last_forward():
# The invariant that guarantees a cache hit: forwarded[:n] this turn ==
# forwarded[:n] last turn (== what the provider cached).
diff --git a/tests/test_cross_turn_cache_safety.py b/tests/test_cross_turn_cache_safety.py
index 1f039af0c..60c8fe8f0 100644
--- a/tests/test_cross_turn_cache_safety.py
+++ b/tests/test_cross_turn_cache_safety.py
@@ -138,3 +138,145 @@ def test_cache_create_stays_bounded_to_the_delta_with_overlay():
# with conversation length. Assert the last turn creates no more than the
# first (which had no cache to reuse).
assert creates[-1] <= creates[0] + 1
+
+
+def test_background_improvement_never_busts_warm_cache_and_lands_on_cold():
+ """The #3379 regression and its fix, end to end: a background improvement
+ to an already-forwarded message must NOT change warm-cache bytes (the
+ confirmed floor overrides it), and must land the moment the provider
+ count collapses (cold cache re-baseline) - so long-session growth is
+ bounded by the TTL-lapse cadence instead of unbounded pinning."""
+ tracker = PrefixCacheTracker("anthropic", PrefixFreezeConfig(min_cached_tokens=0))
+ convo: list[dict] = []
+ prev_forwarded: list[dict] | None = None
+ improved_from_turn = 4
+
+ def pipeline(original, frozen, turn):
+ out = _apply_freeze(original, frozen)
+ if turn >= improved_from_turn:
+ # Background compression later found a much better form for the
+ # very first message (this PR's stated trigger).
+ out = [{**out[0], "content": str(out[0]["content"])[:4]}] + out[1:]
+ return out
+
+ for t in range(1, 9):
+ convo = convo + [{"role": "user", "content": f"tool-output-turn-{t}:" + "X" * 400}]
+ frozen = tracker.get_frozen_message_count()
+ forwarded = overlay_cached_prefix(
+ pipeline(convo, frozen, t),
+ convo,
+ tracker.get_last_original_messages(),
+ tracker.get_last_forwarded_messages(),
+ confirmed_frozen_count=frozen,
+ )
+ expected = sum(_toklen(m) for m in prev_forwarded) if prev_forwarded else 0
+ actual = _provider_cache_read(forwarded, prev_forwarded)
+ assert actual >= expected, f"turn {t}: warm-cache bust ({actual} < {expected})"
+ counts = [_toklen(m) for m in forwarded]
+ tracker.update_from_response(
+ actual,
+ sum(counts) - actual,
+ forwarded,
+ message_token_counts=counts,
+ original_messages=convo,
+ )
+ prev_forwarded = forwarded
+
+ # Cold cache: the provider count collapses, the floor collapses with it,
+ # and the accumulated improvement finally reaches the wire.
+ convo = convo + [{"role": "user", "content": "tool-output-turn-9:" + "X" * 400}]
+ cold = overlay_cached_prefix(
+ pipeline(convo, 0, 9),
+ convo,
+ tracker.get_last_original_messages(),
+ tracker.get_last_forwarded_messages(),
+ confirmed_frozen_count=0,
+ )
+ assert len(str(cold[0]["content"])) < len(str(prev_forwarded[0]["content"])), (
+ "cold-cache turn must re-baseline: the background improvement lands"
+ )
+
+
+def test_prefix_growth_bounded_and_rebaselines_on_the_cold_turn():
+ """The pinned-prefix cost of the confirmed floor, measured.
+
+ While the cache stays warm the confirmed prefix is pinned to its
+ first-forwarded form, so later compression improvements to it do not land -
+ a real context-window cost, not just a cache benefit. This asserts the two
+ bounds that keep it from becoming #3026-style growth:
+
+ 1. Warm turns cannot compound: per-turn growth of the forwarded request is
+ exactly the new message, never the re-inflation of the pinned prefix.
+ 2. The first cold turn re-baselines to precisely what the fresh pipeline
+ would forward, so the pinned overhead is bounded by the TTL-lapse
+ cadence rather than accumulating for the life of the session.
+
+ Worst case for the floor: background compression keeps finding a better
+ form for EVERY message it has already seen, improving each turn.
+ """
+ tracker = PrefixCacheTracker("anthropic", PrefixFreezeConfig(min_cached_tokens=0))
+ convo: list[dict] = []
+ prev_forwarded: list[dict] | None = None
+
+ def pipeline(original, frozen, turn):
+ out = _apply_freeze(original, frozen)
+ # Later turns find better forms for everything already forwarded.
+ keep = max(4, 200 // turn)
+ return [{**m, "content": str(m["content"])[:keep]} for m in out[:-1]] + out[-1:]
+
+ warm_ratios = []
+ for t in range(1, 9):
+ convo = convo + [{"role": "user", "content": f"tool-output-turn-{t}:" + "X" * 400}]
+ frozen = tracker.get_frozen_message_count()
+ fresh = pipeline(convo, frozen, t)
+ forwarded = overlay_cached_prefix(
+ fresh,
+ convo,
+ tracker.get_last_original_messages(),
+ tracker.get_last_forwarded_messages(),
+ confirmed_frozen_count=frozen,
+ )
+ total = sum(_toklen(m) for m in forwarded)
+ ideal = sum(_toklen(m) for m in fresh)
+ if prev_forwarded is not None:
+ prev_total = sum(_toklen(m) for m in prev_forwarded)
+ assert total - prev_total <= _toklen(forwarded[-1]), (
+ f"turn {t}: forwarded grew by {total - prev_total} tokens, more than the "
+ f"{_toklen(forwarded[-1])}-token delta message - the prefix compounded"
+ )
+ warm_ratios.append(total / ideal)
+ actual = _provider_cache_read(forwarded, prev_forwarded)
+ counts = [_toklen(m) for m in forwarded]
+ tracker.update_from_response(
+ actual,
+ sum(counts) - actual,
+ forwarded,
+ message_token_counts=counts,
+ original_messages=convo,
+ )
+ prev_forwarded = forwarded
+
+ # Measured on this worst-case model, forwarded/fresh over turns 2-8:
+ # 1.35, 1.84, 2.33, 2.83, 3.35, 3.88, 4.35 - the pinned prefix does widen
+ # against an ideal pipeline while the cache stays warm (the cost the floor
+ # buys the cache hit with). What the two assertions bound is the shape:
+ # each warm turn adds only its own delta, and the cold turn below zeroes
+ # the gap outright.
+ # Cold turn: the provider count collapses, the floor collapses with it, and
+ # the forwarded request is exactly the fresh pipeline's output again.
+ convo = convo + [{"role": "user", "content": "tool-output-turn-9:" + "X" * 400}]
+ fresh_cold = pipeline(convo, 0, 9)
+ cold = overlay_cached_prefix(
+ fresh_cold,
+ convo,
+ tracker.get_last_original_messages(),
+ tracker.get_last_forwarded_messages(),
+ confirmed_frozen_count=0,
+ )
+ assert sum(_toklen(m) for m in cold) == sum(_toklen(m) for m in fresh_cold), (
+ "cold turn must re-baseline to the fresh pipeline's output"
+ )
+ assert warm_ratios[-1] > warm_ratios[0], (
+ "harness sanity: the warm-turn model must actually be improving the "
+ "prefix, otherwise the re-baseline assertion proves nothing"
+ )
diff --git a/tests/test_proxy_openai_cache_stability.py b/tests/test_proxy_openai_cache_stability.py
index 93e976619..86987e1bf 100644
--- a/tests/test_proxy_openai_cache_stability.py
+++ b/tests/test_proxy_openai_cache_stability.py
@@ -509,3 +509,58 @@ def test_openai_chat_completions_compacts_tools_when_profile_enabled() -> None:
assert "title" not in sent_params
assert "title" not in sent_params["properties"]["path"]
assert "examples" not in sent_params["properties"]["path"]
+
+
+def test_openai_handler_replays_the_provider_confirmed_prefix_even_when_it_inflates() -> None:
+ """#3379's twin on the OpenAI path: inside the provider-confirmed prefix the
+ replay source is exactly what OpenAI hashed, so a byte-larger replay must
+ still go out. Declining it forwards recompressed history and busts the
+ prompt cache from the first changed byte (gpt-5: $1.25/M vs $0.125/M
+ cached), which is strictly worse than replaying at the cache-read rate."""
+ captured = {}
+ # Same client original both turns, but last turn's forwarded form is LARGER
+ # than what the pipeline produces now -- i.e. the replay inflates and the
+ # size bound alone would decline it.
+ previous_original = [{"role": "user", "content": "original prefix"}]
+ previous_forwarded = [{"role": "user", "content": "previously forwarded " * 20}]
+ fake_tracker = _FakePrefixTracker(1, previous_original, previous_forwarded)
+ with _make_proxy_client() as client:
+ proxy = client.app.state.proxy
+ proxy.session_tracker_store.compute_session_id = lambda request, model, messages: (
+ "stable-session"
+ )
+ proxy.session_tracker_store.resolve_tracker = lambda *args, **kwargs: fake_tracker
+
+ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
+ captured["body"] = body
+ return httpx.Response(
+ 200,
+ json={
+ "id": "chatcmpl_confirmed_floor",
+ "choices": [
+ {
+ "index": 0,
+ "message": {"role": "assistant", "content": "ok"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {"prompt_tokens": 20, "completion_tokens": 3, "total_tokens": 23},
+ },
+ )
+
+ proxy._retry_request = _fake_retry
+ response = client.post(
+ "/v1/chat/completions",
+ headers={"authorization": "Bearer test-key"},
+ json={
+ "model": "gpt-4o-mini",
+ "messages": [
+ {"role": "user", "content": "original prefix"},
+ {"role": "user", "content": "new suffix"},
+ ],
+ },
+ )
+
+ assert response.status_code == 200
+ assert captured["body"]["messages"][0] == previous_forwarded[0]
+ assert captured["body"]["messages"][1] == {"role": "user", "content": "new suffix"}
diff --git a/tests/test_session_engine.py b/tests/test_session_engine.py
index a29ae4c10..148d789fe 100644
--- a/tests/test_session_engine.py
+++ b/tests/test_session_engine.py
@@ -182,6 +182,36 @@ def test_finalize_count_hook_failure_falls_back() -> None:
assert turn.tokens is None
+def test_finalize_declines_inflating_replay_by_default() -> None:
+ prev_original, prev_returned = _prev_pair()
+ current = prev_original + [{"role": "user", "content": "next"}]
+ # The pipeline recompressed message 0 SMALLER than the returned form.
+ recompressed = [
+ {"role": "user", "content": "[t]"},
+ {"role": "assistant", "content": "ok"},
+ {"role": "user", "content": "next"},
+ ]
+ turn = finalize_turn(recompressed, current, prev_original, prev_returned)
+ assert not turn.replayed
+ assert turn.messages == recompressed
+
+
+def test_finalize_confirmed_floor_replays_confirmed_bytes() -> None:
+ prev_original, prev_returned = _prev_pair()
+ current = prev_original + [{"role": "user", "content": "next"}]
+ recompressed = [
+ {"role": "user", "content": "[t]"},
+ {"role": "assistant", "content": "ok"},
+ {"role": "user", "content": "next"},
+ ]
+ turn = finalize_turn(
+ recompressed, current, prev_original, prev_returned, confirmed_frozen_count=2
+ )
+ assert turn.replayed
+ assert turn.messages[0]["content"] == "[returned-form]"
+ assert turn.messages[-1]["content"] == "next"
+
+
# --------------------------------------------------------------------------- #
# OpenAI proxy token-path migration: formula identity + marking benefit. #
# --------------------------------------------------------------------------- #