@animalabs/context-manager 0.5.3 → 0.5.5

package/src/strategies/autobiographical.ts

@@ -1,6 +1,7 @@
 import type { JsStore } from '@animalabs/chronicle';
 import type { Membrane, NormalizedRequest, ContentBlock, CompleteOptions } from '@animalabs/membrane';
 import { NativeFormatter } from '@animalabs/membrane';
+import { phaseChannel } from '../phase-channel.js';
 import type {
   ContextStrategy,
   ResettableStrategy,
@@ -15,16 +16,19 @@ import type {
   SummaryLevel,
   SummaryEntry,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
+  RenderStats,
 } from '../types/index.js';
 import { DEFAULT_AUTOBIOGRAPHICAL_CONFIG } from '../types/index.js';
 import { getSummaryParentId } from '../types/strategy.js';
 import { splitMixedToolMessages, stripUnpairedToolBlocks } from '../normalize-tool-messages.js';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { Picker, OverBudgetError, type PickerChunk } from '../adaptive/picker.js';
+import { Picker, OverBudgetError, type PickerChunk, type PickerInputs } from '../adaptive/picker.js';
 import { FlatProfileStrategy } from '../adaptive/strategies/flat-profile.js';
+import { KvStableStrategy } from '../adaptive/strategies/kv-stable.js';
 import { OldestFirstStrategy } from '../adaptive/strategies/oldest-first.js';
 import type {
   FoldingStrategy,
@@ -223,8 +227,6 @@ export interface Chunk {
   tokens: number;
   /** Whether this chunk has been compressed */
   compressed: boolean;
-  /** The diary entry if compressed (legacy mode) */
-  diary?: string;
   /** ID of the L1 SummaryEntry (hierarchical mode) */
   summaryId?: string;
   /** Phase type tag (set by KnowledgeStrategy for semantic chunking) */
@@ -252,6 +254,21 @@ export interface AutobiographicalProgressSnapshot {
   pending: boolean;
 }
 
+/**
+ * Validate + normalize the optional V2 pin fold-depth bounds. Returns only the
+ * fields that are present and valid (non-negative integers), so a classic pin
+ * with no bounds persists exactly as before. `level` takes precedence over
+ * `maxLevel` (pin-at-k is stronger than a cap), so they're never both emitted.
+ */
+function normalizePinLevels(opts?: PinLevelOptions): { level?: number; maxLevel?: number } {
+  const clean = (v: number | undefined): number | undefined =>
+    typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : undefined;
+  const level = clean(opts?.level);
+  if (level !== undefined) return { level };
+  const maxLevel = clean(opts?.maxLevel);
+  return maxLevel !== undefined ? { maxLevel } : {};
+}
+
 /**
  * Autobiographical chunking strategy.
  * Compresses old conversation chunks into summaries in the model's own words.
@@ -271,6 +288,14 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   protected pendingCompression: Promise<void> | null = null;
   protected compressionQueue: number[] = [];
   protected _compressionCount = 0;
+  /**
+   * Monotonic counter of tick() operations that actually processed a queue item
+   * (compressed a chunk or executed a merge). `driveSpeculativeDrain` recurses
+   * while this advances — a length-delta check would falsely read "no progress"
+   * when a productive tick also enqueues a follow-on item (net queue length
+   * unchanged), halting the drain with work still queued.
+   */
+  protected _drainProgress = 0;
 
   // Hierarchical state
   protected summaries: SummaryEntry[] = [];
@@ -583,7 +608,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * Pin a range of messages so they aren't compressed and render raw at
    * their original position. Returns the pin id.
    */
-  pinRange(firstMessageId: string, lastMessageId: string, opts?: { name?: string }): string {
+  pinRange(firstMessageId: string, lastMessageId: string, opts?: PinLevelOptions): string {
     const id = `pin-${this.pinIdCounter++}`;
     this.pins.push({
       id,
@@ -592,6 +617,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       kind: 'pin',
       name: opts?.name,
       created: Date.now(),
+      ...normalizePinLevels(opts),
     });
     this.persistPins();
     return id;
@@ -602,7 +628,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * information the agent wants to retain in full. Functionally a
    * single-message pin with `kind: 'document'`.
    */
-  markDocument(messageId: string, opts?: { name?: string }): string {
+  markDocument(messageId: string, opts?: PinLevelOptions): string {
     const id = `pin-${this.pinIdCounter++}`;
     this.pins.push({
       id,
@@ -611,11 +637,22 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       kind: 'document',
       name: opts?.name,
       created: Date.now(),
+      ...normalizePinLevels(opts),
     });
     this.persistPins();
     return id;
   }
 
+  /**
+   * V2 dynamic pin-at-level-k convenience: fix a range to render at EXACTLY
+   * fold level `level` (0 = raw). Honored only by `foldingStrategy: 'kv-stable'`;
+   * other strategies fall back to treating the range as raw. Equivalent to
+   * `pinRange(first, last, { level })`.
+   */
+  pinAtLevel(firstMessageId: string, lastMessageId: string, level: number, opts?: { name?: string }): string {
+    return this.pinRange(firstMessageId, lastMessageId, { name: opts?.name, level });
+  }
+
   /** Remove a pin or document mark by id. Returns true if removed. */
   unpin(pinId: string): boolean {
     const before = this.pins.length;
@@ -735,6 +772,42 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     return out;
   }
 
+  /**
+   * Resolve the V2 dynamic-pin fold-depth bounds (`ProtectedRange.level` /
+   * `maxLevel`) to message positions. Only pins that carry a bound appear; a
+   * classic raw pin (no bound) is absent here and handled by `pinnedPositions`.
+   * When ranges overlap, the FINEST requirement wins (lowest effective level):
+   * a fixed `level` clamps both ends; a `maxLevel` only caps depth. Honored
+   * solely by the KV-stable controller — see `ProtectedRange`.
+   */
+  protected pinLevelBounds(messages: StoredMessage[]): Map<number, { level?: number; maxLevel?: number }> {
+    const out = new Map<number, { level?: number; maxLevel?: number }>();
+    if (this.pins.length === 0) return out;
+    const positionOf = new Map<string, number>();
+    for (let i = 0; i < messages.length; i++) positionOf.set(messages[i].id, i);
+
+    for (const pin of this.pins) {
+      if (pin.level === undefined && pin.maxLevel === undefined) continue;
+      const first = positionOf.get(pin.firstMessageId);
+      const last = positionOf.get(pin.lastMessageId);
+      if (first === undefined || last === undefined) continue;
+      const lo = Math.min(first, last);
+      const hi = Math.max(first, last);
+      for (let i = lo; i <= hi; i++) {
+        const prev = out.get(i) ?? {};
+        // A fixed level is the strongest constraint; when two pins fix the same
+        // position, the shallower (lower) level wins (finest requirement).
+        if (pin.level !== undefined) {
+          prev.level = prev.level === undefined ? pin.level : Math.min(prev.level, pin.level);
+        } else if (pin.maxLevel !== undefined) {
+          prev.maxLevel = prev.maxLevel === undefined ? pin.maxLevel : Math.min(prev.maxLevel, pin.maxLevel);
+        }
+        out.set(i, prev);
+      }
+    }
+    return out;
+  }
+
   /**
    * Append a summary to the in-memory list and to the chronicle AppendLog.
    * Single point so subclasses inherit persistence.
@@ -1004,20 +1077,31 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    */
   protected driveSpeculativeDrain(ctx: StrategyContext): void {
     if (this.pendingCompression) return;
-    if (this.compressionQueue.length === 0 && this.mergeQueue.length === 0) return;
-    if (this.isAtSpeculativeCap()) return;
-    if (!this.shouldCompressPreflight()) return;
-
-    const beforeChunks = this.compressionQueue.length;
-    const beforeMerges = this.mergeQueue.length;
+    // Merges consolidate existing L_k summaries into L_{k+1} and REDUCE the
+    // unmerged-L1 count; L1 compression PRODUCES new unmerged L1s. The
+    // speculation cap / preflight throttle *production* only — they must never
+    // gate merges, otherwise exceeding the cap (e.g. after a manual backfill)
+    // permanently deadlocks the drain: too many unmerged L1s trips the cap,
+    // which blocks the very merges that would bring the count back down.
+    const hasMerges = this.config.hierarchical === true && this.mergeQueue.length > 0;
+    const hasCompression = this.compressionQueue.length > 0;
+    if (!hasCompression && !hasMerges) return;
+    // Only bail when the *sole* available work is L1 compression that the cap
+    // or preflight currently forbids. Merge work always proceeds.
+    if (!hasMerges && (this.isAtSpeculativeCap() || !this.shouldCompressPreflight())) return;
+
+    const progressBefore = this._drainProgress;
 
     this.tick(ctx)
       .then(() => {
-        const afterChunks = this.compressionQueue.length;
-        const afterMerges = this.mergeQueue.length;
-        // Made progress if either queue shrank.
-        const progressed = afterChunks < beforeChunks || afterMerges < beforeMerges;
-        if (!progressed) return;
+        // Progress = the tick actually processed a queue item (compress or
+        // merge), tracked by `_drainProgress`. A queue-length delta is the
+        // wrong signal: a productive merge tick can also enqueue a follow-on
+        // merge, leaving the length unchanged — which the old check misread as
+        // "no progress" and halted the drain mid-backlog. A genuine no-op tick
+        // (empty queues, at-cap with no merges, no membrane) doesn't advance
+        // the counter, so this still stops cleanly (no runaway recursion).
+        if (this._drainProgress === progressBefore) return;
         // Recurse to drain more. queueMicrotask defers until the current
         // task is done, letting other code (the agent's stream consumer)
         // interleave.
@@ -1029,14 +1113,23 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   }
 
   /**
-   * Whether the strategy's pending+queued L1 budget has reached the cap
+   * Whether the count of *produced, unmerged* L1 summaries has reached the cap
    * configured by `maxSpeculativeL1s`. If no cap is set, always false.
+   *
+   * The cap bounds how many L1 summaries may sit un-consolidated before the
+   * strategy must merge them into L_{k+1} (bounding prefix churn / merge debt).
+   * It deliberately does NOT count the pending `compressionQueue`: that queue is
+   * the backlog of work to be *drained*, not produced summaries. Counting it
+   * here would let a large backlog permanently trip the cap and block the very
+   * compression that would clear it — a deadlock (merges relieve the cap, but
+   * compression of the backlog never resumes). The throttle is on produced L1s;
+   * the queue drains freely, with merges keeping the unmerged count under the cap.
    */
   protected isAtSpeculativeCap(): boolean {
     const cap = this.config.maxSpeculativeL1s;
     if (cap === undefined || cap < 0) return false;
     const unmergedL1s = this.summaries.filter(s => s.level === 1 && !s.mergedInto).length;
-    return unmergedL1s + this.compressionQueue.length > cap;
+    return unmergedL1s > cap;
   }
 
   /**
@@ -1050,6 +1143,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   }
 
   async tick(ctx: StrategyContext): Promise<void> {
+    phaseChannel.report('compress-tick'); // liveness-watchdog phase
     if (this.pendingCompression) return;
 
     if (!ctx.membrane) {
@@ -1057,16 +1151,18 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       return;
     }
 
-    // Priority 1: Compress raw chunks → L1
-    if (this.compressionQueue.length > 0) {
+    // Priority 1: Compress raw chunks → L1. Skipped while at the speculative
+    // cap (maxSpeculativeL1s) so we don't pile up more unmerged L1s; the merge
+    // priority below still runs to consolidate existing L1s and relieve the cap.
+    // No cap configured → isAtSpeculativeCap() is always false → unchanged.
+    if (this.compressionQueue.length > 0 && !this.isAtSpeculativeCap()) {
       const chunkIndex = this.compressionQueue.shift()!;
+      this._drainProgress++; // consumed a queue item (real work or stale-cleanup)
       const chunk = this.chunks[chunkIndex];
 
       if (!chunk || chunk.compressed) return;
 
-      this.pendingCompression = this.config.hierarchical
-        ? this.compressChunkHierarchical(chunk, ctx)
-        : this.compressChunkLegacy(chunk, ctx);
+      this.pendingCompression = this.compressChunkHierarchical(chunk, ctx);
 
       try {
         await this.pendingCompression;
@@ -1087,6 +1183,8 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // and the next tick() retries it.
     if (this.config.hierarchical && this.mergeQueue.length > 0) {
       const merge = this.mergeQueue[0]!;
+      this._drainProgress++; // executing a merge is real work, even if a
+      // follow-on merge gets enqueued and the queue length nets out unchanged
       this.pendingCompression = this.executeMerge(merge.level, merge.sourceIds, ctx);
 
       try {
@@ -1136,12 +1234,13 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   ): ContextEntry[] {
     this.rebuildChunks(store);
 
+    // Image stripping runs inside each select path (before stats commit / cache
+    // markers), so the returned entries are already bounded — see
+    // applyImageStripping.
     if (this.config.adaptiveResolution) {
       return this.selectAdaptive(store, budget);
     }
-    return this.config.hierarchical
-      ? this.selectHierarchical(store, budget)
-      : this.selectLegacy(store, log, budget);
+    return this.selectHierarchical(store, budget);
   }
 
   /**
@@ -1171,16 +1270,89 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * Useful for TUI / dashboards. The token sums use the strategy's own
    * token estimates (which match what `select()` uses for budget math).
    */
-  getRenderStats(store: MessageStoreView): {
-    head: { messages: number; tokens: number };
-    tail: { messages: number; tokens: number };
-    summaries: {
-      l1: { count: number; tokens: number };
-      l2: { count: number; tokens: number };
-      l3: { count: number; tokens: number };
+  // ===========================================================================
+  // Render-stats instrumentation — inspect, don't reconstruct.
+  //
+  // selectAdaptive/selectHierarchical tally each entry into `_rs` AS THEY EMIT
+  // it (raw head/tail, raw middle the picker kept verbatim, and recall pairs
+  // bucketed by the ancestor summary's level), using the same token numbers the
+  // renderer uses for budget math. `getRenderStats()` returns that committed
+  // snapshot, so it reflects what the last compile actually rendered rather than
+  // re-deriving the full pyramid (which, under adaptive resolution, bears little
+  // resemblance to the folded output).
+  // ===========================================================================
+  private _rs: RenderStats | null = null;
+  private _lastRenderStats: RenderStats | null = null;
+
+  /** Begin a render-stats accumulation for one select() pass. */
+  protected rsBegin(): void {
+    this._rs = {
+      head: { messages: 0, tokens: 0 },
+      tail: { messages: 0, tokens: 0 },
+      middleRaw: { messages: 0, tokens: 0 },
+      summaries: {
+        l1: { count: 0, tokens: 0 },
+        l2: { count: 0, tokens: 0 },
+        l3: { count: 0, tokens: 0 },
+      },
+      pending: { chunks: 0, merges: 0 },
+      total: { messages: 0, tokens: 0 },
     };
-    pending: { chunks: number; merges: number };
-  } {
+  }
+
+  /** Tally one (or `count`) raw message(s) into a raw bucket. */
+  protected rsRaw(bucket: 'head' | 'tail' | 'middleRaw', tokens: number, count = 1): void {
+    const r = this._rs;
+    if (!r) return;
+    r[bucket].messages += count;
+    r[bucket].tokens += tokens;
+  }
+
+  /** Tally one emitted recall pair under its ancestor's level (>=3 folds into l3). */
+  protected rsSummary(level: number, tokens: number): void {
+    const r = this._rs;
+    if (!r) return;
+    const k: 'l1' | 'l2' | 'l3' = level <= 1 ? 'l1' : level === 2 ? 'l2' : 'l3';
+    r.summaries[k].count += 1;
+    r.summaries[k].tokens += tokens;
+  }
+
+  /** Commit the accumulated stats as the last-render snapshot. */
+  protected rsEnd(): void {
+    const r = this._rs;
+    if (!r) return;
+    r.pending = {
+      chunks: this.chunks.filter(c => !c.compressed).length,
+      merges: this.mergeQueue.length,
+    };
+    const s = r.summaries;
+    const summaryMsgs = (s.l1.count + s.l2.count + s.l3.count) * 2; // Q/A pair each
+    r.total = {
+      messages: r.head.messages + r.tail.messages + r.middleRaw.messages + summaryMsgs,
+      tokens:
+        r.head.tokens + r.tail.tokens + r.middleRaw.tokens +
+        s.l1.tokens + s.l2.tokens + s.l3.tokens,
+    };
+    this._lastRenderStats = r;
+    this._rs = null;
+  }
+
+  /**
+   * Stats describing the LAST rendered context. Returns the inspected snapshot
+   * captured during the most recent `select()`. Before any compile has run (no
+   * snapshot yet), falls back to a reconstructed pyramid view so callers still
+   * get a non-null shape.
+   */
+  getRenderStats(store: MessageStoreView): RenderStats {
+    return this._lastRenderStats ?? this.reconstructRenderStats(store);
+  }
+
+  /**
+   * Pre-render fallback: re-derive head/tail windows + the full live pyramid.
+   * NOTE: this is the old "reconstruct" behavior and does NOT reflect adaptive
+   * folding — used only until the first compile populates the inspected stats.
+   */
+  protected reconstructRenderStats(store: MessageStoreView): RenderStats {
     const messages = store.getAll();
     const headStart = this.getHeadWindowStartIndex(store);
     const headEnd = this.getHeadWindowEnd(store);
@@ -1197,145 +1369,31 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     const sumLevelTokens = (level: SummaryLevel): number =>
       live(level).reduce((acc, s) => acc + s.tokens, 0);
 
+    const head = { messages: headMsgs.length, tokens: sumTokens(headMsgs) };
+    const tail = { messages: tailMsgs.length, tokens: sumTokens(tailMsgs) };
+    const summaries = {
+      l1: { count: live(1).length, tokens: sumLevelTokens(1) },
+      l2: { count: live(2).length, tokens: sumLevelTokens(2) },
+      l3: { count: live(3).length, tokens: sumLevelTokens(3) },
+    };
     return {
-      head: { messages: headMsgs.length, tokens: sumTokens(headMsgs) },
-      tail: { messages: tailMsgs.length, tokens: sumTokens(tailMsgs) },
-      summaries: {
-        l1: { count: live(1).length, tokens: sumLevelTokens(1) },
-        l2: { count: live(2).length, tokens: sumLevelTokens(2) },
-        l3: { count: live(3).length, tokens: sumLevelTokens(3) },
-      },
+      head,
+      tail,
+      middleRaw: { messages: 0, tokens: 0 },
+      summaries,
       pending: {
         chunks: this.chunks.filter(c => !c.compressed).length,
         merges: this.mergeQueue.length,
       },
+      total: {
+        messages: head.messages + tail.messages
+          + (summaries.l1.count + summaries.l2.count + summaries.l3.count) * 2,
+        tokens: head.tokens + tail.tokens
+          + summaries.l1.tokens + summaries.l2.tokens + summaries.l3.tokens,
+      },
     };
   }
 
-  // ============================================================================
-  // Legacy (single-level) path
-  // ============================================================================
-
-  protected selectLegacy(
-    store: MessageStoreView,
-    _log: ContextLogView,
-    budget: TokenBudget
-  ): ContextEntry[] {
-    const entries: ContextEntry[] = [];
-    const maxTokens = budget.maxTokens - budget.reserveForResponse;
-    let totalTokens = 0;
-    const messages = store.getAll();
-    const msgCap = this.config.maxMessageTokens;
-
-    // 1. Head window: preserved verbatim as raw copies
-    const headStart = this.getHeadWindowStartIndex(store);
-    const headEnd = this.getHeadWindowEnd(store);
-    for (let i = headStart; i < headEnd && i < messages.length; i++) {
-      const msg = messages[i];
-      const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-      const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-      if (this.isOverBudget(totalTokens + tokens, maxTokens)) break;
-
-      entries.push({
-        index: entries.length,
-        sourceMessageId: msg.id,
-        sourceRelation: 'copy',
-        participant: msg.participant,
-        content,
-      });
-      totalTokens += tokens;
-    }
-    // Mark the last head entry as a cache boundary (even if budget truncated the window)
-    if (entries.length > 0) {
-      entries[entries.length - 1].cacheMarker = true;
-    }
-
-    // 2. Middle zone: compressed chunks as diary pairs, uncompressed as raw messages.
-    const rawRecentStart = this.getRecentWindowStart(store);
-    // Track which message IDs are covered by chunks
-    const coveredByChunks = new Set<string>();
-
-    for (const chunk of this.chunks) {
-      for (const m of chunk.messages) coveredByChunks.add(m.id);
-
-      if (chunk.compressed && chunk.diary) {
-        const contextLabel = this.config.summaryContextLabel ?? 'Here is a summary of earlier conversation context:';
-        const summaryParticipant = this.config.summaryParticipant ?? 'Summary';
-
-        const questionEntry: ContextEntry = {
-          index: entries.length,
-          participant: 'Context Manager',
-          content: [{ type: 'text', text: contextLabel }],
-          sourceRelation: 'derived',
-        };
-
-        // Synthesised summary turns must respect maxMessageTokens just like raw
-        // copies do — otherwise a runaway diary can starve recent messages.
-        const answerContent: ContentBlock[] = [{ type: 'text', text: chunk.diary }];
-        const answerEntry: ContextEntry = {
-          index: entries.length + 1,
-          participant: summaryParticipant,
-          content: msgCap > 0 ? this.truncateContent(answerContent, msgCap) : answerContent,
-          sourceRelation: 'derived',
-        };
-
-        const pairTokens = this.estimateTokens(questionEntry.content) +
-                           this.estimateTokens(answerEntry.content);
-
-        if (this.isOverBudget(totalTokens + pairTokens, maxTokens)) break;
-
-        entries.push(questionEntry);
-        entries.push(answerEntry);
-        totalTokens += pairTokens;
-      } else {
-        // Uncompressed: emit raw messages so they aren't lost
-        for (const msg of chunk.messages) {
-          const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-          const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-          if (this.isOverBudget(totalTokens + tokens, maxTokens)) break;
-
-          entries.push({
-            index: entries.length,
-            sourceMessageId: msg.id,
-            sourceRelation: 'copy',
-            participant: msg.participant,
-            content,
-          });
-          totalTokens += tokens;
-        }
-      }
-    }
-
-    // Emit gap messages in the compressible zone not covered by any chunk.
-    // Compressible zone: [0, headStart) ∪ [headEnd, rawRecentStart)
-    for (let i = 0; i < rawRecentStart && i < messages.length; i++) {
-      // Skip head window messages (already emitted verbatim above)
-      if (i >= headStart && i < headEnd) continue;
-      if (coveredByChunks.has(messages[i].id)) continue;
-      const msg = messages[i];
-      const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
-      const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
-      if (this.isOverBudget(totalTokens + tokens, maxTokens)) break;
-
-      entries.push({
-        index: entries.length,
-        sourceMessageId: msg.id,
-        sourceRelation: 'copy',
-        participant: msg.participant,
-        content,
-      });
-      totalTokens += tokens;
-    }
-
-    // 3. Recent uncompressed messages (skip those already in head window)
-    const recentStart = Math.max(this.getRecentWindowStart(store), headEnd);
-    this.emitRecentNewestFirst(entries, store, messages, recentStart, msgCap, maxTokens, totalTokens);
-
-    this.trimOrphanedToolUse(entries);
-    this.pruneToolEntries(entries);
-    return entries;
-  }
-
   /**
    * Emit recent-window messages, evicting OLDEST-first when the budget is tight.
    *
@@ -1355,8 +1413,8 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     msgCap: number,
     maxTokens: number,
     totalTokensBefore: number,
-  ): void {
-    if (recentStart >= messages.length) return;
+  ): { messages: number; tokens: number } {
+    if (recentStart >= messages.length) return { messages: 0, tokens: 0 };
 
     const accepted: number[] = [];
     let acceptedTokens = 0;
@@ -1380,9 +1438,13 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       accepted.shift();
     }
 
+    let emittedTokens = 0;
     for (const i of accepted) {
       const msg = messages[i];
       const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
+      const tokens = msgCap > 0
+        ? Math.min(store.estimateTokens(msg), msgCap + 50)
+        : store.estimateTokens(msg);
       entries.push({
         index: entries.length,
         sourceMessageId: msg.id,
@@ -1390,100 +1452,9 @@ export class AutobiographicalStrategy implements ResettableStrategy {
         participant: msg.participant,
         content,
       });
+      emittedTokens += tokens;
     }
-  }
-
-  protected async compressChunkLegacy(chunk: Chunk, ctx: StrategyContext): Promise<void> {
-    if (!ctx.membrane) {
-      throw new Error('No membrane instance for compression');
-    }
-
-    const priorContext = this.buildPriorContextLegacy(chunk, ctx);
-    const chunkContent = this.formatChunkForCompression(chunk);
-
-    const prompt = this.config.diaryUserPrompt ?? this.config.summaryUserPrompt!;
-    const systemPrompt = this.config.diarySystemPrompt ?? this.config.summarySystemPrompt!;
-
-    const messages = [
-      ...priorContext,
-      {
-        participant: 'Context Manager',
-        content: [{ type: 'text' as const, text: prompt.replace('{content}', chunkContent) }],
-      },
-    ];
-
-    const request: NormalizedRequest = {
-      messages: messages.map((m) => ({
-        participant: m.participant,
-        content: m.content,
-      })),
-      system: systemPrompt,
-      config: {
-        model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
-        maxTokens: 2000,
-      },
-    };
-
-    try {
-      const response = await ctx.membrane.complete(request);
-      const diaryText = response.content
-        .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
-        .map((b) => b.text)
-        .join('\n');
-
-      chunk.compressed = true;
-      chunk.diary = diaryText;
-      this._compressionCount++;
-    } catch (error) {
-      console.error('Failed to compress chunk:', error);
-      throw error;
-    }
-  }
-
-  protected buildPriorContextLegacy(chunk: Chunk, ctx: StrategyContext): Array<{
-    participant: string;
-    content: ContentBlock[];
-  }> {
-    const context: Array<{ participant: string; content: ContentBlock[] }> = [];
-
-    for (const prevChunk of this.chunks) {
-      if (prevChunk.index >= chunk.index) break;
-      if (!prevChunk.compressed || !prevChunk.diary) continue;
-
-      context.push({
-        participant: 'Context Manager',
-        content: [{ type: 'text', text: this.config.summaryContextLabel ?? 'Summary of earlier context:' }],
-      });
-      context.push({
-        participant: this.config.summaryParticipant ?? 'Summary',
-        content: [{ type: 'text', text: prevChunk.diary }],
-      });
-    }
-
-    // Find the actual position of this chunk's first message in the full array
-    const messages = ctx.messageStore.getAll();
-    const firstMsgId = chunk.messages[0]?.id;
-    const chunkAbsStart = firstMsgId
-      ? messages.findIndex(m => m.id === firstMsgId)
-      : -1;
-
-    if (chunkAbsStart > 0) {
-      const precedingStart = Math.max(0, chunkAbsStart - 50);
-      let tokens = 0;
-
-      for (let i = chunkAbsStart - 1; i >= precedingStart && tokens < 15000; i--) {
-        const msg = messages[i];
-        if (!msg) break;
-
-        tokens += ctx.messageStore.estimateTokens(msg);
-        context.unshift({
-          participant: msg.participant,
-          content: msg.content,
-        });
-      }
-    }
-
-    return context;
+    return { messages: accepted.length, tokens: emittedTokens };
   }
 
   // ============================================================================
@@ -1532,6 +1503,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * No system prompt — framing via message structure only.
    */
   protected async compressChunkHierarchical(chunk: Chunk, ctx: StrategyContext): Promise<void> {
+    phaseChannel.report('compress-chunk'); // liveness-watchdog phase
     if (!ctx.membrane) {
       throw new Error('No membrane instance for compression');
     }
@@ -1731,6 +1703,10 @@ export class AutobiographicalStrategy implements ResettableStrategy {
 
     try {
       const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+      // Text-only on purpose: this is the SUMMARIZER's one-shot response —
+      // its thinking/redacted_thinking blocks are scratch work, not part of
+      // the agent's history, and signed thinking is never valid inside a
+      // rewritten summary anyway.
       const summaryText = response.content
         .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
         .map(b => b.text)
@@ -1806,6 +1782,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * summaries when the queue eventually drains.
    */
   protected checkMergeThreshold(): void {
+    phaseChannel.report('merge-threshold'); // liveness-watchdog phase
     if (this.config.speculativeProduction) {
       this.checkMergeThresholdRecursive();
       return;
@@ -2188,6 +2165,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
 
     try {
       const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+      // Text-only on purpose: summarizer scratch thinking is not agent history
       const mergedText = response.content
         .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
         .map(b => b.text)
@@ -2272,6 +2250,8 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * See `docs/adaptive-resolution-design.md` §3, §5.
    */
   protected selectAdaptive(store: MessageStoreView, budget: TokenBudget): ContextEntry[] {
+    phaseChannel.report('context-build'); // liveness-watchdog phase
+    this.rsBegin();
     const entries: ContextEntry[] = [];
     const maxTokens = budget.maxTokens - budget.reserveForResponse;
     const messages = store.getAll();
@@ -2305,10 +2285,11 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       totalTokens += tokens;
       headMessageIds.add(msg.id);
       headTokens += tokens;
+      this.rsRaw('head', tokens);
     }
-    if (entries.length > 0) {
-      entries[entries.length - 1].cacheMarker = true;
-    }
+    // (Cache breakpoints are placed in one pass over the FINAL ordered entries
+    // below — see placeCacheMarkers — capturing the stable folded prefix, not
+    // just the head boundary.)
 
     // Compute tail message IDs (will be emitted at end)
     const effectiveRecentStart = Math.max(recentStart, headEnd);
@@ -2333,6 +2314,11 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // Pinned-position set so the picker doesn't fold messages the user
     // explicitly marked as keep-raw. Built once and reused.
     const pinnedSet = this.pinnedPositions(messages);
+    // V2 dynamic-pin fold-depth bounds (level / maxLevel). A position with a
+    // bound is NOT a classic force-raw pin — the KV-stable controller must be
+    // able to move it to/within its bound — so it renders as `pinned: false`
+    // carrying `pinLevel` / `pinMaxLevel` instead.
+    const pinBounds = this.pinLevelBounds(messages);
 
     // O(1) summary lookup for findAncestorAt — avoids O(summaries) find()
     // calls during emission.
@@ -2346,13 +2332,18 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       const tokens = msgCap > 0
         ? Math.min(store.estimateTokens(msg), msgCap + 50)
         : store.estimateTokens(msg);
+      const bound = pinBounds.get(i);
       pickerChunks.push({
         id: msg.id,
         sequence: i,
         rawTokens: tokens,
         currentResolution: this.resolutions.get(msg.id) ?? 0,
         lockedByAgent: this.locked.has(msg.id),
-        pinned: pinnedSet.has(i),
+        // A classic pin (in pinnedSet with no level bound) stays force-raw. A
+        // leveled pin is not force-raw; it carries its bound instead.
+        pinned: pinnedSet.has(i) && bound === undefined,
+        pinLevel: bound?.level,
+        pinMaxLevel: bound?.maxLevel,
         l1Id: ch?.summaryId,
       });
     }
@@ -2401,7 +2392,13 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     }
 
     // ----- 4. Run the picker -----
-    const totalBudget = maxTokens - totalTokens; // tokens left after head
+    // The picker's token count ALREADY includes the pinned head+tail (it gets
+    // headTokens/tailTokens in pickerInputs and result.finalTokens covers them).
+    // So the budget it folds against is the full maxTokens — NOT maxTokens-head,
+    // which double-counts the head (reserves it twice: once here, once because
+    // finalTokens already includes it). The old form threw ~head-tokens early at
+    // tight budgets and quietly under-used the budget by ~head everywhere.
+    const totalBudget = maxTokens;
     const slack = this.config.compressionSlackRatio ?? 0.1;
     const foldingBudget: FoldingBudget = {
       totalBudget,
@@ -2412,19 +2409,17 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     const headSetForPicker = new Set<ChunkId>(headMessageIds);
     const tailSetForPicker = new Set<ChunkId>(tailMessageIds);
 
-    const picker = this.getAdaptivePicker();
-    const result = picker.run(
-      {
-        chunks: pickerChunks,
-        summaries: summariesMap,
-        recallPairTokens,
-        headChunkIds: headSetForPicker,
-        tailChunkIds: tailSetForPicker,
-        headTokens,
-        tailTokens,
-      },
-      foldingBudget
-    );
+    const pickerInputs: PickerInputs = {
+      chunks: pickerChunks,
+      summaries: summariesMap,
+      recallPairTokens,
+      headChunkIds: headSetForPicker,
+      tailChunkIds: tailSetForPicker,
+      headTokens,
+      tailTokens,
+    };
+    const picker = this.buildPicker(pickerInputs);
+    const result = picker.run(pickerInputs, foldingBudget);
 
     // Commit the new resolutions back to strategy state for next compile.
     // Persist to chronicle only if anything actually changed — avoids
@@ -2552,6 +2547,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
               content,
             });
             totalTokens += tokens;
+            this.rsRaw('middleRaw', tokens);
           } else {
             // summary run — emit Q+A pair, dedup at the strategy level
             const ancestor = currentRun.ancestor;
@@ -2578,6 +2574,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
               entries.push(questionEntry);
               entries.push(answerEntry);
               totalTokens += pairTokens;
+              this.rsSummary(ancestor.level, pairTokens);
             }
           }
           currentRun = null;
@@ -2638,6 +2635,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
           content,
         });
         totalTokens += tokens;
+        this.rsRaw('middleRaw', tokens);
         i++;
       } else {
         const ancestor = this.findAncestorAt(msg.id, resolution, chunksByMessageId, summariesById);
@@ -2653,6 +2651,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
             content,
           });
           totalTokens += tokens;
+          this.rsRaw('middleRaw', tokens);
           i++;
           continue;
         }
@@ -2679,12 +2678,14 @@ export class AutobiographicalStrategy implements ResettableStrategy {
         entries.push(questionEntry);
         entries.push(answerEntry);
         totalTokens += pairTokens;
+        this.rsSummary(ancestor.level, pairTokens);
         i++;
       }
     }
 
     // ----- 6. Emit tail entries newest-first eviction (matches existing behavior) -----
-    this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+    const tailStats = this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+    this.rsRaw('tail', tailStats.tokens, tailStats.messages);
 
     // ----- 7. Post-process: merge consecutive raw entries from the same bodyGroup -----
     // Both head and tail emission paths emit shards as separate ContextEntries.
@@ -2694,10 +2695,59 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // it falls into (preserves KV cache through region transitions).
     const merged = this.mergeAdjacentBodyGroupRaw(entries, store);
 
+    this.pruneToolEntries(merged);
     this.trimOrphanedToolUse(merged);
+    // Strip stale images BEFORE placing markers and committing stats, so both
+    // describe the post-strip context the agent actually receives.
+    this.applyImageStripping(merged, store);
+    // Place ≤4 cache breakpoints across the FINAL ordered entries so the
+    // provider can reuse the stable folded prefix — not just the head. With a
+    // single head marker the cache hit is ~2%; well-placed breakpoints take the
+    // real strategy to ~50% (docs/kv-stable-context-control.md — marker
+    // placement is the dominant KV lever).
+    this.placeCacheMarkers(merged, headMessageIds, tailMessageIds);
+    this.rsEnd();
     return merged;
   }
 
+  /**
+   * Place up to four `cache_control` breakpoints across the final ordered
+   * entries: the head/system boundary, the end of the folded history (the
+   * stable prefix that persists turn-to-turn — the most valuable), a mid-history
+   * seam, and the very end (for pure-append reuse). Mirrors `placeMarkers` in
+   * the adaptive layer but operates on emitted entries. Idempotent; clears any
+   * pre-existing markers first.
+   */
+  protected placeCacheMarkers(
+    entries: ContextEntry[],
+    headMessageIds: ReadonlySet<MessageId>,
+    tailMessageIds: ReadonlySet<MessageId>,
+  ): void {
+    for (const e of entries) if (e.cacheMarker) e.cacheMarker = false;
+    const n = entries.length;
+    if (n === 0) return;
+
+    let lastHead = -1;
+    let firstTail = n;
+    for (let i = 0; i < n; i++) {
+      const sid = entries[i].sourceMessageId;
+      if (sid && headMessageIds.has(sid)) lastHead = i;
+    }
+    for (let i = 0; i < n; i++) {
+      const sid = entries[i].sourceMessageId;
+      if (sid && tailMessageIds.has(sid)) { firstTail = i; break; }
+    }
+    const historyEnd = firstTail - 1; // last middle (folded-history) entry
+
+    const marks = new Set<number>();
+    if (lastHead >= 0) marks.add(lastHead);                       // system / head block
+    if (historyEnd > lastHead) marks.add(historyEnd);            // stable folded prefix (the big one)
+    if (historyEnd - lastHead > 2) marks.add(lastHead + Math.floor((historyEnd - lastHead) / 2)); // mid-history
+    marks.add(n - 1);                                            // end → pure-append reuse
+
+    for (const idx of marks) if (idx >= 0 && idx < n) entries[idx].cacheMarker = true;
+  }
+
   /**
    * Walk an entries array; for every run of consecutive entries that
    *  (a) have sourceRelation: 'copy' (raw, not a synthesized recall pair)
@@ -2791,6 +2841,23 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     return this._adaptivePicker;
   }
 
+  /**
+   * Build the picker for this compile. Instance folding strategies (kv-stable)
+   * need the per-compile `PickerInputs` at construction, so they're built fresh
+   * here; stateless ones (flat-profile / oldest-first) reuse the memoized picker.
+   */
+  protected buildPicker(inputs: PickerInputs): Picker {
+    if (this.config.foldingStrategy === 'kv-stable') {
+      return new Picker(
+        new KvStableStrategy(inputs, {
+          reachTokens: this.config.kvStableReachTokens,
+          mergeThreshold: this.config.mergeThreshold,
+        }),
+      );
+    }
+    return this.getAdaptivePicker();
+  }
+
   /**
    * Walk the summary tree to find the L_k ancestor of a message.
    * Returns null if no ancestor exists at that level (e.g., L_k not yet produced).
@@ -2871,6 +2938,8 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
    */
   protected selectHierarchical(store: MessageStoreView, budget: TokenBudget): ContextEntry[] {
+    phaseChannel.report('context-build'); // liveness-watchdog phase
+    this.rsBegin();
     const entries: ContextEntry[] = [];
     const maxTokens = budget.maxTokens - budget.reserveForResponse;
     const messages = store.getAll();
@@ -2895,6 +2964,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
         content,
       });
       totalTokens += tokens;
+      this.rsRaw('head', tokens);
     }
     // Mark the last head entry as a cache boundary (even if budget truncated the window)
     if (entries.length > 0) {
@@ -3054,6 +3124,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
             entries.push(questionEntry);
             entries.push(answerEntry);
             totalTokens += pairTokens;
+            this.rsSummary(summary.level, pairTokens);
           } else {
             const msg = item.msg;
             const content = msgCap > 0 ? this.truncateContent(msg.content, msgCap) : msg.content;
@@ -3069,6 +3140,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
               content,
             });
             totalTokens += tokens;
+            this.rsRaw('middleRaw', tokens);
           }
         }
       } else {
@@ -3102,6 +3174,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
           entries.push(questionEntry);
           entries.push(answerEntry);
           totalTokens += pairTokens;
+          for (const s of selectedSummaries) this.rsSummary(s.level, s.tokens);
         }
 
         // Sort by position so uncompressed-middle messages and pins both
