@caupulican/pi-agent-core 0.86.3 → 0.86.6

package/dist/session/session-manager.js

@@ -10,6 +10,36 @@ import { normalizePath, resolvePath } from "../utils/paths.js";
 import { uuidv7 } from "../uuid.js";
 import { compactToolResultDetailsForRetention } from "./message-retention.js";
 export const CURRENT_SESSION_VERSION = 3;
+/** Maximum borrowed entries one non-copying SessionManager visit may inspect. */
+export const MAX_SESSION_ENTRY_VISIT_COUNT = 1_024;
+function invalidSessionParentCycle(entryId) {
+    return new Error(`Invalid session entry graph: parent cycle detected at entry "${entryId}".`);
+}
+/** Visit leaf-to-root ancestry through one bounded, cycle-rejecting implementation path. */
+function visitSessionAncestry(start, byId, visitor) {
+    let current = start;
+    // One external start plus every indexed node is the longest possible acyclic walk.
+    let remainingEntries = byId.size + 1;
+    while (current) {
+        if (remainingEntries-- === 0)
+            throw invalidSessionParentCycle(current.id);
+        if (visitor(current) === false)
+            return;
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+}
+const synthesizedSessionContextMessages = new WeakSet();
+function retainSynthesizedSessionContextMessage(message) {
+    synthesizedSessionContextMessages.add(message);
+    return message;
+}
+function cloneSessionContext(context) {
+    return {
+        messages: context.messages.map((message) => synthesizedSessionContextMessages.has(message) ? { ...message } : message),
+        thinkingLevel: context.thinkingLevel,
+        model: context.model ? { ...context.model } : null,
+    };
+}
 function createSessionId() {
     return uuidv7();
 }
@@ -148,11 +178,9 @@ export function buildSessionContext(entries, leafId, byId) {
     }
     // Walk from leaf to root, then reverse once. Repeated front insertion makes long branches quadratic.
     const path = [];
-    let current = leaf;
-    while (current) {
-        path.push(current);
-        current = current.parentId ? byId.get(current.parentId) : undefined;
-    }
+    visitSessionAncestry(leaf, byId, (entry) => {
+        path.push(entry);
+    });
     path.reverse();
     // Extract settings and find compaction
     let thinkingLevel = "off";
@@ -183,15 +211,15 @@ export function buildSessionContext(entries, leafId, byId) {
             messages.push(entry.message);
         }
         else if (entry.type === "custom_message") {
-            messages.push(createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp));
+            messages.push(retainSynthesizedSessionContextMessage(createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp)));
         }
         else if (entry.type === "branch_summary" && entry.summary) {
-            messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+            messages.push(retainSynthesizedSessionContextMessage(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)));
         }
     };
     if (compaction) {
         // Emit summary first
-        messages.push(createCompactionSummaryMessage(compaction.summary, compaction.tokensBefore, compaction.timestamp));
+        messages.push(retainSynthesizedSessionContextMessage(createCompactionSummaryMessage(compaction.summary, compaction.tokensBefore, compaction.timestamp)));
         // Find compaction index in path
         const compactionIdx = path.findIndex((e) => e.type === "compaction" && e.id === compaction.id);
         // Emit kept messages (before compaction, starting from firstKeptEntryId)
@@ -335,6 +363,13 @@ export function loadEntriesFromFile(filePath, options) {
 const ENTRY_ID_PREFIX_BYTES = 64 * 1024;
 const COMPACTED_PAYLOAD_RELEASE_MIN_CHARS = 16 * 1024;
 function indexSessionEntryFileLocations(filePath, startOffset, locations, retainedIds) {
+    const pendingIds = new Set();
+    for (const id of retainedIds) {
+        if (!locations.has(id))
+            pendingIds.add(id);
+    }
+    if (pendingIds.size === 0)
+        return startOffset;
     const fd = openSync(filePath, "r");
     const buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE);
     let position = startOffset;
@@ -348,12 +383,13 @@ function indexSessionEntryFileLocations(filePath, startOffset, locations, retain
                 ? prefixParts[0].toString("utf8")
                 : Buffer.concat(prefixParts, prefixLength).toString("utf8");
             const id = /"id"\s*:\s*"([A-Za-z0-9_-]+)"/.exec(prefix)?.[1];
-            if (id && retainedIds.has(id))
+            if (id && pendingIds.delete(id))
                 locations.set(id, { offset: lineOffset, length: lineLength });
         }
         lineLength = 0;
         prefixLength = 0;
         prefixParts = [];
+        return pendingIds.size === 0;
     };
     try {
         while (true) {
@@ -376,8 +412,10 @@ function indexSessionEntryFileLocations(filePath, startOffset, locations, retain
                 }
                 if (newlineIndex === -1 || newlineIndex >= bytesRead)
                     break;
-                finishLine();
-                lineOffset = chunkOffset + newlineIndex + 1;
+                const nextLineOffset = chunkOffset + newlineIndex + 1;
+                if (finishLine())
+                    return nextLineOffset;
+                lineOffset = nextLineOffset;
                 segmentStart = newlineIndex + 1;
             }
         }
@@ -689,6 +727,7 @@ export class SessionManager {
         this.entryFileLocations = new Map();
         this.coldPayloadEntryIds = new Set();
         this.indexedSessionFileBytes = 0;
+        this.persistenceStateUncertain = false;
         this.cwd = resolvePath(cwd);
         this.sessionDir = normalizePath(sessionDir);
         this.agentDir = agentDir;
@@ -702,6 +741,37 @@ export class SessionManager {
     }
     /** Switch to a different session file (used for resume and branching) */
     setSessionFile(sessionFile) {
+        const recoveringUncertainWrite = this.persistenceStateUncertain;
+        this.persistenceStateUncertain = true;
+        try {
+            if (recoveringUncertainWrite) {
+                const resolvedSessionFile = resolvePath(sessionFile);
+                if (existsSync(resolvedSessionFile)) {
+                    const fileBytes = statSync(resolvedSessionFile).size;
+                    if (fileBytes > 0) {
+                        const fd = openSync(resolvedSessionFile, "r");
+                        const finalByte = Buffer.allocUnsafe(1);
+                        try {
+                            if (readSync(fd, finalByte, 0, 1, fileBytes - 1) !== 1 || finalByte[0] !== 0x0a) {
+                                throw new Error("Session file ends with an incomplete JSONL record after a failed write; repair it or start a new session.");
+                            }
+                        }
+                        finally {
+                            closeSync(fd);
+                        }
+                    }
+                }
+            }
+            this._setSessionFile(sessionFile);
+            this.persistenceStateUncertain = false;
+        }
+        catch (error) {
+            this.persistenceStateUncertain = true;
+            throw error;
+        }
+    }
+    _setSessionFile(sessionFile) {
+        this._invalidateSessionContextCache();
         this._resetEntryFileIndex(true);
         this.sessionFile = resolvePath(sessionFile);
         if (existsSync(this.sessionFile)) {
@@ -742,16 +812,18 @@ export class SessionManager {
             const header = this.fileEntries.find((e) => e.type === "session");
             this.sessionId = header?.id ?? createSessionId();
             this._ensureEntryFileLocations(this.coldPayloadEntryIds);
-            if (migrateToCurrentVersion(this.fileEntries)) {
+            const migrated = migrateToCurrentVersion(this.fileEntries);
+            // Validate and index the complete parent graph before a migration rewrite can
+            // mutate the source file. Malformed cycles must fail synchronously on cold open.
+            this._buildIndex();
+            if (migrated)
                 this._rewriteFile();
-            }
             // Bound in-memory retention: oversized tool result details from disk would
             // otherwise be pinned in fileEntries for the whole process lifetime.
             for (const entry of this.fileEntries) {
                 if (entry.type === "message")
                     compactToolResultDetailsForRetention(entry.message);
             }
-            this._buildIndex();
             this.flushed = true;
             this._releaseExistingCompactedMessagePayloads();
         }
@@ -782,6 +854,8 @@ export class SessionManager {
         this.labelTimestampsById.clear();
         this.leafId = null;
         this.flushed = false;
+        this.persistenceStateUncertain = false;
+        this._invalidateSessionContextCache();
         this._resetEntryFileIndex(true);
         if (this.persist) {
             const fileTimestamp = timestamp.replace(/[:.]/g, "-");
@@ -796,30 +870,63 @@ export class SessionManager {
             this.coldPayloadEntryIds.clear();
     }
     _buildIndex() {
-        this.entries = [];
-        this.byId.clear();
-        this.labelsById.clear();
-        this.labelTimestampsById.clear();
-        this.leafId = null;
+        this._invalidateSessionContextCache();
+        const entries = [];
+        const byId = new Map();
+        const labelsById = new Map();
+        const labelTimestampsById = new Map();
+        let leafId = null;
         for (const entry of this.fileEntries) {
             if (entry.type === "session")
                 continue;
-            this.entries.push(entry);
-            this.byId.set(entry.id, entry);
-            this.leafId = entry.id;
+            if (typeof entry.id !== "string" || entry.id.length === 0) {
+                throw new Error("Invalid session entry graph: every entry requires a non-empty string id.");
+            }
+            if (byId.has(entry.id)) {
+                throw new Error(`Invalid session entry graph: duplicate entry id "${entry.id}".`);
+            }
+            if (entry.parentId !== null && typeof entry.parentId !== "string") {
+                throw new Error(`Invalid session entry graph: entry "${entry.id}" has a malformed parent id.`);
+            }
+            entries.push(entry);
+            byId.set(entry.id, entry);
+            leafId = entry.id;
             if (entry.type === "label") {
                 if (entry.label) {
-                    this.labelsById.set(entry.targetId, entry.label);
-                    this.labelTimestampsById.set(entry.targetId, entry.timestamp);
+                    labelsById.set(entry.targetId, entry.label);
+                    labelTimestampsById.set(entry.targetId, entry.timestamp);
                 }
                 else {
-                    this.labelsById.delete(entry.targetId);
-                    this.labelTimestampsById.delete(entry.targetId);
+                    labelsById.delete(entry.targetId);
+                    labelTimestampsById.delete(entry.targetId);
                 }
             }
         }
+        const settledEntryIds = new Set();
+        for (const entry of entries) {
+            if (settledEntryIds.has(entry.id))
+                continue;
+            const activeEntryIds = new Set();
+            const traversedEntryIds = [];
+            visitSessionAncestry(entry, byId, (current) => {
+                if (settledEntryIds.has(current.id))
+                    return false;
+                if (activeEntryIds.has(current.id)) {
+                    throw invalidSessionParentCycle(current.id);
+                }
+                activeEntryIds.add(current.id);
+                traversedEntryIds.push(current.id);
+            });
+            for (const entryId of traversedEntryIds)
+                settledEntryIds.add(entryId);
+        }
+        this.entries = entries;
+        this.byId = byId;
+        this.labelsById = labelsById;
+        this.labelTimestampsById = labelTimestampsById;
+        this.leafId = leafId;
         for (const id of this.coldPayloadEntryIds) {
-            if (!this.byId.has(id))
+            if (!byId.has(id))
                 this.coldPayloadEntryIds.delete(id);
         }
     }
@@ -868,27 +975,45 @@ export class SessionManager {
         return this.sessionFile;
     }
     _ensureEntryFileLocations(retainedIds) {
-        if (!this.sessionFile || !existsSync(this.sessionFile))
+        if (retainedIds.size === 0 || !this.sessionFile || !existsSync(this.sessionFile))
             return;
         const fileBytes = statSync(this.sessionFile).size;
         if (fileBytes < this.indexedSessionFileBytes)
             this._resetEntryFileIndex();
-        if (fileBytes === this.indexedSessionFileBytes)
+        const allLocated = () => {
+            for (const id of retainedIds) {
+                if (!this.entryFileLocations.has(id))
+                    return false;
+            }
+            return true;
+        };
+        if (allLocated())
             return;
-        const idsToIndex = new Set(this.coldPayloadEntryIds);
-        for (const id of retainedIds)
-            idsToIndex.add(id);
-        this.indexedSessionFileBytes = indexSessionEntryFileLocations(this.sessionFile, this.indexedSessionFileBytes, this.entryFileLocations, idsToIndex);
+        const scanStart = this.indexedSessionFileBytes;
+        if (fileBytes > scanStart) {
+            this.indexedSessionFileBytes = indexSessionEntryFileLocations(this.sessionFile, scanStart, this.entryFileLocations, retainedIds);
+            if (allLocated())
+                return;
+        }
+        // The missing target may precede the incremental cursor. Rebuild only for the bounded
+        // requested set; forward sequential pages continue from the exact prior line boundary.
+        if (scanStart === 0)
+            return;
+        this._resetEntryFileIndex();
+        this.indexedSessionFileBytes = indexSessionEntryFileLocations(this.sessionFile, 0, this.entryFileLocations, retainedIds);
+    }
+    _getEntryFileLocation(entryId) {
+        let location = this.entryFileLocations.get(entryId);
+        if (location)
+            return location;
+        this._ensureEntryFileLocations(new Set([entryId]));
+        location = this.entryFileLocations.get(entryId);
+        return location;
     }
     _readCompactedMessageProperty(entryId, property) {
         if (!this.sessionFile)
             throw new Error(`Compacted session payload ${entryId} is unavailable`);
-        let location = this.entryFileLocations.get(entryId);
-        if (!location) {
-            this._resetEntryFileIndex();
-            this._ensureEntryFileLocations(new Set([entryId]));
-            location = this.entryFileLocations.get(entryId);
-        }
+        const location = this._getEntryFileLocation(entryId);
         if (!location)
             throw new Error(`Compacted session payload ${entryId} is unavailable`);
         const fd = openSync(this.sessionFile, "r");
@@ -937,30 +1062,43 @@ export class SessionManager {
             },
         });
     }
+    _releasableMessageProperties(entry) {
+        const message = entry.message;
+        const properties = [];
+        for (const property of ["content", "output"]) {
+            const descriptor = Object.getOwnPropertyDescriptor(message, property);
+            if (descriptor &&
+                !descriptor.get &&
+                "value" in descriptor &&
+                retainedStringChars(descriptor.value, COMPACTED_PAYLOAD_RELEASE_MIN_CHARS) >=
+                    COMPACTED_PAYLOAD_RELEASE_MIN_CHARS) {
+                properties.push(property);
+            }
+        }
+        return properties;
+    }
     _releaseExistingCompactedMessagePayloads() {
-        let current = this.leafId ? this.byId.get(this.leafId) : undefined;
-        while (current) {
+        const leaf = this.leafId ? this.byId.get(this.leafId) : undefined;
+        visitSessionAncestry(leaf, this.byId, (current) => {
             if (current.type === "compaction") {
                 this._releaseCompactedMessagePayloads(current.firstKeptEntryId, current.parentId);
-                return;
+                return false;
             }
-            current = current.parentId ? this.byId.get(current.parentId) : undefined;
-        }
+        });
     }
     _releaseCompactedMessagePayloads(firstKeptEntryId, compactionParentId) {
         if (!this.persist || !this.flushed || !this.sessionFile)
             return;
         const keptEntryIds = new Set();
-        let currentId = compactionParentId;
         let foundFirstKept = false;
-        while (currentId) {
-            keptEntryIds.add(currentId);
-            if (currentId === firstKeptEntryId) {
+        const compactionParent = compactionParentId ? this.byId.get(compactionParentId) : undefined;
+        visitSessionAncestry(compactionParent, this.byId, (current) => {
+            keptEntryIds.add(current.id);
+            if (current.id === firstKeptEntryId) {
                 foundFirstKept = true;
-                break;
+                return false;
             }
-            currentId = this.byId.get(currentId)?.parentId ?? null;
-        }
+        });
         if (!foundFirstKept)
             return;
         const retainedIds = new Set();
@@ -968,21 +1106,11 @@ export class SessionManager {
         for (const entry of this.entries) {
             if (entry.type !== "message")
                 continue;
-            const message = entry.message;
-            const properties = [];
-            for (const property of ["content", "output"]) {
-                const descriptor = Object.getOwnPropertyDescriptor(message, property);
-                if (descriptor &&
-                    !descriptor.get &&
-                    "value" in descriptor &&
-                    retainedStringChars(descriptor.value, COMPACTED_PAYLOAD_RELEASE_MIN_CHARS) >=
-                        COMPACTED_PAYLOAD_RELEASE_MIN_CHARS) {
-                    retainedIds.add(entry.id);
-                    if (!keptEntryIds.has(entry.id))
-                        properties.push(property);
-                }
-            }
-            if (properties.length > 0)
+            const properties = this._releasableMessageProperties(entry);
+            if (properties.length === 0)
+                continue;
+            retainedIds.add(entry.id);
+            if (!keptEntryIds.has(entry.id))
                 releases.push({ entry, properties });
         }
         this._ensureEntryFileLocations(retainedIds);
@@ -996,42 +1124,87 @@ export class SessionManager {
     _persist(entry) {
         if (!this.persist || !this.sessionFile)
             return;
-        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-        if (!hasAssistant) {
-            if (this.flushed) {
-                this._ensureSessionFileParent(this.sessionFile);
-                appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
-            }
-            else {
-                // Mark as not flushed so when assistant arrives, all entries get written
-                this.flushed = false;
-            }
-            return;
+        if (this.persistenceStateUncertain) {
+            throw new Error("Session persistence state is uncertain after a failed write; reopen the session file or start a new session before appending.");
         }
-        if (!this.flushed) {
-            this._ensureSessionFileParent(this.sessionFile);
-            const fd = openSync(this.sessionFile, "wx");
-            try {
-                for (const e of this.fileEntries) {
-                    writeFileSync(fd, `${JSON.stringify(e)}\n`);
+        try {
+            const hasAssistant = (entry.type === "message" && entry.message.role === "assistant") ||
+                this.fileEntries.some((candidate) => candidate.type === "message" && candidate.message.role === "assistant");
+            if (!hasAssistant) {
+                if (this.flushed) {
+                    this._ensureSessionFileParent(this.sessionFile);
+                    appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
                 }
+                return;
             }
-            finally {
-                closeSync(fd);
+            if (!this.flushed) {
+                this._ensureSessionFileParent(this.sessionFile);
+                const fd = openSync(this.sessionFile, "wx");
+                try {
+                    for (const candidate of this.fileEntries) {
+                        writeFileSync(fd, `${JSON.stringify(candidate)}\n`);
+                    }
+                    writeFileSync(fd, `${JSON.stringify(entry)}\n`);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                this.flushed = true;
+            }
+            else {
+                this._ensureSessionFileParent(this.sessionFile);
+                appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
             }
-            this.flushed = true;
         }
-        else {
-            this._ensureSessionFileParent(this.sessionFile);
-            appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
+        catch (error) {
+            // append/write/close failures may leave a partial JSONL suffix. Do not publish the
+            // entry in memory, and fence every later append until an explicit reload owns the
+            // surviving canonical prefix.
+            this.persistenceStateUncertain = true;
+            throw error;
         }
     }
     _appendEntry(entry) {
+        this._persist(entry);
         this.fileEntries.push(entry);
         this.entries.push(entry);
         this.byId.set(entry.id, entry);
         this.leafId = entry.id;
-        this._persist(entry);
+        this._advanceSessionContextCache(entry);
+    }
+    _invalidateSessionContextCache() {
+        this.sessionContextCache = undefined;
+    }
+    /** Advance a materialized linear projection without walking its immutable ancestry again. */
+    _advanceSessionContextCache(entry) {
+        const cached = this.sessionContextCache;
+        if (!cached || cached.leafId !== entry.parentId || entry.type === "compaction") {
+            this._invalidateSessionContextCache();
+            return;
+        }
+        switch (entry.type) {
+            case "message":
+                cached.context.messages.push(entry.message);
+                if (entry.message.role === "assistant") {
+                    cached.context.model = { provider: entry.message.provider, modelId: entry.message.model };
+                }
+                break;
+            case "custom_message":
+                cached.context.messages.push(retainSynthesizedSessionContextMessage(createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp)));
+                break;
+            case "branch_summary":
+                if (entry.summary) {
+                    cached.context.messages.push(retainSynthesizedSessionContextMessage(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)));
+                }
+                break;
+            case "thinking_level_change":
+                cached.context.thinkingLevel = entry.thinkingLevel;
+                break;
+            case "model_change":
+                cached.context.model = { provider: entry.provider, modelId: entry.modelId };
+                break;
+        }
+        cached.leafId = entry.id;
     }
     /** Append a message as child of current leaf, then advance leaf. Returns entry id.
      * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
@@ -1220,11 +1393,10 @@ export class SessionManager {
     getBranch(fromId) {
         const path = [];
         const startId = fromId ?? this.leafId;
-        let current = startId ? this.byId.get(startId) : undefined;
-        while (current) {
-            path.push(current);
-            current = current.parentId ? this.byId.get(current.parentId) : undefined;
-        }
+        const start = startId ? this.byId.get(startId) : undefined;
+        visitSessionAncestry(start, this.byId, (entry) => {
+            path.push(entry);
+        });
         path.reverse();
         return path;
     }
@@ -1237,20 +1409,30 @@ export class SessionManager {
      */
     getLatestCustomEntryOnBranch(customType, fromId) {
         const startId = fromId ?? this.leafId;
-        let current = startId ? this.byId.get(startId) : undefined;
-        while (current) {
-            if (current.type === "custom" && current.customType === customType)
-                return current;
-            current = current.parentId ? this.byId.get(current.parentId) : undefined;
-        }
-        return undefined;
+        const start = startId ? this.byId.get(startId) : undefined;
+        let match;
+        visitSessionAncestry(start, this.byId, (entry) => {
+            if (entry.type !== "custom" || entry.customType !== customType)
+                return;
+            match = entry;
+            return false;
+        });
+        return match;
     }
     /**
      * Build the session context (what gets sent to the LLM).
      * Uses tree traversal from current leaf.
      */
     buildSessionContext() {
-        return buildSessionContext(this.getEntries(), this.leafId, this.byId);
+        let cached = this.sessionContextCache;
+        if (!cached || cached.leafId !== this.leafId) {
+            cached = {
+                leafId: this.leafId,
+                context: buildSessionContext(this.entries, this.leafId, this.byId),
+            };
+            this.sessionContextCache = cached;
+        }
+        return cloneSessionContext(cached.context);
     }
     /**
      * Get session header.
@@ -1276,6 +1458,94 @@ export class SessionManager {
     getEntryCount() {
         return this.entries.length;
     }
+    /**
+     * Release large own payload properties from one already-persisted message without reopening the
+     * session. Calling this immediately after append advances the bounded file-location cursor only
+     * across the new suffix; cold getters restore the exact property from that canonical JSONL line.
+     */
+    releasePersistedMessagePayload(entryId) {
+        const entry = this.byId.get(entryId);
+        if (!entry || entry.type !== "message") {
+            throw new TypeError(`Session entry ${entryId} is not a persisted message.`);
+        }
+        if (!this.persist || !this.flushed || !this.sessionFile) {
+            throw new Error(`Session message ${entryId} is not durably persisted.`);
+        }
+        if (this.persistenceStateUncertain) {
+            throw new Error("Session persistence state is uncertain after a failed write; reopen the session file before releasing payloads.");
+        }
+        const properties = this._releasableMessageProperties(entry);
+        if (properties.length === 0)
+            return;
+        const location = this._getEntryFileLocation(entryId);
+        if (!location)
+            throw new Error(`Persisted session message ${entryId} has no canonical file location.`);
+        for (const property of properties)
+            this._releaseMessageProperty(entry, property);
+    }
+    /**
+     * Visit one bounded entry range without allocating an entries slice or cloning payloads.
+     * Entries are borrowed read-only for the callback duration. `persistedBytes` is a conservative
+     * serialized-size signal for disk-backed cold payloads; infinity means the payload cannot be
+     * restored through the bounded index and consumers must skip it.
+     */
+    visitEntries(startIndex, maxEntries, visitor) {
+        if (!Number.isSafeInteger(startIndex) || startIndex < 0 || startIndex > this.entries.length) {
+            throw new TypeError("Session entry visit start index is invalid.");
+        }
+        if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > MAX_SESSION_ENTRY_VISIT_COUNT) {
+            throw new TypeError(`Session entry visit count must be from 1 through ${MAX_SESSION_ENTRY_VISIT_COUNT}.`);
+        }
+        const endIndex = Math.min(this.entries.length, startIndex + maxEntries);
+        const visitedColdPayloadEntryIds = new Set();
+        for (let index = startIndex; index < endIndex; index += 1) {
+            const entryId = this.entries[index].id;
+            if (this.coldPayloadEntryIds.has(entryId))
+                visitedColdPayloadEntryIds.add(entryId);
+        }
+        if (visitedColdPayloadEntryIds.size > 0)
+            this._ensureEntryFileLocations(visitedColdPayloadEntryIds);
+        for (let index = startIndex; index < endIndex; index += 1) {
+            const entry = this.entries[index];
+            const coldPayload = this.coldPayloadEntryIds.has(entry.id);
+            const persistedBytes = coldPayload
+                ? (this.entryFileLocations.get(entry.id)?.length ?? Number.POSITIVE_INFINITY)
+                : undefined;
+            visitor(entry, index, persistedBytes);
+        }
+        return endIndex;
+    }
+    /**
+     * Read only a bounded UTF-8 prefix of one persisted entry's canonical JSONL record.
+     * This lets owners classify cold payloads without invoking a disk-backed message getter or
+     * allocating the complete retained line. Returns undefined for in-memory or unknown entries.
+     */
+    readEntryJsonPrefix(entryId, maxBytes) {
+        if (!this.sessionFile || !this.byId.has(entryId))
+            return undefined;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > ENTRY_ID_PREFIX_BYTES) {
+            throw new TypeError(`Session entry JSON prefix bytes must be from 1 through ${ENTRY_ID_PREFIX_BYTES}.`);
+        }
+        const location = this._getEntryFileLocation(entryId);
+        if (!location)
+            return undefined;
+        const bytesToRead = Math.min(maxBytes, location.length);
+        const buffer = Buffer.allocUnsafe(bytesToRead);
+        const fd = openSync(this.sessionFile, "r");
+        let bytesRead = 0;
+        try {
+            while (bytesRead < bytesToRead) {
+                const count = readSync(fd, buffer, bytesRead, bytesToRead - bytesRead, location.offset + bytesRead);
+                if (count === 0)
+                    break;
+                bytesRead += count;
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
     /**
      * Return recent user-entered prompt text for input recall, oldest entry first.
      * This walks only the active branch and does not build/render full session context.
@@ -1285,15 +1555,16 @@ export class SessionManager {
         if (maxEntries === 0)
             return [];
         const history = [];
-        let entry = this.leafId ? this.byId.get(this.leafId) : undefined;
-        while (entry && history.length < maxEntries) {
+        const leaf = this.leafId ? this.byId.get(this.leafId) : undefined;
+        visitSessionAncestry(leaf, this.byId, (entry) => {
             if (entry.type === "message" && entry.message.role === "user") {
                 const text = this.getUserInputText(entry.message);
                 if (text)
                     history.push(text);
             }
-            entry = entry.parentId ? this.byId.get(entry.parentId) : undefined;
-        }
+            if (history.length >= maxEntries)
+                return false;
+        });
         return history.reverse();
     }
     getUserInputText(message) {
@@ -1366,6 +1637,7 @@ export class SessionManager {
         if (!this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
+        this._invalidateSessionContextCache();
         this.leafId = branchFromId;
     }
     /**
@@ -1374,6 +1646,7 @@ export class SessionManager {
      * Use this when navigating to re-edit the first user message.
      */
     resetLeaf() {
+        this._invalidateSessionContextCache();
         this.leafId = null;
     }
     /**
@@ -1385,6 +1658,7 @@ export class SessionManager {
         if (branchFromId !== null && !this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
+        this._invalidateSessionContextCache();
         this.leafId = branchFromId;
         const entry = {
             type: "branch_summary",
@@ -1464,7 +1738,9 @@ export class SessionManager {
         if (this.persist && hasAssistant) {
             // Keep the source manager active while cold compacted getters serialize into the copy.
             branched._rewriteFile();
-            branched.flushed = true;
+            // Reload through the branch owner so every disk-backed getter closes over the new
+            // canonical file instead of retaining the source manager's payload arena.
+            branched.setSessionFile(newSessionFile);
         }
         else {
             branched.flushed = false;
@@ -1479,6 +1755,7 @@ export class SessionManager {
      */
     createBranchedSession(leafId) {
         const branched = this.createBranchedSessionManager(leafId);
+        this._invalidateSessionContextCache();
         this.sessionId = branched.sessionId;
         this.sessionFile = branched.sessionFile;
         this.flushed = branched.flushed;
@@ -1488,6 +1765,7 @@ export class SessionManager {
         this.labelsById = branched.labelsById;
         this.labelTimestampsById = branched.labelTimestampsById;
         this.leafId = branched.leafId;
+        this.persistenceStateUncertain = branched.persistenceStateUncertain;
         this.coldPayloadEntryIds.clear();
         for (const id of branched.coldPayloadEntryIds)
             this.coldPayloadEntryIds.add(id);