【中文】Compaction 中两处独立缓存失效（补丁 + 回归测试）— Two independent cache breaks in compaction on master @ 687f282e86: patch and regression specs

[Trove-design]

	中文摘要
🔍	问题：自动压缩时，摘要请求几乎完全不命中前缀缓存（KV Cache），在 master @ 687f282e86 上仍可复现。原因有两个，彼此独立：① 摘要请求没有继承请求头中的 reasoningEffort / temperature / stop；② 新发现：tool-result 修剪器在摘要之前改写了摘要请求要重放的历史，从第一个被改写的字节起全部重新计算。只修复 ① 解决不了 ②。
🔧	修复：仅在 provider / model 完全一致时继承这三个字段；需要摘要时，修剪器只处理保留的尾部，被摘要的区域保持逐字节不变。
📊	效果：真实 agent loop + 模拟前缀缓存：每次摘要的未缓存部分从约 2.2 万 / 8.4 万 / 33 万 token 降到约 470 token（32k / 128k / 512k 窗口），整个会话的未缓存 token 减少 34–41%。
✅	验证：新增及修改的回归测试在 master 上 6 个失败，打补丁后全部通过（见下方回答）；packages/compaction/ 共 236 个测试通过，tsc -b 与 oxlint 无报错。
📦	补丁：10 个文件，+630 / −29，可直接 git apply 到 687f282e86（即当前 master），见下方回答。

---

Important

TL;DR: The summary call misses the prefix cache for two independent reasons. Effort parity, as discussed in #1944 and #3002, fixes the first; the second survives it. The answer below has a patch that fixes both, with regression specs. Through the real agent loop on a simulated prefix cache, the uncached part of every summary call drops to the ~470-token instruction, at 32k, 128k and 512k windows alike (master: about 22k / 84k / 332k).

🔍 Two independent causes

	Cause	Where on master	Already reported in #1944 as
1	Envelope drift: the summary call drops reasoningEffort, temperature and stop from the routed header	summarizer.ts#L152-L162 vs. the loop's agent.ts#L695-L702	11.8% hit, cached part = static head (@deepseekv41flash); high vs none (@bulhenvaster)
2	New: the prune pass rewrites the region the summary call is about to replay	index.ts#L321-L326	"24% right after a history rewrite" (@codeOct); "~110K re-reads" (@bulhenvaster)

