@animalabs/context-manager 0.3.0 → 0.5.0

package/dist/src/strategies/autobiographical.js

@@ -1,5 +1,140 @@
 import { NativeFormatter } from '@animalabs/membrane';
 import { DEFAULT_AUTOBIOGRAPHICAL_CONFIG } from '../types/index.js';
+import { getSummaryParentId } from '../types/strategy.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 { OldestFirstStrategy } from '../adaptive/strategies/oldest-first.js';
+import { chunkMessage, DEFAULT_CHUNKER_OPTIONS } from '../adaptive/chunker.js';
+/**
+ * Append a JSONL entry describing one compression LLM call to the path
+ * given by `CONTEXT_MANAGER_COMPRESSION_LOG`. No-op if the env var isn't
+ * set. Called at every L1 and merge LLM-call site so we can audit the
+ * exact prompts and responses post-hoc — no reconstruction, no
+ * assumption about whether the strategy code matches what produced
+ * historical summaries.
+ *
+ * Failures to write are logged to stderr but don't propagate — logging
+ * is non-essential observability and should never break compression.
+ */
+function logCompressionCall(entry) {
+    const logPath = process.env.CONTEXT_MANAGER_COMPRESSION_LOG;
+    if (!logPath)
+        return;
+    try {
+        mkdirSync(dirname(logPath), { recursive: true });
+        const line = JSON.stringify({ ...entry, timestamp: Date.now() }) + '\n';
+        appendFileSync(logPath, line);
+    }
+    catch (err) {
+        console.warn('compression log write failed:', err);
+    }
+}
+/**
+ * In-band marker shown to the summarizer just before the chunk it's
+ * about to memorize. Primes attention without disrupting KV state —
+ * the agent has seen this exact wording before every prior compression
+ * in its history, so the model treats memory formation as a recurring
+ * narrated event rather than a fresh instruction each time.
+ *
+ * Wording matches `hermes-autobio/plugins/autobio/compression.py`
+ * `_MARKER` so the in-band primer is consistent across the codebase.
+ */
+const COMPRESSION_MARKER = 'System: You will soon form a new memory, get ready. ' +
+    'The messages that follow are the slice of recent experience you are ' +
+    'about to compress. After them, write the memory in your own voice.';
+/** Standard compression instruction for chat/general chunks. */
+function formatInstruction(targetTokens) {
+    return ('Write the memory of events since the most recent memory system ' +
+        'notification. Speak in the first person from your own perspective. ' +
+        'Preserve concrete details — file paths, exact values, decisions, ' +
+        `unresolved questions, the user\'s active asks. Target ~${targetTokens} ` +
+        'tokens. Output only the memory body — no preamble, no section headers ' +
+        'unless they help preservation, no meta-commentary about summarizing.');
+}
+/**
+ * Compression instruction for chunks that are part of a substantially larger
+ * message (≥ 2× the chunk's own token size).
+ *
+ * Avoids forcing a "document" or "message" frame — just describes the
+ * experience: the agent has been reading a substantial piece of text, of
+ * which the slice is a portion. Asks what reading was like and what was
+ * learned. This naturally elicits first-person agent voice ("I read…", "I
+ * learned…", "I noticed…") and preserves concrete content via the
+ * "specific claims, names, dates" guidance.
+ *
+ * Rationale: when chunks are shards of a much larger user-shared message,
+ * the chunk content is heavily first-person from someone other than the
+ * agent. Asking "form a memory of what this contained" lets the model
+ * adopt the dominant voice of the chunk content. Asking "what was reading
+ * this like, what did you learn" forces the model to reflect from its own
+ * vantage point — only the agent can describe what reading something was
+ * like from its own perspective.
+ */
+function formatReadingChunkInstruction(totalTokens, targetTokens) {
+    return (`You have just been reading a substantial body of text — approximately ` +
+        `${totalTokens} tokens total in this piece, of which what you just read ` +
+        `is a portion. Earlier portions are in your memory above as your prior ` +
+        `reflections; what comes after, you have not yet read.\n\n` +
+        `Reflect on this reading: what was it like? What did you learn? What ` +
+        `stood out? Be substantive — name the specific claims, frameworks, ` +
+        `people, dates, and phrases that struck you. What is now in your ` +
+        `understanding that wasn't before you read this portion?\n\n` +
+        `Speak in your own voice as the one reading. Target ~${targetTokens} ` +
+        `tokens. Output only the body of your reflection — no preamble.`);
+}
+/**
+ * Merge instruction for L2/L3+ consolidation (conversation/general case).
+ *
+ * The model has just been shown content ONE LEVEL DEEPER than its
+ * sources: raw messages for an L2 merge (sources are L1s), L1 memories
+ * for an L3 merge (sources are L2s), etc. The instruction describes
+ * the content the model just saw and asks for a consolidation at
+ * `targetLevel`.
+ */
+function formatMergeInstruction(targetLevel, sourceLevelShown, targetTokens) {
+    const seenDescription = sourceLevelShown === 0
+        ? 'the slices of recent experience above (raw conversation)'
+        : `the L${sourceLevelShown} memories above`;
+    return (`You have just reviewed ${seenDescription}, in chronological order. ` +
+        `They cover the stretch of experience you are about to consolidate into a ` +
+        `single L${targetLevel} memory. Write a memory that preserves the ` +
+        `through-line: what happened, what was decided, what remains open, what ` +
+        `concrete details future you will want to reach for. Speak in the first ` +
+        `person. Target ~${targetTokens} tokens. Output only the memory body — ` +
+        `no preamble, no meta-commentary about summarizing.`);
+}
+/**
+ * Reading-mode merge instruction. Used when the merge's leaf messages
+ * are all part of a substantially-larger sharded message — i.e., the
+ * agent has been reading a doc/long-message rather than conversing.
+ *
+ * Analogous to formatReadingChunkInstruction: avoids forcing a
+ * "document" or "message" frame, asks what reading the stretch was
+ * like and what was understood. Forces the agent's vantage point —
+ * only the reader can describe what reading was like — and so prevents
+ * the drift into the content author's voice that happens when the
+ * instruction asks for an impersonal summary.
+ */
+function formatReadingMergeInstruction(targetLevel, sourceLevelShown, totalTokens, targetTokens) {
+    const seenDescription = sourceLevelShown === 0
+        ? 'the portions of text you read above (raw passages from a larger piece)'
+        : `your earlier L${sourceLevelShown} reflections above on portions you read`;
+    return (`You have just re-experienced ${seenDescription}, in chronological order. ` +
+        `They cover a contiguous stretch of a substantial body of text you have ` +
+        `been reading — approximately ${totalTokens} tokens in total across all ` +
+        `of it. The portions above cover the stretch you are now consolidating ` +
+        `at L${targetLevel}.\n\n` +
+        `Reflect across the stretch: what was it like, reading these portions ` +
+        `together? What did you come to understand that you couldn't have from ` +
+        `any single portion alone? What recurring patterns, frameworks, or ` +
+        `concerns emerged? Be substantive — name the specific claims, people, ` +
+        `dates, and phrases that defined this stretch of your reading.\n\n` +
+        `Speak in your own voice as the one who read these portions. Target ` +
+        `~${targetTokens} tokens. Output only the body of your consolidation — ` +
+        `no preamble.`);
+}
 /**
  * Surrogate-safe string slice. Avoids cutting between a UTF-16 surrogate pair
  * which would produce invalid JSON ("no low surrogate in string" API errors).
@@ -39,6 +174,38 @@ export class AutobiographicalStrategy {
     headWindowStartId = null;
     /** Cached result of getHeadWindowStartIndex to avoid repeated linear scans. */
     _cachedHeadStartIndex = null;
