feat(compaction): park cuts post-turn, apply in place when the re-write is free (PR-3)

[philmerrell]

Stacked on #1128 (PR-2), which is stacked on #1125 (PR-1). Merge in order; this PR's diff is the one commit on top.

Why

PR-1 decides what to cut and PR-2 bounds the summary, but a cut still landed at the next restore whether or not the prompt-cache prefix was warm, and never landed at all on a warm (cached) agent. Under Bedrock caching a cut costs one re-write of whatever survives, so the cheapest turn to pay it on is one that was going to re-write anyway. The 2026-09-15 replay of 20 heavy Sonnet 5 sessions applied exactly this rule (cut only when cold or at the hard ceiling) to get the $102.64 → $73.70 input-side result recorded in the spec. Thresholds spec §3.5.

What

• Post-turn parks, never applies. update_after_turn stores the cut and its bounded summary as pendingCheckpoint / pendingSummary / pendingHardCeiling / pendingSince. checkpoint stays the applied value (what the restore slices at). A second over-ceiling turn while a cut is parked is a no-op; it never cuts deeper.
• Head of turn decides. The stream coordinator calls apply_pending_compaction(agent, prefix_key="<model>|<agent>") before the first model call of every turn, on cached and freshly restored agents alike. It applies when, in order: cache_expired (more than cache_ttl_seconds since the previous turn — the entry is gone and the next call re-writes regardless), prefix_changed (the model|agent key differs from the persisted one — the cached prefix is already invalid), or hard_ceiling (the previous turn's input reached the hard ceiling the cut was computed under). Otherwise it waits.
• Applied in place. messages[:] = [first_with_summary] + messages[k+1:] with k = pendingCheckpoint − _live_offset; then the state is promoted and persisted. The result is byte-identical to what _apply_compaction derives from stored history under the promoted state (pinned by a parity test), so a cold restore after a live apply reads the same prefix.
• Aliasing carries the offset. _adopt_session_conversation copies _live_offset when it points a new agent at the live list.
• Measured. Each application persists the reason, cacheGapSeconds and pendingSince on compaction.policy, logs rewrite_scheduled vs rewrite_forced, and emits CompactionApplied / CompactionAppliedForced / CompactionCacheGapSeconds; the cut record gains CompactionDeferred.
• Kill switch AGENTCORE_MEMORY_COMPACTION_DEFERRED_APPLY_ENABLED=false applies immediately (PR-1/2 behavior). Legacy mode is always immediate.

Behavior to know about

Between the ceiling and the hard ceiling, a session on a warm cache keeps its current prefix until a pause longer than the cache TTL, a model or agent switch, or the hard ceiling. That is the trade the replay priced: a few turns of larger cache reads (0.1×) instead of an extra prefix re-write (1.25×) on a warm turn.

Not in this PR

context_window_limit on the Strands model config (needs the window at agent construction). Offload escalation when the protected tail alone exceeds the floor (PR-4). Selective 1h TTL experiment (PR-5).

Tests

Parking, no-deeper-cut, kill switch and legacy; warm/same-prefix waits; cache-expired, prefix-changed and hard-ceiling apply; first-ever key is not a change; live apply equals cold restore; pending beyond the live list is dropped; re-arm and cut again after apply; metrics carry the reason; state round-trip; offset sync on alias. The shared fixture pins existing suites to the immediate path explicitly. Full backend suite: 8659 passed, 3 skipped.

🤖 Generated with Claude Code