@animalabs/context-manager 0.5.2 → 0.5.4

package/dist/src/strategies/autobiographical.js

@@ -1,11 +1,12 @@
 import { NativeFormatter } from '@animalabs/membrane';
 import { DEFAULT_AUTOBIOGRAPHICAL_CONFIG } from '../types/index.js';
 import { getSummaryParentId } from '../types/strategy.js';
-import { splitMixedToolMessages } from '../normalize-tool-messages.js';
+import { splitMixedToolMessages, stripUnpairedToolBlocks } from '../normalize-tool-messages.js';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Picker, OverBudgetError } 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 { chunkMessage, DEFAULT_CHUNKER_OPTIONS } from '../adaptive/chunker.js';
 /**
@@ -923,9 +924,7 @@ export class AutobiographicalStrategy {
             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;
             }
@@ -992,12 +991,13 @@ export class AutobiographicalStrategy {
     }
     select(store, log, budget) {
         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);
     }
     /**
      * Get summary statistics for observability.
@@ -1022,7 +1022,85 @@ export class AutobiographicalStrategy {
      * Useful for TUI / dashboards. The token sums use the strategy's own
      * token estimates (which match what `select()` uses for budget math).
      */
+    // ===========================================================================
+    // 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).
+    // ===========================================================================
+    _rs = null;
+    _lastRenderStats = null;
+    /** Begin a render-stats accumulation for one select() pass. */
+    rsBegin() {
+        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 },
+        };
+    }
+    /** Tally one (or `count`) raw message(s) into a raw bucket. */
+    rsRaw(bucket, tokens, count = 1) {
+        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). */
+    rsSummary(level, tokens) {
+        const r = this._rs;
+        if (!r)
+            return;
+        const k = 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. */
+    rsEnd() {
+        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) {
+        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.
+     */
+    reconstructRenderStats(store) {
         const messages = store.getAll();
         const headStart = this.getHeadWindowStartIndex(store);
         const headEnd = this.getHeadWindowEnd(store);
@@ -1032,131 +1110,30 @@ export class AutobiographicalStrategy {
         const tailMsgs = messages.slice(recentStart);
         const live = (level) => this.summaries.filter(s => s.level === level && !s.mergedInto);
         const sumLevelTokens = (level) => 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
-    // ============================================================================
-    selectLegacy(store, _log, budget) {
-        const entries = [];
-        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();
-        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 = {
-                    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 = [{ type: 'text', text: chunk.diary }];
-                const answerEntry = {
-                    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.
      *
@@ -1170,7 +1147,7 @@ export class AutobiographicalStrategy {
      */
     emitRecentNewestFirst(entries, store, messages, recentStart, msgCap, maxTokens, totalTokensBefore) {
         if (recentStart >= messages.length)
-            return;
+            return { messages: 0, tokens: 0 };
         const accepted = [];
         let acceptedTokens = 0;
         for (let i = messages.length - 1; i >= recentStart; i--) {
@@ -1190,9 +1167,13 @@ export class AutobiographicalStrategy {
             !this.hasToolUse(messages[accepted[0]])) {
             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,
@@ -1200,86 +1181,9 @@ export class AutobiographicalStrategy {
                 participant: msg.participant,
                 content,
             });
+            emittedTokens += tokens;
         }
-    }
-    async compressChunkLegacy(chunk, ctx) {
-        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', text: prompt.replace('{content}', chunkContent) }],
-            },
-        ];
-        const request = {
-            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.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;
-        }
-    }
-    buildPriorContextLegacy(chunk, ctx) {
-        const context = [];
-        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 };
     }
     // ============================================================================
     // Hierarchical (L1/L2/L3) path
@@ -1410,10 +1314,20 @@ export class AutobiographicalStrategy {
         // raw messages reappear.
         const chunkFirstId = chunk.messages[0]?.id;
         if (chunkFirstId) {
+            // Expand summary sourceIds down to leaf message IDs. An L2 in
+            // `priorSummaries` has L1 IDs in its sourceIds, not message IDs;
+            // a flat walk would miss every message it transitively covers.
+            // (Bug 10 — same shape as executeMerge.)
+            const summariesById = new Map();
+            for (const s of this.summaries)
+                summariesById.set(s.id, s);
             const priorSummaryMessageIds = new Set();
+            for (const s of this.summaries) {
+                if (s.level === 1)
+                    this.expandSummaryToLeafMessageIds(s, summariesById, priorSummaryMessageIds);
+            }
             for (const s of priorSummaries) {
-                for (const id of s.sourceIds)
-                    priorSummaryMessageIds.add(id);
+                this.expandSummaryToLeafMessageIds(s, summariesById, priorSummaryMessageIds);
             }
             const chunkStartIdx = allMessages.findIndex((m) => m.id === chunkFirstId);
             for (let i = headEndIdx; i < chunkStartIdx && i < allMessages.length; i++) {
@@ -1457,6 +1371,11 @@ export class AutobiographicalStrategy {
         const split = splitMixedToolMessages(llmMessages);
         // Collapse consecutive same-participant messages for API compliance
         const collapsed = this.collapseConsecutiveMessages(split);
+        // Defense in depth against chunk boundaries that cut a tool cycle
+        // (rebuildChunks tries to avoid this, but covers only the most common
+        // case). The API rejects any tool_use that isn't immediately followed
+        // by its tool_result, and any tool_result that doesn't follow a use.
+        const cleaned = stripUnpairedToolBlocks(collapsed);
         // NO system prompt. The agent's identity is established by the head
         // (the actual conversation opening — user message + agent reply that
         // grounded the original instance). A system prompt would (a) add a
@@ -1466,7 +1385,7 @@ export class AutobiographicalStrategy {
         // structural one carried by the conversation itself. Anchoring
         // identity by the chronicle's actual head is more honest.
         const request = {
-            messages: collapsed.map(m => ({ participant: m.participant, content: m.content })),
+            messages: cleaned.map(m => ({ participant: m.participant, content: m.content })),
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: Math.round(targetTokens * 1.5),
@@ -1478,6 +1397,10 @@ export class AutobiographicalStrategy {
         let logSummaryId;
         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.type === 'text')
                 .map(b => b.text)
@@ -1514,7 +1437,7 @@ export class AutobiographicalStrategy {
             logCompressionCall({
                 operation: 'compress_l1',
                 system: null,
-                messages: collapsed.map((m) => ({
+                messages: cleaned.map((m) => ({
                     participant: m.participant,
                     // Flatten content for logging — store text only; binary content
                     // would bloat the log and isn't typical in compression input.
@@ -1767,10 +1690,20 @@ export class AutobiographicalStrategy {
         // The full unmerged-frontier set covers what's "compressed somewhere"
         // for the raw-middle dedup below — a budget-dropped recall pair
         // doesn't make its underlying raw messages reappear.
+        //
+        // Critical: `sourceIds` on an L2+ summary points at L1 IDs, not raw
+        // message IDs. The dedup happens against raw message IDs, so we must
+        // recursively expand each summary down to its leaf message IDs.
+        // Without this, every message under any L2 leaks back in as raw text
+        // (Bug 10: 525-message merge requests on a 4234-msg conversation).
+        // Also expand merged L1s as defense in depth.
         const priorSummaryMessageIds = new Set();
+        for (const s of this.summaries) {
+            if (s.level === 1)
+                this.expandSummaryToLeafMessageIds(s, summariesById, priorSummaryMessageIds);
+        }
         for (const s of priorSummariesAll) {
-            for (const id of s.sourceIds)
-                priorSummaryMessageIds.add(id);
+            this.expandSummaryToLeafMessageIds(s, summariesById, priorSummaryMessageIds);
         }
         for (const s of keptPriorSummaries) {
             llmMessages.push({
@@ -1871,11 +1804,12 @@ export class AutobiographicalStrategy {
         // Same bundled-tool-cycle defense as compressChunkHierarchical.
         const split = splitMixedToolMessages(llmMessages);
         const collapsed = this.collapseConsecutiveMessages(split);
+        const cleaned = stripUnpairedToolBlocks(collapsed);
         // NO system prompt — identity is established by the head window
         // (present at the start of llmMessages above) and by the prior
         // recall pairs. Same rationale as compressChunkHierarchical.
         const request = {
-            messages: collapsed.map(m => ({ participant: m.participant, content: m.content })),
+            messages: cleaned.map(m => ({ participant: m.participant, content: m.content })),
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: Math.round(targetTokens * 1.5),
@@ -1887,6 +1821,7 @@ export class AutobiographicalStrategy {
         let logNewSummaryId;
         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.type === 'text')
                 .map(b => b.text)
@@ -1930,7 +1865,7 @@ export class AutobiographicalStrategy {
             logCompressionCall({
                 operation: `merge_l${targetLevel}`,
                 system: null,
-                messages: collapsed.map((m) => ({
+                messages: cleaned.map((m) => ({
                     participant: m.participant,
                     text: m.content
                         .filter((b) => b.type === 'text')
@@ -1966,6 +1901,7 @@ export class AutobiographicalStrategy {
      * See `docs/adaptive-resolution-design.md` §3, §5.
      */
     selectAdaptive(store, budget) {
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -1996,10 +1932,11 @@ export class AutobiographicalStrategy {
             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);
         for (let i = effectiveRecentStart; i < messages.length; i++) {
@@ -2094,8 +2031,7 @@ export class AutobiographicalStrategy {
         };
         const headSetForPicker = new Set(headMessageIds);
         const tailSetForPicker = new Set(tailMessageIds);
-        const picker = this.getAdaptivePicker();
-        const result = picker.run({
+        const pickerInputs = {
             chunks: pickerChunks,
             summaries: summariesMap,
             recallPairTokens,
@@ -2103,7 +2039,9 @@ export class AutobiographicalStrategy {
             tailChunkIds: tailSetForPicker,
             headTokens,
             tailTokens,
-        }, foldingBudget);
+        };
+        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
         // unnecessary state-slot writes on no-op compiles (which is the common
@@ -2210,6 +2148,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                     else {
                         // summary run — emit Q+A pair, dedup at the strategy level
@@ -2237,6 +2176,7 @@ export class AutobiographicalStrategy {
                             entries.push(questionEntry);
                             entries.push(answerEntry);
                             totalTokens += pairTokens;
+                            this.rsSummary(ancestor.level, pairTokens);
                         }
                     }
                     currentRun = null;
@@ -2310,6 +2250,7 @@ export class AutobiographicalStrategy {
                     content,
                 });
                 totalTokens += tokens;
+                this.rsRaw('middleRaw', tokens);
                 i++;
             }
             else {
@@ -2327,6 +2268,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                     i++;
                     continue;
                 }
@@ -2354,11 +2296,13 @@ export class AutobiographicalStrategy {
                 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.
         // The middle path already merges consecutive same-bodyGroup raw shards into
@@ -2366,9 +2310,62 @@ export class AutobiographicalStrategy {
         // a sharded message renders as ONE API message regardless of which region
         // 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.
+     */
+    placeCacheMarkers(entries, headMessageIds, tailMessageIds) {
+        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();
+        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)
@@ -2457,6 +2454,20 @@ export class AutobiographicalStrategy {
         this._adaptivePicker = new Picker(strategy);
         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.
+     */
+    buildPicker(inputs) {
+        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).
@@ -2483,6 +2494,45 @@ export class AutobiographicalStrategy {
             return null;
         return current;
     }
+    /**
+     * Recursively expand a summary's `sourceIds` down to the leaf message IDs
+     * it covers, adding each leaf into `out`.
+     *
+     * Required because `SummaryEntry.sourceIds` are level-relative: an L1's
+     * sourceIds are raw message IDs (sourceLevel=0), but an L2's sourceIds
+     * are L1 IDs (sourceLevel=1), and so on. Any dedup that walks `sourceIds`
+     * directly only works for L1s — once L2+ summaries enter the picture
+     * (which happens as soon as `mergeThreshold` L1s accumulate during
+     * interleaved compression+merge ticks), the dedup silently fails and
+     * already-summarized messages leak back into the request as raw text.
+     * That's how Bug 10 produced 200k+ token merge prompts on a 4234-msg
+     * import.
+     *
+     * Callers should also expand merged L1s (not just the unmerged frontier)
+     * as defense in depth — a stale `mergedInto` pointer or a partially
+     * applied merge shouldn't surface raw messages.
+     *
+     * `visited` guards against pathological cycles in the summary graph (a
+     * corrupted store or a future merge regression that lets a summary
+     * reference itself). The hierarchy is a DAG by construction, but a
+     * stack overflow during compression — exactly when the safety net is
+     * supposed to save the session — is too steep a price for trusting that.
+     */
+    expandSummaryToLeafMessageIds(summary, summariesById, out, visited = new Set()) {
+        if (visited.has(summary.id))
+            return;
+        visited.add(summary.id);
+        if (summary.sourceLevel === 0) {
+            for (const id of summary.sourceIds)
+                out.add(id);
+            return;
+        }
+        for (const childId of summary.sourceIds) {
+            const child = summariesById.get(childId);
+            if (child)
+                this.expandSummaryToLeafMessageIds(child, summariesById, out, visited);
+        }
+    }
     // ============================================================================
     // Hierarchical (threshold-driven) path
     // ============================================================================
@@ -2491,6 +2541,7 @@ export class AutobiographicalStrategy {
      * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
      */
     selectHierarchical(store, budget) {
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -2513,6 +2564,7 @@ export class AutobiographicalStrategy {
                 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) {
@@ -2662,6 +2714,7 @@ export class AutobiographicalStrategy {
                         entries.push(questionEntry);
                         entries.push(answerEntry);
                         totalTokens += pairTokens;
+                        this.rsSummary(summary.level, pairTokens);
                     }
                     else {
                         const msg = item.msg;
@@ -2679,6 +2732,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                 }
             }
@@ -2710,6 +2764,8 @@ export class AutobiographicalStrategy {
                     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
                 // appear in their chronological place after the combined recall pair.
@@ -2729,6 +2785,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                 }
             }
         }
@@ -2737,9 +2794,14 @@ export class AutobiographicalStrategy {
         // 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;
     }
     // ============================================================================
@@ -2960,6 +3022,7 @@ export class AutobiographicalStrategy {
             },
         };
         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.type === 'text')
             .map(b => b.text)
@@ -3036,6 +3099,16 @@ export class AutobiographicalStrategy {
             currentTokens += msgTokens;
             const shouldClose = currentTokens >= this.config.targetChunkTokens &&
                 currentChunk.length >= 4;
+            // Don't close a chunk on a message containing a tool_use block —
+            // the matching tool_result lives in the immediately-following user
+            // message, and the Anthropic API rejects a request where a tool_use
+            // isn't immediately followed by its tool_result. Defer the close
+            // by one iteration so the result rides along in the same chunk.
+            // The stripUnpairedToolBlocks runtime pass is a safety net for the
+            // rare case where a tool_use is the very last message in the store.
+            if (shouldClose && this.lastMessageContainsToolUse(currentChunk)) {
+                continue;
+            }
             if (shouldClose) {
                 const chunk = this.createChunk(this.chunks.length, chunkFilteredStart, i + 1, currentChunk, currentTokens, existingCompressed);
                 this.chunks.push(chunk);
@@ -3055,6 +3128,19 @@ export class AutobiographicalStrategy {
             }
         }
     }
+    /**
+     * Returns true if the last message in the chunk-in-progress contains a
+     * `tool_use` block. Used by `rebuildChunks` to defer chunk closure until
+     * the matching `tool_result` (in the immediately-following user message)
+     * is pulled into the same chunk. See `stripUnpairedToolBlocks` for the
+     * runtime safety net.
+     */
+    lastMessageContainsToolUse(chunk) {
+        const last = chunk[chunk.length - 1];
+        if (!last)
+            return false;
+        return last.content.some((b) => b.type === 'tool_use');
+    }
     createChunk(index, startIndex, endIndex, messages, tokens, existingCompressed) {
         const chunk = {
             index,
@@ -3068,7 +3154,6 @@ export class AutobiographicalStrategy {
         const existing = existingCompressed.get(key);
         if (existing) {
             chunk.compressed = true;
-            chunk.diary = existing.diary;
             chunk.summaryId = existing.summaryId;
         }
         // In hierarchical mode, also check if a summary exists for this chunk
@@ -3084,6 +3169,97 @@ export class AutobiographicalStrategy {
     chunkKey(chunk) {
         return chunk.messages.map((m) => m.id).join(':');
     }
+    /** True if any content block is a live image. */
+    hasImageBlock(content) {
+        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. */
+    getImageStripStart(store, depthTokens) {
+        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. */
+    static 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. */
+    applyImageStripping(entries, store) {
+        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();
+        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) => {
+            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.tokenEstimate ?? 1600) - placeholderTokens;
+                    if (this._rs && reclaimed > 0)
+                        this._rs[bucket].tokens -= reclaimed;
+                    return { type: 'text', text: AutobiographicalStrategy.IMAGE_PLACEHOLDER };
+                }
+                keptImages++;
+                return block;
+            });
+        }
+    }
     getRecentWindowStart(store) {
         const messages = store.getAll();
         let tokens = 0;