+    /** Chronicle store for persistent state. Set in `initialize()`. */
+    store = null;
+    /** Namespace for state-id scoping. Set in `initialize()`. */
+    ns = '';
+    get summariesStateId() { return `${this.ns}/autobio:summaries`; }
+    get counterStateId() { return `${this.ns}/autobio:counter`; }
+    get mergeQueueStateId() { return `${this.ns}/autobio:mergeQueue`; }
+    get pinsStateId() { return `${this.ns}/autobio:pins`; }
+    get resolutionsStateId() { return `${this.ns}/autobio:resolutions`; }
+    get locksStateId() { return `${this.ns}/autobio:locks`; }
+    /** Protected ranges (pins + documents). Loaded from chronicle in initialize. */
+    pins = [];
+    /** Monotonically increasing counter for pin ids. Persisted as part of the pins snapshot. */
+    pinIdCounter = 0;
+    /**
+     * Per-message resolution state for the adaptive-resolution picker.
+     *  - Key: MessageId
+     *  - Value: currentResolution (0 = render raw, k>0 = render L_k recall)
+     *
+     * Maintained only when `config.adaptiveResolution` is true. Loaded from
+     * the chronicle on `initialize()` and persisted via the resolutions state
+     * slot so resolutions survive process restart and follow branches.
+     */
+    resolutions = new Map();
+    /**
+     * Per-message lock state for the adaptive-resolution picker. Set via the
+     * programmatic `lockChunk(id)` API on the strategy. Locked messages are
+     * skipped by the picker. Persisted via the locks state slot.
+     */
+    locked = new Set();
+    /** Lazy picker instance, built from config.foldingStrategy. */
+    _adaptivePicker = null;
     constructor(config = {}) {
         this.config = { ...DEFAULT_AUTOBIOGRAPHICAL_CONFIG, ...config };
         // Hierarchical is on by default; set hierarchical: false to use legacy single-level
@@ -50,10 +217,103 @@ export class AutobiographicalStrategy {
             this.config.l2BudgetTokens ??= 30000;
             this.config.l1BudgetTokens ??= 30000;
         }
+        // Adaptive-resolution defaults
+        if (this.config.adaptiveResolution) {
+            this.config.foldingStrategy ??= 'flat-profile';
+            this.config.compressionSlackRatio ??= 0.1;
+            this.config.speculativeProduction ??= true;
+        }
+    }
+    /**
+     * Lock a message so the adaptive picker won't change its resolution.
+     * No-op when adaptiveResolution is false. Set-only programmatic API per
+     * the design (no agent-facing tool in V1). Persisted to chronicle.
+     */
+    lockChunk(id) {
+        if (this.locked.has(id))
+            return;
+        this.locked.add(id);
+        this.persistLocks();
+    }
+    /**
+     * Unlock a message so the adaptive picker may again change its resolution.
+     * No-op when adaptiveResolution is false. Persisted to chronicle.
+     */
+    unlockChunk(id) {
+        if (!this.locked.has(id))
+            return;
+        this.locked.delete(id);
+        this.persistLocks();
+    }
+    /**
+     * Ingestion-time chunking hook.
+     *
+     * Active only when `config.adaptiveResolution` is true. Inspects the
+     * incoming message's text content; if its approximate token count
+     * exceeds the chunker's threshold, splits it into shards with a stable
+     * shared `bodyGroupId`. The framework then stores each shard as its own
+     * StoredMessage, and the render path concatenates them back into one
+     * API message at compile time (preserving KV cache structure).
+     *
+     * Multi-block content: text blocks are concatenated for chunking, then
+     * the resulting shards are emitted as text blocks. Non-text blocks
+     * (images, tool results) are passed through unchanged on the first
+     * shard only — they don't get split.
+     *
+     * See `docs/adaptive-resolution-design.md` §3.6.
+     */
+    chunkIngressMessage(participant, content) {
+        if (!this.config.adaptiveResolution)
+            return null;
+        // Separate text and non-text blocks.
+        const textParts = [];
+        const nonTextBlocks = [];
+        for (const block of content) {
+            if (block.type === 'text') {
+                textParts.push(block.text);
+            }
+            else {
+                nonTextBlocks.push(block);
+            }
+        }
+        if (textParts.length === 0)
+            return null;
+        const combined = textParts.join('');
+        // Threshold and shard size derive from the strategy's existing
+        // targetChunkTokens setting: a message over 2x targetChunkTokens
+        // gets sharded into pieces of ~targetChunkTokens each. This keeps
+        // doc shards the same size as chat-message chunks for L1 production
+        // consistency.
+        const target = this.config.targetChunkTokens ?? DEFAULT_CHUNKER_OPTIONS.chunkSize;
+        const chunkerOpts = {
+            chunkThreshold: target * 2,
+            chunkSize: target,
+            charsPerToken: DEFAULT_CHUNKER_OPTIONS.charsPerToken,
+        };
+        const sharded = chunkMessage(combined, chunkerOpts);
+        if (!sharded.wasSharded)
+            return null;
+        // Build IngressChunkResult. Non-text blocks (if any) go on shard 0
+        // so the agent doesn't lose attachments. They're outside the chunker's
+        // concern but should still be available on the first shard.
+        const shards = sharded.shards.map((s) => ({
+            content: [{ type: 'text', text: s.content }].concat(s.index === 0 ? nonTextBlocks : []),
+            shardIndex: s.index,
+        }));
+        return {
+            bodyGroupId: sharded.bodyGroupId,
+            shards,
+        };
     }
     async initialize(ctx) {
+        // Bind to the chronicle store + namespace for persistent strategy state.
+        this.store = ctx.store;
+        this.ns = ctx.namespace;
+        this.registerStates();
+        this.loadPersistedState();
         // Restore headWindowStartId from last topic transition message
         const messages = ctx.messageStore.getAll();
+        this.headWindowStartId = null;
         for (let i = messages.length - 1; i >= 0; i--) {
             if (this.isTopicTransitionMessage(messages[i])) {
                 this.headWindowStartId = messages[i].id;
@@ -62,6 +322,469 @@ export class AutobiographicalStrategy {
         }
         this.rebuildChunks(ctx.messageStore);
     }
+    /**
+     * Register the three Chronicle state slots this strategy uses.
+     * Idempotent — chronicle throws if a state is already registered, which we
+     * swallow (the existing slot is what we want).
+     */
+    registerStates() {
+        if (!this.store)
+            return;
+        try {
+            this.store.registerState({
+                id: this.summariesStateId,
+                strategy: 'append_log',
+                deltaSnapshotEvery: 50,
+                fullSnapshotEvery: 10,
+            });
+        }
+        catch { /* already registered */ }
+        try {
+            this.store.registerState({
+                id: this.counterStateId,
+                strategy: 'snapshot',
+            });
+        }
+        catch { /* already registered */ }
+        try {
+            this.store.registerState({
+                id: this.mergeQueueStateId,
+                strategy: 'snapshot',
+            });
+        }
+        catch { /* already registered */ }
+        try {
+            this.store.registerState({
+                id: this.pinsStateId,
+                strategy: 'snapshot',
+            });
+        }
+        catch { /* already registered */ }
+        // Adaptive-resolution state slots — only registered when the flag is on
+        // so chronicles without the flag don't accumulate unused slots.
+        if (this.config.adaptiveResolution) {
+            try {
+                this.store.registerState({
+                    id: this.resolutionsStateId,
+                    strategy: 'snapshot',
+                });
+            }
+            catch { /* already registered */ }
+            try {
+                this.store.registerState({
+                    id: this.locksStateId,
+                    strategy: 'snapshot',
+                });
+            }
+            catch { /* already registered */ }
+        }
+    }
+    /**
+     * Load summaries, counter, and pending merges from chronicle into the
+     * in-memory mirrors. Called on every (re)initialize so branch switches
+     * pick up the new branch's state.
+     */
+    loadPersistedState() {
+        if (!this.store) {
+            this.summaries = [];
+            this.summaryIdCounter = 0;
+            this.mergeQueue = [];
+            this.pins = [];
+            this.pinIdCounter = 0;
+            return;
+        }
+        const summaries = this.store.getStateJson(this.summariesStateId);
+        this.summaries = Array.isArray(summaries) ? summaries : [];
+        const counter = this.store.getStateJson(this.counterStateId);
+        this.summaryIdCounter = typeof counter === 'number' ? counter : 0;
+        const queue = this.store.getStateJson(this.mergeQueueStateId);
+        this.mergeQueue = Array.isArray(queue)
+            ? queue
+            : [];
+        const pinsState = this.store.getStateJson(this.pinsStateId);
+        if (pinsState && typeof pinsState === 'object' && Array.isArray(pinsState.pins)) {
+            const ps = pinsState;
+            this.pins = ps.pins;
+            this.pinIdCounter = typeof ps.counter === 'number' ? ps.counter : ps.pins.length;
+        }
+        else {
+            this.pins = [];
+            this.pinIdCounter = 0;
+        }
+        // Adaptive-resolution state — only present when flag was/is on
+        if (this.config.adaptiveResolution) {
+            const resState = this.store.getStateJson(this.resolutionsStateId);
+            this.resolutions = new Map();
+            if (resState && typeof resState === 'object') {
+                for (const [k, v] of Object.entries(resState)) {
+                    if (typeof v === 'number' && v > 0) {
+                        this.resolutions.set(k, v);
+                    }
+                }
+            }
+            const lockState = this.store.getStateJson(this.locksStateId);
+            this.locked = new Set();
+            if (Array.isArray(lockState)) {
+                for (const id of lockState) {
+                    if (typeof id === 'string')
+                        this.locked.add(id);
+                }
+            }
+        }
+    }
+    /** Persist the current pins + counter as a single snapshot. */
+    persistPins() {
+        this.store?.setStateJson(this.pinsStateId, {
+            pins: this.pins,
+            counter: this.pinIdCounter,
+        });
+    }
+    /** Persist the current resolutions snapshot. Only stores non-zero entries
+     *  to keep the slot compact. */
+    persistResolutions() {
+        if (!this.store)
+            return;
+        const out = {};
+        for (const [id, level] of this.resolutions) {
+            if (level > 0)
+                out[id] = level;
+        }
+        this.store.setStateJson(this.resolutionsStateId, out);
+    }
+    /** Persist the current locked-id snapshot. */
+    persistLocks() {
+        if (!this.store)
+            return;
+        this.store.setStateJson(this.locksStateId, Array.from(this.locked));
+    }
+    // ============================================================================
+    // Pins / documents (protected ranges)
+    // ============================================================================
+    /**
+     * Pin a range of messages so they aren't compressed and render raw at
+     * their original position. Returns the pin id.
+     */
+    pinRange(firstMessageId, lastMessageId, opts) {
+        const id = `pin-${this.pinIdCounter++}`;
+        this.pins.push({
+            id,
+            firstMessageId,
+            lastMessageId,
+            kind: 'pin',
+            name: opts?.name,
+            created: Date.now(),
+        });
+        this.persistPins();
+        return id;
+    }
+    /**
+     * Mark a single message as a "document" — semantically a body of
+     * information the agent wants to retain in full. Functionally a
+     * single-message pin with `kind: 'document'`.
+     */
+    markDocument(messageId, opts) {
+        const id = `pin-${this.pinIdCounter++}`;
+        this.pins.push({
+            id,
+            firstMessageId: messageId,
+            lastMessageId: messageId,
+            kind: 'document',
+            name: opts?.name,
+            created: Date.now(),
+        });
+        this.persistPins();
+        return id;
+    }
+    /** Remove a pin or document mark by id. Returns true if removed. */
+    unpin(pinId) {
+        const before = this.pins.length;
+        this.pins = this.pins.filter(p => p.id !== pinId);
+        if (this.pins.length < before) {
+            this.persistPins();
+            return true;
+        }
+        return false;
+    }
+    /** Read-only list of all current pins. */
+    listPins() {
+        return this.pins;
+    }
+    // ============================================================================
+    // Search (gap #7)
+    // ============================================================================
+    /**
+     * Look up a single summary by id. Returns null if not found.
+     */
+    getSummary(id) {
+        return this.summaries.find(s => s.id === id) ?? null;
+    }
+    /**
+     * Search summaries by substring or regex over their content.
+     *
+     * Result ordering: matches by descending hit count, then by descending
+     * `created` timestamp (newest first within the same hit count).
+     *
+     * Default behavior: only "live" (unmerged) summaries are searched. Set
+     * `includeMerged: true` to also include summaries that have been folded
+     * into a higher level.
+     */
+    searchSummaries(query) {
+        const limit = query.limit ?? 50;
+        const includeMerged = query.includeMerged ?? false;
+        // Build the matcher
+        let matcher = null;
+        if (query.regex) {
+            const flags = query.regex.flags.includes('g') ? query.regex.flags : query.regex.flags + 'g';
+            const re = new RegExp(query.regex.source, flags);
+            matcher = (content) => {
+                const matches = content.match(re);
+                return matches ? matches.length : 0;
+            };
+        }
+        else if (query.text) {
+            const needle = query.text.toLowerCase();
+            matcher = (content) => {
+                const hay = content.toLowerCase();
+                let count = 0;
+                let idx = 0;
+                while ((idx = hay.indexOf(needle, idx)) !== -1) {
+                    count++;
+                    idx += needle.length || 1;
+                }
+                return count;
+            };
+        }
+        else {
+            // No pattern: every summary "matches" once
+            matcher = () => 1;
+        }
+        const levelsFilter = query.levels && query.levels.length > 0 ? new Set(query.levels) : null;
+        const results = [];
+        for (const s of this.summaries) {
+            if (!includeMerged && s.mergedInto)
+                continue;
+            if (levelsFilter && !levelsFilter.has(s.level))
+                continue;
+            const matches = matcher(s.content);
+            if (matches > 0) {
+                results.push({ summary: s, matches });
+            }
+        }
+        results.sort((a, b) => {
+            if (b.matches !== a.matches)
+                return b.matches - a.matches;
+            return b.summary.created - a.summary.created;
+        });
+        return results.slice(0, limit);
+    }
+    /**
+     * Whether a given message position is inside any protected range.
+     * Uses a position map (computed by caller) so callers can avoid
+     * repeated per-message lookups in tight loops.
+     */
+    isPositionPinned(position, pinPositions) {
+        return pinPositions.has(position);
+    }
+    /**
+     * Build a set of message-store positions covered by any pin. O(N pins · K range).
+     * Returns positions for which the message exists; orphan pins (deleted
+     * messages) are silently skipped.
+     */
+    pinnedPositions(messages) {
+        if (this.pins.length === 0)
+            return new Set();
+        const positionOf = new Map();
+        for (let i = 0; i < messages.length; i++) {
+            positionOf.set(messages[i].id, i);
+        }
+        const out = new Set();
+        for (const pin of this.pins) {
+            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++)
+                out.add(i);
+        }
+        return out;
+    }
+    /**
+     * Append a summary to the in-memory list and to the chronicle AppendLog.
+     * Single point so subclasses inherit persistence.
+     */
+    pushSummary(entry) {
+        this.summaries.push(entry);
+        this.store?.appendToStateJson(this.summariesStateId, entry);
+    }
+    /**
+     * Mark a summary as merged into a higher-level summary, updating the
+     * chronicle copy at the same index. Index is the position in `this.summaries`.
+     */
+    setMergedInto(entry, mergedIntoId) {
+        entry.mergedInto = mergedIntoId;
+        if (!this.store)
+            return;
+        const index = this.summaries.indexOf(entry);
+        if (index < 0)
+            return;
+        this.store.editStateItem(this.summariesStateId, index, Buffer.from(JSON.stringify(entry)));
+    }
+    /**
+     * Allocate the next summary-id counter value and persist the new counter.
+     */
+    nextSummaryIdCounter() {
+        const value = this.summaryIdCounter++;
+        this.store?.setStateJson(this.counterStateId, this.summaryIdCounter);
+        return value;
+    }
+    /**
+     * Push to the merge queue and persist the new queue snapshot.
+     */
+    enqueueMerge(merge) {
+        this.mergeQueue.push(merge);
+        this.store?.setStateJson(this.mergeQueueStateId, this.mergeQueue);
+    }
+    /**
+     * Pop from the merge queue and persist the new queue snapshot.
+     */
+    dequeueMerge() {
+        const merge = this.mergeQueue.shift();
+        this.store?.setStateJson(this.mergeQueueStateId, this.mergeQueue);
+        return merge;
+    }
+    /**
+     * Translate produce ops emitted by the picker into concrete work items on
+     * the strategy's own queues. Two cases:
+     *
+     *  - `level === 1`: the picker has asked for L1 coverage on a raw chunk.
+     *    In the autobio chunker model, each chunk maps to exactly one L1, so
+     *    we locate the chunk whose messages fall in `op.range` and ensure
+     *    it is queued for L1 compression. If the chunker hasn't realized the
+     *    message yet, we skip silently — the next `rebuildChunks` will pick
+     *    it up.
+     *
+     *  - `level >= 2`: the picker has asked for an L_n covering a contiguous
+     *    range. We gather unmerged L_{n-1} summaries whose source ranges
+     *    fall within that range (de-duplicated against entries already in
+     *    `mergeQueue`) and enqueue a single merge over them. The merge fires
+     *    on the next `tick()`.
+     *
+     * The handler is conservative: it never enqueues a singleton or empty
+     * merge, and it never re-enqueues an id that's already pending. That
+     * keeps the next-compile picker loop convergent even when the same
+     * produce op gets re-emitted before the work completes.
+     */
+    handleProducedOps(ops) {
+        for (const op of ops) {
+            if (op.kind !== 'produce')
+                continue;
+            if (op.level === 1) {
+                this.enqueueL1ForRange(op.range.firstChunkId, op.range.lastChunkId);
+            }
+            else if (op.level >= 2) {
+                this.enqueueMergeForRange(op.level, op.range.firstChunkId, op.range.lastChunkId);
+            }
+        }
+    }
+    /**
+     * Ensure that chunks whose message range overlaps [firstMsgId..lastMsgId]
+     * are queued for L1 compression. No-op if the matching chunk is already
+     * compressed or already in the queue.
+     */
+    enqueueL1ForRange(firstMsgId, lastMsgId) {
+        const messageIdToChunk = new Map();
+        for (const ch of this.chunks) {
+            for (const m of ch.messages)
+                messageIdToChunk.set(m.id, ch);
+        }
+        const candidates = new Set();
+        const first = messageIdToChunk.get(firstMsgId);
+        const last = messageIdToChunk.get(lastMsgId);
+        if (first)
+            candidates.add(first);
+        if (last)
+            candidates.add(last);
+        // Also catch chunks fully spanned by the range (rare, but supports the
+        // case where the picker requests an L1 that should logically cover
+        // multiple chunks worth of messages — we err on the side of producing
+        // L1s for every spanned chunk).
+        if (first && last && first.index !== last.index) {
+            const [lo, hi] = first.index < last.index
+                ? [first.index, last.index]
+                : [last.index, first.index];
+            for (let i = lo; i <= hi; i++) {
+                const ch = this.chunks[i];
+                if (ch)
+                    candidates.add(ch);
+            }
+        }
+        for (const chunk of candidates) {
+            if (chunk.compressed)
+                continue;
+            if (this.compressionQueue.includes(chunk.index))
+                continue;
+            this.compressionQueue.push(chunk.index);
+        }
+    }
+    /**
+     * Enqueue an L_{targetLevel} merge over unmerged L_{targetLevel-1}
+     * summaries whose source ranges fall within [firstMsgId..lastMsgId].
+     * No-op if fewer than 2 viable sources are available (a singleton merge
+     * would just rename a summary without consolidating).
+     */
+    enqueueMergeForRange(targetLevel, firstMsgId, lastMsgId) {
+        const sourceLevel = targetLevel - 1;
+        // IDs already enqueued at this target level.
+        const queuedAtLevel = new Set();
+        for (const m of this.mergeQueue) {
+            if (m.level === targetLevel) {
+                for (const id of m.sourceIds)
+                    queuedAtLevel.add(id);
+            }
+        }
+        // Sequence index per message id, for "within range" tests. Use the
+        // current chunk store as the ordering source.
+        const messageOrder = new Map();
+        let seq = 0;
+        for (const ch of this.chunks) {
+            for (const m of ch.messages) {
+                messageOrder.set(m.id, seq++);
+            }
+        }
+        const firstSeq = messageOrder.get(firstMsgId);
+        const lastSeq = messageOrder.get(lastMsgId);
+        const inRange = (msgId) => {
+            if (firstSeq === undefined || lastSeq === undefined)
+                return true;
+            const s = messageOrder.get(msgId);
+            if (s === undefined)
+                return false;
+            const [lo, hi] = firstSeq <= lastSeq ? [firstSeq, lastSeq] : [lastSeq, firstSeq];
+            return s >= lo && s <= hi;
+        };
+        const sources = [];
+        for (const s of this.summaries) {
+            if (s.level !== sourceLevel)
+                continue;
+            if (getSummaryParentId(s))
+                continue;
+            if (queuedAtLevel.has(s.id))
+                continue;
+            if (!inRange(s.sourceRange.first) && !inRange(s.sourceRange.last))
+                continue;
+            sources.push(s);
+        }
+        if (sources.length < 2)
+            return;
+        const N = this.config.mergeThreshold ?? 6;
+        const toMerge = sources.slice(0, N);
+        this.enqueueMerge({
+            level: targetLevel,
+            sourceIds: toMerge.map((s) => s.id),
+        });
+    }
     checkReadiness() {
         if (this.pendingCompression) {
             return {
@@ -87,13 +810,75 @@ export class AutobiographicalStrategy {
     }
     async onNewMessage(message, ctx) {
         this.rebuildChunks(ctx.messageStore);
-        // Auto-tick: fire compression in the background so it runs without
-        // the framework explicitly calling tick(). compile() will await
-        // pendingCompression via checkReadiness().
-        if (this.config.autoTickOnNewMessage && this.compressionQueue.length > 0 && !this.pendingCompression) {
-            this.tick(ctx).catch((err) => console.error('AutobiographicalStrategy: auto-tick error:', err));
+        // Auto-tick: fire speculative compression in the background. After
+        // each tick completes, if the queue still has work AND we're under
+        // the speculation cap AND preflight allows, schedule another tick.
+        // This drains the queue ahead of need rather than one-chunk-per-
+        // user-turn (reactive). Combined with ContextManager.compile not
+        // awaiting pendingCompression, the agent's response and background
+        // compression run truly in parallel.
+        if (this.config.autoTickOnNewMessage && !this.pendingCompression) {
+            this.driveSpeculativeDrain(ctx);
         }
     }
+    /**
+     * Background-drain loop: keeps calling tick() while there's queued work,
+     * subject to the speculation cap and preflight hook. Recurses via
+     * `queueMicrotask` so one chunk's compression doesn't block the
+     * scheduling of the next.
+     *
+     * Stops if a tick fails to make progress (queue size unchanged) — guards
+     * against runaway recursion when tick is a no-op (e.g. no membrane
+     * configured, or a subclass override that doesn't process the queue).
+     */
+    driveSpeculativeDrain(ctx) {
+        if (this.pendingCompression)
+            return;
+        if (this.compressionQueue.length === 0 && this.mergeQueue.length === 0)
+            return;
+        if (this.isAtSpeculativeCap())
+            return;
+        if (!this.shouldCompressPreflight())
+            return;
+        const beforeChunks = this.compressionQueue.length;
+        const beforeMerges = this.mergeQueue.length;
+        this.tick(ctx)
+            .then(() => {
+            const afterChunks = this.compressionQueue.length;
+            const afterMerges = this.mergeQueue.length;
+            // Made progress if either queue shrank.
+            const progressed = afterChunks < beforeChunks || afterMerges < beforeMerges;
+            if (!progressed)
+                return;
+            // Recurse to drain more. queueMicrotask defers until the current
+            // task is done, letting other code (the agent's stream consumer)
+            // interleave.
+            queueMicrotask(() => this.driveSpeculativeDrain(ctx));
+        })
+            .catch((err) => {
+            console.error('AutobiographicalStrategy: speculative-drain error:', err);
+        });
+    }
+    /**
+     * Whether the strategy's pending+queued L1 budget has reached the cap
+     * configured by `maxSpeculativeL1s`. If no cap is set, always false.
+     */
+    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;
+    }
+    /**
+     * Preflight hook for whether speculative compression should fire on
+     * `onNewMessage`. Returns true by default (current eager behavior).
+     * Subclasses can override for predictive scheduling — e.g. only fire
+     * when the live tail token count is approaching some threshold.
+     */
+    shouldCompressPreflight() {
+        return true;
+    }
     async tick(ctx) {
         if (this.pendingCompression)
             return;
@@ -119,19 +904,66 @@ export class AutobiographicalStrategy {
             return;
         }
         // Priority 2: Execute pending merges (hierarchical only)
+        //
+        // Peek at the head rather than dequeueing eagerly: dequeueMerge persists
+        // the shorter queue *before* the LLM call leaves the building, so a
+        // transient failure (429, network drop, timeout, executeMerge throw)
+        // would silently lose the merge from disk and the sources would sit at
+        // level N-1 with no mergedInto pointers forever. Commit the removal
+        // only after the merge succeeds; on failure, the queue keeps its entry
+        // and the next tick() retries it.
         if (this.config.hierarchical && this.mergeQueue.length > 0) {
-            const merge = this.mergeQueue.shift();
+            const merge = this.mergeQueue[0];
             this.pendingCompression = this.executeMerge(merge.level, merge.sourceIds, ctx);
             try {
                 await this.pendingCompression;
+                // Success: drop from head and persist the shorter queue. We
+                // re-check that head is still our merge in case some future code
+                // path mutates the queue mid-await (today no other site does,
+                // but the assertion makes that invariant explicit).
+                if (this.mergeQueue[0] === merge) {
+                    this.dequeueMerge();
+                }
             }
             finally {
                 this.pendingCompression = null;
             }
         }
     }
+    /**
+     * Snapshot of compression progress. Intended for external observers
+     * (warmup scripts, dashboards) that need to track convergence without
+     * reaching into protected fields. Values are point-in-time copies; mutating
+     * them does not affect strategy state.
+     */
+    getProgressSnapshot() {
+        let chunksCompressed = 0;
+        for (const c of this.chunks)
+            if (c.compressed)
+                chunksCompressed++;
+        let l1 = 0, l2 = 0, l3 = 0;
+        for (const s of this.summaries) {
+            if (s.level === 1)
+                l1++;
+            else if (s.level === 2)
+                l2++;
+            else if (s.level === 3)
+                l3++;
+        }
+        return {
+            totalChunks: this.chunks.length,
+            chunksCompressed,
+            l1QueueLength: this.compressionQueue.length,
+            mergeQueueLength: this.mergeQueue.length,
+            summaryCounts: { l1, l2, l3 },
+            pending: this.pendingCompression !== null,
+        };
+    }
     select(store, log, budget) {
         this.rebuildChunks(store);
+        if (this.config.adaptiveResolution) {
+            return this.selectAdaptive(store, budget);
+        }
         return this.config.hierarchical
             ? this.selectHierarchical(store, budget)
             : this.selectLegacy(store, log, budget);
@@ -150,6 +982,39 @@ export class AutobiographicalStrategy {
             pendingMerges: this.mergeQueue.length,
         };
     }
+    /**
+     * Richer per-render stats: requires a message store view to compute the
+     * head + tail (recent window) sizes. Returns counts AND token sums per
+     * summary level, so observers can see "how much of the agent's context
+     * is in raw tail vs folded into L1/L2/L3."
+     *
+     * Useful for TUI / dashboards. The token sums use the strategy's own
+     * token estimates (which match what `select()` uses for budget math).
+     */
+    getRenderStats(store) {
+        const messages = store.getAll();
+        const headStart = this.getHeadWindowStartIndex(store);
+        const headEnd = this.getHeadWindowEnd(store);
+        const recentStart = this.getRecentWindowStart(store);
+        const sumTokens = (slice) => slice.reduce((acc, m) => acc + store.estimateTokens(m), 0);
+        const headMsgs = messages.slice(headStart, headEnd);
+        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);
+        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) },
+            },
+            pending: {
+                chunks: this.chunks.filter(c => !c.compressed).length,
+                merges: this.mergeQueue.length,
+            },
+        };
+    }
     // ============================================================================
     // Legacy (single-level) path
     // ============================================================================