@@ -3121,6 +3194,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
             content,
           });
           totalTokens += tokens;
+          this.rsRaw('middleRaw', tokens);
         }
       }
     }
@@ -3130,10 +3204,15 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // budget, the latest messages (the ones the agent actually needs to act
     // on) are preserved and the oldest recent-window messages are dropped.
     const effectiveRecentStart = Math.max(recentStart, headEnd);
-    this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+    const tailStats = this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+    this.rsRaw('tail', tailStats.tokens, tailStats.messages);
 
     this.trimOrphanedToolUse(entries);
     this.pruneToolEntries(entries);
+    // Strip stale images before committing stats so RenderStats.total reflects
+    // the post-strip context (this path places no cache markers).
+    this.applyImageStripping(entries, store);
+    this.rsEnd();
     return entries;
   }
 
@@ -3388,6 +3467,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     };
 
     const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
+    // Text-only on purpose: summarizer scratch thinking is not agent history
     return response.content
       .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
       .map(b => b.text)
@@ -3561,7 +3641,6 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     const existing = existingCompressed.get(key);
     if (existing) {
       chunk.compressed = true;
-      chunk.diary = existing.diary;
       chunk.summaryId = existing.summaryId;
     }
 
@@ -3583,6 +3662,98 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     return chunk.messages.map((m) => m.id).join(':');
   }
 
