dsh-context-compression-improved 0.1.1 → 0.2.1

package/packages/selector/src/pruner.ts

@@ -0,0 +1,2144 @@
+/**
+ * Replay-safe, model-free context-compression selector for tool results.
+ *
+ * Standard profiles never rewrite ordinary Assistant prose. The only durable
+ * replacements emitted here are content-only `tool/result` rewrites whose
+ * full source remains in the append-only Session log.
+ *
+ * @module dsh-context-compression-improved-runtime
+ */
+
+import { Service } from '@deepseek-ai/cordis'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent, ToolResultMessage } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-compaction'
+import type {} from '@deepseek-ai/dsh-settings'
+import type {
+  CompactionTokenView,
+  ObservedPromptUsage,
+  TokenCount,
+} from './runtime/measurement.ts'
+import { measureForCompaction } from './runtime/measurement.ts'
+import { sessionEvents } from './runtime/session-events.ts'
+import { countExactCanonicalTextFields } from './runtime/token-count.ts'
+import type {} from '@deepseek-ai/dsh-tools'
+import {
+  tailTrimMessage,
+  tailTrimRef,
+  tailTrimStub,
+} from './runtime/tail-trim.ts'
+import { installContextCompressionRetrieve } from './runtime/retrieve.ts'
+import type { PrunerState } from './pruner/state.ts'
+import { countOmittedLines, CAPACITY_PRESSURE_RATIO } from './pruner/tuning.ts'
+import type { ToolCallInfo, SnapshotCandidate, PlannedReplacement, HistoryPlanOutcome } from './pruner/types.ts'
+import {
+  onlyTextBlock,
+  onlyTextBlocks,
+  countToolContent,
+  exactTokens,
+  sameProviderMeasurementKey,
+  unavailableCount,
+  recoveryMarker,
+  summarize,
+  emptyResult,
+  measureContent,
+  pressureCost,
+  nativePruneContent,
+} from './pruner/content.ts'
+import {
+  hasOpenTurn,
+  rootToolResultSeq,
+  sourceRef as sourceRefFn,
+  latestCompletedToolStep,
+  routeAuditFact,
+  tokenizerAuditFact,
+  isError,
+  historyOutcome,
+} from './pruner/session.ts'
+import { buildLocatorBlock, findCompactionTrace } from './runtime/tokenpilot/locator.ts'
+import { clusterOmittedLines, isSupersededRead, toolCallPath } from './runtime/tokenpilot/read-state.ts'
+import {
+  Estimator,
+  backoffCooldownMs,
+  buildEstimatorSystemPrompt,
+  buildEstimatorUserPrompt,
+  isCoolingDown,
+  parseEstimatorAnswer,
+  type EstimatorFailures,
+  type EstimatorSample,
+} from './runtime/tokenpilot/estimator.ts'
+
+import {
+  DedupeTable,
+  dedupeHash,
+  dedupePlaceholder,
+  flattenPlainText,
+} from './runtime/tokenpilot/dedup.ts'
+import {
+  codePointLength,
+  CONTEXT_COMPRESSION_SETTINGS_NAMESPACE,
+  ContextCompressionSettingsSchema,
+  parseContextCompressionSettings,
+  DEFAULTS,
+  PRUNE_MARKER,
+  resolveConfig,
+  resolvePolicy,
+} from './runtime/config.ts'
+import {
+  historicalPlaceholder,
+  reduceFreshToolResult,
+  verifyReduction,
+} from './runtime/reducers.ts'
+import type {
+  CompressionPolicy,
+  ContextCompressionSettings,
+  HistoryMode,
+  PrunedEntry,
+  PruneResult,
+  PruneSessionOptions,
+  PruneStage,
+  ToolResultPruneConfig,
+} from './runtime/types.ts'
+import { COMPRESSION_PROFILES } from './runtime/types.ts'
+import {
+  decideConservativeAdaptive,
+  deriveAdaptiveTokenBounds,
+} from './runtime/adaptive-cost.ts'
+import {
+  DEEPSEEK_OFFICIAL_PRICE_CATALOG_VERSION,
+  priceOfficialDeepSeekUsage,
+  resolveOfficialDeepSeekPrice,
+} from './runtime/deepseek-official-pricing.ts'
+import { emitCompressionAudit } from './runtime/audit.ts'
+import { assertNever, deepFreeze } from './runtime/value.ts'
+import type {
+  CompressionAuditComponent,
+  CompressionAuditEvaluationStatus,
+} from './runtime/audit.ts'
+
+export {
+  codePointLength,
+  CONTEXT_COMPRESSION_SETTINGS_NAMESPACE,
+  ContextCompressionSettingsSchema,
+  parseContextCompressionSettings,
+  AUTO_COMPACT_THRESHOLD_LIMITS,
+  DEFAULTS,
+  isCompressionProfile,
+  isValidAutoCompactThresholdPercent,
+  PRUNE_MARKER,
+  resolveConfig,
+  resolvePolicy,
+} from './runtime/config.ts'
+export {
+  CustomCompressionPolicySchema,
+  DEFAULT_CUSTOM_COMPRESSION_POLICY,
+  resolveCustomPolicy,
+} from './runtime/custom-policy.ts'
+export type { CustomPolicyResolutionOptions } from './runtime/custom-policy.ts'
+export { historicalPlaceholder, normalizeTerminalText, reduceFreshToolResult, verifyReduction } from './runtime/reducers.ts'
+export { measureForCompaction } from './runtime/measurement.ts'
+export type {
+  CompactionTokenView,
+  MeasuredTokenSurfaceNode,
+} from './runtime/measurement.ts'
+export type {
+  AutoCompactSettings,
+  CodeSkeletonSettings,
+  CompressionPolicy,
+  CompressionProfile,
+  CustomCompressionBudget,
+  CustomCompressionPolicy,
+  CustomCompressionUnit,
+  CustomHistoryPolicy,
+  CustomPrefixPolicy,
+  CustomTailTrimPolicy,
+  CustomCompressionPolicyV1,
+  CustomCompressionPolicyV2,
+  CustomCompressionPolicyV3,
+  ContextCompressionSettings,
+  HistoryMode,
+  PrunedEntry,
+  PruneResult,
+  PruneSessionOptions,
+  PruneStage,
+  ResolvedConfig,
+  ToolResultPruneConfig,
+} from './runtime/types.ts'
+
+// Re-export the canonical profile list from the type module as a runtime value.
+export { COMPRESSION_PROFILES } from './runtime/types.ts'
+
+
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    toolResultPruner: ToolResultPruner
+  }
+}
+
+/** Mixed deterministic selector behind the existing `ctx.toolResultPruner` seam. */
+export class ToolResultPruner extends Service {
+  static inject = ['tokenMeter']
+
+  static Config: z<ToolResultPruneConfig> = z.object({
+    profile: z.union([...COMPRESSION_PROFILES]).default(DEFAULTS.profile),
+    headChars: z.number().step(1).min(0).default(DEFAULTS.headChars),
+    tailChars: z.number().step(1).min(0).default(DEFAULTS.tailChars),
+    nativeTriggerTokens: z.number().step(1).min(1).required(false),
+    nativeTargetTokens: z.number().step(1).min(1).required(false),
+    freshTriggerTokens: z.number().step(1).min(1).required(false),
+    freshTargetTokens: z.number().step(1).min(1).required(false),
+    aggregateTriggerTokens: z.number().step(1).min(1).required(false),
+    aggregateTargetTokens: z.number().step(1).min(1).required(false),
+    historyTriggerTokens: z.number().step(1).min(1).required(false),
+    historyKeepRecentToolCalls: z.number().step(1).min(0).required(false),
+    historyKeepRecentTokens: z.number().step(1).min(0).required(false),
+    historyMinReclaimTokens: z.number().step(1).min(1).required(false),
+    autoCompactThresholdPercent: z.number().step(1).min(50).max(90).required(false),
+  })
+
+  /** Consolidated per-session mutable state. */
+  readonly state: PrunerState
+
+  constructor(ctx: Context, config: ToolResultPruneConfig = {}) {
+    super(ctx, 'toolResultPruner')
+    ctx.inject(['tools', 'systemPrompt'], recoveryCtx => {
+      installContextCompressionRetrieve(recoveryCtx)
+    })
+    this.state = {
+      config: resolveConfig(config),
+      sessionSettings: new WeakMap(),
+      firstExposure: new WeakMap(),
+      recoveryExemptions: new WeakMap(),
+      dedupeTables: new WeakMap(),
+      estimatorVerdicts: new WeakMap(),
+      estimatorFailures: new WeakMap(),
+      warnedFailures: new WeakMap(),
+      postflightDiagnostics: new WeakMap(),
+      activeRequestBoundaries: new WeakMap(),
+      tailTrimBoundaryAttempts: new WeakMap(),
+      policyResolutionAudits: new WeakMap(),
+    }
+
+    ctx.on('session/event', (session, event) => {
+      if (event.type === 'compaction/summary') {
+        emitCompressionAudit(ctx.logger, {
+          schemaVersion: 1,
+          kind: 'native-auto-compact',
+          sessionId: String(session.id),
+          manifestEventType: 'compaction/summary',
+          manifestSeq: event.seq,
+          reducer: 'llm-summary',
+          provider: event.data.provider,
+          model: event.data.model,
+          tokensBefore: event.data.shadowedTokenCount,
+          tokensAfter: null,
+        })
+        return
+      }
+      if (event.type === 'compaction/end') {
+        // TokenPilot-inspired A2: annotate the landed summary checkpoint with
+        // an Exact Sources locator block. Strictly after compaction/end so no
+        // open-compaction invariant ever observes the rewrite.
+        try {
+          this.attachSummaryLocator(session, event.data.compactionId)
+        } catch (error: unknown) {
+          this.auditFailure(session, 'pressure', 'summary-locator', error)
+          ctx.logger.warn('context-compression summary locator failed open: %o', error)
+        }
+      }
+    })
+
+    // This is the true first-exposure boundary available in the Harness:
+    // the preceding step's results are already durable, the new step is open,
+    // and the next model request has not yet derived its history.
+    ctx.on('agent/pre-step', async ({ agent, signal, turn, step }, next) => {
+      const boundary = {}
+      this.state.activeRequestBoundaries.set(agent.session, boundary)
+      try {
+        if (!signal.aborted) {
+          try {
+            // Only the immediately preceding step can contain results that have
+            // not yet been exposed. This freezes both REDUCE and KEEP decisions:
+            // older original events are never reconsidered after a profile change.
+            this.runRequestBoundary(agent.session, turn, step - 1, signal)
+          } catch (error: unknown) {
+            this.auditFailure(agent.session, 'fresh', 'request-boundary', error)
+            ctx.logger.warn('context-compression fresh pass failed open: %o', error)
+          }
+        }
+        return await next()
+      } finally {
+        if (this.state.activeRequestBoundaries.get(agent.session) === boundary) {
+          this.state.activeRequestBoundaries.delete(agent.session)
+        }
+      }
+    }, { prepend: true })
+
+    ctx.on('agent/turn-stopping', ({ agent, turn, signal }) => {
+      if (signal.aborted) return
+      try {
+        const step = latestCompletedToolStep(agent.session, turn)
+        if (step !== undefined) this.runRequestBoundary(agent.session, turn, step, signal)
+      } catch (error: unknown) {
+        this.auditFailure(agent.session, 'fresh', 'terminal-pass', error)
+        ctx.logger.warn('context-compression terminal pass failed open: %o', error)
+      }
+      // TokenPilot-inspired E1: advisory estimator pass, strictly off the
+      // synchronous chain. Verdicts only feed the next pressure pass.
+      void this.postflightEstimatorPass(agent.session, signal).catch(() => undefined)
+    })
+  }
+
+  /**
+   * Measure text content in Unicode code points; non-text blocks cost zero.
+   * @param blocks - tool-result content to measure.
+   * @returns total Unicode code points across text blocks.
+   */
+  measureContent(blocks: readonly ContentBlock[]): number {
+    return measureContent(blocks)
+  }
+
+  /**
+   * Apply the configured native head/middle/tail transform.
+   * @param blocks - original tool-result content.
+   * @returns reduced content, or `null` when no reduction is required.
+   */
+  pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null {
+    return nativePruneContent(
+      blocks,
+      this.state.config.headChars + codePointLength(PRUNE_MARKER) + this.state.config.tailChars,
+      this.state.config.headChars,
+      this.state.config.tailChars,
+    )
+  }
+
+  /**
+   * Run one stable-surface pass. `fresh` is invoked before every request and
+   * only reduces original oversized results. `pressure` is called by
+   * compaction-basic and may additionally age old results at one high-water.
+   * @param session - session whose current tool-result surface may be rewritten.
+   * @param options - pass stage and optional completed-step coordinates.
+   * @returns landed replacements and aggregate Unicode-code-point savings.
+   */
+  pruneSession(session: Session, options: PruneSessionOptions = {}): PruneResult {
+    const stage = options.stage ?? 'pressure'
+    // External callers (compaction-basic) do not carry routed capacity; the
+    // runtime resolves it itself so the frozen Auto Compact linkage and the
+    // Custom percentage policy see one consistent context window.
+    const contextWindowTokens = options.contextWindowTokens ?? this.contextWindowForRequest(session)
+    const policy = this.activePolicy(session, contextWindowTokens, stage)
+    if (policy === undefined) return emptyResult()
+    const profile = policy.profile
+    const view = measureForCompaction(this.ctx, session)
+    if (stage === 'fresh') return this.decideFreshStep(session, options, policy, view)
+    if (profile === 'off') return emptyResult()
+
+    const landed: PrunedEntry[] = []
+    if (policy.nativeToolResultEnabled) {
+      const candidates = this.snapshot(session, view)
+      const eligible = candidates.filter(candidate => !this.isRecoveryExempt(session, candidate))
+      const exactUnavailable = eligible.some(candidate => candidate.count.kind !== 'exact-tokenizer')
+      if (exactUnavailable) {
+        this.warnExactUnavailable(session, view, 'native')
+      }
+      const planned = eligible
+        .map(candidate => this.planNative(candidate, session, stage, policy, view))
+        .filter((entry): entry is PlannedReplacement => entry !== null)
+      landed.push(...this.landAll(session, planned))
+      if (landed.length === 0) {
+        const exact = eligible.flatMap(candidate => candidate.count.kind === 'exact-tokenizer'
+          ? [candidate.count.tokens] : [])
+        this.auditComponent(session, policy, 'native-tool-result', 'pressure', 'skipped',
+          exactUnavailable ? 'exact-tokenizer-unavailable'
+            : exact.length === 0 ? 'no-tool-result-candidates'
+              : Math.max(...exact) <= policy.nativeTriggerTokens ? 'at-or-below-trigger'
+                : planned.length === 0 ? 'no-valid-reduction'
+                  : 'recovery-tool-unavailable', {
+            measurementKind: exactUnavailable ? 'unavailable' : 'exact-tokenizer',
+            ...(exact.length === 0 ? {} : { currentTokens: Math.max(...exact) }),
+            triggerTokens: policy.nativeTriggerTokens,
+            targetTokens: policy.nativeTargetTokens,
+          })
+      }
+      return summarize(landed)
+    }
+
+    let historyOutcome: HistoryPlanOutcome = { kind: 'planned', plans: [] }
+    let historyAllowed = false
+    if (policy.historyMode === 'adaptive') {
+      historyOutcome = this.planHistoricalAging(session, policy, view)
+      // Adaptive cost authority is meaningful only after the structural
+      // planner has formed a real batch. A planning skip keeps its own reason
+      // (for example exact-tokenizer-unavailable) and never becomes a false
+      // adaptive-cost-rejected decision merely because it has zero plans.
+      if (historyOutcome.kind === 'planned') {
+        const capacityPressure = this.capacityPressureActive(session, view, policy)
+        historyAllowed = this.adaptiveHistoryAllowed(
+          session,
+          view,
+          historyOutcome.plans,
+          capacityPressure,
+        )
+        if (historyAllowed) {
+          landed.push(...this.landAll(session, historyOutcome.plans))
+        }
+      }
+    } else {
+      historyAllowed = this.historyAllowed(session, policy, view)
+      if (historyAllowed) {
+        historyOutcome = this.planHistoricalAging(session, policy, view)
+        if (historyOutcome.kind === 'planned') {
+          landed.push(...this.landAll(session, historyOutcome.plans))
+        }
+      }
+    }
+    if (!landed.some(entry => entry.stage === 'pressure')) {
+      this.auditHistoryEvaluation(session, policy, view, historyAllowed, historyOutcome)
+    }
+    if (policy.tailTrim?.enabled === true) {
+      const tailView = measureForCompaction(this.ctx, session)
+      this.landOldestTailTrimGroup(session, policy, tailView)
+    } else {
+      this.auditComponent(session, policy, 'tail-trim', 'pressure', 'disabled', 'profile-policy')
+    }
+    return summarize(landed)
+  }
+
+  private activeSettings(session: Session): ContextCompressionSettings {
+    const frozen = this.state.sessionSettings.get(session)
+    if (frozen !== undefined) return frozen
+    // Harness 0.1.1 brands namespace values through a helper while 0.1.2
+    // validates the same public literal at its SettingsProvider boundary.
+    const settings = this.ctx.get('settings')?.get(CONTEXT_COMPRESSION_SETTINGS_NAMESPACE as never)
+    let resolved: ContextCompressionSettings
+    let settingsSource: 'host-settings' | 'plugin-config-fallback' = settings === undefined
+      ? 'plugin-config-fallback'
+      : 'host-settings'
+    let autoCompactThresholdSource: 'generation-config' | 'host-settings' | 'schema-default'
+      = settings === undefined ? 'schema-default' : 'host-settings'
+    let settingsInvalidFallback: 'lossless-off' | undefined
+    try {
+      resolved = settings === undefined
+        ? ContextCompressionSettingsSchema({ profile: this.state.config.profile } as never)
+        // Validate the Host value BEFORE cloning: structuredClone normalizes
+        // class/exotic prototypes to Object.prototype and would otherwise
+        // erase the very boundary the parser is responsible for enforcing.
+        : parseContextCompressionSettings(settings)
+    } catch (error: unknown) {
+      // A malformed persisted document must fail open LOSSLESSLY: freezing the
+      // deployment default could silently re-enable lossy compression the
+      // user never chose (for example a stored `off` plus an unknown key), so
+      // the session freezes effectively off and keeps every original result.
+      const reason = error instanceof Error ? error.message : String(error)
+      this.auditFailure(session, 'pressure', 'policy-resolution', error)
+      this.warnOnce(
+        session,
+        `settings-invalid:${reason}`,
+        'context-compression froze this session effectively off because the stored settings document is invalid: %s',
+        reason,
+      )
+      resolved = ContextCompressionSettingsSchema({ profile: 'off' } as never)
+      settingsSource = 'plugin-config-fallback'
+      autoCompactThresholdSource = 'schema-default'
+      settingsInvalidFallback = 'lossless-off'
+    }
+    if (this.state.config.autoCompactThresholdPercent !== undefined) {
+      // The preset overlay froze this generation's threshold into the
+      // deployment config; it supersedes the live Host setting so Auto
+      // Compact and micro compact can never split across two thresholds.
+      resolved = {
+        ...resolved,
+        autoCompact: { thresholdPercent: this.state.config.autoCompactThresholdPercent },
+      }
+      autoCompactThresholdSource = 'generation-config'
+    }
+    const snapshot = deepFreeze(structuredClone(resolved))
+    this.state.sessionSettings.set(session, snapshot)
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'policy-frozen',
+      sessionId: String(session.id),
+      settingsSource,
+      autoCompactThresholdSource,
+      ...settingsInvalidFallback === undefined ? {} : { settingsInvalidFallback },
+      settings: snapshot,
+      deploymentConfig: this.state.config,
+    })
+    return snapshot
+  }
+
+  /**
+   * TokenPilot-inspired A2: replace the compaction summary checkpoint node
+   * with the same summary plus an Exact Sources locator block. Fails open:
+   * any unresolved shape (no trace, no checkpoint node, already annotated)
+   * leaves the summary untouched.
+   */
+  private attachSummaryLocator(session: Session, compactionId: string): void {
+    const policy = this.activePolicy(session)
+    if (policy?.presetOptions?.summaryLocator !== true) return
+    const events = sessionEvents(session)
+    const trace = findCompactionTrace(events, compactionId)
+    if (trace === undefined) return
+    const located = buildLocatorBlock(events, trace.summaryShadowedRange)
+    if (located === null) return
+    const block = located.text
+    // Locate the summary checkpoint surface node: the user/message replacement
+    // carrying this compaction's checkpoint provenance. Newest match wins.
+    let checkpointSeq: number | undefined
+    for (const seq of [...session.surface.nodes].reverse()) {
+      const event = events[seq]
+      if (event === undefined || event.type !== 'user/message') continue
+      const source = (event.data as { source?: { compactionId?: unknown } }).source
+      if (source === undefined || source === null) continue
+      if (source.compactionId !== compactionId) continue
+      checkpointSeq = seq
+      break
+    }
+    if (checkpointSeq === undefined) return
+    const original = events[checkpointSeq]
+    if (original?.type !== 'user/message') return
+    const data = original.data as UserMessage & { source?: unknown }
+    const content = data.content.map(block => ({ ...block })) as typeof data.content
+    const textBlocks = content.filter((block): block is Extract<(typeof content)[number], { type: 'text' }> => block.type === 'text')
+    const lastText = textBlocks.at(-1)
+    const marker = '## Exact Sources (locators)'
+    if (lastText === undefined) return
+    if (lastText.text.includes(marker)) return
+    lastText.text = `${lastText.text}\n\n${block}`
+    // Drop the checkpoint provenance: this replacement is a plain plugin-source
+    // user/message surface rewrite, not a new compaction checkpoint, and
+    // carrying the marker would fail the host's closed-transaction validation.
+    const replacement = createUserMessage({
+      content,
+      source: { kind: 'plugin', plugin: 'dsh-context-compression-improved-runtime' },
+    })
+    session.append('user/message', replacement, {
+      surfaceOp: { op: 'replace', start: checkpointSeq, end: checkpointSeq },
+      sourceEventSeqs: [checkpointSeq],
+    })
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'summary-locator',
+      sessionId: String(session.id),
+      profile: policy.profile,
+      checkpointSeq,
+      summarySeq: trace.summarySeq,
+      locatorChars: codePointLength(located.text),
+      spillFiles: located.spillFiles,
+      touchedFiles: located.touchedFiles,
+    })
+  }
+
+  /**
+   * TokenPilot-inspired E1: sample oversized historical reads and ask the
+   * auxiliary estimator whether their file state is still likely to be
+   * referenced. Fire-and-forget: never awaited on the pruning chain, failures
+   * back off exponentially per Session, verdicts only extend the rule-only
+   * superseded classification.
+   */
+  private async postflightEstimatorPass(session: Session, signal: AbortSignal): Promise<void> {
+    const policy = this.activePolicy(session)
+    const presetOptions = policy?.presetOptions
+    if (policy === undefined || presetOptions?.readState !== true) return
+    const estimatorMode = presetOptions.estimator?.mode ?? ''
+    if (estimatorMode === '') return
+    const failures = this.state.estimatorFailures.get(session)
+    if (isCoolingDown(failures, Date.now())) return
+
+    const events = sessionEvents(session)
+    const samples: EstimatorSample[] = []
+    const now = Date.now()
+    for (const candidate of this.snapshot(session, measureForCompaction(this.ctx, session))) {
+      if (samples.length >= 3) break
+      if (candidate.event.data.turn === undefined) continue
+      const tokens = exactTokens(candidate.count)
+      if (tokens === undefined || tokens <= policy.freshTriggerTokens) continue
+      const path = toolCallPath(candidate.call.arguments)
+      if (path === undefined) continue
+      if (isSupersededRead(events, candidate.seq, path)) continue
+      if (this.state.estimatorVerdicts.get(session)?.has(candidate.seq) === true) continue
+      samples.push({ seq: candidate.seq, path, turn: candidate.event.data.turn })
+    }
+    if (samples.length === 0) return
+
+    const estimator = new Estimator(this.ctx, this.activeSettings(session).presetOptions ?? {})
+    const answer = await estimator.ask(buildEstimatorSystemPrompt(), buildEstimatorUserPrompt(samples), signal)
+    const latencyMs = Date.now() - now
+    const ok = answer !== undefined && signal.aborted === false
+    let expired = 0
+    if (ok && answer !== undefined) {
+      let verdicts = this.state.estimatorVerdicts.get(session)
+      if (verdicts === undefined) {
+        verdicts = new Map()
+        this.state.estimatorVerdicts.set(session, verdicts)
+      }
+      for (const verdict of parseEstimatorAnswer(answer)) {
+        if (verdicts.has(verdict.seq)) continue
+        verdicts.set(verdict.seq, verdict.expired)
+        if (verdict.expired) expired += 1
+      }
+    } else {
+      const next: EstimatorFailures = {
+        failures: (failures?.failures ?? 0) + 1,
+        cooldownUntil: Date.now() + backoffCooldownMs((failures?.failures ?? 0) + 1),
+      }
+      this.state.estimatorFailures.set(session, next)
+    }
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'estimator-outcome',
+      sessionId: String(session.id),
+      profile: policy.profile,
+      channel: estimatorMode === 'host' ? 'host' : 'direct',
+      sampled: samples.length,
+      expired,
+      latencyMs,
+      ok,
+    })
+  }
+
+  private activePolicy(
+    session: Session,
+    contextWindowTokens?: number,
+    stage: PruneStage = 'pressure',
+  ): CompressionPolicy | undefined {
+    const settings = this.activeSettings(session)
+    try {
+      const policy = resolvePolicy(
+        this.state.config,
+        settings.profile,
+        settings.custom,
+        {
+          ...contextWindowTokens === undefined ? {} : { contextWindowTokens },
+          autoCompactThresholdPercent: settings.autoCompact.thresholdPercent,
+        },
+      )
+      // Route changes must produce a fresh audit record even when the policy
+      // object is unchanged, or the dedupe would hide a mid-session reroute.
+      const route = routeAuditFact(session)
+      const auditKey = JSON.stringify({
+        policy,
+        contextWindowTokens: contextWindowTokens ?? null,
+        route: route ?? null,
+      })
+      // Deduplicate only CONSECUTIVE identical resolutions: a permanent set
+      // would hide an A -> B -> A reroute's third record.
+      if (this.state.policyResolutionAudits.get(session) !== auditKey) {
+        this.state.policyResolutionAudits.set(session, auditKey)
+        // Deployment config overrides win over the Auto Compact linkage, so a
+        // standard profile whose History watermarks were replaced must not
+        // audit itself as purely linkage-derived.
+        const overriddenLinkedFields = ([
+          'historyTriggerTokens',
+          'historyKeepRecentTokens',
+          'historyMinReclaimTokens',
+        ] as const).filter(key => this.state.config[key] !== undefined).length
+        emitCompressionAudit(this.ctx.logger, {
+          schemaVersion: 1,
+          kind: 'policy-resolved',
+          sessionId: String(session.id),
+          policy,
+          ...contextWindowTokens === undefined ? {} : { contextWindowTokens },
+          coordination: {
+            thresholdPercent: settings.autoCompact.thresholdPercent,
+            ...policy.autoCompactTokens === undefined ? {} : { autoCompactTokens: policy.autoCompactTokens },
+            ...policy.microDeadlineTokens === undefined ? {} : { microDeadlineTokens: policy.microDeadlineTokens },
+            paramSource: settings.profile === 'custom'
+              ? 'custom-manual'
+              : overriddenLinkedFields === 3 ? 'deployment-override'
+                : overriddenLinkedFields > 0 ? 'mixed'
+                  : policy.microDeadlineTokens === undefined ? 'fixed-preset' : 'auto-compact-linked',
+          },
+          ...route === undefined ? {} : { route },
+          ...route === undefined ? {} : tokenizerAuditFact(route),
+        })
+      }
+      return policy
+    } catch (error: unknown) {
+      const reason = error instanceof Error ? error.message : String(error)
+      this.auditFailure(session, stage, 'policy-resolution', error)
+      this.warnOnce(
+        session,
+        `custom-policy:${settings.profile}:${reason}`,
+        'context-compression kept original tool results because the Custom policy is not effective: %s',
+        reason,
+      )
+      return undefined
+    }
+  }
+
+
+
+  private contextWindowForRequest(
+    session: Session,
+  ): number | undefined {
+    const settings = this.activeSettings(session)
+    // History linkage needs routed capacity for standard profiles, and the
+    // Custom percentage policy needs it for context-percent documents. Off and
+    // Native never link, and token-unit Custom stays manual.
+    if (settings.profile === 'off' || settings.profile === 'native') return undefined
+    if (settings.profile === 'custom' && settings.custom.unit !== 'context-percent') return undefined
+    const config = session.requestHeader()?.config
+    const routed = session.requestContext()
+    if (config === undefined || config.provider.length === 0 || config.model.length === 0 || routed === undefined) {
+      return undefined
+    }
+    if (routed.provider !== config.provider || routed.model !== config.model) {
+      this.warnOnce(
+        session,
+        `custom-context-window-route:${config.provider}\0${config.model}`,
+        'context-compression kept the context-linked policy inactive because durable route capacity belongs to %s/%s, not %s/%s',
+        routed.provider,
+        routed.model,
+        config.provider,
+        config.model,
+      )
+      return undefined
+    }
+    if (!Number.isSafeInteger(routed.contextWindow) || routed.contextWindow === undefined || routed.contextWindow <= 0) {
+      this.warnOnce(
+        session,
+        `custom-context-window-capacity:${config.provider}\0${config.model}`,
+        'context-compression kept the context-linked policy inactive because %s/%s has no positive durable context capacity',
+        config.provider,
+        config.model,
+      )
+      return undefined
+    }
+    return routed.contextWindow
+  }
+
+  private runRequestBoundary(
+    session: Session,
+    turn: number,
+    step: number,
+    signal: AbortSignal,
+  ): void {
+    const contextWindowTokens = this.contextWindowForRequest(session)
+    if (signal.aborted) return
+    const policy = this.activePolicy(session, contextWindowTokens, 'fresh')
+    if (policy === undefined) return
+    const capacity = contextWindowTokens === undefined ? {} : { contextWindowTokens }
+    this.pruneSession(session, { stage: 'fresh', freshTurn: turn, freshStep: step, ...capacity })
+    if (policy.historyMode !== 'disabled' || policy.tailTrim?.enabled === true) {
+      this.pruneSession(session, { stage: 'pressure', ...capacity })
+    }
+  }
+
+  /** Resolve historical-aging authority without accepting caller-supplied elevation. */
+  private historyAllowed(session: Session, policy: CompressionPolicy, view: CompactionTokenView): boolean {
+    switch (policy.historyMode) {
+      case 'disabled':
+        return false
+      case 'routine':
+        return true
+      case 'capacity-pressure':
+        return this.capacityPressureActive(session, view, policy)
+      case 'adaptive':
+        return false
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        return assertNever(policy.historyMode, 'history mode')
+    }
+  }
+
+  /**
+   * Match the compaction-basic pressure gate using public durable data. The
+   * frozen Auto Compact deadline `D = floor(A x 0.875)` replaces the legacy
+   * fixed 0.7 ratio once the standard-profile linkage resolved; without
+   * linkage the 0.7 ratio is the documented fallback and reproduces the
+   * previous behavior.
+   */
+  private capacityPressureActive(
+    session: Session,
+    view: CompactionTokenView,
+    policy: CompressionPolicy,
+  ): boolean {
+    const deadline = policy.microDeadlineTokens
+    if (deadline !== undefined) return view.totalTokens >= deadline
+    const header = session.requestHeader()?.config
+    const routed = session.requestContext()
+    const contextWindow = routed?.contextWindow
+    if (header === undefined || routed === undefined
+      || routed.provider !== header.provider
+      || routed.model !== header.model
+      || contextWindow === undefined
+      || !Number.isSafeInteger(contextWindow)
+      || contextWindow <= 0) return false
+    return view.totalTokens >= Math.floor(contextWindow * CAPACITY_PRESSURE_RATIO)
+  }
+
+  /** Emit one bounded, independently correlatable postflight cost diagnostic per completed attempt. */
+  private logAdaptivePostflight(session: Session, usage: ObservedPromptUsage): void {
+    const attemptId = String(usage.attemptId)
+    if (this.state.postflightDiagnostics.get(session) === attemptId) return
+    this.state.postflightDiagnostics.set(session, attemptId)
+
+    const key = usage.key
+    let priceRecord: Readonly<Record<string, unknown>> | undefined
+    let cost: ReturnType<typeof priceOfficialDeepSeekUsage> | { readonly kind: 'unpriced'; readonly reason: string }
+    if (key === undefined) {
+      cost = { kind: 'unpriced', reason: 'measurement key unavailable' }
+    } else if (usage.responseModelId !== key.modelId) {
+      cost = { kind: 'unpriced', reason: 'response model mismatch or unavailable' }
+    } else if (usage.observedOutputTokens === undefined) {
+      cost = { kind: 'unpriced', reason: 'output token count unavailable' }
+    } else if (usage.cacheStatus !== 'complete'
+      || usage.cacheReadTokens === undefined
+      || usage.cacheMissTokens === undefined) {
+      cost = { kind: 'unpriced', reason: 'complete cache split unavailable' }
+    } else {
+      const startedAt = new Date(usage.startedAtMs)
+      const completedAt = new Date(usage.completedAtMs)
+      const resolution = resolveOfficialDeepSeekPrice({
+        provider: key.provider,
+        baseUrlClass: key.baseUrlClass,
+        apiRoute: key.apiRoute,
+        modelId: key.modelId,
+        currency: 'USD',
+        at: startedAt,
+      })
+      if (resolution.kind === 'priced') {
+        priceRecord = {
+          catalogVersion: resolution.record.catalogVersion,
+          checkedAt: resolution.record.checkedAt,
+          sourceUrl: resolution.record.sourceUrl,
+          currency: resolution.record.currency,
+          modelId: resolution.record.modelId,
+          apiRoute: resolution.record.apiRoute,
+          startBand: resolution.record.band,
+        }
+      }
+      cost = priceOfficialDeepSeekUsage({
+        provider: key.provider,
+        baseUrlClass: key.baseUrlClass,
+        apiRoute: key.apiRoute,
+        modelId: key.modelId,
+        currency: 'USD',
+        startedAt,
+        completedAt,
+        usage: {
+          cacheReadTokens: usage.cacheReadTokens,
+          cacheMissTokens: usage.cacheMissTokens,
+          outputTokens: usage.observedOutputTokens,
+        },
+      })
+    }
+
+    this.ctx.logger.debug(`context-compression adaptive postflight ${JSON.stringify({
+      sessionId: String(session.id),
+      providerRequestOrdinal: Number(usage.providerRequestOrdinal),
+      attemptId,
+      startedAtMs: usage.startedAtMs,
+      completedAtMs: usage.completedAtMs,
+      measurementKind: usage.measurement.kind,
+      catalogVersion: DEEPSEEK_OFFICIAL_PRICE_CATALOG_VERSION,
+      ...(priceRecord === undefined ? {} : { priceRecord }),
+      usage: {
+        promptTokens: usage.observedPromptTokens,
+        ...(usage.observedOutputTokens === undefined ? {} : { outputTokens: usage.observedOutputTokens }),
+        cacheStatus: usage.cacheStatus ?? 'unknown',
+        ...(usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: usage.cacheReadTokens }),
+        ...(usage.cacheMissTokens === undefined ? {} : { cacheMissTokens: usage.cacheMissTokens }),
+      },
+      cost,
+    })}`)
+  }
+
+  /** Decide one already-planned History batch from adjacent request-level facts only. */
+  private adaptiveHistoryAllowed(
+    session: Session,
+    view: CompactionTokenView,
+    plans: readonly PlannedReplacement[],
+    capacityPressure: boolean,
+  ): boolean {
+    const log = (
+      allowHistory: boolean,
+      reason: string,
+      detail: Readonly<Record<string, unknown>> = {},
+    ): boolean => {
+      this.ctx.logger.debug(`context-compression adaptive ${JSON.stringify({
+        sessionId: String(session.id),
+        allowHistory,
+        reason,
+        catalogVersion: DEEPSEEK_OFFICIAL_PRICE_CATALOG_VERSION,
+        ...detail,
+      })}`)
+      return allowHistory
+    }
+    const usage = view.lastCompletedUsage
+    if (usage !== undefined) this.logAdaptivePostflight(session, usage)
+    if (plans.length === 0) return false
+    if (capacityPressure) return log(true, 'capacity-override')
+
+    const currentKey = view.latestEnvelopeKey
+    if (usage === undefined) return log(false, 'usage-unavailable')
+    if (usage.key === undefined || currentKey === undefined) {
+      return log(false, 'measurement-key-unavailable')
+    }
+    if (!sameProviderMeasurementKey(usage.key, currentKey)) {
+      return log(false, 'measurement-key-mismatch')
+    }
+    if (usage.responseModelId !== usage.key.modelId) {
+      return log(false, 'response-model-mismatch-or-unavailable')
+    }
+    if (usage.cacheStatus !== 'complete'
+      || usage.cacheReadTokens === undefined
+      || usage.cacheMissTokens === undefined) {
+      return log(false, 'cache-split-incomplete')
+    }
+
+    const price = resolveOfficialDeepSeekPrice({
+      provider: usage.key.provider,
+      baseUrlClass: usage.key.baseUrlClass,
+      apiRoute: usage.key.apiRoute,
+      modelId: usage.key.modelId,
+      currency: 'USD',
+      at: new Date(),
+    })
+    if (price.kind === 'unpriced') return log(false, `adaptive-unknown-price:${price.reason}`)
+
+    const exactReclaimedTokens = plans.reduce(
+      (sum, plan) => sum + plan.tokensBefore - plan.tokensAfter,
+      0,
+    )
+    const earliestChangedSeq = Math.min(...plans.map(plan => plan.candidate.seq))
+    const bounds = deriveAdaptiveTokenBounds({
+      exactReclaimedTokens,
+      earliestChangedSeq,
+      previousPromptTokens: usage.observedPromptTokens,
+      expectedTokenizerRevision: usage.key.tokenizerRevision,
+      previousRequestMeasurement: usage.measurement,
+      measuredNodes: view.measuredNodes,
+    })
+    const decision = decideConservativeAdaptive({
+      capacityPressure: false,
+      bounds,
+      inputCacheHitRate: price.record.inputCacheHit,
+      inputCacheMissRate: price.record.inputCacheMiss,
+      observedCacheReadTokens: usage.cacheReadTokens,
+    })
+    return log(decision.allowHistory, decision.reason, {
+      priceBand: price.record.band,
+      observedPromptTokens: usage.observedPromptTokens,
+      observedCacheReadTokens: usage.cacheReadTokens,
+      bounds,
+      ...'minimumRemovalValue' in decision
+        ? { minimumRemovalValue: decision.minimumRemovalValue }
+        : {},
+      ...'maximumCacheLossPenalty' in decision
+        ? { maximumCacheLossPenalty: decision.maximumCacheLossPenalty }
+        : {},
+    })
+  }
+
+  private decisions(session: Session): Set<number> {
+    let decisions = this.state.firstExposure.get(session)
+    if (decisions === undefined) {
+      decisions = new Set()
+      this.state.firstExposure.set(session, decisions)
+    }
+    return decisions
+  }
+
+  /**
+   * TokenPilot-style skipReduction: recovery tool output is permanently exempt
+   * from every reduction pass so retrieved content can never enter a
+   * compress-restore-oscillation loop. A call-name match covers the built-in
+   * recovery tool; the per-session set admits future recovery paths.
+   */
+  private isRecoveryExempt(session: Session, candidate: SnapshotCandidate): boolean {
+    if (candidate.call.name === 'context_compression_retrieve') return true
+    return this.state.recoveryExemptions.get(session)?.has(candidate.seq) ?? false
+  }
+
+  /** Register a result seq as permanently exempt from further reduction. */
+  private grantRecoveryExemption(session: Session, seq: number): void {
+    let exemptions = this.state.recoveryExemptions.get(session)
+    if (exemptions === undefined) {
+      exemptions = new Set()
+      this.state.recoveryExemptions.set(session, exemptions)
+    }
+    exemptions.add(seq)
+  }
+
+  private decideFreshStep(
+    session: Session,
+    options: PruneSessionOptions,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): PruneResult {
+    if (options.freshTurn === undefined || options.freshStep === undefined) {
+      this.auditComponent(session, policy, 'fresh', 'fresh',
+        policy.freshEnabled ? 'skipped' : 'disabled',
+        policy.freshEnabled ? 'missing-completed-step-coordinates' : 'profile-policy')
+      this.auditComponent(session, policy, 'aggregate', 'fresh',
+        policy.aggregateEnabled ? 'skipped' : 'disabled',
+        policy.aggregateEnabled ? 'missing-completed-step-coordinates' : 'profile-policy')
+      return emptyResult()
+    }
+    const decisions = this.decisions(session)
+    const candidates = this.snapshot(session, view).filter(candidate =>
+      typeof candidate.event.surfaceOp !== 'object'
+      && candidate.event.data.turn === options.freshTurn
+      && candidate.event.data.step === options.freshStep
+      && !decisions.has(candidate.seq))
+    if (candidates.length === 0) {
+      this.auditComponent(session, policy, 'fresh', 'fresh',
+        policy.freshEnabled ? 'skipped' : 'disabled',
+        policy.freshEnabled ? 'no-new-tool-result-candidates' : 'profile-policy')
+      this.auditComponent(session, policy, 'aggregate', 'fresh',
+        policy.aggregateEnabled ? 'skipped' : 'disabled',
+        policy.aggregateEnabled ? 'no-new-tool-result-candidates' : 'profile-policy')
+      return emptyResult()
+    }
+
+    const plans = new Map<number, PlannedReplacement>()
+    let freshPlanned = 0
+    const dedupeEnabled = policy.presetOptions?.dedupeToolResults === true
+    const exactCandidateTokens = candidates.map(candidate => exactTokens(candidate.count))
+    const exactAvailable = exactCandidateTokens.every(tokens => tokens !== undefined)
+    const maxCandidateTokens = exactAvailable
+      ? Math.max(...exactCandidateTokens as number[])
+      : undefined
+    if (policy.freshEnabled) {
+      if (candidates.some(candidate => candidate.call.name !== 'context_compression_retrieve'
+        && candidate.count.kind !== 'exact-tokenizer')) {
+        this.warnExactUnavailable(session, view, 'fresh')
+      }
+      for (const candidate of candidates) {
+        if (this.isRecoveryExempt(session, candidate)) continue
+        if (dedupeEnabled) {
+          const dedupePlan = this.planDedupe(candidate, session, policy, view)
+          if (dedupePlan !== null) {
+            plans.set(candidate.seq, dedupePlan)
+            continue
+          }
+        }
+        const plan = this.planFresh(candidate, session, policy, view)
+        if (plan !== null) {
+          plans.set(candidate.seq, plan)
+          freshPlanned += 1
+        }
+      }
+    }
+    let aggregateInputTokens: number | undefined
+    let aggregatePlanned = 0
+    if (policy.aggregateEnabled) {
+      const aggregateAvailable = exactAvailable
+      if (!aggregateAvailable) this.warnExactUnavailable(session, view, 'aggregate')
+      let total = aggregateAvailable
+        ? candidates.reduce((sum, candidate) => sum + (plans.get(candidate.seq)?.tokensAfter
+          ?? exactTokens(candidate.count) ?? 0), 0)
+        : 0
+      if (aggregateAvailable) aggregateInputTokens = total
+      if (aggregateAvailable && total > policy.aggregateTriggerTokens) {
+        const remaining = candidates
+          .filter(candidate => !this.isRecoveryExempt(session, candidate))
+          .sort((a, b) => Number(isError(a)) - Number(isError(b))
+            || (plans.get(b.seq)?.tokensAfter ?? exactTokens(b.count) ?? 0)
+              - (plans.get(a.seq)?.tokensAfter ?? exactTokens(a.count) ?? 0))
+        for (const candidate of remaining) {
+          const previous = plans.get(candidate.seq)
+          const plan = this.planAggregate(candidate, session, view)
+          const previousTokens = previous?.tokensAfter ?? exactTokens(candidate.count) ?? 0
+          if (plan === null || plan.tokensAfter >= previousTokens) continue
+          plans.set(candidate.seq, plan)
+          aggregatePlanned += 1
+          total -= previousTokens - plan.tokensAfter
+          if (total <= policy.aggregateTargetTokens) break
+        }
+        if (total > policy.aggregateTargetTokens) {
+          this.ctx.logger.warn(
+            'context-compression fresh aggregate residual: %d tokens exceed target %d',
+            total,
+            policy.aggregateTargetTokens,
+          )
+        }
+      }
+    }
+
+    const landed = this.landAll(session, candidates
+      .map(candidate => plans.get(candidate.seq))
+      .filter((plan): plan is PlannedReplacement => plan !== undefined))
+    const freshLanded = landed.some(entry => entry.stage === 'fresh'
+      && plans.get(entry.originalSeq)?.component === 'fresh')
+    const aggregateLanded = landed.some(entry => entry.stage === 'fresh'
+      && plans.get(entry.originalSeq)?.component === 'aggregate')
+    if (!freshLanded) {
+      this.auditComponent(session, policy, 'fresh', 'fresh',
+        policy.freshEnabled ? 'skipped' : 'disabled',
+        !policy.freshEnabled ? 'profile-policy'
+          : !exactAvailable ? 'exact-tokenizer-unavailable'
+            : (maxCandidateTokens ?? 0) <= policy.freshTriggerTokens ? 'at-or-below-trigger'
+              : freshPlanned > 0 && aggregatePlanned > 0 ? 'superseded-by-aggregate'
+                : freshPlanned === 0 ? 'no-valid-reduction'
+                  : 'recovery-tool-unavailable', {
+          measurementKind: exactAvailable ? 'exact-tokenizer' : 'unavailable',
+          ...(maxCandidateTokens === undefined ? {} : { currentTokens: maxCandidateTokens }),
+          triggerTokens: policy.freshTriggerTokens,
+          targetTokens: policy.freshTargetTokens,
+        })
+    }
+    if (!aggregateLanded) {
+      this.auditComponent(session, policy, 'aggregate', 'fresh',
+        policy.aggregateEnabled ? 'skipped' : 'disabled',
+        !policy.aggregateEnabled ? 'profile-policy'
+          : !exactAvailable ? 'exact-tokenizer-unavailable'
+            : (aggregateInputTokens ?? 0) <= policy.aggregateTriggerTokens ? 'at-or-below-trigger'
+              : aggregatePlanned === 0 ? 'no-valid-reduction'
+                : 'recovery-tool-unavailable', {
+          measurementKind: exactAvailable ? 'exact-tokenizer' : 'unavailable',
+          ...(aggregateInputTokens === undefined ? {} : { currentTokens: aggregateInputTokens }),
+          triggerTokens: policy.aggregateTriggerTokens,
+          targetTokens: policy.aggregateTargetTokens,
+        })
+    }
+    for (const candidate of candidates) decisions.add(candidate.seq)
+    return summarize(landed)
+  }
+
+  private snapshot(session: Session, view: CompactionTokenView): SnapshotCandidate[] {
+    const events = sessionEvents(session)
+    const calls = new Map<string, ToolCallInfo>()
+    for (const event of events) {
+      if (event.type === 'tool/call') {
+        calls.set(event.data.callId, { name: event.data.name, arguments: event.data.arguments })
+      }
+    }
+    const candidates: SnapshotCandidate[] = []
+    const measured = new Map(view.measuredNodes.map(node => [node.seq, node.count]))
+    const projectionPrices = new Map(view.nodes.map(node => [node.seq, node.tokens]))
+    for (const seq of [...session.surface.nodes]) {
+      const event = events[seq]
+      if (event?.type !== 'tool/result') continue
+      const shadowedHeuristicTokenCount = projectionPrices.get(seq)
+      if (shadowedHeuristicTokenCount === undefined) {
+        throw new Error(`surface node ${String(seq)} is absent from the atomic legacy projection`)
+      }
+      const content = event.data.message.content[0].content
+      candidates.push({
+        seq,
+        event,
+        call: calls.get(event.data.message.source.callId) ?? { name: 'unknown', arguments: '{}' },
+        count: onlyTextBlocks(content) === null
+          ? unavailableCount(`surface node ${String(seq)} contains unsupported rich tool-result content`)
+          : measured.get(seq) ?? unavailableCount(`surface node ${String(seq)} is absent from the atomic token view`),
+        shadowedHeuristicTokenCount,
+        characterPressure: pressureCost(content),
+      })
+    }
+    return candidates
+  }
+
+  private planNative(
+    candidate: SnapshotCandidate,
+    session: Session,
+    stage: PruneStage,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): PlannedReplacement | null {
+    if (this.isRecoveryExempt(session, candidate)) return null
+    const tokensBefore = exactTokens(candidate.count)
+    if (tokensBefore === undefined || tokensBefore <= policy.nativeTriggerTokens) return null
+    const result = candidate.event.data.message.content[0]
+    if (onlyTextBlocks(result.content) === null) return null
+    const sourceSeq = rootToolResultSeq(session, candidate.seq)
+    const marker = recoveryMarker(sourceRefFn(session, sourceSeq), 'tool result middle pruned')
+    let head = this.state.config.headChars
+    let tail = this.state.config.tailChars
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      const threshold = head + codePointLength(marker) + tail
+      const content = nativePruneContent(result.content, threshold, head, tail, marker)
+      if (content !== null) {
+        const plan = this.plan(
+          candidate,
+          content,
+          sourceSeq,
+          'native-head-tail',
+          stage,
+          'native-tool-result',
+          undefined,
+          view,
+        )
+        if (plan !== null && plan.tokensAfter <= policy.nativeTargetTokens) return plan
+      }
+      if (head === 0 && tail === 0) break
+      head = Math.floor(head / 2)
+      tail = Math.floor(tail / 2)
+    }
+    return this.planAggregate(
+      candidate,
+      session,
+      view,
+      'native-whole-result',
+      stage,
+      policy.nativeTargetTokens,
+      'native-tool-result',
+    )
+  }
+
+  /**
+   * TokenPilot-inspired A1: replace a byte-identical repeat of an earlier
+   * oversized tool result with a pointer to its first occurrence. The first
+   * occurrence's hash is always recorded so later repeats can point at the
+   * append-only original event even after the surface copy is reduced.
+   */
+  private planDedupe(
+    candidate: SnapshotCandidate,
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): PlannedReplacement | null {
+    if (typeof candidate.event.surfaceOp === 'object') return null
+    const result = candidate.event.data.message.content[0]
+    const text = flattenPlainText(result.content)
+    if (text === undefined) return null
+    const tokensBefore = exactTokens(candidate.count)
+    if (tokensBefore === undefined || tokensBefore <= policy.freshTriggerTokens) return null
+    let table = this.state.dedupeTables.get(session)
+    if (table === undefined) {
+      table = new DedupeTable()
+      this.state.dedupeTables.set(session, table)
+    }
+    const hash = dedupeHash(text, 'trim-eol')
+    const entry = table.get(hash)
+    if (entry !== undefined && entry.seq !== candidate.seq) {
+      const placeholder = dedupePlaceholder(entry, codePointLength(text))
+      const plan = this.plan(
+        candidate,
+        [{ type: 'text', text: placeholder }],
+        entry.seq,
+        'dedupe-pointer',
+        'fresh',
+        'fresh',
+        undefined,
+        view,
+        { noNetSavingsGuard: true },
+      )
+      if (plan !== null) return plan
+      return null
+    }
+    if (entry === undefined) {
+      table.record(hash, {
+        seq: candidate.seq,
+        sourceRef: sourceRefFn(session, candidate.seq),
+        toolName: candidate.call.name,
+        originalChars: codePointLength(text),
+      })
+    }
+    return null
+  }
+
+  private planFresh(
+    candidate: SnapshotCandidate,
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): PlannedReplacement | null {
+    // A replace event already reflects one frozen first-exposure decision. The
+    // pre-step coordinate filter prevents previously-kept originals from ever
+    // being reconsidered after their first request.
+    if (typeof candidate.event.surfaceOp === 'object') return null
+    const result = candidate.event.data.message.content[0]
+    const tokensBefore = exactTokens(candidate.count)
+    if (tokensBefore === undefined || tokensBefore <= policy.freshTriggerTokens) return null
+    const sourceSeq = candidate.seq
+    const sourceRef = sourceRefFn(session, sourceSeq)
+    const textBlock = onlyTextBlock(result.content)
+    if (textBlock !== null) {
+      let budgetChars = Math.max(1, Math.floor(codePointLength(textBlock.text) * 0.75))
+      const codeSkeleton = this.activeSettings(session).codeSkeleton.enabled
+      for (let attempt = 0; attempt < 10; attempt += 1) {
+        const output = reduceFreshToolResult({
+          toolName: candidate.call.name,
+          argumentsText: candidate.call.arguments,
+          text: textBlock.text,
+          budgetChars,
+          sourceRef,
+          isError: result.isError === true || candidate.event.data.error !== undefined,
+          codeSkeleton,
+        })
+        if (output !== null) {
+          const plan = this.plan(
+            candidate,
+            [{ ...textBlock, text: output.text }],
+            sourceSeq,
+            output.reducer,
+            'fresh',
+            'fresh',
+            undefined,
+            view,
+            { noNetSavingsGuard: policy.presetOptions?.noNetSavingsGuard === true },
+          )
+          if (plan !== null && plan.tokensAfter <= policy.freshTargetTokens) return plan
+        }
+        if (budgetChars === 1) break
+        budgetChars = Math.max(1, Math.floor(budgetChars / 2))
+      }
+    }
+
+    return this.planAggregate(
+      candidate,
+      session,
+      view,
+      'fresh-whole-result',
+      'fresh',
+      policy.freshTargetTokens,
+      'fresh',
+    )
+  }
+
+  private planAggregate(
+    candidate: SnapshotCandidate,
+    session: Session,
+    view: CompactionTokenView,
+    reducer = 'fresh-step-aggregate',
+    stage: PruneStage = 'fresh',
+    targetTokens?: number,
+    component: CompressionAuditComponent = 'aggregate',
+    historyMode?: HistoryMode,
+  ): PlannedReplacement | null {
+    if (isError(candidate)) {
+      return this.planErrorEvidence(
+        candidate,
+        session,
+        view,
+        stage,
+        targetTokens,
+        component,
+        historyMode,
+      )
+    }
+    const sourceSeq = rootToolResultSeq(session, candidate.seq)
+    const sourceRef = sourceRefFn(session, sourceSeq)
+    const text = [
+      '[Tool result reduced to satisfy the completed-step aggregate budget]',
+      `tool: ${candidate.call.name}`,
+      `source: ${sourceRef}`,
+      'Use context_compression_retrieve with this source if the omitted evidence is necessary.',
+    ].join('\n')
+    const plan = this.plan(
+      candidate,
+      [{ type: 'text', text }],
+      sourceSeq,
+      reducer,
+      stage,
+      component,
+      historyMode,
+      view,
+    )
+    return plan !== null && (targetTokens === undefined || plan.tokensAfter <= targetTokens)
+      ? plan
+      : null
+  }
+
+  /** Preserve bounded diagnostic evidence whenever an all-text error is reduced. */
+  private planErrorEvidence(
+    candidate: SnapshotCandidate,
+    session: Session,
+    view: CompactionTokenView,
+    stage: PruneStage,
+    targetTokens?: number,
+    component: CompressionAuditComponent = 'aggregate',
+    historyMode?: HistoryMode,
+  ): PlannedReplacement | null {
+    if (!isError(candidate)) return null
+    const result = candidate.event.data.message.content[0]
+    const blocks = onlyTextBlocks(result.content)
+    if (blocks === null) return null
+    const text = blocks.map(block => block.text).join('\n')
+    const sourceSeq = rootToolResultSeq(session, candidate.seq)
+    const sourceRef = sourceRefFn(session, sourceSeq)
+    const output = historicalPlaceholder({
+      toolName: candidate.call.name,
+      sourceRef,
+      charsBefore: codePointLength(text),
+      isError: true,
+      text,
+      compact: false,
+    })
+    const input = {
+      toolName: candidate.call.name,
+      argumentsText: candidate.call.arguments,
+      text,
+      budgetChars: 1_200,
+      sourceRef,
+      isError: true,
+    }
+    if (!verifyReduction(input, output)) return null
+    const plan = this.plan(
+      candidate,
+      [{ type: 'text', text: output.text }],
+      sourceSeq,
+      'error-evidence-placeholder',
+      stage,
+      component,
+      historyMode,
+      view,
+    )
+    return plan !== null && (targetTokens === undefined || plan.tokensAfter <= targetTokens)
+      ? plan
+      : null
+  }
+
+  private planHistoricalAging(
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): HistoryPlanOutcome {
+    const candidates = this.snapshot(session, view)
+    const events = sessionEvents(session)
+    const exact: number[] = []
+    for (const candidate of candidates) {
+      const tokens = exactTokens(candidate.count)
+      if (tokens === undefined) {
+        this.warnExactUnavailable(session, view, 'history')
+        return { kind: 'exact-tokenizer-unavailable' }
+      }
+      exact.push(tokens)
+    }
+    const total = exact.reduce((sum, tokens) => sum + tokens, 0)
+    const trigger = policy.historyTriggerTokens
+    // Full-request last chance: ordinary prose, images, prompts, or schemas can
+    // push the complete request past the Auto Compact deadline before the tool
+    // results alone cross the profile trigger.
+    const deadline = policy.microDeadlineTokens
+    const lastChance = deadline !== undefined && view.totalTokens >= deadline
+    if (total <= trigger && !lastChance) return { kind: 'below-profile-trigger' }
+
+    const protectedSeqs = this.protectedHistoryCandidateSeqs(candidates, policy)
+    const isUnsafe = (candidate: SnapshotCandidate): boolean => {
+      if (this.isRecoveryExempt(session, candidate)) return true
+      const result = candidate.event.data.message.content[0]
+      const block = onlyTextBlock(result.content)
+      return block?.text.includes('[Old tool result content cleared from active context]') === true
+    }
+    // Distinguish "nothing safe to touch" (recovery tool output or already
+    // cleared) from "everything left is inside the protected working set":
+    // both skip, but they are different operational facts.
+    const safe = candidates.filter(candidate => !isUnsafe(candidate))
+    const eligible = safe.filter(candidate => !protectedSeqs.has(candidate.seq))
+    if (eligible.length === 0) {
+      return safe.length === 0
+        ? { kind: 'no-safe-candidates' }
+        : { kind: 'protected-working-set' }
+    }
+    const planned: PlannedReplacement[] = []
+    let reclaim = 0
+    // With a frozen Auto Compact deadline, microTarget = max(0, D - M) and one
+    // batch must justify its cache break by pulling the complete request back
+    // below the deadline. Without linkage (Custom manual, or no resolved
+    // routed capacity) the loop keeps its traditional target and the batch
+    // still commits once it reaches the minimum reclaim.
+    const microTarget = deadline === undefined ? undefined : Math.max(0, deadline - policy.historyMinReclaimTokens)
+    const required = Math.max(
+      policy.historyMinReclaimTokens,
+      total - trigger,
+      ...(microTarget === undefined ? [] : [view.totalTokens - microTarget]),
+    )
+    const batchTarget = microTarget === undefined
+      ? policy.historyMinReclaimTokens
+      : required
+    for (const candidate of eligible) {
+      const result = candidate.event.data.message.content[0]
+      const block = onlyTextBlock(result.content)
+      // TokenPilot-inspired R2: a read output whose file was later mutated is
+      // superseded — its text can no longer match the file — so it takes the
+      // small whole-result placeholder before the ordinary reducer runs.
+      if (policy.presetOptions?.readState === true && block !== null) {
+        const readPath = toolCallPath(candidate.call.arguments)
+        const estimatorExpired = this.state.estimatorVerdicts.get(session)?.get(candidate.seq) === true
+        if (readPath !== undefined
+          && (isSupersededRead(events, candidate.seq, readPath) || estimatorExpired)) {
+          const plan = this.planAggregate(
+            candidate,
+            session,
+            view,
+            'superseded-read-whole-result',
+            'pressure',
+            undefined,
+            'history',
+            policy.historyMode,
+          )
+          if (plan === null) continue
+          planned.push(plan)
+          reclaim += plan.tokensBefore - plan.tokensAfter
+          if (reclaim >= required) break
+          continue
+        }
+      }
+      const sourceSeq = rootToolResultSeq(session, candidate.seq)
+      if (block === null) {
+        const plan = this.planAggregate(
+          candidate,
+          session,
+          view,
+          'historical-rich-whole-result',
+          'pressure',
+          undefined,
+          'history',
+          policy.historyMode,
+        )
+        if (plan === null) continue
+        planned.push(plan)
+        reclaim += plan.tokensBefore - plan.tokensAfter
+        if (reclaim >= required) break
+        continue
+      }
+      const output = historicalPlaceholder({
+        toolName: candidate.call.name,
+        sourceRef: sourceRefFn(session, sourceSeq),
+        charsBefore: codePointLength(block.text),
+        isError: result.isError === true || candidate.event.data.error !== undefined,
+        text: block.text,
+        compact: false,
+      })
+      const verifyInput = {
+        toolName: candidate.call.name,
+        argumentsText: candidate.call.arguments,
+        text: block.text,
+        budgetChars: 1_200,
+        sourceRef: sourceRefFn(session, sourceSeq),
+        isError: result.isError === true || candidate.event.data.error !== undefined,
+      }
+      if (!verifyReduction(verifyInput, output)) continue
+      // TokenPilot-inspired R3: when read-state semantics are on, append an
+      // error/warn/info census of the omitted lines so the model keeps
+      // meta-knowledge about what was dropped.
+      let replacementText = output.text
+      if (policy.presetOptions?.readState === true) {
+        const omitted = countOmittedLines(block.text, output.text)
+        const census = omitted === undefined ? undefined : clusterOmittedLines(block.text, omitted)
+        if (census !== undefined) replacementText = `${output.text}
+[... ${census} ...]`
+      }
+      const plan = this.plan(
+        candidate,
+        [{ ...block, text: replacementText }],
+        sourceSeq,
+        output.reducer,
+        'pressure',
+        'history',
+        policy.historyMode,
+        view,
+      )
+      if (plan === null) continue
+      planned.push(plan)
+      reclaim += plan.tokensBefore - plan.tokensAfter
+      if (reclaim >= required) break
+    }
+    // Linked batches must reach the deadline target; unlinked batches keep
+    // the traditional minimum-reclaim commit threshold.
+    if (reclaim >= batchTarget && planned.length > 0) return historyOutcome(planned)
+    return lastChance
+      ? { kind: 'cannot-reach-deadline-target', reclaim, required }
+      : { kind: 'insufficient-reclaim', reclaim, required }
+  }
+
+  private protectedHistoryResultSeqs(
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): Set<number> | null {
+    const candidates = this.snapshot(session, view)
+    if (candidates.some(candidate => exactTokens(candidate.count) === undefined)) return null
+    return this.protectedHistoryCandidateSeqs(candidates, policy)
+  }
+
+  /** Select the newest completed tool calls and token tail for History-derived stages. */
+  private protectedHistoryCandidateSeqs(
+    candidates: readonly SnapshotCandidate[],
+    policy: CompressionPolicy,
+  ): Set<number> {
+    const protectedSeqs = new Set<number>()
+    for (let index = candidates.length - 1;
+      index >= 0 && candidates.length - index <= policy.historyKeepRecentToolCalls;
+      index--) {
+      const candidate = candidates[index]
+      if (candidate !== undefined) protectedSeqs.add(candidate.seq)
+    }
+    let recentTokens = 0
+    for (let index = candidates.length - 1;
+      index >= 0 && recentTokens < policy.historyKeepRecentTokens;
+      index--) {
+      const candidate = candidates[index]
+      if (candidate === undefined) continue
+      protectedSeqs.add(candidate.seq)
+      recentTokens += exactTokens(candidate.count) ?? 0
+    }
+    return protectedSeqs
+  }
+
+  /** Atomically replace at most one oldest safe completed tool-call group. */
+  private landOldestTailTrimGroup(
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+  ): void {
+    const tailTrim = policy.tailTrim
+    if (tailTrim?.enabled !== true) return
+    const events = sessionEvents(session)
+    if (view.currentSurface.kind !== 'exact-tokenizer'
+      || view.currentSurface.tokens <= tailTrim.triggerTokens) {
+      if (view.currentSurface.kind !== 'exact-tokenizer') this.warnExactUnavailable(session, view, 'tailtrim')
+      this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+        view.currentSurface.kind !== 'exact-tokenizer'
+          ? 'exact-tokenizer-unavailable' : 'at-or-below-trigger', {
+          measurementKind: view.currentSurface.kind,
+          ...(view.currentSurface.kind === 'exact-tokenizer'
+            ? { currentTokens: view.currentSurface.tokens }
+            : {}),
+          triggerTokens: tailTrim.triggerTokens,
+        })
+      return
+    }
+    const surfaceCount = view.currentSurface
+    if (!this.hasRecoveryTool(session)) {
+      this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+        'recovery-tool-unavailable', {
+          measurementKind: 'exact-tokenizer',
+          currentTokens: surfaceCount.tokens,
+          triggerTokens: tailTrim.triggerTokens,
+        })
+      return
+    }
+    if (!hasOpenTurn(session)) {
+      this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+        'no-open-turn', {
+          measurementKind: 'exact-tokenizer',
+          currentTokens: surfaceCount.tokens,
+          triggerTokens: tailTrim.triggerTokens,
+        })
+      return
+    }
+    const protectedResults = this.protectedHistoryResultSeqs(session, policy, view)
+    if (protectedResults === null) {
+      this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+        'exact-tokenizer-unavailable-in-protected-set', {
+          measurementKind: 'unavailable',
+          currentTokens: surfaceCount.tokens,
+          triggerTokens: tailTrim.triggerTokens,
+        })
+      return
+    }
+    const measured = new Map(view.measuredNodes.map(node => [node.seq, node.count]))
+    const heuristic = new Map(view.nodes.map(node => [node.seq, node.tokens]))
+    const completedTurns = new Set<number>()
+    const completedSteps = new Set<string>()
+    for (const event of events) {
+      if (event.type === 'turn/end') completedTurns.add(event.data.turn)
+      else if (event.type === 'step/end') completedSteps.add(`${String(event.data.turn)}:${String(event.data.step)}`)
+    }
+    const firstCompletedSurfaceTurn = session.surface.nodes
+      .map(seq => events[seq])
+      .filter((event): event is SessionEvent<'assistant/message'> | SessionEvent<'tool/result'> =>
+        (event?.type === 'assistant/message' || event?.type === 'tool/result')
+          && completedTurns.has(event.data.turn))
+      .reduce<number | undefined>(
+        (first, event) => first === undefined ? event.data.turn : Math.min(first, event.data.turn),
+        undefined,
+      )
+    const nodes = [...session.surface.nodes]
+    for (let index = 0; index < nodes.length; index++) {
+      const assistantSeq = nodes[index]
+      if (assistantSeq === undefined) continue
+      const assistant = events[assistantSeq]
+      if (assistant?.type !== 'assistant/message'
+        || assistant.data.interrupted === true
+        || assistant.data.message.content.length === 0
+        || assistant.data.message.content.some(block => block.type !== 'tool-call')
+        || assistant.data.turn === firstCompletedSurfaceTurn
+        || !completedTurns.has(assistant.data.turn)
+        || !completedSteps.has(`${String(assistant.data.turn)}:${String(assistant.data.step)}`)) continue
+      const calls = assistant.data.message.content as Extract<ContentBlock, { type: 'tool-call' }>[]
+      if (calls.some(call => call.name === 'context_compression_retrieve')) continue
+      const callIds = calls.map(call => String(call.id))
+      if (new Set(callIds).size !== callIds.length) continue
+      const resultSeqs = nodes.slice(index + 1, index + 1 + calls.length)
+      if (resultSeqs.length !== calls.length || resultSeqs.some(seq => protectedResults.has(seq))) continue
+      const results = resultSeqs.map(seq => events[seq])
+      if (results.some((event): boolean => {
+        if (event?.type !== 'tool/result'
+          || event.data.turn !== assistant.data.turn || event.data.step !== assistant.data.step
+          || event.data.error !== undefined) return true
+        const block = event.data.message.content[0]
+        if (block.isError === true) return true
+        // Images and other rich inner blocks stay fail-open: a TailTrim stub
+        // would silently delete them from the active context.
+        return block.content.some(contentBlock => contentBlock.type !== 'text')
+      })) continue
+      const next = events[nodes[index + 1 + calls.length] ?? -1]
+      if (next?.type === 'tool/result'
+        && next.data.turn === assistant.data.turn
+        && next.data.step === assistant.data.step) continue
+      const resultIds = results.map(event => event?.type === 'tool/result'
+        ? String(event.data.message.source.callId) : '')
+      if (new Set(resultIds).size !== resultIds.length
+        || resultIds.some((id, resultIndex) => id !== callIds[resultIndex])) continue
+      const shadowedSeqs = [assistantSeq, ...resultSeqs]
+      const roots = shadowedSeqs.map(seq => this.uniqueAppendRoot(session, seq))
+      if (roots.some(root => root === null)) continue
+      const sourceEventSeqs = roots as number[]
+      if (new Set(sourceEventSeqs).size !== sourceEventSeqs.length) continue
+      const counts = shadowedSeqs.map(seq => measured.get(seq))
+      if (counts.some(count => count?.kind !== 'exact-tokenizer')) continue
+      const exactCounts = counts as Extract<TokenCount, { kind: 'exact-tokenizer' }>[]
+      if (exactCounts.some(count => count.tokenizerId !== surfaceCount.tokenizerId
+        || count.tokenizerRevision !== surfaceCount.tokenizerRevision)) continue
+      const tokensBefore = exactCounts.reduce((sum, count) => sum + count.tokens, 0)
+      const manifestSeq = events.length
+      const ref = tailTrimRef(String(session.id), manifestSeq)
+      const stub = tailTrimStub(ref, calls.map(call => call.name), sourceEventSeqs)
+      if (stub === null) continue
+      const stubCount = countExactCanonicalTextFields(
+        [stub],
+        candidate => view.countCanonicalText(candidate),
+        'TailTrim group stub',
+      )
+      if (stubCount.kind !== 'exact-tokenizer'
+        || stubCount.tokenizerId !== surfaceCount.tokenizerId
+        || stubCount.tokenizerRevision !== surfaceCount.tokenizerRevision
+        || stubCount.tokens <= 0
+        || tokensBefore - stubCount.tokens < policy.historyMinReclaimTokens) continue
+      const heuristicTokens = shadowedSeqs.reduce((sum, seq) => sum + (heuristic.get(seq) ?? 0), 0)
+      const range = { start: assistantSeq, end: resultSeqs.at(-1) ?? assistantSeq }
+      if (!this.reserveTailTrimBoundaryAttempt(session)) {
+        this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+          'already-attempted-at-request-boundary', {
+            measurementKind: 'exact-tokenizer',
+            currentTokens: surfaceCount.tokens,
+            triggerTokens: tailTrim.triggerTokens,
+          })
+        return
+      }
+      const manifest = session.append('compaction/prune', {
+        shadowedRange: range,
+        shadowedSeqs,
+        shadowedTokenCount: heuristicTokens,
+      })
+      let replacement: SessionEvent<'user/message'>
+      try {
+        replacement = session.append('user/message', tailTrimMessage(stub), {
+          surfaceOp: { op: 'replace', ...range },
+          sourceEventSeqs: [manifest.seq, ...shadowedSeqs],
+        })
+      } catch (error) {
+        this.auditPublicationFailure(
+          session,
+          'pressure',
+          'tail-trim',
+          manifest.seq,
+          error,
+        )
+        return
+      }
+      emitCompressionAudit(this.ctx.logger, {
+        schemaVersion: 1,
+        kind: 'rewrite',
+        sessionId: String(session.id),
+        profile: policy.profile,
+        component: 'tail-trim',
+        stage: 'pressure',
+        reducer: 'pair-preserving-tail-trim',
+        manifestEventType: 'compaction/prune',
+        manifestSeq: manifest.seq,
+        replacementSeq: replacement.seq,
+        sourceSeqs: sourceEventSeqs,
+        tokensBefore,
+        tokensAfter: stubCount.tokens,
+        tokensRemoved: tokensBefore - stubCount.tokens,
+        tokenizerId: stubCount.tokenizerId,
+        tokenizerRevision: stubCount.tokenizerRevision,
+      })
+      return
+    }
+    this.auditComponent(session, policy, 'tail-trim', 'pressure', 'skipped',
+      'no-safe-eligible-tool-group', {
+        measurementKind: 'exact-tokenizer',
+        currentTokens: surfaceCount.tokens,
+        triggerTokens: tailTrim.triggerTokens,
+      })
+  }
+
+  private reserveTailTrimBoundaryAttempt(session: Session): boolean {
+    const boundary = this.state.activeRequestBoundaries.get(session)
+    if (boundary === undefined) return true
+    if (this.state.tailTrimBoundaryAttempts.get(session) === boundary) return false
+    this.state.tailTrimBoundaryAttempts.set(session, boundary)
+    return true
+  }
+
+  private uniqueAppendRoot(session: Session, seq: number): number | null {
+    const events = sessionEvents(session)
+    const pending: Array<{ seq: number; depth: number }> = [{ seq, depth: 0 }]
+    const visited = new Set<number>()
+    const roots = new Set<number>()
+    while (pending.length > 0) {
+      const next = pending.pop()
+      if (next === undefined || next.depth > 64 || visited.has(next.seq)) continue
+      visited.add(next.seq)
+      if (visited.size > 64) return null
+      const event = events[next.seq]
+      if (event === undefined || (event.type !== 'assistant/message' && event.type !== 'tool/result')) return null
+      if (event.surfaceOp === 'append') roots.add(event.seq)
+      else if (typeof event.surfaceOp === 'object') {
+        const sources = event.sourceEventSeqs
+        if (sources === undefined || sources.length === 0) return null
+        for (const source of sources) pending.push({ seq: source, depth: next.depth + 1 })
+      } else return null
+      if (roots.size > 1) return null
+    }
+    return roots.size === 1 ? [...roots][0] ?? null : null
+  }
+
+  private plan(
+    candidate: SnapshotCandidate,
+    content: ContentBlock[],
+    sourceSeq: number,
+    reducer: string,
+    stage: PruneStage,
+    component: CompressionAuditComponent,
+    historyMode: HistoryMode | undefined,
+    view: CompactionTokenView,
+    options: { readonly noNetSavingsGuard?: boolean } = {},
+  ): PlannedReplacement | null {
+    const countBefore = candidate.count
+    if (countBefore.kind !== 'exact-tokenizer') return null
+    const countAfter = countToolContent(content, view)
+    if (countAfter.kind !== 'exact-tokenizer'
+      || countAfter.tokenizerId !== countBefore.tokenizerId
+      || countAfter.tokenizerRevision !== countBefore.tokenizerRevision) return null
+    const tokensBefore = countBefore.tokens
+    const tokensAfter = countAfter.tokens
+    if (tokensAfter <= 0 || tokensAfter >= tokensBefore) return null
+    // TokenPilot-style no-net-savings: even when the exact tokenizer reports a
+    // saving, a replacement whose text is not smaller than its original adds
+    // noise without reclaiming context. Text-level because the placeholder
+    // guidance lines (source refs, retrieval hints) must pay for themselves.
+    if (options.noNetSavingsGuard === true) {
+      const originalBlocks = onlyTextBlocks(candidate.event.data.message.content[0].content)
+      const replacementBlocks = onlyTextBlocks(content)
+      if (originalBlocks !== null && replacementBlocks !== null) {
+        const originalChars = originalBlocks.reduce((sum, block) => sum + codePointLength(block.text), 0)
+        const replacementChars = replacementBlocks.reduce((sum, block) => sum + codePointLength(block.text), 0)
+        if (replacementChars >= originalChars) return null
+      }
+    }
+    const charsBefore = candidate.characterPressure
+    const charsAfter = pressureCost(content)
+    return {
+      candidate,
+      content,
+      sourceSeq,
+      reducer,
+      stage,
+      component,
+      ...historyMode === undefined ? {} : { historyMode },
+      charsBefore,
+      charsAfter,
+      tokensBefore,
+      tokensAfter,
+      tokenizerId: countBefore.tokenizerId,
+      tokenizerRevision: countBefore.tokenizerRevision,
+    }
+  }
+
+  private land(session: Session, plan: PlannedReplacement): PrunedEntry | null {
+    const { candidate } = plan
+    const result = candidate.event.data.message.content[0]
+    const message = freezeMessage<ToolResultMessage>({
+      ...candidate.event.data.message,
+      content: [{ ...result, content: plan.content }] as [typeof result],
+    })
+    const manifest = session.append('compaction/prune', {
+      shadowedRange: { start: candidate.seq, end: candidate.seq },
+      shadowedSeqs: [candidate.seq],
+      shadowedTokenCount: candidate.shadowedHeuristicTokenCount,
+    })
+    let replacement: SessionEvent<'tool/result'>
+    try {
+      replacement = session.append('tool/result', {
+        ...candidate.event.data,
+        message,
+      }, {
+        surfaceOp: { op: 'replace', start: candidate.seq, end: candidate.seq },
+        sourceEventSeqs: [candidate.seq],
+      })
+    } catch (error) {
+      this.auditPublicationFailure(
+        session,
+        plan.stage,
+        plan.component,
+        manifest.seq,
+        error,
+      )
+      return null
+    }
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'rewrite',
+      sessionId: String(session.id),
+      profile: this.activeSettings(session).profile,
+      component: plan.component,
+      stage: plan.stage,
+      reducer: plan.reducer,
+      ...plan.historyMode === undefined ? {} : { historyMode: plan.historyMode },
+      manifestEventType: 'compaction/prune',
+      manifestSeq: manifest.seq,
+      replacementSeq: replacement.seq,
+      sourceSeqs: [plan.sourceSeq],
+      tokensBefore: plan.tokensBefore,
+      tokensAfter: plan.tokensAfter,
+      tokensRemoved: plan.tokensBefore - plan.tokensAfter,
+      tokenizerId: plan.tokenizerId,
+      tokenizerRevision: plan.tokenizerRevision,
+    })
+    return {
+      originalSeq: candidate.seq,
+      sourceSeq: plan.sourceSeq,
+      replacementSeq: replacement.seq,
+      callId: candidate.event.data.message.source.callId,
+      reducer: plan.reducer,
+      stage: plan.stage,
+      charsBefore: plan.charsBefore,
+      charsAfter: plan.charsAfter,
+      tokensBefore: plan.tokensBefore,
+      tokensAfter: plan.tokensAfter,
+    }
+  }
+
+  private landAll(session: Session, plans: readonly PlannedReplacement[]): PrunedEntry[] {
+    if (plans.length === 0) return []
+    if (!this.hasRecoveryTool(session)) {
+      this.warnOnce(
+        session,
+        'missing-context-retrieve',
+        'context-compression kept original tool results because context_compression_retrieve is unavailable',
+      )
+      return []
+    }
+    if (!hasOpenTurn(session)) {
+      throw new Error('tool-result pruning cannot append a surface replacement outside any open turn')
+    }
+    const landed: PrunedEntry[] = []
+    for (const plan of plans) {
+      const entry = this.land(session, plan)
+      if (entry === null) break
+      landed.push(entry)
+    }
+    return landed
+  }
+
+  private hasRecoveryTool(session: Session): boolean {
+    const tools = this.ctx.get('tools')
+    if (tools === undefined) return false
+    const agent = this.ctx.get('agents')?.get(session.id)
+    return tools.get('context_compression_retrieve', agent) !== undefined
+  }
+
+  private auditHistoryEvaluation(
+    session: Session,
+    policy: CompressionPolicy,
+    view: CompactionTokenView,
+    allowed: boolean,
+    outcome: HistoryPlanOutcome,
+  ): void {
+    if (policy.historyMode === 'disabled') {
+      this.auditComponent(session, policy, 'history', 'pressure', 'disabled', 'profile-policy', {
+        historyMode: policy.historyMode,
+      })
+      return
+    }
+    if (!allowed && outcome.kind === 'planned') {
+      // The authority gate itself refused: below the frozen micro deadline
+      // (capacity-pressure) or the adaptive cost estimate rejected the batch.
+      const deadlineTrigger = policy.microDeadlineTokens
+      const capacity = deadlineTrigger === undefined ? session.requestContext()?.contextWindow : undefined
+      const capacityTrigger = deadlineTrigger !== undefined
+        ? deadlineTrigger
+        : Number.isSafeInteger(capacity) && capacity !== undefined && capacity > 0
+          ? Math.floor(capacity * CAPACITY_PRESSURE_RATIO)
+          : undefined
+      this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+        policy.historyMode === 'capacity-pressure'
+          ? 'below-micro-deadline' : 'adaptive-cost-rejected', {
+          historyMode: policy.historyMode,
+          measurementKind: view.currentSurface.kind,
+          currentTokens: view.totalTokens,
+          ...(capacityTrigger === undefined ? {} : { triggerTokens: capacityTrigger }),
+        })
+      return
+    }
+    const deadline = policy.microDeadlineTokens
+    const lastChance = deadline !== undefined && view.totalTokens >= deadline
+    const detail = (extra: Readonly<Record<string, number>> = {}): Readonly<{
+      historyMode?: HistoryMode
+      measurementKind?: 'exact-tokenizer' | 'tokenizer-estimate' | 'unavailable'
+      currentTokens?: number
+      triggerTokens?: number
+      reclaimTokens?: number
+      requiredTokens?: number
+    }> => ({
+      historyMode: policy.historyMode,
+      measurementKind: outcome.kind === 'exact-tokenizer-unavailable' ? 'unavailable' : 'exact-tokenizer',
+      currentTokens: view.totalTokens,
+      ...(outcome.kind === 'insufficient-reclaim' || outcome.kind === 'cannot-reach-deadline-target'
+        ? { reclaimTokens: outcome.reclaim, requiredTokens: outcome.required }
+        : {}),
+      ...extra,
+    })
+    switch (outcome.kind) {
+      case 'exact-tokenizer-unavailable':
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'exact-tokenizer-unavailable', detail({ triggerTokens: policy.historyTriggerTokens }))
+        return
+      case 'below-profile-trigger':
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'below-profile-trigger', detail({ triggerTokens: policy.historyTriggerTokens }))
+        return
+      case 'no-safe-candidates':
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'no-safe-candidates', detail({ triggerTokens: policy.historyTriggerTokens }))
+        return
+      case 'protected-working-set':
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'protected-working-set', detail({ triggerTokens: policy.historyTriggerTokens }))
+        return
+      case 'insufficient-reclaim':
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'insufficient-reclaim', detail({ triggerTokens: policy.historyTriggerTokens }))
+        return
+      case 'cannot-reach-deadline-target':
+        // Planning engaged through the full-request last-chance gate; the
+        // routine trigger numbers below would misdescribe why nothing landed.
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          'cannot-reach-deadline-target', detail(lastChance ? { triggerTokens: deadline } : {}))
+        return
+      case 'planned':
+        // A committed batch that landed nothing means the recovery tool was
+        // unavailable at landing time; a degenerate empty commit reads as an
+        // unreachable target instead.
+        this.auditComponent(session, policy, 'history', 'pressure', 'skipped',
+          outcome.plans.length > 0 ? 'recovery-tool-unavailable' : 'insufficient-reclaim',
+          detail({ triggerTokens: lastChance ? deadline : policy.historyTriggerTokens }))
+        return
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        return assertNever(outcome, 'history plan outcome')
+    }
+  }
+
+  private auditComponent(
+    session: Session,
+    policy: CompressionPolicy,
+    component: CompressionAuditComponent,
+    stage: PruneStage,
+    status: CompressionAuditEvaluationStatus,
+    reason: string,
+    detail: Readonly<{
+      historyMode?: HistoryMode
+      measurementKind?: 'exact-tokenizer' | 'tokenizer-estimate' | 'unavailable'
+      currentTokens?: number
+      triggerTokens?: number
+      targetTokens?: number
+      reclaimTokens?: number
+      requiredTokens?: number
+    }> = {},
+  ): void {
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'component-evaluation',
+      sessionId: String(session.id),
+      profile: policy.profile,
+      component,
+      stage,
+      status,
+      reason,
+      ...detail,
+    })
+  }
+
+  private auditFailure(
+    session: Session,
+    stage: PruneStage,
+    operation:
+      | 'request-boundary'
+      | 'terminal-pass'
+      | 'policy-resolution'
+      | 'summary-locator'
+      | 'publication',
+    error: unknown,
+  ): void {
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'failure',
+      sessionId: String(session.id),
+      stage,
+      operation,
+      errorName: error instanceof Error ? error.name : 'UnknownError',
+      errorMessage: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  private auditPublicationFailure(
+    session: Session,
+    stage: PruneStage,
+    component: CompressionAuditComponent,
+    manifestSeq: number,
+    error: unknown,
+  ): void {
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'failure',
+      sessionId: String(session.id),
+      stage,
+      operation: 'publication',
+      component,
+      manifestSeq,
+      errorName: error instanceof Error ? error.name : 'UnknownError',
+      errorMessage: 'surface replacement append failed after compaction/prune committed',
+    })
+  }
+
+  private warnExactUnavailable(
+    session: Session,
+    view: CompactionTokenView,
+    gate: 'native' | 'fresh' | 'aggregate' | 'history' | 'tailtrim',
+  ): void {
+    const provider = view.providerRoute ?? 'unbound-provider'
+    const model = view.modelId ?? 'unbound-model'
+    this.warnOnce(
+      session,
+      `exact-tokenizer:${gate}:${provider}\0${model}`,
+      'context-compression %s kept original tool results because exact tokenizer counts are unavailable for %s/%s',
+      gate,
+      provider,
+      model,
+    )
+  }
+
+  private warnOnce(
+    session: Session,
+    key: string,
+    message: string,
+    ...args: unknown[]
+  ): void {
+    let warned = this.state.warnedFailures.get(session)
+    if (warned === undefined) {
+      warned = new Set()
+      this.state.warnedFailures.set(session, warned)
+    }
+    if (warned.has(key)) return
+    warned.add(key)
+    this.ctx.logger.warn(message, ...args)
+  }
+
+}
+
+export default ToolResultPruner