@animalabs/context-manager 0.5.3 → 0.5.5

package/dist/src/strategies/autobiographical.js

@@ -1,4 +1,5 @@
 import { NativeFormatter } from '@animalabs/membrane';
+import { phaseChannel } from '../phase-channel.js';
 import { DEFAULT_AUTOBIOGRAPHICAL_CONFIG } from '../types/index.js';
 import { getSummaryParentId } from '../types/strategy.js';
 import { splitMixedToolMessages, stripUnpairedToolBlocks } from '../normalize-tool-messages.js';
@@ -6,6 +7,7 @@ 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';
 /**
@@ -149,6 +151,20 @@ function safeSlice(str, start, end) {
     }
     return str.slice(start, end);
 }
+/**
+ * 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) {
+    const clean = (v) => 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.
@@ -166,6 +182,14 @@ export class AutobiographicalStrategy {
     pendingCompression = null;
     compressionQueue = [];
     _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.
+     */
+    _drainProgress = 0;
     // Hierarchical state
     summaries = [];
     summaryIdCounter = 0;
@@ -474,6 +498,7 @@ export class AutobiographicalStrategy {
             kind: 'pin',
             name: opts?.name,
             created: Date.now(),
+            ...normalizePinLevels(opts),
         });
         this.persistPins();
         return id;
@@ -492,10 +517,20 @@ export class AutobiographicalStrategy {
             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, lastMessageId, level, opts) {
+        return this.pinRange(firstMessageId, lastMessageId, { name: opts?.name, level });
+    }
     /** Remove a pin or document mark by id. Returns true if removed. */
     unpin(pinId) {
         const before = this.pins.length;
@@ -611,6 +646,45 @@ export class AutobiographicalStrategy {
         }
         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`.
+     */
+    pinLevelBounds(messages) {
+        const out = new Map();
+        if (this.pins.length === 0)
+            return out;
+        const positionOf = new Map();
+        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.
@@ -865,21 +939,31 @@ export class AutobiographicalStrategy {
     driveSpeculativeDrain(ctx) {
         if (this.pendingCompression)
             return;
-        if (this.compressionQueue.length === 0 && this.mergeQueue.length === 0)
+        // 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;
-        if (this.isAtSpeculativeCap())
+        // 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;
-        if (!this.shouldCompressPreflight())
-            return;
-        const beforeChunks = this.compressionQueue.length;
-        const beforeMerges = this.mergeQueue.length;
+        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)
+            // 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)
@@ -891,15 +975,24 @@ export class AutobiographicalStrategy {
         });
     }
     /**
-     * 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.
      */
     isAtSpeculativeCap() {
         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;
     }
     /**
      * Preflight hook for whether speculative compression should fire on
@@ -911,21 +1004,24 @@ export class AutobiographicalStrategy {
         return true;
     }
     async tick(ctx) {
+        phaseChannel.report('compress-tick'); // liveness-watchdog phase
         if (this.pendingCompression)
             return;
         if (!ctx.membrane) {
             console.warn('AutobiographicalStrategy: No membrane instance for compression');
             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;
             }
@@ -945,6 +1041,8 @@ export class AutobiographicalStrategy {
         // 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 {
                 await this.pendingCompression;
@@ -992,12 +1090,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 +1121,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 +1209,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 +1246,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 +1266,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 +1280,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
@@ -1312,6 +1315,7 @@ export class AutobiographicalStrategy {
      * No system prompt — framing via message structure only.
      */
     async compressChunkHierarchical(chunk, ctx) {
+        phaseChannel.report('compress-chunk'); // liveness-watchdog phase
         if (!ctx.membrane) {
             throw new Error('No membrane instance for compression');
         }
@@ -1493,6 +1497,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)
@@ -1566,6 +1574,7 @@ export class AutobiographicalStrategy {
      * summaries when the queue eventually drains.
      */
     checkMergeThreshold() {
+        phaseChannel.report('merge-threshold'); // liveness-watchdog phase
         if (this.config.speculativeProduction) {
             this.checkMergeThresholdRecursive();
             return;
@@ -1913,6 +1922,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)
@@ -1992,6 +2002,8 @@ export class AutobiographicalStrategy {
      * See `docs/adaptive-resolution-design.md` §3, §5.
      */
     selectAdaptive(store, budget) {
+        phaseChannel.report('context-build'); // liveness-watchdog phase
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -2022,10 +2034,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++) {
@@ -2047,6 +2060,11 @@ export class AutobiographicalStrategy {
         // 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.
         const summariesById = new Map();
@@ -2059,13 +2077,18 @@ export class AutobiographicalStrategy {
             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,
             });
         }
@@ -2111,7 +2134,13 @@ export class AutobiographicalStrategy {
             recallPairTokens.set(s.id, s.tokens + 20);
         }
         // ----- 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 = {
             totalBudget,
@@ -2120,8 +2149,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,
@@ -2129,7 +2157,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
@@ -2236,6 +2266,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                     else {
                         // summary run — emit Q+A pair, dedup at the strategy level
@@ -2263,6 +2294,7 @@ export class AutobiographicalStrategy {
                             entries.push(questionEntry);
                             entries.push(answerEntry);
                             totalTokens += pairTokens;
+                            this.rsSummary(ancestor.level, pairTokens);
                         }
                     }
                     currentRun = null;
@@ -2336,6 +2368,7 @@ export class AutobiographicalStrategy {
                     content,
                 });
                 totalTokens += tokens;
+                this.rsRaw('middleRaw', tokens);
                 i++;
             }
             else {
@@ -2353,6 +2386,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                     i++;
                     continue;
                 }
@@ -2380,11 +2414,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
@@ -2392,9 +2428,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)
@@ -2483,6 +2572,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).
@@ -2556,6 +2659,8 @@ export class AutobiographicalStrategy {
      * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
      */
     selectHierarchical(store, budget) {
+        phaseChannel.report('context-build'); // liveness-watchdog phase
+        this.rsBegin();
         const entries = [];
         const maxTokens = budget.maxTokens - budget.reserveForResponse;
         const messages = store.getAll();
@@ -2578,6 +2683,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) {
@@ -2727,6 +2833,7 @@ export class AutobiographicalStrategy {
                         entries.push(questionEntry);
                         entries.push(answerEntry);
                         totalTokens += pairTokens;
+                        this.rsSummary(summary.level, pairTokens);
                     }
                     else {
                         const msg = item.msg;
@@ -2744,6 +2851,7 @@ export class AutobiographicalStrategy {
                             content,
                         });
                         totalTokens += tokens;
+                        this.rsRaw('middleRaw', tokens);
                     }
                 }
             }
@@ -2775,6 +2883,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.
@@ -2794,6 +2904,7 @@ export class AutobiographicalStrategy {
                         content,
                     });
                     totalTokens += tokens;
+                    this.rsRaw('middleRaw', tokens);
                 }
             }
         }
@@ -2802,9 +2913,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;
     }
     // ============================================================================
@@ -3025,6 +3141,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)
@@ -3156,7 +3273,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
@@ -3172,6 +3288,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;