+  /** True if any content block is a live image. */
+  protected hasImageBlock(content: ContentBlock[]): boolean {
+    return content.some((b) => b.type === 'image');
+  }
+
+  /** Message index marking the image-strip depth boundary: walks newest→oldest
+   *  summing the same per-message estimate as getRecentWindowStart, and returns
+   *  the index of the first message still within `depthTokens`. Messages before
+   *  this index have their images stripped to placeholders. */
+  protected getImageStripStart(store: MessageStoreView, depthTokens: number): number {
+    const messages = store.getAll();
+    let tokens = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      tokens += store.estimateTokens(messages[i]);
+      if (tokens > depthTokens) return i + 1;
+    }
+    return 0;
+  }
+
+  /** Text substituted for an image block once it leaves the live-image window. */
+  private static readonly IMAGE_PLACEHOLDER = '[image dropped from live context]';
+
+  /** Post-pass over compiled entries: replace image blocks with a text
+   *  placeholder once they fall outside the live-image window — either deeper
+   *  than `imageStripDepthTokens` from the newest message, or beyond the
+   *  `maxLiveImages` most-recent images (counted newest-first). Summaries are
+   *  already text, so they're naturally unaffected. The adjacent
+   *  "[image attachment: <name>]" text added at ingest preserves the filename,
+   *  so the placeholder itself stays terse. Reduces tokens, so it never pushes
+   *  a compiled context back over budget.
+   *
+   *  Runs INSIDE each select path, *before* `rsEnd()` and `placeCacheMarkers`,
+   *  so the committed render stats (and the cache breakpoints) describe the
+   *  post-strip context. As it strips, it decrements the matching raw bucket of
+   *  the in-progress render stats by the reclaimed tokens, keeping
+   *  `RenderStats.total` equal to the real rendered size. */
+  protected applyImageStripping(entries: ContextEntry[], store: MessageStoreView): void {
+    const maxLive = this.config.maxLiveImages ?? 0;             // 0 = unlimited count
+    const depthTokens = this.config.imageStripDepthTokens ?? 0; // 0 = no depth strip
+    if (maxLive === 0 && depthTokens === 0) return;             // policy disabled
+
+    const messages = store.getAll();
+    const posById = new Map<string, number>();
+    for (let i = 0; i < messages.length; i++) posById.set(messages[i].id, i);
+    const stripStart = depthTokens > 0 ? this.getImageStripStart(store, depthTokens) : 0;
+
+    // Same region windows select() bucketed by, so a stripped image's reclaimed
+    // tokens come back out of the bucket it was originally tallied into.
+    const headStart = this.getHeadWindowStartIndex(store);
+    const headEnd = this.getHeadWindowEnd(store);
+    const recentStart = Math.max(this.getRecentWindowStart(store), headEnd);
+    const bucketAt = (pos: number): 'head' | 'tail' | 'middleRaw' => {
+      if (pos < 0) return 'middleRaw'; // no resolvable region — keep total == Σbuckets
+      if (pos >= headStart && pos < headEnd) return 'head';
+      if (pos >= recentStart) return 'tail';
+      return 'middleRaw';
+    };
+    const placeholderTokens = Math.ceil(AutobiographicalStrategy.IMAGE_PLACEHOLDER.length / 4);
+
+    // Image-bearing entries, newest-first by source position. Entries with no
+    // resolvable source position sort last (pos -1) and never count as "live".
+    const ordered = entries
+      .map((entry, idx) => ({
+        idx,
+        pos: entry.sourceMessageId !== undefined ? posById.get(entry.sourceMessageId) ?? -1 : -1,
+      }))
+      .filter(({ idx }) => this.hasImageBlock(entries[idx].content))
+      .sort((a, b) => b.pos - a.pos);
+
+    let keptImages = 0;
+    for (const { idx, pos } of ordered) {
+      const entry = entries[idx];
+      const tooDeep = depthTokens > 0 && (pos < 0 || pos < stripStart);
+      const bucket = bucketAt(pos);
+      entry.content = entry.content.map((block) => {
+        if (block.type !== 'image') return block;
+        const overCount = maxLive > 0 && keptImages >= maxLive;
+        if (tooDeep || overCount) {
+          // The renderer estimates an image at `tokenEstimate ?? 1600` (see
+          // message-store/context-log). Hand that back to the bucket, less the
+          // placeholder text that replaces it, so the stats match the output.
+          const reclaimed =
+            ((block as { tokenEstimate?: number }).tokenEstimate ?? 1600) - placeholderTokens;
+          if (this._rs && reclaimed > 0) this._rs[bucket].tokens -= reclaimed;
+          return { type: 'text', text: AutobiographicalStrategy.IMAGE_PLACEHOLDER } as ContentBlock;
+        }
+        keptImages++;
+        return block;
+      });
+    }
+  }
+
   protected getRecentWindowStart(store: MessageStoreView): number {
     const messages = store.getAll();
     let tokens = 0;