Both break a guarantee the package README states twice: the replayed prefix "match[es] the conversation's last routed request byte-for-byte" (README#L108, README#L233).

Cause 1: the request envelope

The loop builds every request by spreading the durable request header, ...header.config (agent.ts#L696). summarizeWithLlm reads the very same header (summarizer.ts#L127) but keeps only provider and model, so dsh-llm substitutes the adapter's default effort. The package's own doc names exactly these fields as cache-relevant (call-config.ts#L1-L7), and the DeepSeek adapter serializes effort as thinking plus output_config.effort (serialize.ts#L147-L157).

Field	Conversation request	Summary call on master	Summary call, patched
provider, model	from the header	from the header	from the header
reasoningEffort	from the header, e.g. max	missing, adapter default high	from the header, same route only
temperature, stop	from the header	missing	from the header, same route only
tools	from the header	from the header	from the header
maxTokens	from the header	policy cap	policy cap (reason in the answer below)

Cause 2: the prune pass rewrites the replayed region

The base bundle mounts the tool-result pruner by default (cordis.patch.yml#L425-L430, 8,192 chars). Once pressure qualifies, compactIfNeeded lands pruneSession() over the whole surface and only then builds the summary input, from the rewritten surface. Oversized tool results admitted since the last checkpoint are still verbatim in the cached prefix, so the first one rewritten becomes the first divergent byte. Effort parity cannot touch this.

How a prefix cache bills: a request is charged at the cache-hit price up to the first byte that differs from an earlier request, and at the full price from that byte on.

%%{init: {"flowchart": {"rankSpacing": 28, "nodeSpacing": 24, "padding": 8}}}%%
flowchart TB
  subgraph A ["① cached: last request"]
    direction LR
    a1["tools +<br/>system prompt"] --> a2["turns<br/>1 … k"] --> a3["tool result j<br/>original"] --> a4["turns<br/>j+1 … n"] ~~~ a5[" "]
  end
  subgraph B ["② master: summary call"]
    direction LR
    b1["tools +<br/>system prompt"] --> b2["turns<br/>1 … k"] --> b3["tool result j<br/>rewritten ✗"] --> b4["turns<br/>j+1 … n"] --> b5["summary<br/>instruction"]
  end
  subgraph C ["③ patched: summary call"]
    direction LR
    c1["tools +<br/>system prompt"] --> c2["turns<br/>1 … k"] --> c3["tool result j<br/>original ✓"] --> c4["turns<br/>j+1 … n"] --> c5["summary<br/>instruction"]
  end
  A ~~~ B ~~~ C
  classDef ref fill:#f6f8fa,stroke:#8c959f,color:#1f2328
  classDef hit fill:#dafbe1,stroke:#1a7f37,color:#0f3d1c
  classDef miss fill:#ffebe9,stroke:#cf222e,color:#6e0b12
  classDef fresh fill:#ddf4ff,stroke:#0969da,color:#0a3069
  classDef ghost fill:transparent,stroke:transparent,color:transparent
  class a1,a2,a3,a4 ref
  class b1,b2,c1,c2,c3,c4 hit
  class b3,b4 miss
  class b5,c5 fresh
  class a5 ghost
  style A fill:transparent,stroke:#8c959f
  style B fill:transparent,stroke:#8c959f
  style C fill:transparent,stroke:#8c959f

Loading

🟩 served from the cache · 🟥 computed again at full price · 🟦 new input, unavoidable · ⬜ what the cache already holds

In the 128k run measured in the answer below, with the effort already aligned, the red part of the first summary call was 73,241 of 83,945 tokens (87%). Patched, only the 469-token instruction is new.

Fix, measurements, verification and the full patch follow in the answer below.

[Trove-design]

Fix for both causes above, as a patch on master @ 687f282e86, with regression specs.

🔧 Fix

Envelope. inheritedCallControls() copies reasoningEffort, temperature and stop only on an exact provider/model match, so a stale header from a resumed session can never leak an effort into a different route (@ProdaZhang's freshness concern). The effort actually sent is now recorded on compaction/summary, which the event's own contract already asks for (types.ts#L43-L51).

Note

maxTokens is deliberately not inherited. The cap is an output budget, not prompt bytes: in @deepseekv41flash's corpus (#1944), the 7 folds whose effort matched hit 99.9% while the summarizer still sent its own cap. master now sizes that cap to the compaction headroom (65,536, config.ts#L75-L76); the 8,192-token truncations in #3002 predate this. Inheriting a routed cap of, say, 256k can push prompt + max_tokens past the window on strict OpenAI-compatible servers.

Prune order (cache-aware-prune.ts). The pass is planned first with a new pure ToolResultPruner.planSession() and priced before anything lands:

Situation	master	Patched
The prune pass alone clears pressure	prune everywhere	unchanged
A summary runs anyway	prune everywhere, then summarize the rewritten region	prune only the retained tail, summarize the untouched region
Context-overflow recovery	prune first	unchanged: the summary prompt itself has to fit the window

Pruning the region saves nothing when a summary runs, because the checkpoint shadows it anyway; the summarizer now also reads full-fidelity tool output. The retained tail is re-prefilled after the checkpoint regardless (its position shifts), so pruning it costs nothing extra.

📊 Measured

Real agent loop, token meter, pruner and compaction-basic; only the provider is simulated. The simulated cache keys a request family on (provider, model, effort, temperature, stop) and reuses the longest byte prefix of any earlier request in that family; maxTokens is not part of the key, per @deepseekv41flash's corpus in #1944. Setup: 60 scripted tool steps, conversation effort max, adapter default high, pruner budgets that rewrite every third result without clearing pressure on their own.

Window	Summary calls (3 folds), uncached tokens on master	… patched	Hit rate	Whole session, uncached tokens
32k	21,845 · 22,282 · 21,898	469–470	0–0.7% → 97.9%	191,515 → 126,899 (−34%)
128k	83,945 · 85,282 · 83,998	469–470	0–0.2% → 99.4%	616,847 → 365,031 (−41%)
512k	332,345 · 337,282 · 332,398	469–470	0% → 99.9%	2,442,047 → 1,441,431 (−41%)

Each cause in isolation: effort only puts every fold at 0–0.8% on master and at 97.7% or more patched. Pruner only (effort already aligned) drops folds whose region held a rewritten result to 11.9–44.2% on master; patched, every fold is at 97.9% or more.

At a 512k prefix on V4-Pro off-peak pricing, one fold goes from about $0.22 to about $0.008. A miss costs 30× (Pro) to 50× (Flash) a cache hit per token, so the gap grows linearly with every token of context.

Tip

The simulator is a worst case for cause 1: an effort mismatch misses everything, as on @bulhenvaster's server. DeepSeek's own endpoint still served the ~18k static head in @deepseekv41flash's data. Same conclusion: the conversation body misses.

✅ Verification

File	On master	With the patch
compaction-basic/tests/prefix-cache-integrity.spec.ts (new, 6 cases)	5 failing, 1 passing¹	all 6 passing
compaction-basic/tests/compaction-basic.spec.ts (1 case rewritten to the new contract)	failing	passing
compaction-basic/tests/support/prefix-cache.ts (new: prefix-cache simulator and scripted workload)	n/a	test helper
Whole packages/compaction/ suite	230 passed	236 passed, 0 failed

¹ The structural guard passes on both trees by design; see below.

Patch: compaction-basic/src/{summarizer,index,region,cache-aware-prune}.ts, compaction-tool-result-pruner/src/{index,types}.ts, compaction/src/types.ts (tsc -b clean).

With the patch the compaction suite is green (236 passed), tsc -b is clean for the three touched packages, tsc is clean for the new and changed spec files, scripts/run-oxlint.ts reports nothing, and git apply --check succeeds on a fresh checkout of 687f282e86, which is still the tip of master.

The window-scaling case, verbatim from the new spec (MAX_UNCACHED_SUMMARY_TOKENS = 2_000):

it.each([32_000, 128_000, 512_000])('bounds the uncached summary prompt independently of a %i-token window', async (window) => {
  const run = await runWorkload({ window, steps: 60, effort: 'max', pruner: 'rewrite-only' })
  const summaries = run.cache.compactions()

  expect(summaries.length).toBeGreaterThanOrEqual(2)
  for (const summary of summaries) {
    expect(hitRatio(summary)).toBeGreaterThanOrEqual(0.95)
    expect(uncached(summary)).toBeLessThanOrEqual(MAX_UNCACHED_SUMMARY_TOKENS)
  }
  assertNoSilentRewrite(run)
}, 60_000)

assertNoSilentRewrite is the structural guard: every conversation request must be a strict byte extension of the previous one, unless a durable surface replacement (checkpoint, prune, prompt consolidation) landed in between. It passes on both trees today. It is there to catch the next per-request drift, not this one.

🧭 Scope

• Retained tail. The first request after a checkpoint still re-prefills checkpoint plus retained tail, roughly retainRatio × message budget (82–87k at 512k in the runs above). That is inherent to positional prefix caches and is now the dominant per-fold cost. It is a policy question, which I will take up in a separate proposal.
• toolChoice: 'none' for the summary call ([bug] Compaction sends the tool schemas with no tool choice, so a tool-capable model answers with a tool call and the summary is lost silently #5521) is orthogonal and needs adapter plumbing.
• Docs. README L108 and L233 become true again; L166 and its zh mirror need one sentence: "if summarization remains necessary, only the retained tail is trimmed."

📦 Patch and reproduce

# save the full patch below as compaction-cache-integrity.patch
git checkout 687f282e86 && git apply compaction-cache-integrity.patch
# a full `pnpm install` currently fails behind proxies on cdn.sheetjs.com;
# the filtered install is enough:
pnpm install --frozen-lockfile --filter "@deepseek-ai/dsh-compaction-basic..." --filter "@deepseek-ai/dsh-compaction-tool-result-pruner..."
npx vitest run packages/compaction/

Full patch: git apply on 687f282e86 · 10 files · +630 / −29

diff --git a/packages/compaction/compaction-basic/src/cache-aware-prune.ts b/packages/compaction/compaction-basic/src/cache-aware-prune.ts
new file mode 100644
index 0000000000..be869e3cb5
--- /dev/null
+++ b/packages/compaction/compaction-basic/src/cache-aware-prune.ts
@@ -0,0 +1,93 @@
+/**
+ * Cache-aware ordering of the model-free prune pass relative to the summary.
+ *
+ * The summary call is cache-warm only while `[tools, system, region]` is a
+ * byte prefix of the last routed request. Rewriting any node of that region
+ * before the call moves the first divergent byte from the instruction to the
+ * first rewritten tool result, and the provider prefills everything after it
+ * again. When a summary will run anyway, region nodes are about to be
+ * shadowed by the checkpoint, so pruning them saves nothing; only the
+ * retained tail is pruned, and the tail is re-prefilled after the replacement
+ * regardless because its position shifts.
+ *
+ * @module @deepseek-ai/dsh-compaction-basic/cache-aware-prune
+ */
+
+import type { ToolResultPruner, PlannedPrune } from '@deepseek-ai/dsh-compaction-tool-result-pruner'
+import { freezeMessage } from '@deepseek-ai/dsh-llm'
+import type { ToolResultMessage } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { TokenMeasurement, TokenMeter } from '@deepseek-ai/dsh-token-meter'
+import { selectCompactableRange } from './region.ts'
+
+/** What the pressure path should do with the model-free pass. */
+export type PrunePlan =
+  /** Nothing is over budget. */
+  | { readonly kind: 'none' }
+  /** The pass alone clears pressure: land it everywhere, as before. */
+  | { readonly kind: 'prune-only' }
+  /** A summary runs anyway: land only the nodes after the summarized region. */
+  | { readonly kind: 'tail-only'; readonly tail: ReadonlySet<SessionSeq> }
+
+/**
+ * Re-price a measurement as if the planned replacements had landed, using the
+ * same heuristic the shadow-price protocol records for each replacement.
+ * @param meter - effective token meter.
+ * @param measurement - current measurement of the unpruned surface.
+ * @param plan - replacements the pass would land.
+ * @returns a measurement over the same seqs with projected prices.
+ */
+export function projectPrunedMeasurement(
+  meter: TokenMeter,
+  measurement: TokenMeasurement,
+  plan: readonly PlannedPrune[],
+): TokenMeasurement {
+  const savings = new Map<SessionSeq, number>()
+  for (const { seq, original, content } of plan) {
+    const replacement = freezeMessage<ToolResultMessage>({ ...original, content })
+    savings.set(seq, Math.max(0, meter.estimateMessage(original) - meter.estimateMessage(replacement)))
+  }
+  let saved = 0
+  const nodes = measurement.nodes.map((node) => {
+    const delta = Math.min(node.tokens, savings.get(node.seq) ?? 0)
+    if (delta === 0) return node
+    saved += delta
+    return { ...node, tokens: node.tokens - delta, heuristicTokens: Math.max(0, node.heuristicTokens - delta) }
+  })
+  return {
+    ...measurement,
+    nodes,
+    surfaceTokens: measurement.surfaceTokens - saved,
+    totalTokens: Math.max(0, measurement.totalTokens - saved),
+  }
+}
+
+/**
+ * Decide how the prune pass lands for one pressure compaction.
+ * @param prune - the optional sibling pruner service.
+ * @param meter - effective token meter.
+ * @param session - session under pressure.
+ * @param measurement - current measurement at or above the threshold.
+ * @param thresholdTokens - resolved pressure threshold.
+ * @param retainTokens - verbatim tail budget the summary keeps.
+ * @returns the landing decision.
+ */
+export function planPrune(
+  prune: Pick<ToolResultPruner, 'planSession'>,
+  meter: TokenMeter,
+  session: Session,
+  measurement: TokenMeasurement,
+  thresholdTokens: number,
+  retainTokens: number,
+): PrunePlan {
+  const plan = prune.planSession(session)
+  if (plan.length === 0) return { kind: 'none' }
+  const projected = projectPrunedMeasurement(meter, measurement, plan)
+  if (projected.totalTokens < thresholdTokens) return { kind: 'prune-only' }
+  // Select on projected prices so the retained tail matches what the
+  // summary would keep after a full pass; the tail is then pruned for real.
+  const range = selectCompactableRange(session, projected, retainTokens)
+  const nodes = session.surface.nodes
+  const tailStart = range === null ? 0 : nodes.indexOf(range.end) + 1
+  return { kind: 'tail-only', tail: new Set(nodes.slice(tailStart)) }
+}
diff --git a/packages/compaction/compaction-basic/src/index.ts b/packages/compaction/compaction-basic/src/index.ts
index 163cec3810..cae4681006 100644
--- a/packages/compaction/compaction-basic/src/index.ts
+++ b/packages/compaction/compaction-basic/src/index.ts
@@ -27,6 +27,7 @@ import {
   compactSurfaceRegion,
   selectCompactableRange,
 } from './region.ts'
+import { planPrune } from './cache-aware-prune.ts'
 import { summarizeWithLlm } from './summarizer.ts'
 import type { SummarizationInput, SummaryResult } from './summarizer.ts'
 import type {
@@ -318,11 +319,30 @@ export class BasicCompactionEngine extends CompactionEngine {
     )
     if (measurement.totalTokens < spec.thresholdTokens) return null
 
-    // Once pressure qualifies, land the model-free pass before choosing a
-    // summary range, then remeasure through the singleton replay fold.
+    // Once pressure qualifies, the model-free pass runs first. When it alone
+    // clears pressure it lands everywhere. When a summary runs anyway, it must
+    // not rewrite the region the summary call replays, or that call misses
+    // the provider prefix cache from the first rewritten node on; only the
+    // retained tail is pruned (see cache-aware-prune.ts).
     if (prune !== undefined) {
-      prune.pruneSession(agent.session)
-      measurement = meter.measure(agent.session)
+      const decision = planPrune(
+        prune, meter, agent.session, measurement, spec.thresholdTokens, spec.retainTokens,
+      )
+      switch (decision.kind) {
+        case 'none':
+          break
+        case 'prune-only':
+          prune.pruneSession(agent.session)
+          measurement = meter.measure(agent.session)
+          break
+        case 'tail-only':
+          prune.pruneSession(agent.session, seq => decision.tail.has(seq))
+          measurement = meter.measure(agent.session)
+          break
+        /* v8 ignore next -- closed-union exhaustiveness guard */
+        default:
+          assertNever(decision, 'prune decision')
+      }
     }
     if (measurement.totalTokens < spec.thresholdTokens) return null
 
diff --git a/packages/compaction/compaction-basic/src/region.ts b/packages/compaction/compaction-basic/src/region.ts
index 7b3d77d299..0ac082a7a8 100644
--- a/packages/compaction/compaction-basic/src/region.ts
+++ b/packages/compaction/compaction-basic/src/region.ts
@@ -481,6 +481,7 @@ function commitCompactionBody(
     summary,
     provider,
     model,
+    reasoningEffort,
     maxTokens,
     usage,
     checkpointMessage,
@@ -500,6 +501,7 @@ function commitCompactionBody(
     shadowedTokenCount,
     provider,
     model,
+    ...reasoningEffort === undefined ? {} : { reasoningEffort },
     ...maxTokens === undefined ? {} : { maxTokens },
     ...usage === undefined ? {} : { usage },
   })
diff --git a/packages/compaction/compaction-basic/src/summarizer.ts b/packages/compaction/compaction-basic/src/summarizer.ts
index 2d258fa410..5503bf4266 100644
--- a/packages/compaction/compaction-basic/src/summarizer.ts
+++ b/packages/compaction/compaction-basic/src/summarizer.ts
@@ -8,8 +8,9 @@ import type { Context } from '@deepseek-ai/cordis'
 import { contentHasImage, BlockAssembler, LlmError } from '@deepseek-ai/dsh-llm'
 import { deepFreeze } from '@deepseek-ai/dsh-util-values'
 import type {
-  ContentBlock, FinishReason, GenerateOptions, Message, RequestMessage, TokenUsage, ToolSchema,
+  ContentBlock, FinishReason, GenerateOptions, Message, ReasoningEffortId, RequestMessage, TokenUsage, ToolSchema,
 } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 
 interface SummaryConfig {
@@ -88,6 +89,8 @@ export type SummaryResult = {
   summary: ContentBlock[]
   provider: string
   model: string
+  /** The reasoning effort the summarize call sent, when one was inherited. */
+  reasoningEffort?: ReasoningEffortId
   maxTokens?: number
   /** Provider-reported usage for this summarization request. */
   usage?: TokenUsage
@@ -106,10 +109,37 @@ export type SummaryResult = {
   }
 )
 
+/**
+ * Prompt-shaping controls the summarization call copies from the latest
+ * durable request header when it targets exactly that route. dsh-llm's
+ * call-config documents provider, model, reasoning effort, and sampling as
+ * request-header state that can affect cache reuse; without them the replayed
+ * prefix belongs to a different request family and is prefilled cold (#1944,
+ * #3002). `maxTokens` is deliberately not inherited: it caps output rather
+ * than shaping the cached prompt, and the policy sizes it against the
+ * reserved compaction headroom so the call still fits the window.
+ * @param header - latest durable request header, when one was routed.
+ * @param target - provider/model the summarization call will use.
+ * @returns the controls to spread into the summarization request.
+ */
+export function inheritedCallControls(
+  header: Pick<EpochHeader, 'config'> | undefined,
+  target: { readonly provider: string; readonly model: string },
+): Pick<GenerateOptions, 'reasoningEffort' | 'temperature' | 'stop'> {
+  const config = header?.config
+  if (config === undefined || config.provider !== target.provider || config.model !== target.model) return {}
+  return {
+    ...config.reasoningEffort === undefined ? {} : { reasoningEffort: config.reasoningEffort },
+    ...config.temperature === undefined ? {} : { temperature: config.temperature },
+    ...config.stop === undefined ? {} : { stop: [...config.stop] },
+  }
+}
+
 /**
  * Run the default cache-reusing `ctx.llm.stream()` summarization call: replay
- * the conversation prefix, then append the compaction instruction as the final
- * user message so the provider's warm prefix cache is reused.
+ * the conversation prefix with the routed request's prompt-shaping controls,
+ * then append the compaction instruction as the final user message so the
+ * provider's warm prefix cache is reused.
  * @param ctx - context providing the LLM service.
  * @param config - resolved backend configuration.
  * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
@@ -124,7 +154,8 @@ export async function summarizeWithLlm(
   agent: Agent,
   signal?: AbortSignal,
 ): Promise<SummaryResult> {
-  const latest = agent.session.requestHeader()?.config
+  const header = agent.session.requestHeader()
+  const latest = header?.config
   const configured = config.summarizationProvider.length === 0
     ? undefined
     : { provider: config.summarizationProvider, model: config.summarizationModel }
@@ -152,6 +183,7 @@ export async function summarizeWithLlm(
   const options: GenerateOptions = {
     provider: target.provider,
     model: target.model,
+    ...inheritedCallControls(header, target),
     messages,
     toolHistory: agent.session.toolHistory(),
     ...input.tools === undefined ? {} : { tools: [...input.tools] },
@@ -175,6 +207,7 @@ export async function summarizeWithLlm(
     llmStreamCall: true,
     provider: options.provider,
     model: options.model,
+    ...options.reasoningEffort === undefined ? {} : { reasoningEffort: options.reasoningEffort },
     maxTokens: config.maxTokens,
     ...(assembler.usage === undefined ? {} : { usage: assembler.usage }),
   }
diff --git a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
index 3736aa5c5e..6a820b4ea2 100644
--- a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
+++ b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts
@@ -983,7 +983,7 @@ describe('optional model-free tool-result pruning', () => {
     expect(session.surface.replaceGeneration).toBe(1)
   })
 
-  it('summarizes the pruned surface when pruning is insufficient', async () => {
+  it('summarizes the byte-identical region and prunes only the retained tail when pruning is insufficient', async () => {
     const ctx = createContext(2_000)
     void new ToolResultPruner(ctx, pruneConfig)
     const compact = new TestCompactionEngine(ctx, {
@@ -994,11 +994,22 @@ describe('optional model-free tool-result pruning', () => {
       retainTokens: 50,
     })
     const session = toolConversation()
+    const routed = session.deriveMessages()
 
-    expect(await compactIfNeeded(compact, session)).not.toBeNull()
+    const result = await compactIfNeeded(compact, session)
+    expect(result).not.toBeNull()
     expect(compact.calls).toHaveLength(1)
-    expect(summarizedText(compact.calls[0]!.input)).toContain('tool result middle pruned')
-    expect(summarizedText(compact.calls[0]!.input)).not.toContain('result 1 '.repeat(300))
+    // The replay is a prefix of the last routed history, so the provider cache stays warm.
+    const replayed = compact.calls[0]!.input.messages
+    expect(replayed).toEqual(routed.slice(0, replayed.length))
+    expect(summarizedText(compact.calls[0]!.input)).toContain('result 1 '.repeat(300))
+    expect(summarizedText(compact.calls[0]!.input)).not.toContain('tool result middle pruned')
+    // Every landed prune shadows a node after the summarized region.
+    const prunes = session.snapshotEvents().filter(event => event.type === 'compaction/prune')
+    expect(prunes.length).toBeGreaterThan(0)
+    for (const event of prunes) {
+      expect(event.data.shadowedRange.start).toBeGreaterThan(result!.shadowedRange.end)
+    }
   })
 
   it('retains the original compaction-basic behavior without the optional plugin', async () => {
diff --git a/packages/compaction/compaction-basic/tests/prefix-cache-integrity.spec.ts b/packages/compaction/compaction-basic/tests/prefix-cache-integrity.spec.ts
new file mode 100644
index 0000000000..024bece74d
--- /dev/null
+++ b/packages/compaction/compaction-basic/tests/prefix-cache-integrity.spec.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { hitRatio, runWorkload } from './support/prefix-cache.ts'
+import type { CacheObservation, WorkloadRun } from './support/prefix-cache.ts'
+
+/**
+ * Cache-integrity contract for automatic compaction (discussions #1944, #3002).
+ *
+ * 1. The summary call is a warm replay: same request family as the routed
+ *    conversation, and `[tools, system, region]` stays a byte prefix of the
+ *    last routed request, so only the trailing instruction is new.
+ * 2. Between compactions the conversation is append-only: every request is a
+ *    strict byte extension of the previous one.
+ * 3. Both hold independently of volume: the uncached part of a summary call
+ *    is bounded by the instruction, not by the window.
+ */
+
+/** Upper bound for the novel part of a warm summary call: the instruction plus framing. */
+const MAX_UNCACHED_SUMMARY_TOKENS = 2_000
+
+function uncached(observation: CacheObservation): number {
+  return observation.promptTokens - observation.cachedTokens
+}
+
+/**
+ * No unexplained cache break: every conversation request extends its
+ * predecessor byte for byte unless a durable surface replacement (checkpoint,
+ * prune, or prompt consolidation) landed in between.
+ */
+function assertNoSilentRewrite(run: WorkloadRun): void {
+  let rewritten = false
+  let seenConversation = false
+  for (const observation of run.cache.log) {
+    if (observation.rewritesSincePrevious.length > 0) rewritten = true
+    if (observation.purpose === 'compaction') continue
+    if (seenConversation && !rewritten) {
+      expect(observation.extendsPreviousConversation, `request #${observation.index} rewrote cached history silently`).toBe(true)
+    }
+    seenConversation = true
+    rewritten = false
+  }
+}
+
+describe('compaction keeps the provider prefix cache warm', () => {
+  it('replays the routed reasoning effort in the summary call', async () => {
+    const run = await runWorkload({ window: 64_000, steps: 40, effort: 'max' })
+    const summaries = run.cache.compactions()
+
+    expect(summaries.length).toBeGreaterThanOrEqual(2)
+    for (const summary of summaries) {
+      expect(summary.reasoningEffort).toBe('max')
+      expect(hitRatio(summary)).toBeGreaterThanOrEqual(0.95)
+      expect(uncached(summary)).toBeLessThanOrEqual(MAX_UNCACHED_SUMMARY_TOKENS)
+    }
+    const events = run.session.snapshotEvents().filter(event => event.type === 'compaction/summary')
+    expect(events.map(event => event.data.reasoningEffort)).toEqual(summaries.map(() => 'max'))
+  })
+
+  it('does not rewrite the replayed region with the model-free prune pass', async () => {
+    const run = await runWorkload({ window: 64_000, steps: 40, pruner: 'rewrite-only' })
+    const events = run.session.snapshotEvents()
+
+    expect(events.some(event => event.type === 'compaction/prune')).toBe(true)
+    const summaries = run.cache.compactions()
+    expect(summaries.length).toBeGreaterThanOrEqual(2)
+    for (const summary of summaries) {
+      expect(hitRatio(summary)).toBeGreaterThanOrEqual(0.95)
+      expect(uncached(summary)).toBeLessThanOrEqual(MAX_UNCACHED_SUMMARY_TOKENS)
+    }
+  })
+
+  it('never breaks the cache without a durable rewrite event', async () => {
+    const run = await runWorkload({ window: 64_000, steps: 40, effort: 'max', pruner: 'rewrite-only' })
+
+    assertNoSilentRewrite(run)
+    // The first request after a checkpoint still reuses the static head (tools + system prompt).
+    const conversations = run.cache.conversations()
+    expect(conversations.every(observation => observation.index === 0 || observation.cachedTokens > 0)).toBe(true)
+  })
+
+  it.each([32_000, 128_000, 512_000])('bounds the uncached summary prompt independently of a %i-token window', async (window) => {
+    const run = await runWorkload({ window, steps: 60, effort: 'max', pruner: 'rewrite-only' })
+    const summaries = run.cache.compactions()
+
+    expect(summaries.length).toBeGreaterThanOrEqual(2)
+    for (const summary of summaries) {
+      expect(hitRatio(summary)).toBeGreaterThanOrEqual(0.95)
+      expect(uncached(summary)).toBeLessThanOrEqual(MAX_UNCACHED_SUMMARY_TOKENS)
+    }
+    assertNoSilentRewrite(run)
+  }, 60_000)
+})
diff --git a/packages/compaction/compaction-basic/tests/support/prefix-cache.ts b/packages/compaction/compaction-basic/tests/support/prefix-cache.ts
new file mode 100644
index 0000000000..ef0f9a4d45
--- /dev/null
+++ b/packages/compaction/compaction-basic/tests/support/prefix-cache.ts
@@ -0,0 +1,315 @@
+/**
+ * Deterministic provider-side prefix-cache simulator and a scripted coding
+ * workload for cache-integrity regression specs.
+ *
+ * The simulator keys a request family on the prompt-shaping envelope
+ * (provider, model, reasoning effort, temperature, stop) and reuses the
+ * longest byte prefix of any earlier request in the same family. That matches
+ * the failure observed in discussion #1944, where a server template renders
+ * the reasoning effort ahead of the conversation. `maxTokens` is an output cap
+ * and deliberately not part of the key: the #1944 corpus shows folds with a
+ * matching effort but a different cap still reusing 99.9% of the prefix.
+ *
+ * Token counts use the token meter's fixed density (4 chars per token) over
+ * the provider-visible serialization: role, content, and tool-call
+ * correlation, never local message ids or sources.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { createUserMessage, LlmAdapter, ReasoningEffortId, ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmResolvedModelInfo, RequestMessage, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic'
+import type { BasicCompactionConfig } from '@deepseek-ai/dsh-compaction-basic'
+import ToolResultPruner from '@deepseek-ai/dsh-compaction-tool-result-pruner'
+import type { ToolResultPruneConfig } from '@deepseek-ai/dsh-compaction-tool-result-pruner'
+import TokenMeter from '@deepseek-ai/dsh-token-meter'
+import { isReplacementSurfaceEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+
+/** One request as the simulated provider cache saw it. */
+export interface CacheObservation {
+  readonly index: number
+  readonly purpose: 'conversation' | 'compaction'
+  readonly reasoningEffort: string | undefined
+  readonly maxTokens: number | undefined
+  readonly promptTokens: number
+  readonly cachedTokens: number
+  /** Whether this request is a strict byte extension of the previous conversation request. */
+  readonly extendsPreviousConversation: boolean
+  /** Durable surface replacements (event types) landed since the previous request. */
+  readonly rewritesSincePrevious: readonly string[]
+}
+
+const CHARS_PER_TOKEN = 4
+
+function tokensOf(chars: number): number {
+  return Math.ceil(chars / CHARS_PER_TOKEN)
+}
+
+function wireUnit(message: RequestMessage): string {
+  return JSON.stringify([
+    message.role,
+    message.content,
+    'toolCallId' in message ? message.toolCallId : null,
+  ])
+}
+
+interface CacheEntry {
+  readonly key: string
+  readonly ids: readonly number[]
+  readonly units: readonly string[]
+  readonly chars: number
+}
+
+/** Longest common byte prefix of two unit sequences, interned by id. */
+function commonPrefixChars(a: CacheEntry, ids: readonly number[], units: readonly string[]): number {
+  let chars = 0
+  const n = Math.min(a.ids.length, ids.length)
+  for (let index = 0; index < n; index += 1) {
+    const left = a.units[index]!
+    if (a.ids[index] === ids[index]) {
+      chars += left.length
+      continue
+    }
+    const right = units[index]!
+    const limit = Math.min(left.length, right.length)
+    let shared = 0
+    while (shared < limit && left.charCodeAt(shared) === right.charCodeAt(shared)) shared += 1
+    return chars + shared
+  }
+  return chars
+}
+
+/** Simulated provider prefix cache; every observed request becomes reusable. */
+export class PrefixCache {
+  readonly log: CacheObservation[] = []
+  private readonly entries: CacheEntry[] = []
+  private readonly interned = new Map<string, number>()
+  private lastConversation: CacheEntry | undefined
+  private pendingRewrites: string[] = []
+
+  /** Record a durable surface replacement; the next observation carries it. */
+  noteRewrite(kind: string): void {
+    this.pendingRewrites.push(kind)
+  }
+
+  private intern(unit: string): number {
+    let id = this.interned.get(unit)
+    if (id === undefined) {
+      id = this.interned.size
+      this.interned.set(unit, id)
+    }
+    return id
+  }
+
+  observe(options: GenerateOptions): CacheObservation {
+    const key = JSON.stringify([
+      options.provider,
+      options.model,
+      options.reasoningEffort ?? null,
+      options.temperature ?? null,
+      options.stop ?? null,
+    ])
+    const units = [JSON.stringify(options.tools ?? []), ...options.messages.map(wireUnit)]
+    const ids = units.map(unit => this.intern(unit))
+    const chars = units.reduce((total, unit) => total + unit.length, 0)
+    let cached = 0
+    for (const entry of this.entries) {
+      if (entry.key === key) cached = Math.max(cached, commonPrefixChars(entry, ids, units))
+    }
+    const entry: CacheEntry = { key, ids, units, chars }
+    const purpose = options.purpose === 'compaction' ? 'compaction' : 'conversation'
+    const previous = this.lastConversation
+    const extendsPreviousConversation = previous !== undefined
+      && previous.key === key
+      && commonPrefixChars(previous, ids, units) === previous.chars
+    this.entries.push(entry)
+    if (purpose === 'conversation') this.lastConversation = entry
+    const observation: CacheObservation = {
+      index: this.log.length,
+      purpose,
+      reasoningEffort: options.reasoningEffort,
+      maxTokens: options.maxTokens,
+      promptTokens: tokensOf(chars),
+      cachedTokens: tokensOf(cached),
+      extendsPreviousConversation,
+      rewritesSincePrevious: this.pendingRewrites,
+    }
+    this.pendingRewrites = []
+    this.log.push(observation)
+    return observation
+  }
+
+  compactions(): CacheObservation[] {
+    return this.log.filter(entry => entry.purpose === 'compaction')
+  }
+
+  conversations(): CacheObservation[] {
+    return this.log.filter(entry => entry.purpose === 'conversation')
+  }
+}
+
+/** Deterministic filler with no long repeated runs, so prefixes stay honest. */
+function prose(label: string, chars: number): string {
+  let text = `${label}: `
+  let state = label.length * 2654435761 >>> 0
+  while (text.length < chars) {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0
+    text += `w${(state % 9973).toString(36)} `
+  }
+  return text.slice(0, chars)
+}
+
+/** Shape of one scripted coding session scaled to a model context window. */
+export interface Workload {
+  /** Context window the adapter declares for the routed model. */
+  readonly window: number
+  /** Tool steps the scripted model runs before its final answer. */
+  readonly steps: number
+  /** Conversation effort; the adapter default is `high`. */
+  readonly effort?: 'low' | 'high' | 'max'
+  /**
+   * Mount the model-free pruner. `rewrite-only` derives budgets from the
+   * window so every third result is rewritten but the pass alone never clears
+   * pressure, which isolates the effect of the rewrite on the summary call.
+   */
+  readonly pruner?: 'rewrite-only' | ToolResultPruneConfig
+  /** Deterministic summarizer output. */
+  readonly summary?: (call: number) => string
+  /** Opening user message. */
+  readonly prompt?: string
+  /** Extra compaction configuration. */
+  readonly compaction?: BasicCompactionConfig
+}
+
+/** Scripted model: tool calls with prose, then a final answer; summaries on `purpose: compaction`. */
+class ScriptedCodingModel extends LlmAdapter {
+  private conversationCalls = 0
+  private summaryCalls = 0
+
+  constructor(
+    private readonly cache: PrefixCache,
+    private readonly workload: Workload,
+    private readonly stepChars: number,
+  ) {
+    super()
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    const effort = (id: string) => ({ id: ReasoningEffortId(id), name: id })
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: model,
+      context: { contextWindow: this.workload.window },
+      defaultMaxTokens: Math.floor(this.workload.window / 16),
+      reasoning: { efforts: [effort('low'), effort('high'), effort('max')], defaultEffort: ReasoningEffortId('high') },
+    })
+  }
+
+  override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.cache.observe(options)
+    if (options.purpose === 'compaction') {
+      const call = this.summaryCalls
+      this.summaryCalls += 1
+      const text = this.workload.summary?.(call)
+        ?? `## Primary Request and Intent\n- checkpoint ${call}\n## Current Work\n- ${prose(`summary-${call}`, 400)}`
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'block-end', index: 0, block: { type: 'text', text } }
+      yield { type: 'finish', reason: { kind: 'stop' } }
+      return
+    }
+    const n = this.conversationCalls
+    this.conversationCalls += 1
+    if (n < this.workload.steps) {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'block-end', index: 0, block: { type: 'text', text: prose(`reasoning-${n}`, this.stepChars) } }
+      yield { type: 'block-start', index: 1, blockType: 'tool-call' }
+      yield {
+        type: 'block-end',
+        index: 1,
+        block: { type: 'tool-call', id: ToolCallId(`call-${n}`), name: 'read_file', arguments: `{"i":${n}}` },
+      }
+      yield { type: 'finish', reason: { kind: 'tool-calls' } }
+      return
+    }
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: 'done' } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+/** Result of one scripted session run. */
+export interface WorkloadRun {
+  readonly cache: PrefixCache
+  readonly session: Session
+}
+
+/**
+ * Run one scripted session through the real agent loop, token meter,
+ * compaction-basic, and (optionally) the tool-result pruner.
+ * @param workload - window, step count, effort, and pruner budgets.
+ * @returns the cache log and the finished session.
+ */
+export async function runWorkload(workload: Workload): Promise<WorkloadRun> {
+  const ctx = new Context()
+  const cache = new PrefixCache()
+  // About 24 steps fill a window: prose plus a tool result per step.
+  const stepTokens = Math.floor(workload.window / 24)
+  const stepChars = Math.floor(stepTokens * CHARS_PER_TOKEN * 0.45)
+  const rewriteThreshold = Math.ceil(stepChars * 1.5)
+  const pruner: ToolResultPruneConfig | undefined = workload.pruner === 'rewrite-only'
+    ? { thresholdChars: rewriteThreshold, headChars: rewriteThreshold - 1_000, tailChars: 900 }
+    : workload.pruner
+  // Every third result overflows the prune budget by a few hundred chars.
+  const bigResultChars = workload.pruner === 'rewrite-only' ? rewriteThreshold + 300 : stepChars * 2
+  await mountAgentLoopTestDependencies(ctx)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(TokenMeter)
+  if (pruner !== undefined) await ctx.plugin(ToolResultPruner, pruner)
+  ctx.llm.registerAdapter(['mock'], new ScriptedCodingModel(cache, workload, stepChars))
+  ctx.on('session/event', (_session, event) => {
+    if (isReplacementSurfaceEvent(event)) cache.noteRewrite(event.type)
+  })
+  ctx.tools.register(defineContentToolFixture({
+    name: 'read_file',
+    description: 'Read one file of the workspace.',
+    parameters: { i: { type: 'number' } },
+    execute({ i }) {
+      const index = i ?? 0
+      const size = index % 3 === 1 ? bigResultChars : stepChars
+      return Promise.resolve([{ type: 'text', text: prose(`file-${index}`, size) }])
+    },
+  }))
+  await ctx.plugin(BasicCompactionEngine, {
+    thresholdRatio: 0.8,
+    headroomTokens: Math.floor(workload.window / 16),
+    retainRatio: 0.16,
+    compactionRetries: 1,
+    ...workload.compaction,
+  })
+  try {
+    const agent = await ctx.agentLoop.create(SessionId(`cache-${workload.window}-${workload.effort ?? 'default'}`), {
+      provider: 'mock',
+      model: 'mock',
+      ...workload.effort === undefined ? {} : { reasoningEffort: ReasoningEffortId(workload.effort) },
+    })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: workload.prompt ?? 'Refactor the workspace.' }], source: { kind: 'user' } }))
+    await agent.whenIdle()
+    const last = agent.session.snapshotEvents().at(-1)
+    if (last?.type !== 'turn/end' || last.data.reason.kind !== 'completed') {
+      throw new Error(`scripted turn did not complete: ${JSON.stringify(last)}`)
+    }
+    return { cache, session: agent.session }
+  } finally {
+    await ctx.fiber.dispose()
+  }
+}
+
+/** Fraction of a request's prompt served from the simulated cache. */
+export function hitRatio(observation: CacheObservation): number {
+  return observation.promptTokens === 0 ? 1 : observation.cachedTokens / observation.promptTokens
+}
diff --git a/packages/compaction/compaction-tool-result-pruner/src/index.ts b/packages/compaction/compaction-tool-result-pruner/src/index.ts
index 5f536bfc9b..267a259083 100644
--- a/packages/compaction/compaction-tool-result-pruner/src/index.ts
+++ b/packages/compaction/compaction-tool-result-pruner/src/index.ts
@@ -15,6 +15,7 @@ import type {} from '@deepseek-ai/dsh-compaction'
 import type {} from '@deepseek-ai/dsh-token-meter'
 import { codePointLength, DEFAULTS, PRUNE_MARKER, resolveConfig } from './config.ts'
 import type {
+  PlannedPrune,
   PrunedEntry,
   PruneResult,
   ResolvedConfig,
@@ -23,6 +24,7 @@ import type {
 
 export { codePointLength, DEFAULTS, PRUNE_MARKER, resolveConfig } from './config.ts'
 export type {
+  PlannedPrune,
   PrunedEntry,
   PruneResult,
   ResolvedConfig,
@@ -35,8 +37,7 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
-interface SnapshotCandidate {
-  readonly seq: SessionSeq
+interface SnapshotCandidate extends PlannedPrune {
   readonly event: SessionEvent<'tool/result'>
 }
 
@@ -121,6 +122,19 @@ export class ToolResultPruner extends Service {
     return pruned
   }
 
+  /**
+   * Compute the replacements a pass would land, without appending anything.
+   * Callers that must keep part of the surface byte-stable (a cache-warm
+   * replay of the history prefix, for example) price the plan first and then
+   * land only the nodes they choose.
+   * @param session - session whose current surface is inspected.
+   * @param include - optional filter over current surface seqs; defaults to every node.
+   * @returns over-budget tool-result nodes with their pruned content, in surface order.
+   */
+  planSession(session: Session, include?: (seq: SessionSeq) => boolean): PlannedPrune[] {
+    return this.snapshot(session, include).map(({ seq, original, content }) => ({ seq, original, content }))
+  }
+
   /**
    * Prune every over-budget tool result from one stable current-surface snapshot.
    * Each replacement preserves the complete event data except for `content`,
@@ -129,25 +143,15 @@ export class ToolResultPruner extends Service {
    * shadowed node through the injected token meter, so pure consumers can
    * subtract it without per-node state.
    * @param session - session whose current surface is rewritten.
+   * @param include - optional filter over current surface seqs; omitted nodes stay byte-identical.
    * @returns landed replacements and aggregate Unicode-code-point savings.
    * @throws when the session rejects a replacement; replacements committed
    * earlier in the pass remain durable.
    */
-  pruneSession(session: Session): PruneResult {
-    const candidates: SnapshotCandidate[] = []
-    for (const seq of [...session.surface.nodes]) {
-      // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
-      const event = session.eventAt(seq)
-      /* v8 ignore next -- surface seqs are validated contiguous log references. */
-      if (event?.type === 'tool/result') candidates.push({ seq, event })
-    }
-
+  pruneSession(session: Session, include?: (seq: SessionSeq) => boolean): PruneResult {
     const pruned: PrunedEntry[] = []
     let charsRemoved = 0
-    for (const { seq, event } of candidates) {
-      const original = session.deriveEventMessage(event) as ToolResultMessage
-      const content = this.pruneContent(original.content)
-      if (content === null) continue
+    for (const { seq, event, original, content } of this.snapshot(session, include)) {
       const charsBefore = this.measureContent(original.content)
       const charsAfter = this.measureContent(content)
       const message = freezeMessage<ToolResultMessage>({
@@ -180,6 +184,22 @@ export class ToolResultPruner extends Service {
     }
     return { pruned, charsRemoved }
   }
+
+  /** Snapshot every included over-budget tool-result node before any replacement lands. */
+  private snapshot(session: Session, include?: (seq: SessionSeq) => boolean): SnapshotCandidate[] {
+    const candidates: SnapshotCandidate[] = []
+    for (const seq of [...session.surface.nodes]) {
+      if (include !== undefined && !include(seq)) continue
+      // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+      const event = session.eventAt(seq)
+      /* v8 ignore next -- surface seqs are validated contiguous log references. */
+      if (event?.type !== 'tool/result') continue
+      const original = session.deriveEventMessage(event) as ToolResultMessage
+      const content = this.pruneContent(original.content)
+      if (content !== null) candidates.push({ seq, event, original, content })
+    }
+    return candidates
+  }
 }
 
 export default ToolResultPruner
diff --git a/packages/compaction/compaction-tool-result-pruner/src/types.ts b/packages/compaction/compaction-tool-result-pruner/src/types.ts
index 8cc6934b10..c108879c1b 100644
--- a/packages/compaction/compaction-tool-result-pruner/src/types.ts
+++ b/packages/compaction/compaction-tool-result-pruner/src/types.ts
@@ -1,4 +1,4 @@
-import type { ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, ToolCallId, ToolResultMessage } from '@deepseek-ai/dsh-llm'
 import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 
 /** Character-budget policy for deterministic tool-result pruning. */
@@ -32,6 +32,16 @@ export interface PrunedEntry {
   readonly charsAfter: number
 }
 
+/** One replacement a pass would land, computed without touching the log. */
+export interface PlannedPrune {
+  /** Current surface node whose tool result is over budget. */
+  readonly seq: SessionSeq
+  /** Model-visible message the node derives today. */
+  readonly original: ToolResultMessage
+  /** Pruned content the replacement would carry. */
+  readonly content: ContentBlock[]
+}
+
 /** Aggregate outcome of one stable-surface pruning pass. */
 export interface PruneResult {
   /** Replacements in the snapshotted surface order. */
diff --git a/packages/compaction/compaction/src/types.ts b/packages/compaction/compaction/src/types.ts
index 0c69c53deb..09ed8d5729 100644
--- a/packages/compaction/compaction/src/types.ts
+++ b/packages/compaction/compaction/src/types.ts
@@ -7,7 +7,7 @@
  * @module @deepseek-ai/dsh-compaction/types
  */
 
-import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, ReasoningEffortId, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type { CompactionId } from './brand.ts'
@@ -47,6 +47,12 @@ declare module '@deepseek-ai/dsh-session/types' {
        * this summary" has a durable answer (the reconstructability Agent Note).
        */
       model: string
+      /**
+       * The reasoning effort the summarize call sent, when one applied. It is
+       * part of the call's cache-relevant envelope, so a fold that missed the
+       * prefix cache can be diagnosed from the log alone.
+       */
+      reasoningEffort?: ReasoningEffortId
       /** The generation cap the summarize call sent, when one applied. */
       maxTokens?: number
       /** Provider-reported token usage for the summarization request, when emitted. */

Happy to open this as a pull request as soon as external contributions are accepted.