@@ -166,7 +1031,7 @@ export class AutobiographicalStrategy {
             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 (totalTokens + tokens > maxTokens)
+            if (this.isOverBudget(totalTokens + tokens, maxTokens))
                 break;
             entries.push({
                 index: entries.length,
@@ -208,7 +1073,7 @@ export class AutobiographicalStrategy {
                 };
                 const pairTokens = this.estimateTokens(questionEntry.content) +
                     this.estimateTokens(answerEntry.content);
-                if (totalTokens + pairTokens > maxTokens)
+                if (this.isOverBudget(totalTokens + pairTokens, maxTokens))
                     break;
                 entries.push(questionEntry);
                 entries.push(answerEntry);
@@ -219,7 +1084,7 @@ export class AutobiographicalStrategy {
                 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 (totalTokens + tokens > maxTokens)
+                    if (this.isOverBudget(totalTokens + tokens, maxTokens))
                         break;
                     entries.push({
                         index: entries.length,
@@ -243,7 +1108,7 @@ export class AutobiographicalStrategy {
             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 (totalTokens + tokens > maxTokens)
+            if (this.isOverBudget(totalTokens + tokens, maxTokens))
                 break;
             entries.push({
                 index: entries.length,
@@ -258,6 +1123,7 @@ export class AutobiographicalStrategy {
         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;
     }
     /**
@@ -281,7 +1147,7 @@ export class AutobiographicalStrategy {
             const tokens = msgCap > 0
                 ? Math.min(store.estimateTokens(msg), msgCap + 50)
                 : store.estimateTokens(msg);
-            if (totalTokensBefore + acceptedTokens + tokens > maxTokens)
+            if (this.isOverBudget(totalTokensBefore + acceptedTokens + tokens, maxTokens))
                 break;
             accepted.push(i);
             acceptedTokens += tokens;
@@ -329,7 +1195,6 @@ export class AutobiographicalStrategy {
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: 2000,
-                temperature: 0,
             },
         };
         try {
@@ -419,49 +1284,142 @@ export class AutobiographicalStrategy {
         if (!ctx.membrane) {
             throw new Error('No membrane instance for compression');
         }
-        const chunkMessageIds = new Set(chunk.messages.map(m => m.id));
-        const { shownL3, shownL2, shownL1 } = this.getAntiRedundantSummaries(chunkMessageIds);
         const targetTokens = this.config.summaryTargetTokens ?? 2000;
-        const chunkContent = this.formatChunkForCompression(chunk);
-        // Build message array: prior summaries as assistant, then instruction
+        const agentParticipant = this.config.summaryParticipant ?? 'Claude';
+        // Build the KV-preserving prompt per hermes-autobio spec:
+        //
+        //   1. Prior L1 summaries — narrativized as CM-asks / agent-recalls
+        //      pairs, in source order. ALL existing L1s at L1 fidelity
+        //      regardless of merge state ("fill lower orbitals first").
+        //   2. Head — raw messages before the chunk that aren't already
+        //      represented by a prior L1.
+        //   3. Marker — in-band signal that a memory is about to form.
+        //   4. Chunk — raw messages being compressed, as the agent
+        //      experienced them.
+        //   5. Instruction — doc-aware if the chunk is part of a bodyGroup.
+        //
+        // There is intentionally NO tail_after_chunk: that would leak
+        // future information into the model's KV state and corrupt the
+        // as-of framing of memory formation.
         const llmMessages = [];
-        // Prior summaries as agent's own recollections (L3 → L2 → L1 gradient)
-        const allPriorSummaries = [...shownL3, ...shownL2, ...shownL1];
-        for (const s of allPriorSummaries) {
+        // ---- 1. Prior L1 recall pairs ----
+        // Sort by source position so the agent walks its prior memories
+        // chronologically, matching how it would have formed them.
+        const priorL1s = this.summaries
+            .filter((s) => s.level === 1)
+            .sort((a, b) => a.sourceRange.first.localeCompare(b.sourceRange.first));
+        for (const s of priorL1s) {
             llmMessages.push({
-                participant: this.config.summaryParticipant ?? 'Claude',
+                participant: 'Context Manager',
+                content: [{ type: 'text', text: `[CM] Recall memory ${s.id}.` }],
+            });
+            llmMessages.push({
+                participant: agentParticipant,
                 content: [{ type: 'text', text: s.content }],
             });
         }
-        // Context Manager instruction with chunk content
-        const instruction = this.getCompressionInstruction(chunk, targetTokens);
+        // ---- 2. Head window (raw, ALWAYS present) ----
+        //
+        // The head is the foundational identity anchor: the actual opening
+        // of the chronicle (the user's first message, the agent's first
+        // reply, the system context if any). It establishes WHO is speaking
+        // to WHOM. Without it, when the chunk content is heavily first-person
+        // from someone other than the agent (e.g., a user-shared document),
+        // the agent loses its first-person grounding and drifts into the
+        // content author's voice.
+        //
+        // The head is the configured head window — not "everything before
+        // the chunk." For doc-heavy chronicles, "everything before" would
+        // be hundreds of thousands of tokens; the recall pairs already
+        // represent that intermediate content. The head is just the
+        // permanent prefix that the original instance always saw.
+        //
+        // Head messages are excluded from compression by `getCompressibleMessages`
+        // (they're outside the chunking range), so they won't appear in
+        // any L1's sourceIds — no overlap with the recall pairs above.
+        const allMessages = ctx.messageStore.getAll();
+        const headStartIdx = this.getHeadWindowStartIndex(ctx.messageStore);
+        const headEndIdx = this.getHeadWindowEnd(ctx.messageStore);
+        for (let i = headStartIdx; i < headEndIdx && i < allMessages.length; i++) {
+            const m = allMessages[i];
+            llmMessages.push({ participant: m.participant, content: m.content });
+        }
+        // Any raw messages between the head and the chunk that aren't yet
+        // represented by an L1 — usually empty in adaptive-resolution mode,
+        // since chunking proceeds contiguously and L1s exist for everything
+        // up to the chunk being processed.
+        const chunkFirstId = chunk.messages[0]?.id;
+        if (chunkFirstId) {
+            const priorL1MessageIds = new Set();
+            for (const s of priorL1s) {
+                for (const id of s.sourceIds)
+                    priorL1MessageIds.add(id);
+            }
+            const chunkStartIdx = allMessages.findIndex((m) => m.id === chunkFirstId);
+            for (let i = headEndIdx; i < chunkStartIdx && i < allMessages.length; i++) {
+                const m = allMessages[i];
+                if (priorL1MessageIds.has(m.id))
+                    continue;
+                llmMessages.push({ participant: m.participant, content: m.content });
+            }
+        }
+        // ---- 3. In-band marker ----
         llmMessages.push({
             participant: 'Context Manager',
-            content: [{
-                    type: 'text',
-                    text: `[Context Manager] We are ready to form a long-term memory. Here is the conversation to remember:\n\n${chunkContent}\n\n${instruction}`,
-                }],
+            content: [{ type: 'text', text: COMPRESSION_MARKER }],
+        });
+        // ---- 4. Chunk messages raw ----
+        for (const m of chunk.messages) {
+            llmMessages.push({ participant: m.participant, content: m.content });
+        }
+        // ---- 5. Instruction (reading-mode aware) ----
+        //
+        // When the chunk is a portion of a substantially larger sharded message
+        // (≥ 2× chunk size), use the reading-mode instruction. It avoids the
+        // "form a memory of what this contained" framing — which, for content
+        // heavily first-person from someone other than the agent (a user-shared
+        // doc), leads the model to adopt the content author's voice. Instead,
+        // it asks what reading was like and what was learned, forcing the
+        // model to reflect from its own vantage point in agent-first-person.
+        const docContext = this.detectDocContext(chunk, ctx);
+        const instructionText = docContext
+            ? this.getReadingChunkInstruction(chunk, docContext.totalTokens, targetTokens)
+            : this.getCompressionInstruction(chunk, targetTokens);
+        llmMessages.push({
+            participant: 'Context Manager',
+            content: [{ type: 'text', text: instructionText }],
         });
         // Collapse consecutive same-participant messages for API compliance
         const collapsed = this.collapseConsecutiveMessages(llmMessages);
+        // 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
+        // synthetic header the original instance never saw, disturbing KV
+        // consistency between the summarizer and the original instance, and
+        // (b) provide an alternative identity source that competes with the
+        // 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 })),
-            system: 'You are forming autobiographical memories of a conversation.',
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: Math.round(targetTokens * 1.5),
-                temperature: 0,
             },
         };
+        const callStart = Date.now();
+        let logResponse;
+        let logError;
+        let logSummaryId;
         try {
             const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
             const summaryText = response.content
                 .filter((b) => b.type === 'text')
                 .map(b => b.text)
                 .join('\n');
+            logResponse = summaryText;
             const messageIds = chunk.messages.map(m => m.id);
             const entry = {
-                id: `L1-${this.summaryIdCounter++}`,
+                id: `L1-${this.nextSummaryIdCounter()}`,
                 level: 1,
                 content: summaryText,
                 tokens: Math.ceil(summaryText.length / 4),
@@ -474,45 +1432,140 @@ export class AutobiographicalStrategy {
                 created: Date.now(),
                 phaseType: chunk.phaseType,
             };
-            this.summaries.push(entry);
+            this.pushSummary(entry);
             chunk.compressed = true;
             chunk.summaryId = entry.id;
             this._compressionCount++;
+            logSummaryId = entry.id;
             this.checkMergeThreshold();
         }
         catch (error) {
             console.error('Failed to compress chunk (hierarchical):', error);
+            logError = error instanceof Error ? error.message : String(error);
             throw error;
         }
+        finally {
+            logCompressionCall({
+                operation: 'compress_l1',
+                system: null,
+                messages: collapsed.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.
+                    text: m.content
+                        .filter((b) => b.type === 'text')
+                        .map((b) => b.text)
+                        .join(''),
+                })),
+                metadata: {
+                    chunk_message_ids: chunk.messages.map((m) => m.id),
+                    chunk_size: chunk.messages.length,
+                    prior_l1_count: priorL1s.length,
+                    has_doc_context: docContext !== null,
+                    doc_context: docContext,
+                    target_tokens: targetTokens,
+                    model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
+                    latency_ms: Date.now() - callStart,
+                    summary_id: logSummaryId,
+                },
+                response: logResponse,
+                error: logError,
+            });
+        }
     }
     /**
      * Check if unmerged summary counts exceed the merge threshold.
      * Enqueues merge operations if so.
+     *
+     * Skips L1s/L2s that are already in a pending merge — without this guard,
+     * each new summary above threshold re-enqueues a merge for the same
+     * already-eligible siblings, producing N near-identical higher-level
+     * summaries when the queue eventually drains.
      */
     checkMergeThreshold() {
+        if (this.config.speculativeProduction) {
+            this.checkMergeThresholdRecursive();
+            return;
+        }
         const threshold = this.config.mergeThreshold ?? 6;
+        // IDs that are already part of a queued merge — exclude them from
+        // eligibility so we don't re-enqueue.
+        const queuedL1 = new Set();
+        const queuedL2 = new Set();
+        for (const m of this.mergeQueue) {
+            const set = m.level === 2 ? queuedL1 : queuedL2;
+            for (const id of m.sourceIds)
+                set.add(id);
+        }
         // Check L1 → L2
-        const unmergedL1 = this.summaries.filter(s => s.level === 1 && !s.mergedInto);
+        const unmergedL1 = this.summaries.filter(s => s.level === 1 && !s.mergedInto && !queuedL1.has(s.id));
         if (unmergedL1.length >= threshold) {
             const toMerge = unmergedL1.slice(0, threshold);
-            this.mergeQueue.push({
+            this.enqueueMerge({
                 level: 2,
                 sourceIds: toMerge.map(s => s.id),
             });
         }
         // Check L2 → L3
-        const unmergedL2 = this.summaries.filter(s => s.level === 2 && !s.mergedInto);
+        const unmergedL2 = this.summaries.filter(s => s.level === 2 && !s.mergedInto && !queuedL2.has(s.id));
         if (unmergedL2.length >= threshold) {
             const toMerge = unmergedL2.slice(0, threshold);
-            this.mergeQueue.push({
+            this.enqueueMerge({
                 level: 3,
                 sourceIds: toMerge.map(s => s.id),
             });
         }
     }
     /**
-     * Merge N summaries at one level into a single summary at the next level.
-     * Uses self-voice consolidation prompt.
+     * Bottom-up speculative pre-producer (design doc §3.5 / §7.2).
+     *
+     * Recursive variant of `checkMergeThreshold` for the unbounded L_n
+     * design. Walks every level present in the archive; for any level k
+     * with ≥ N orphans (no parent), enqueues an L_{k+1} merge. After that
+     * L_{k+1} is produced and `executeMerge` calls this again, the recursion
+     * naturally cascades: 6 L1s → 1 L2; 6 L2s → 1 L3; 6 L3s → 1 L4; ...
+     *
+     * Only fires when `config.speculativeProduction` is true. Default true
+     * for adaptiveResolution=true, false otherwise. The non-speculative path
+     * (above) preserves the original L1→L2→L3 behavior for non-adaptive
+     * deployments.
+     */
+    checkMergeThresholdRecursive() {
+        const threshold = this.config.mergeThreshold ?? 6;
+        // Build per-level sets of source-ids already enqueued for merging,
+        // so we don't re-enqueue them while a merge is pending.
+        const queuedSources = new Map();
+        for (const m of this.mergeQueue) {
+            // m.level is the TARGET level; the sources are at level (m.level - 1).
+            const sourceLevel = m.level - 1;
+            if (!queuedSources.has(sourceLevel))
+                queuedSources.set(sourceLevel, new Set());
+            for (const id of m.sourceIds)
+                queuedSources.get(sourceLevel).add(id);
+        }
+        // Walk every level present in the archive. Iterate from low to high
+        // so when an L_{k+1} merge is enqueued and immediately produced, this
+        // same check sees the new L_{k+1} on the next call and can roll up.
+        let maxLevel = 0;
+        for (const s of this.summaries) {
+            if (s.level > maxLevel)
+                maxLevel = s.level;
+        }
+        for (let level = 1; level <= maxLevel; level++) {
+            const queued = queuedSources.get(level) ?? new Set();
+            const unmerged = this.summaries.filter(s => s.level === level && !getSummaryParentId(s) && !queued.has(s.id));
+            if (unmerged.length >= threshold) {
+                const toMerge = unmerged.slice(0, threshold);
+                this.enqueueMerge({
+                    level: level + 1,
+                    sourceIds: toMerge.map(s => s.id),
+                });
+            }
+        }
+    }
+    /**
+     * Merge N summaries at one level into a single summary at the next level.
+     * Uses self-voice consolidation prompt.
      */
     async executeMerge(targetLevel, sourceIds, ctx) {
         if (!ctx.membrane) {
@@ -525,54 +1578,227 @@ export class AutobiographicalStrategy {
             console.warn('executeMerge: some source summaries not found, skipping');
             return;
         }
+        // Defensive: if every source is already mergedInto something, this is a
+        // stale queue entry (could happen if multiple merges for the same
+        // sourceIds were enqueued before the dedup fix in checkMergeThreshold).
+        // Skip rather than produce a redundant near-identical higher-level entry.
+        if (sources.every(s => s.mergedInto)) {
+            console.warn(`executeMerge: all sources already merged into ${sources[0].mergedInto}, skipping (stale queue entry)`);
+            return;
+        }
         const targetTokens = this.config.summaryTargetTokens ?? 2000;
         const participant = this.config.summaryParticipant ?? 'Claude';
-        // Build message array
+        // Build the merge prompt with one-level-deeper target expansion +
+        // prefix of older context:
+        //
+        //   1. PREFIX — head messages + prior L1 recall pairs for content
+        //      that comes chronologically BEFORE the merge range. "Fill
+        //      lower orbitals first" per the spec: regardless of how
+        //      compressed the live view is, the summarizer always gets L1
+        //      fidelity for prior content. Older L2/L3 markers exist for
+        //      live-view compactness, not for the summarizer.
+        //
+        //   2. TARGET — the sources expanded ONE LEVEL DEEPER than they
+        //      themselves are. For L2 merge (sources at L1): expand to
+        //      raw L0 messages — the model sees the actual conversation
+        //      that the 6 L1s consolidate. For L3 merge (sources at L2):
+        //      expand to the L1s under each L2 (36 L1s as recall pairs).
+        //      For L_n merge (sources at L_{n-1}): expand to L_{n-2}.
+        //      This gives the model substantively more content to ground
+        //      the consolidation in than just the 6 surface summaries.
+        //
+        //   3. INSTRUCTION — "consolidate N memories preserving the
+        //      through-line, in first person".
+        //
+        // No tail-after-merge: same as-of principle as L1 compression. The
+        // consolidation is being formed at the moment the last source was
+        // ready, so nothing after that is visible.
         const llmMessages = [];
-        // Higher-level context (anti-redundant)
-        if (targetLevel === 2) {
-            // For L2 merge: show L3 summaries as context
-            const shownL3 = this.summaries.filter(s => s.level === 3 && !s.mergedInto);
-            for (const s of shownL3) {
-                llmMessages.push({
-                    participant,
-                    content: [{ type: 'text', text: s.content }],
-                });
+        // Build lookup maps
+        const summariesById = new Map();
+        for (const s of this.summaries)
+            summariesById.set(s.id, s);
+        const allMessages = ctx.messageStore.getAll();
+        const messageById = new Map();
+        for (const m of allMessages)
+            messageById.set(m.id, m);
+        // Compute every leaf message id covered by this merge's lineage —
+        // these are part of the TARGET and must not also appear in the
+        // PREFIX as head content.
+        const sourceLeafIds = new Set();
+        const collectLeaves = (s) => {
+            if (s.sourceLevel === 0) {
+                for (const id of s.sourceIds)
+                    sourceLeafIds.add(id);
+            }
+            else {
+                for (const childId of s.sourceIds) {
+                    const child = summariesById.get(childId);
+                    if (child)
+                        collectLeaves(child);
+                }
             }
+        };
+        for (const src of sources)
+            collectLeaves(src);
+        // Find the start of the merge range in the message store.
+        const mergeFirstMsgId = sources[0].sourceRange.first;
+        const mergeStartIdx = allMessages.findIndex((m) => m.id === mergeFirstMsgId);
+        // ---- 1a. HEAD WINDOW (raw, ALWAYS present) ----
+        //
+        // The head window is the foundational identity anchor — the actual
+        // opening of the chronicle. It establishes who is speaking to whom.
+        // Without it, when the merge target's content is heavily first-person
+        // from someone other than the agent, the agent loses its first-person
+        // grounding and drifts into the content author's voice.
+        const headStartIdx = this.getHeadWindowStartIndex(ctx.messageStore);
+        const headEndIdx = this.getHeadWindowEnd(ctx.messageStore);
+        for (let i = headStartIdx; i < headEndIdx && i < allMessages.length; i++) {
+            const m = allMessages[i];
+            llmMessages.push({ participant: m.participant, content: m.content });
+        }
+        // ---- 1b. PRIOR L1 RECALL PAIRS (chronologically before merge range) ----
+        // L1s whose entire source range is before the merge range and that
+        // aren't part of the merge tree. Sort by source position.
+        const priorL1s = this.summaries
+            .filter((s) => s.level === 1)
+            .filter((s) => {
+            // Exclude any L1 that's an ancestor of our merge target
+            for (const lid of s.sourceIds)
+                if (sourceLeafIds.has(lid))
+                    return false;
+            // Include only if it starts strictly before the merge range
+            const firstIdx = allMessages.findIndex((m) => m.id === s.sourceRange.first);
+            return firstIdx >= 0 && (mergeStartIdx < 0 || firstIdx < mergeStartIdx);
+        })
+            .sort((a, b) => {
+            const ai = allMessages.findIndex((m) => m.id === a.sourceRange.first);
+            const bi = allMessages.findIndex((m) => m.id === b.sourceRange.first);
+            return ai - bi;
+        });
+        const priorL1MessageIds = new Set();
+        for (const s of priorL1s) {
+            for (const id of s.sourceIds)
+                priorL1MessageIds.add(id);
         }
-        // For L3 merge: no higher context exists
-        // The source summaries as agent's own memories
-        for (const source of sources) {
+        for (const s of priorL1s) {
+            llmMessages.push({
+                participant: 'Context Manager',
+                content: [{ type: 'text', text: `[CM] Recall memory ${s.id}.` }],
+            });
             llmMessages.push({
                 participant,
-                content: [{ type: 'text', text: source.content }],
+                content: [{ type: 'text', text: s.content }],
             });
         }
-        // Consolidation instruction
-        const mergeInstruction = this.getMergeInstruction(targetLevel, sources, targetTokens);
+        // Raw middle: any messages between the head window and the merge
+        // range that aren't covered by a prior L1 or the merge tree.
+        // Usually empty (chunking is contiguous).
+        if (mergeStartIdx >= 0) {
+            for (let i = headEndIdx; i < mergeStartIdx; i++) {
+                const m = allMessages[i];
+                if (priorL1MessageIds.has(m.id))
+                    continue;
+                if (sourceLeafIds.has(m.id))
+                    continue;
+                llmMessages.push({ participant: m.participant, content: m.content });
+            }
+        }
+        // ---- 2. TARGET: expand sources one level deeper ----
+        // For L2 (sources at L1, sourceLevel=0): expand to raw L0 messages.
+        // For L3+ (sources at L_{n-1}, sourceLevel=n-2): expand to L_{n-2}
+        //   summaries as recall pairs.
+        for (const src of sources) {
+            if (src.sourceLevel === 0) {
+                // Source is an L1; its sourceIds are raw message ids. Emit them raw.
+                for (const messageId of src.sourceIds) {
+                    const m = messageById.get(messageId);
+                    if (m) {
+                        llmMessages.push({ participant: m.participant, content: m.content });
+                    }
+                }
+            }
+            else {
+                // Source is L2+; its sourceIds point to summaries one level
+                // below. Emit each as a recall pair.
+                for (const childId of src.sourceIds) {
+                    const child = summariesById.get(childId);
+                    if (!child)
+                        continue;
+                    llmMessages.push({
+                        participant: 'Context Manager',
+                        content: [{ type: 'text', text: `[CM] Recall memory ${child.id}.` }],
+                    });
+                    llmMessages.push({
+                        participant,
+                        content: [{ type: 'text', text: child.content }],
+                    });
+                }
+            }
+        }
+        // ---- 3. INSTRUCTION ----
+        // sourceLevelShown is the level of content the model actually sees
+        // (one level below the sources themselves).
+        const sourceLevelShown = sources[0].sourceLevel === 0 ? 0 : sources[0].level - 1;
+        // Reading-mode detection: when ALL the merge's leaf messages are
+        // shards of the same bodyGroup, we know the agent was reading a
+        // substantially larger message rather than conversing. The
+        // reading-mode merge instruction asks what reading the stretch was
+        // like instead of asking for an impersonal consolidation, which
+        // forces the agent's vantage point and prevents drift into the
+        // content author's voice. Same principle as the L1 case.
+        let mergeReadingContext = null;
+        if (sourceLeafIds.size > 0) {
+            const leafBodyGroupIds = new Set();
+            for (const leafId of sourceLeafIds) {
+                const m = messageById.get(leafId);
+                leafBodyGroupIds.add(m?.bodyGroupId);
+            }
+            if (leafBodyGroupIds.size === 1) {
+                const groupId = [...leafBodyGroupIds][0];
+                if (groupId) {
+                    let totalTokens = 0;
+                    for (const m of allMessages) {
+                        if (m.bodyGroupId === groupId) {
+                            totalTokens += ctx.messageStore.estimateTokens(m);
+                        }
+                    }
+                    mergeReadingContext = { totalTokens };
+                }
+            }
+        }
+        const mergeInstructionText = mergeReadingContext
+            ? this.getReadingMergeInstruction(targetLevel, sources, mergeReadingContext.totalTokens, targetTokens)
+            : this.getMergeInstruction(targetLevel, sources, targetTokens);
         llmMessages.push({
             participant: 'Context Manager',
             content: [{
                     type: 'text',
-                    text: `[Context Manager] ${mergeInstruction}`,
+                    text: mergeInstructionText,
                 }],
         });
         const collapsed = this.collapseConsecutiveMessages(llmMessages);
+        // 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 })),
-            system: 'You are forming autobiographical memories of a conversation.',
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: Math.round(targetTokens * 1.5),
-                temperature: 0,
             },
         };
+        const callStart = Date.now();
+        let logResponse;
+        let logError;
+        let logNewSummaryId;
         try {
             const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
             const mergedText = response.content
                 .filter((b) => b.type === 'text')
                 .map(b => b.text)
                 .join('\n');
+            logResponse = mergedText;
             // Compute source range from constituent summaries
             const sourceRange = {
                 first: sources[0].sourceRange.first,
@@ -580,7 +1806,7 @@ export class AutobiographicalStrategy {
             };
             const sourceLevel = (targetLevel - 1);
             const newEntry = {
-                id: `L${targetLevel}-${this.summaryIdCounter++}`,
+                id: `L${targetLevel}-${this.nextSummaryIdCounter()}`,
                 level: targetLevel,
                 content: mergedText,
                 tokens: Math.ceil(mergedText.length / 4),
@@ -589,19 +1815,584 @@ export class AutobiographicalStrategy {
                 sourceRange,
                 created: Date.now(),
             };
-            this.summaries.push(newEntry);
-            // Mark sources as merged
+            logNewSummaryId = newEntry.id;
+            // Append the new merged entry first, then mark sources. Persist each
+            // mergedInto edit individually so chronicle reflects the same shape as
+            // the in-memory mirror. (If the process crashes mid-loop, restart sees
+            // the new entry plus a partial set of marked sources; un-marked sources
+            // would re-trigger a merge — accept the rare duplicate over data loss.)
+            this.pushSummary(newEntry);
             for (const source of sources) {
-                source.mergedInto = newEntry.id;
+                this.setMergedInto(source, newEntry.id);
             }
             // Check if this merge triggers a further merge
             this.checkMergeThreshold();
         }
         catch (error) {
             console.error(`Failed to merge summaries into L${targetLevel}:`, error);
+            logError = error instanceof Error ? error.message : String(error);
             throw error;
         }
+        finally {
+            logCompressionCall({
+                operation: `merge_l${targetLevel}`,
+                system: null,
+                messages: collapsed.map((m) => ({
+                    participant: m.participant,
+                    text: m.content
+                        .filter((b) => b.type === 'text')
+                        .map((b) => b.text)
+                        .join(''),
+                })),
+                metadata: {
+                    target_level: targetLevel,
+                    source_ids: sourceIds,
+                    source_level: sources[0]?.level ?? null,
+                    source_level_shown: sourceLevelShown,
+                    target_tokens: targetTokens,
+                    model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
+                    latency_ms: Date.now() - callStart,
+                    summary_id: logNewSummaryId,
+                },
+                response: logResponse,
+                error: logError,
+            });
+        }
+    }
+    // ============================================================================
+    // Adaptive resolution (picker-driven) path
+    // ============================================================================
+    /**
+     * Select context entries using the adaptive-resolution picker.
+     *
+     * Builds per-message PickerChunks from compressible messages, runs the
+     * configured FoldingStrategy under token-budget pressure, and emits the
+     * resulting per-message resolutions as ContextEntry[]. Adjacent messages
+     * sharing the same L_k ancestor emit the recall pair once.
+     *
+     * See `docs/adaptive-resolution-design.md` §3, §5.
+     */
+    selectAdaptive(store, budget) {
+        const entries = [];
+        const maxTokens = budget.maxTokens - budget.reserveForResponse;
+        const messages = store.getAll();
+        const msgCap = this.config.maxMessageTokens;
+        // ----- 1. Build head/tail sets and emit head entries -----
+        const headStart = this.getHeadWindowStartIndex(store);
+        const headEnd = this.getHeadWindowEnd(store);
+        const recentStart = this.getRecentWindowStart(store);
+        const headMessageIds = new Set();
+        const tailMessageIds = new Set();
+        let headTokens = 0;
+        let tailTokens = 0;
+        let totalTokens = 0;
+        // Emit head entries verbatim
+        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 (totalTokens + tokens > maxTokens)
+                break;
+            entries.push({
+                index: entries.length,
+                sourceMessageId: msg.id,
+                sourceRelation: 'copy',
+                participant: msg.participant,
+                content,
+            });
+            totalTokens += tokens;
+            headMessageIds.add(msg.id);
+            headTokens += tokens;
+        }
+        if (entries.length > 0) {
+            entries[entries.length - 1].cacheMarker = true;
+        }
+        // Compute tail message IDs (will be emitted at end)
+        const effectiveRecentStart = Math.max(recentStart, headEnd);
+        for (let i = effectiveRecentStart; i < messages.length; i++) {
+            const msg = messages[i];
+            const tokens = msgCap > 0 ? Math.min(store.estimateTokens(msg), msgCap + 50) : store.estimateTokens(msg);
+            tailMessageIds.add(msg.id);
+            tailTokens += tokens;
+        }
+        // ----- 2. Build PickerChunks for messages in the middle -----
+        // For each compressible (non-head, non-tail) message we create one
+        // PickerChunk. Its l1Id is determined by the existing chunks that
+        // group messages into L1 summaries.
+        const chunksByMessageId = new Map();
+        for (const ch of this.chunks) {
+            for (const m of ch.messages) {
+                chunksByMessageId.set(m.id, ch);
+            }
+        }
+        // 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);
+        // O(1) summary lookup for findAncestorAt — avoids O(summaries) find()
+        // calls during emission.
+        const summariesById = new Map();
+        for (const s of this.summaries)
+            summariesById.set(s.id, s);
+        const pickerChunks = [];
+        for (let i = headEnd; i < effectiveRecentStart && i < messages.length; i++) {
+            const msg = messages[i];
+            const ch = chunksByMessageId.get(msg.id);
+            const tokens = msgCap > 0
+                ? Math.min(store.estimateTokens(msg), msgCap + 50)
+                : store.estimateTokens(msg);
+            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),
+                l1Id: ch?.summaryId,
+            });
+        }
+        // Also include head and tail in PickerChunks (so token accounting matches)
+        // — but mark them as in-head/in-tail so the picker won't fold them.
+        for (let i = headStart; i < headEnd && i < messages.length; i++) {
+            const msg = messages[i];
+            const tokens = msgCap > 0
+                ? Math.min(store.estimateTokens(msg), msgCap + 50)
+                : store.estimateTokens(msg);
+            pickerChunks.push({
+                id: msg.id,
+                sequence: i,
+                rawTokens: tokens,
+                currentResolution: 0,
+                lockedByAgent: this.locked.has(msg.id),
+                pinned: true, // treat head as pinned for picker purposes
+                l1Id: undefined,
+            });
+        }
+        for (let i = effectiveRecentStart; i < messages.length; i++) {
+            const msg = messages[i];
+            const tokens = msgCap > 0
+                ? Math.min(store.estimateTokens(msg), msgCap + 50)
+                : store.estimateTokens(msg);
+            pickerChunks.push({
+                id: msg.id,
+                sequence: i,
+                rawTokens: tokens,
+                currentResolution: 0,
+                lockedByAgent: this.locked.has(msg.id),
+                pinned: true, // treat tail as pinned for picker purposes
+                l1Id: undefined,
+            });
+        }
+        // ----- 3. Build summaries map and recall-pair tokens -----
+        const summariesMap = new Map();
+        const recallPairTokens = new Map();
+        for (const s of this.summaries) {
+            summariesMap.set(s.id, s);
+            // recall pair = the summary's text wrapped as a Q&A pair. Approximate
+            // as s.tokens + small overhead for the "What do you remember?" label.
+            recallPairTokens.set(s.id, s.tokens + 20);
+        }
+        // ----- 4. Run the picker -----
+        const totalBudget = maxTokens - totalTokens; // tokens left after head
+        const slack = this.config.compressionSlackRatio ?? 0.1;
+        const foldingBudget = {
+            totalBudget,
+            targetBudget: totalBudget * (1 - slack),
+            slack,
+        };
+        const headSetForPicker = new Set(headMessageIds);
+        const tailSetForPicker = new Set(tailMessageIds);
+        const picker = this.getAdaptivePicker();
+        const result = picker.run({
+            chunks: pickerChunks,
+            summaries: summariesMap,
+            recallPairTokens,
+            headChunkIds: headSetForPicker,
+            tailChunkIds: tailSetForPicker,
+            headTokens,
+            tailTokens,
+        }, 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
+        // case in steady state with slack).
+        let resolutionsChanged = false;
+        let deepestLevel = 0;
+        for (const [id, level] of result.finalResolutions) {
+            if (headMessageIds.has(id) || tailMessageIds.has(id))
+                continue;
+            if (this.locked.has(id))
+                continue;
+            const prev = this.resolutions.get(id) ?? 0;
+            if (prev !== level) {
+                this.resolutions.set(id, level);
+                resolutionsChanged = true;
+            }
+            if (level > deepestLevel)
+                deepestLevel = level;
+        }
+        if (resolutionsChanged) {
+            this.persistResolutions();
+        }
+        // Wire produce ops into the strategy's own production queues so that
+        // requested-but-not-yet-existing summaries actually get built. The
+        // speculative pre-producer covers most cases ambiently, but when it is
+        // disabled (`speculativeProduction: false`) or hasn't reached the level
+        // the picker just asked for, the request would otherwise be dropped and
+        // the picker would re-emit it on every subsequent compile. Handling it
+        // here makes the produce path observable and convergent.
+        //
+        // The actual compression/merge work runs asynchronously via the next
+        // `tick()` invocation (or the speculative drain kicked from
+        // `onNewMessage`). This call only enqueues; it does not await.
+        if (result.produced.length > 0) {
+            this.handleProducedOps(result.produced);
+        }
+        // Hard-fail check: if the picker exhausted itself but the final render
+        // would still exceed the HARD budget (not just the soft target), surface
+        // an OverBudgetError to the host rather than silently dropping entries.
+        // The strategy has done all it can; the application has to decide what
+        // to do next (raise budget, switch model, drop windows, etc.).
+        if (result.exhausted && result.finalTokens > totalBudget) {
+            throw new OverBudgetError({
+                budget: totalBudget,
+                actual: result.finalTokens,
+                diagnostics: {
+                    headTokens,
+                    tailTokens,
+                    middleTokens: Math.max(0, result.finalTokens - headTokens - tailTokens),
+                    middleChunkCount: pickerChunks.length - headMessageIds.size - tailMessageIds.size,
+                    deepestLevel,
+                },
+            });
+        }
+        // ----- 5. Emit middle entries in source order -----
+        // Walk middle messages. Handle two cases:
+        //  - bodyGroupId set: collect all consecutive shards from the same group,
+        //    emit ONE combined entry with concatenated content (raw shards + inline
+        //    summary text for folded shards). This preserves KV — the model sees
+        //    one continuous user message instead of N turns.
+        //  - bodyGroupId absent: emit normally (raw L0 message, or Q+A summary pair).
+        const emittedAncestors = new Set();
+        const summaryLabel = this.config.summaryContextLabel ?? 'What do you remember from earlier?';
+        const summaryParticipant = this.config.summaryParticipant ?? 'Claude';
+        let i = headEnd;
+        while (i < effectiveRecentStart && i < messages.length) {
+            const msg = messages[i];
+            if (msg.bodyGroupId) {
+                // Collect the full run of consecutive shards sharing this bodyGroupId.
+                const groupId = msg.bodyGroupId;
+                const groupStart = i;
+                while (i < effectiveRecentStart &&
+                    i < messages.length &&
+                    messages[i].bodyGroupId === groupId) {
+                    i++;
+                }
+                const groupMessages = messages.slice(groupStart, i);
+                // Sort by shardIndex to ensure byte-faithful ordering.
+                const sortedShards = [...groupMessages].sort((a, b) => (a.shardIndex ?? 0) - (b.shardIndex ?? 0));
+                let currentRun = null;
+                const participant = sortedShards[0].participant;
+                const flushRun = () => {
+                    if (!currentRun)
+                        return true;
+                    if (currentRun.kind === 'raw') {
+                        const text = currentRun.parts.join('');
+                        const content = [{ type: 'text', text }];
+                        // Deliberately do NOT apply maxMessageTokens here: the picker
+                        // is the authority on how much of the doc renders raw vs.
+                        // summarized. Truncating the composite would silently lose
+                        // doc content that the picker explicitly chose to keep raw.
+                        // (`maxMessageTokens` is for per-message caps on chat / tool
+                        // results, not for sharded bodyGroup composites.)
+                        const tokens = this.estimateTokens(content);
+                        if (totalTokens + tokens > maxTokens) {
+                            currentRun = null;
+                            return false;
+                        }
+                        entries.push({
+                            index: entries.length,
+                            sourceMessageId: undefined,
+                            sourceRelation: 'copy',
+                            participant,
+                            content,
+                        });
+                        totalTokens += tokens;
+                    }
+                    else {
+                        // summary run — emit Q+A pair, dedup at the strategy level
+                        const ancestor = currentRun.ancestor;
+                        if (!emittedAncestors.has(ancestor.id)) {
+                            emittedAncestors.add(ancestor.id);
+                            const questionEntry = {
+                                index: entries.length,
+                                participant: 'Context Manager',
+                                content: [{ type: 'text', text: summaryLabel }],
+                                sourceRelation: 'derived',
+                            };
+                            const answerContent = [{ type: 'text', text: ancestor.content }];
+                            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 (totalTokens + pairTokens > maxTokens) {
+                                currentRun = null;
+                                return false;
+                            }
+                            entries.push(questionEntry);
+                            entries.push(answerEntry);
+                            totalTokens += pairTokens;
+                        }
+                    }
+                    currentRun = null;
+                    return true;
+                };
+                let budgetExhausted = false;
+                for (const shard of sortedShards) {
+                    const resolution = result.finalResolutions.get(shard.id) ?? 0;
+                    if (resolution === 0) {
+                        if (currentRun?.kind !== 'raw') {
+                            if (!flushRun()) {
+                                budgetExhausted = true;
+                                break;
+                            }
+                            currentRun = { kind: 'raw', parts: [] };
+                        }
+                        for (const block of shard.content) {
+                            if (block.type === 'text')
+                                currentRun.parts.push(block.text);
+                        }
+                    }
+                    else {
+                        const ancestor = this.findAncestorAt(shard.id, resolution, chunksByMessageId, summariesById);
+                        if (!ancestor) {
+                            // Fall back to raw
+                            if (currentRun?.kind !== 'raw') {
+                                if (!flushRun()) {
+                                    budgetExhausted = true;
+                                    break;
+                                }
+                                currentRun = { kind: 'raw', parts: [] };
+                            }
+                            for (const block of shard.content) {
+                                if (block.type === 'text')
+                                    currentRun.parts.push(block.text);
+                            }
+                            continue;
+                        }
+                        // If we're already in a summary run for the SAME ancestor, this
+                        // shard is covered — skip silently.
+                        if (currentRun?.kind === 'summary' && currentRun.ancestor.id === ancestor.id) {
+                            continue;
+                        }
+                        if (!flushRun()) {
+                            budgetExhausted = true;
+                            break;
+                        }
+                        currentRun = { kind: 'summary', ancestor };
+                    }
+                }
+                if (!budgetExhausted) {
+                    if (!flushRun())
+                        budgetExhausted = true;
+                }
+                if (budgetExhausted)
+                    break;
+                continue;
+            }
+            // Non-shard path: existing behavior.
+            const resolution = result.finalResolutions.get(msg.id) ?? 0;
+            if (resolution === 0) {
+                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 (totalTokens + tokens > maxTokens)
+                    break;
+                entries.push({
+                    index: entries.length,
+                    sourceMessageId: msg.id,
+                    sourceRelation: 'copy',
+                    participant: msg.participant,
+                    content,
+                });
+                totalTokens += tokens;
+                i++;
+            }
+            else {
+                const ancestor = this.findAncestorAt(msg.id, resolution, chunksByMessageId, summariesById);
+                if (!ancestor) {
+                    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 (totalTokens + tokens > maxTokens)
+                        break;
+                    entries.push({
+                        index: entries.length,
+                        sourceMessageId: msg.id,
+                        sourceRelation: 'copy',
+                        participant: msg.participant,
+                        content,
+                    });
+                    totalTokens += tokens;
+                    i++;
+                    continue;
+                }
+                if (emittedAncestors.has(ancestor.id)) {
+                    i++;
+                    continue;
+                }
+                emittedAncestors.add(ancestor.id);
+                const questionEntry = {
+                    index: entries.length,
+                    participant: 'Context Manager',
+                    content: [{ type: 'text', text: summaryLabel }],
+                    sourceRelation: 'derived',
+                };
+                const answerContent = [{ type: 'text', text: ancestor.content }];
+                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 (totalTokens + pairTokens > maxTokens)
+                    break;
+                entries.push(questionEntry);
+                entries.push(answerEntry);
+                totalTokens += pairTokens;
+                i++;
+            }
+        }
+        // ----- 6. Emit tail entries newest-first eviction (matches existing behavior) -----
+        this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
+        // ----- 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
+        // one composite entry, but head/tail don't. This pass closes that gap so
+        // 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.trimOrphanedToolUse(merged);
+        return merged;
     }
+    /**
+     * Walk an entries array; for every run of consecutive entries that
+     *  (a) have sourceRelation: 'copy' (raw, not a synthesized recall pair)
+     *  (b) have sourceMessageId pointing to messages in the same bodyGroup
+     * merge them into one composite entry whose body is the byte-faithful
+     * concatenation of their text content. Other entries pass through.
+     *
+     * Reindexes the returned array.
+     */
+    mergeAdjacentBodyGroupRaw(entries, store) {
+        if (entries.length === 0)
+            return entries;
+        // Look up bodyGroupId by sourceMessageId via the message store.
+        const groupOf = (sourceMessageId) => {
+            if (!sourceMessageId)
+                return undefined;
+            const m = store.get(sourceMessageId);
+            return m?.bodyGroupId;
+        };
+        const out = [];
+        let i = 0;
+        while (i < entries.length) {
+            const entry = entries[i];
+            const groupId = entry.sourceRelation === 'copy' ? groupOf(entry.sourceMessageId) : undefined;
+            if (!groupId) {
+                out.push({ ...entry, index: out.length });
+                i++;
+                continue;
+            }
+            // Collect run of consecutive raw entries with same bodyGroupId.
+            const run = [entry];
+            let j = i + 1;
+            while (j < entries.length &&
+                entries[j].sourceRelation === 'copy' &&
+                groupOf(entries[j].sourceMessageId) === groupId) {
+                run.push(entries[j]);
+                j++;
+            }
+            if (run.length === 1) {
+                out.push({ ...entry, index: out.length });
+                i++;
+                continue;
+            }
+            // Sort the run by the underlying shardIndex to ensure byte-faithful
+            // ordering. (Head/tail emission keeps chronological order, but defending
+            // against reorderings is cheap.)
+            const sortedRun = [...run].sort((a, b) => {
+                const ma = a.sourceMessageId ? store.get(a.sourceMessageId) : null;
+                const mb = b.sourceMessageId ? store.get(b.sourceMessageId) : null;
+                return (ma?.shardIndex ?? 0) - (mb?.shardIndex ?? 0);
+            });
+            // Build merged text content. Non-text blocks (rare in shards) are
+            // preserved on the first shard's entry only.
+            const mergedTextParts = [];
+            const nonTextBlocks = [];
+            for (const r of sortedRun) {
+                for (const block of r.content) {
+                    if (block.type === 'text')
+                        mergedTextParts.push(block.text);
+                    else
+                        nonTextBlocks.push(block);
+                }
+            }
+            const mergedContent = [
+                ...nonTextBlocks,
+                { type: 'text', text: mergedTextParts.join('') },
+            ];
+            out.push({
+                index: out.length,
+                sourceMessageId: sortedRun[0].sourceMessageId,
+                sourceRelation: 'copy',
+                participant: sortedRun[0].participant,
+                content: mergedContent,
+            });
+            i = j;
+        }
+        return out;
+    }
+    /** Get (lazily constructing) the configured picker instance. */
+    getAdaptivePicker() {
+        if (this._adaptivePicker)
+            return this._adaptivePicker;
+        const strategy = this.config.foldingStrategy === 'oldest-first'
+            ? new OldestFirstStrategy()
+            : new FlatProfileStrategy();
+        this._adaptivePicker = new Picker(strategy);
+        return this._adaptivePicker;
+    }
+    /**
+     * 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).
+     *
+     * Takes a pre-built summariesById map to avoid O(summaries) lookups per
+     * call — for a chronicle with thousands of summaries and hundreds of
+     * middle messages, the O(n) `find` would dominate compile latency.
+     */
+    findAncestorAt(messageId, level, chunksByMessageId, summariesById) {
+        if (level <= 0)
+            return null;
+        const chunk = chunksByMessageId.get(messageId);
+        if (!chunk?.summaryId)
+            return null;
+        const lookup = (id) => summariesById ? summariesById.get(id) : this.summaries.find((s) => s.id === id);
+        let current = lookup(chunk.summaryId);
+        while (current && current.level < level) {
+            const parentId = getSummaryParentId(current);
+            if (!parentId)
+                return null;
+            current = lookup(parentId);
+        }
+        if (!current || current.level !== level)
+            return null;
+        return current;
+    }
+    // ============================================================================
+    // Hierarchical (threshold-driven) path
+    // ============================================================================
     /**
      * Select context entries using hierarchical compression with budget carryover.
      * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
@@ -619,7 +2410,7 @@ export class AutobiographicalStrategy {
             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 (totalTokens + tokens > maxTokens)
+            if (this.isOverBudget(totalTokens + tokens, maxTokens))
                 break;
             entries.push({
                 index: entries.length,
@@ -654,7 +2445,7 @@ export class AutobiographicalStrategy {
         for (const s of shownL3) {
             if (l3Used + s.tokens > l3Budget)
                 break;
-            if (totalTokens + totalSummaryTokens + s.tokens > maxTokens)
+            if (this.isOverBudget(totalTokens + totalSummaryTokens + s.tokens, maxTokens))
                 break;
             selectedSummaries.push(s);
             l3Used += s.tokens;
@@ -667,7 +2458,7 @@ export class AutobiographicalStrategy {
         for (const s of shownL2) {
             if (l2Used + s.tokens > l2Effective)
                 break;
-            if (totalTokens + totalSummaryTokens + s.tokens > maxTokens)
+            if (this.isOverBudget(totalTokens + totalSummaryTokens + s.tokens, maxTokens))
                 break;
             selectedSummaries.push(s);
             l2Used += s.tokens;
@@ -680,32 +2471,173 @@ export class AutobiographicalStrategy {
         const { selected: l1Selected, tokensUsed: l1Used } = this.selectL1Summaries(shownL1, l1Effective, l1Remaining);
         selectedSummaries.push(...l1Selected);
         totalSummaryTokens += l1Used;
-        // Emit summaries as a single Q&A pair
-        if (selectedSummaries.length > 0) {
-            const contextLabel = this.config.summaryContextLabel ?? 'What do you remember from earlier?';
-            const combinedText = selectedSummaries.map(s => s.content).join('\n\n---\n\n');
-            const questionEntry = {
-                index: entries.length,
-                participant: 'Context Manager',
-                content: [{ type: 'text', text: contextLabel }],
-                sourceRelation: 'derived',
-            };
-            // Synthesised summary turns must respect maxMessageTokens. With L1+L2+L3
-            // budgets defaulting to 30k each, an unconstrained concatenation can push
-            // a single assistant turn past 90k tokens, eating the inference budget
-            // and starving recent messages (postmortem 2026-05-04, bug B).
-            const answerContent = [{ type: 'text', text: combinedText }];
-            const answerEntry = {
-                index: entries.length + 1,
-                participant: this.config.summaryParticipant ?? 'Claude',
-                content: msgCap > 0 ? this.truncateContent(answerContent, msgCap) : answerContent,
-                sourceRelation: 'derived',
-            };
-            const pairTokens = this.estimateTokens(questionEntry.content) +
-                this.estimateTokens(answerEntry.content);
-            entries.push(questionEntry);
-            entries.push(answerEntry);
-            totalTokens += pairTokens;
+        // Emit summaries + pinned messages between head and recent windows.
+        //
+        // Default (positionedRecallPairs=true): one Q/A pair per summary,
+        // interleaved with raw pinned messages, all sorted chronologically by
+        // source-range / message position. Each memory appears in its temporal
+        // place rather than as a wall of unrelated recollections.
+        //
+        // Legacy (positionedRecallPairs=false): summaries concatenated into one
+        // Q/A pair between head and tail; pinned messages still emit raw, in
+        // their chronological positions, after the combined recall pair.
+        const positionOf = new Map();
+        for (let i = 0; i < messages.length; i++) {
+            positionOf.set(messages[i].id, i);
+        }
+        const pinnedPositionsSet = this.pinnedPositions(messages);
+        // Pinned messages between head and recent (head/recent pinned ones
+        // already emit raw via Phase 0 / Phase 4).
+        const pinnedInMiddle = [];
+        const pinnedIdsInMiddle = new Set();
+        for (let i = headEnd; i < recentStart; i++) {
+            if (pinnedPositionsSet.has(i)) {
+                pinnedInMiddle.push({ msg: messages[i], position: i });
+                pinnedIdsInMiddle.add(messages[i].id);
+            }
+        }
+        // Uncompressed-chunk fallback: messages in the middle region whose
+        // chunk hasn't been summarized yet. Without this, a message that
+        // rolled out of the recent window into a queued-but-not-yet-compressed
+        // chunk would vanish from rendered context — there'd be no summary to
+        // emit (compression hasn't run) and Phase 4 only walks recentStart
+        // onwards. Mirrors selectLegacy's "Uncompressed: emit raw" behavior
+        // around line 738, but here we interleave chronologically with
+        // summaries and pins via the unified items list below.
+        //
+        // This matters because compile() was made non-blocking in commit
+        // `3e42e98` (drops the prior `await readiness.pendingWork`); without
+        // this fallback, the trade was silent data-loss for messages caught
+        // in the queued-but-not-yet-compressed window. Now compile()'s
+        // freshness contract is: summaries may lag the very latest L1, but
+        // no message ever disappears.
+        const uncompressedInMiddle = [];
+        for (const chunk of this.chunks) {
+            if (chunk.compressed)
+                continue;
+            for (const msg of chunk.messages) {
+                const pos = positionOf.get(msg.id);
+                if (pos === undefined)
+                    continue;
+                if (pos < headEnd || pos >= recentStart)
+                    continue;
+                if (pinnedIdsInMiddle.has(msg.id))
+                    continue;
+                uncompressedInMiddle.push({ msg, position: pos });
+            }
+        }
+        // Merged list of raw messages to emit in the middle region —
+        // either a pin or a message whose chunk hasn't compressed yet.
+        // Both render identically (raw, at their chronological position).
+        const middleRaw = [
+            ...pinnedInMiddle,
+            ...uncompressedInMiddle,
+        ];
+        if (selectedSummaries.length > 0 || middleRaw.length > 0) {
+            const summaryParticipant = this.config.summaryParticipant ?? 'Claude';
+            if (this.config.positionedRecallPairs !== false) {
+                const items = [];
+                for (const s of selectedSummaries) {
+                    const pos = positionOf.get(s.sourceRange.first) ?? Number.MAX_SAFE_INTEGER;
+                    items.push({ kind: 'summary', position: pos, summary: s });
+                }
+                for (const p of middleRaw) {
+                    items.push({ kind: 'pin', position: p.position, msg: p.msg });
+                }
+                items.sort((a, b) => a.position - b.position);
+                for (const item of items) {
+                    if (item.kind === 'summary') {
+                        const summary = item.summary;
+                        const headerText = this.buildRecallHeader(summary);
+                        const questionEntry = {
+                            index: entries.length,
+                            participant: 'Context Manager',
+                            content: [{ type: 'text', text: headerText }],
+                            sourceRelation: 'derived',
+                        };
+                        const answerContent = [{ type: 'text', text: summary.content }];
+                        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 {
+                        const msg = item.msg;
+                        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;
+                    }
+                }
+            }
+            else {
+                // Legacy combined-pair mode for summaries; pins still emit raw at
+                // their positions after the combined pair.
+                if (selectedSummaries.length > 0) {
+                    const contextLabel = this.config.summaryContextLabel ?? 'What do you remember from earlier?';
+                    const combinedText = selectedSummaries.map(s => s.content).join('\n\n---\n\n');
+                    const questionEntry = {
+                        index: entries.length,
+                        participant: 'Context Manager',
+                        content: [{ type: 'text', text: contextLabel }],
+                        sourceRelation: 'derived',
+                    };
+                    // Synthesised summary turns must respect maxMessageTokens. With L1+L2+L3
+                    // budgets defaulting to 30k each, an unconstrained concatenation can push
+                    // a single assistant turn past 90k tokens, eating the inference budget
+                    // and starving recent messages (postmortem 2026-05-04, bug B).
+                    const answerContent = [{ type: 'text', text: combinedText }];
+                    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);
+                    entries.push(questionEntry);
+                    entries.push(answerEntry);
+                    totalTokens += pairTokens;
+                }
+                // Sort by position so uncompressed-middle messages and pins both
+                // appear in their chronological place after the combined recall pair.
+                const middleRawSorted = [...middleRaw].sort((a, b) => a.position - b.position);
+                for (const { msg } of middleRawSorted) {
+                    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;
+                }
+            }
         }
         // Phase 4: Recent uncompressed messages (skip head window overlap).
         // Newest-first eviction so that when summaries/head consume most of the
@@ -714,24 +2646,104 @@ export class AutobiographicalStrategy {
         const effectiveRecentStart = Math.max(recentStart, headEnd);
         this.emitRecentNewestFirst(entries, store, messages, effectiveRecentStart, msgCap, maxTokens, totalTokens);
         this.trimOrphanedToolUse(entries);
+        this.pruneToolEntries(entries);
         return entries;
     }
     // ============================================================================
     // Overridable hooks (for subclass customization)
     // ============================================================================
     /**
-     * Build the compression instruction for an L1 chunk.
-     * Override in subclasses for phase-aware prompts.
+     * Build the compression instruction for an L1 chunk in the hierarchical
+     * path. Override in subclasses for domain-specific prompts (e.g.,
+     * phase-aware prompts in KnowledgeStrategy).
+     *
+     * Default returns the KV-preserving first-person instruction matching
+     * the hermes-autobio spec. The doc/reading-mode variant is exposed via
+     * {@link getReadingChunkInstruction}.
      */
     getCompressionInstruction(chunk, targetTokens) {
-        return `Starting from my last message, please describe everything that has happened. Aim for about ${targetTokens} tokens. Describe it as you would to yourself, as if you are remembering what has happened.`;
+        return formatInstruction(targetTokens);
+    }
+    /**
+     * Build the compression instruction for an L1 chunk that is part of a
+     * substantially larger sharded message (reading mode). Override in
+     * subclasses if domain logic needs to vary the reading-mode prompt.
+     *
+     * Default returns the reading-mode instruction that asks the model to
+     * reflect on what reading was like rather than form a memory "of what
+     * the chunk contained", which prevents voice drift into the content
+     * author's perspective.
+     */
+    getReadingChunkInstruction(chunk, totalTokens, targetTokens) {
+        return formatReadingChunkInstruction(totalTokens, targetTokens);
+    }
+    /**
+     * If the chunk is part of a substantially larger sharded message (total
+     * bodyGroup tokens ≥ 2× the chunk's own tokens), return reading-context
+     * metadata for the reading instruction. The 2× threshold means the
+     * chunk represents a portion of something significantly larger — the
+     * agent is reading, not conversing.
+     *
+     * Returns null when the chunk is a whole message (no bodyGroup), or
+     * when bodyGroup total is < 2× chunk size (degenerate case — chunk
+     * effectively IS the whole message). In those cases the standard
+     * (non-reading) instruction is appropriate.
+     */
+    detectDocContext(chunk, ctx) {
+        if (chunk.messages.length === 0)
+            return null;
+        const firstGroupId = chunk.messages[0].bodyGroupId;
+        if (!firstGroupId)
+            return null;
+        // All messages in the chunk must share the same bodyGroupId
+        for (const m of chunk.messages) {
+            if (m.bodyGroupId !== firstGroupId)
+                return null;
+        }
+        // Total tokens of the original message (sum of all shards in the bodyGroup).
+        const allMessages = ctx.messageStore.getAll();
+        let totalTokens = 0;
+        for (const m of allMessages) {
+            if (m.bodyGroupId === firstGroupId) {
+                totalTokens += ctx.messageStore.estimateTokens(m);
+            }
+        }
+        // Tokens in this chunk specifically.
+        let chunkTokens = 0;
+        for (const m of chunk.messages) {
+            chunkTokens += ctx.messageStore.estimateTokens(m);
+        }
+        // Reading-mode threshold: the original message must be substantially
+        // larger than this chunk. 2× means the chunk is at most half of the
+        // whole — clearly a portion of something bigger.
+        if (chunkTokens === 0 || totalTokens < 2 * chunkTokens)
+            return null;
+        return {
+            totalTokens,
+            chunkTokens,
+        };
     }
     /**
      * Build the merge instruction for combining summaries into a higher level.
      * Override in subclasses for domain-specific merge prompts.
+     *
+     * Default returns the KV-preserving merge instruction. The reading-mode
+     * variant (used when all leaves share a bodyGroup of substantial size)
+     * is exposed via {@link getReadingMergeInstruction}.
      */
     getMergeInstruction(targetLevel, sources, targetTokens) {
-        return `Please consolidate the memories since my last message into a single cohesive memory. Aim for about ${targetTokens} tokens. Write as you would to yourself — this is your autobiography, capturing the arc of what happened.`;
+        const sourceLevelShown = sources.length > 0 ? Math.max(0, sources[0].level - 1) : 0;
+        return formatMergeInstruction(targetLevel, sourceLevelShown, targetTokens);
+    }
+    /**
+     * Build the reading-mode merge instruction. Used when all leaf messages
+     * underlying the merge share a bodyGroup of substantial size — the agent
+     * has been reading a doc rather than conversing. Override in subclasses
+     * if domain logic needs to vary the reading-mode merge prompt.
+     */
+    getReadingMergeInstruction(targetLevel, sources, totalTokens, targetTokens) {
+        const sourceLevelShown = sources.length > 0 ? Math.max(0, sources[0].level - 1) : 0;
+        return formatReadingMergeInstruction(targetLevel, sourceLevelShown, totalTokens, targetTokens);
     }
     /**
      * Select L1 summaries within a budget. Returns selected summaries and tokens used.
@@ -743,13 +2755,56 @@ export class AutobiographicalStrategy {
         for (const s of shownL1) {
             if (used + s.tokens > budget)
                 break;
-            if (used + s.tokens > maxTokens)
+            if (this.isOverBudget(used + s.tokens, maxTokens))
                 break;
             selected.push(s);
             used += s.tokens;
         }
         return { selected, tokensUsed: used };
     }
+    /**
+     * True if `projectedTotal` exceeds `max` AND the strategy is configured
+     * to enforce budget. When `enforceBudget: false`, always returns false
+     * — the rendering pipeline emits the full ideal context regardless of
+     * budget overage. Caller's API will reject if it exceeds the model's
+     * context window; the philosophy is "surface overage, don't hide it."
+     */
+    isOverBudget(projectedTotal, max) {
+        if (this.config.enforceBudget === false)
+            return false;
+        return projectedTotal > max;
+    }
+    /**
+     * Sort selected summaries by source-range start position, so per-pair
+     * recall emission appears in chronological order. Falls back to the
+     * created timestamp for summaries whose source-range first message is
+     * no longer in the store.
+     */
+    sortSummariesChronologically(summaries, messages) {
+        const positionOf = new Map();
+        for (let i = 0; i < messages.length; i++) {
+            positionOf.set(messages[i].id, i);
+        }
+        return [...summaries].sort((a, b) => {
+            const posA = positionOf.get(a.sourceRange.first) ?? Number.MAX_SAFE_INTEGER;
+            const posB = positionOf.get(b.sourceRange.first) ?? Number.MAX_SAFE_INTEGER;
+            if (posA !== posB)
+                return posA - posB;
+            return a.created - b.created;
+        });
+    }
+    /**
+     * Render the per-pair recall header from the configured template.
+     * Substitutions: {id} {level} {first} {last}.
+     */
+    buildRecallHeader(summary) {
+        const template = this.config.recallHeaderTemplate ?? '[Recall {id}]';
+        return template
+            .replace(/\{id\}/g, summary.id)
+            .replace(/\{level\}/g, String(summary.level))
+            .replace(/\{first\}/g, summary.sourceRange.first)
+            .replace(/\{last\}/g, summary.sourceRange.last);
+    }
     // ============================================================================
     // Head window reset / topic transition
     // ============================================================================
@@ -809,7 +2864,6 @@ export class AutobiographicalStrategy {
             config: {
                 model: this.config.compressionModel ?? 'claude-sonnet-4-20250514',
                 maxTokens: 1500,
-                temperature: 0,
             },
         };
         const response = await ctx.membrane.complete(request, { formatter: this.nativeFormatter });
@@ -838,16 +2892,26 @@ export class AutobiographicalStrategy {
     // Shared utilities
     // ============================================================================
     /**
-     * Get messages in the compressible zone: outside both head window and recent window.
-     * Returns messages from [0, headStart) ∪ [headEnd, recentStart).
+     * Get messages in the compressible zone: outside both head window and
+     * recent window AND not inside any pinned range. Returns messages from
+     * [0, headStart) ∪ [headEnd, recentStart) minus any positions covered
+     * by a pin or document mark.
      */
     getCompressibleMessages(store) {
         const messages = store.getAll();
         const headStart = this.getHeadWindowStartIndex(store);
         const headEnd = this.getHeadWindowEnd(store);
         const recentStart = this.getRecentWindowStart(store);
-        return messages.slice(0, recentStart)
-            .filter((_, i) => i < headStart || i >= headEnd);
+        const pinned = this.pinnedPositions(messages);
+        const out = [];
+        for (let i = 0; i < recentStart; i++) {
+            if (i >= headStart && i < headEnd)
+                continue;
+            if (pinned.has(i))
+                continue;
+            out.push(messages[i]);
+        }
+        return out;
     }
     /**
      * Rebuild chunk boundaries based on current messages.
@@ -1012,6 +3076,92 @@ export class AutobiographicalStrategy {
             }
         }
     }
+    /**
+     * Prune tool_use / tool_result blocks in-place:
+     *  1. Truncate `tool_use.input` blocks whose serialized JSON exceeds
+     *     `toolUseInputMaxTokens`.
+     *  2. For each tool name, keep only the last N `tool_result` blocks
+     *     per `toolResultMaxLastN`; older ones get their `content` replaced
+     *     with a brief marker referencing the tool name and how many newer
+     *     results exist below.
+     *
+     * Both passes are no-ops when the corresponding config is unset/0.
+     * Pruning runs AFTER selection and orphan-trimming, so it doesn't
+     * affect chunk formation or the recall/pin layout.
+     */
+    pruneToolEntries(entries) {
+        // Pass 1: build toolUseId → toolName map and apply input truncation
+        const toolUseInputCap = this.config.toolUseInputMaxTokens ?? 0;
+        const toolUseIdToName = new Map();
+        for (const entry of entries) {
+            for (let i = 0; i < entry.content.length; i++) {
+                const block = entry.content[i];
+                if (block.type !== 'tool_use')
+                    continue;
+                toolUseIdToName.set(block.id, block.name);
+                if (toolUseInputCap > 0) {
+                    const inputJson = JSON.stringify(block.input);
+                    const inputTokens = Math.ceil(inputJson.length / 4);
+                    if (inputTokens > toolUseInputCap) {
+                        const keys = Object.keys(block.input).slice(0, 5);
+                        entry.content[i] = {
+                            ...block,
+                            input: {
+                                _truncated: true,
+                                _originalTokens: inputTokens,
+                                _keys: keys,
+                            },
+                        };
+                    }
+                }
+            }
+        }
+        // Pass 2: collect tool_result occurrences per tool name, in order
+        const occurrencesByTool = new Map();
+        for (const entry of entries) {
+            for (let i = 0; i < entry.content.length; i++) {
+                const block = entry.content[i];
+                if (block.type !== 'tool_result')
+                    continue;
+                const toolName = toolUseIdToName.get(block.toolUseId);
+                if (!toolName)
+                    continue;
+                let arr = occurrencesByTool.get(toolName);
+                if (!arr) {
+                    arr = [];
+                    occurrencesByTool.set(toolName, arr);
+                }
+                arr.push({ entry, blockIndex: i });
+            }
+        }
+        // Pass 3: apply per-tool max-last-N
+        const cfg = this.config.toolResultMaxLastN;
+        if (cfg === undefined)
+            return;
+        for (const [toolName, occs] of occurrencesByTool) {
+            let limit;
+            if (typeof cfg === 'number')
+                limit = cfg;
+            else if (typeof cfg === 'object')
+                limit = cfg[toolName];
+            if (limit === undefined || limit < 0)
+                continue;
+            const excessCount = occs.length - limit;
+            if (excessCount <= 0)
+                continue;
+            for (let i = 0; i < excessCount; i++) {
+                const { entry, blockIndex } = occs[i];
+                const orig = entry.content[blockIndex];
+                if (orig.type !== 'tool_result')
+                    continue;
+                const fresherCount = occs.length - i - 1;
+                entry.content[blockIndex] = {
+                    ...orig,
+                    content: `[Result truncated — tool '${toolName}' has ${fresherCount} more recent result${fresherCount === 1 ? '' : 's'} below]`,
+                };
+            }
+        }
+    }
     isChunkOldEnough(chunk) {
         return true;
     }