@averyyy/pi-coding-agent 0.82.1-piclient.3 → 0.82.1-piclient.4

package/dist/core/session-manager.js

@@ -1,14 +1,61 @@
 import { uuidv7 } from "@earendil-works/pi-ai";
 import { randomUUID } from "crypto";
-import { appendFileSync, closeSync, createReadStream, existsSync, mkdirSync, openSync, readdirSync, readSync, statSync, writeFileSync, } from "fs";
+import { closeSync, createReadStream, existsSync, constants as fsConstants, fsyncSync, mkdirSync, openSync, readdirSync, readSync, renameSync, statSync, unlinkSync, writeSync, } from "fs";
 import { readdir, stat } from "fs/promises";
-import { join, resolve } from "path";
+import { basename, dirname, join, resolve } from "path";
 import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
+import { isDeepStrictEqual } from "util";
+import { serialize as serializeV8 } from "v8";
 import { getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "./messages.js";
+import { appendPiServerTreeHash, hashPiServerTreeEntry, PI_SERVER_EMPTY_TREE_HASH } from "./pi-server-protocol.js";
 export const CURRENT_SESSION_VERSION = 3;
+let sessionManagerPersistenceTestHooks;
+export function setSessionManagerPersistenceTestHooks(hooks) {
+    sessionManagerPersistenceTestHooks = hooks;
+}
+export const DEFAULT_SESSION_MANAGER_CAPACITY_LIMITS = Object.freeze({
+    maxEntries: 250_000,
+    maxLogicalBytes: 256 * 1024 * 1024,
+});
+export const ENV_SESSION_MAX_ENTRIES = "PI_SESSION_MAX_ENTRIES";
+export const ENV_SESSION_MAX_LOGICAL_BYTES = "PI_SESSION_MAX_LOGICAL_BYTES";
+export const ENV_SESSION_MAX_FILE_BYTES = "PI_SESSION_MAX_FILE_BYTES";
+export class SessionManagerCapacityError extends Error {
+    code = "PI_SESSION_CAPACITY_EXCEEDED";
+    retryable = false;
+    resource;
+    sessionId;
+    path;
+    current;
+    requested;
+    limit;
+    constructor(input) {
+        super(`Session capacity exceeded: resource=${input.resource}, session=${input.sessionId}, path=${input.path ?? "<memory>"}, requested=${input.requested}, limit=${input.limit}`);
+        this.name = "SessionManagerCapacityError";
+        this.resource = input.resource;
+        this.sessionId = input.sessionId;
+        this.path = input.path;
+        this.current = input.current;
+        this.requested = input.requested;
+        this.limit = input.limit;
+    }
+}
+let sessionManagerCapacityOverrides = {};
+export function configureSessionManagerCapacityLimits(overrides) {
+    for (const [name, value] of Object.entries(overrides)) {
+        if (!Number.isSafeInteger(value) || (value ?? 0) <= 0) {
+            throw new RangeError(`${name} must be a positive safe integer`);
+        }
+    }
+    sessionManagerCapacityOverrides = { ...sessionManagerCapacityOverrides, ...overrides };
+    return getSessionManagerCapacityLimits();
+}
+export function resetSessionManagerCapacityLimits() {
+    sessionManagerCapacityOverrides = {};
+}
 function createSessionId() {
     return uuidv7();
 }
@@ -121,6 +168,40 @@ function buildEntryIndex(entries, byId) {
     }
     return index;
 }
+function validateSessionTreeShape(entries) {
+    const index = new Map();
+    for (const entry of entries) {
+        if (index.has(entry.id))
+            throw new Error(`Duplicate session entry id ${entry.id}`);
+        index.set(entry.id, entry);
+    }
+    for (const entry of entries) {
+        if (entry.parentId !== null && !index.has(entry.parentId)) {
+            throw new Error(`Parent entry ${entry.parentId} does not exist`);
+        }
+    }
+    const visitState = new Map();
+    for (const entry of entries) {
+        if (visitState.get(entry.id) === "visited")
+            continue;
+        const path = [];
+        let current = entry;
+        while (current) {
+            const state = visitState.get(current.id);
+            if (state === "visiting") {
+                throw new Error(`Session tree contains a parent cycle at entry ${current.id}`);
+            }
+            if (state === "visited")
+                break;
+            visitState.set(current.id, "visiting");
+            path.push(current);
+            current = current.parentId === null ? undefined : index.get(current.parentId);
+        }
+        for (const pathEntry of path)
+            visitState.set(pathEntry.id, "visited");
+    }
+    return index;
+}
 function buildSessionPath(entries, leafId, byId) {
     const index = buildEntryIndex(entries, byId);
     let leaf;
@@ -136,7 +217,12 @@ function buildSessionPath(entries, leafId, byId) {
     }
     const path = [];
     let current = leaf;
+    const seen = new Set();
     while (current) {
+        if (seen.has(current.id)) {
+            throw new Error(`Session tree contains a parent cycle at entry ${current.id}`);
+        }
+        seen.add(current.id);
         path.push(current);
         current = current.parentId ? index.get(current.parentId) : undefined;
     }
@@ -183,7 +269,10 @@ export function sessionEntryToContextMessages(entry) {
         return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
     }
     if (entry.type === "compaction") {
-        return [createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp)];
+        return [
+            createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp),
+            ...(entry.retainedTail ?? []),
+        ];
     }
     return [];
 }
@@ -211,6 +300,10 @@ export function buildContextEntries(entries, leafId, byId) {
         return path;
     }
     const contextEntries = [compaction];
+    if (compaction.retainedTail !== undefined) {
+        contextEntries.push(...path.slice(compactionIdx + 1));
+        return contextEntries;
+    }
     let foundFirstKept = false;
     for (let i = 0; i < compactionIdx; i++) {
         const entry = path[i];
@@ -256,21 +349,238 @@ const SESSION_READ_BUFFER_SIZE = 1024 * 1024;
 const SESSION_HEADER_READ_BUFFER_SIZE = 4096;
 /** Bound synchronous header discovery while allowing large cwd and custom metadata fields. */
 const MAX_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;
+const SESSION_FILE_ENVELOPE_OVERHEAD_BYTES = 1024 * 1024;
+const WINDOWS_SESSION_RENAME_RETRIES = 4;
+const MAX_WINDOWS_SESSION_RENAME_DELAY_MS = 80;
+function readPositiveSafeIntegerEnvironment(name) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]*$/u.test(raw)) {
+        throw new Error(`${name} must be a positive safe integer`);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+export function getSessionManagerCapacityLimits() {
+    const maxEntries = sessionManagerCapacityOverrides.maxEntries ??
+        readPositiveSafeIntegerEnvironment(ENV_SESSION_MAX_ENTRIES) ??
+        DEFAULT_SESSION_MANAGER_CAPACITY_LIMITS.maxEntries;
+    const maxLogicalBytes = sessionManagerCapacityOverrides.maxLogicalBytes ??
+        readPositiveSafeIntegerEnvironment(ENV_SESSION_MAX_LOGICAL_BYTES) ??
+        DEFAULT_SESSION_MANAGER_CAPACITY_LIMITS.maxLogicalBytes;
+    const derivedMaxFileBytes = maxLogicalBytes + maxEntries + SESSION_FILE_ENVELOPE_OVERHEAD_BYTES;
+    if (!Number.isSafeInteger(derivedMaxFileBytes)) {
+        throw new Error("Session capacity limits are too large to derive a safe session file limit");
+    }
+    const maxFileBytes = sessionManagerCapacityOverrides.maxFileBytes ??
+        readPositiveSafeIntegerEnvironment(ENV_SESSION_MAX_FILE_BYTES) ??
+        derivedMaxFileBytes;
+    return { maxEntries, maxLogicalBytes, maxFileBytes };
+}
+function sessionCapacityError(resource, sessionId, path, current, requested, limit) {
+    return new SessionManagerCapacityError({ resource, sessionId, path, current, requested, limit });
+}
+function serializeEntryJson(entry) {
+    const serialized = JSON.stringify(entry);
+    if (serialized === undefined) {
+        throw new Error(`Session entry ${entry.type} could not be serialized`);
+    }
+    return serialized;
+}
+function measureSessionEntryLogicalBytes(entry) {
+    try {
+        return Buffer.byteLength(serializeEntryJson(entry), "utf8");
+    }
+    catch (error) {
+        if (entry.type !== "custom")
+            throw error;
+        // Native in-memory custom entries intentionally support cyclic structured
+        // data. They have no JSON representation, so account their exact V8
+        // structured-clone bytes; all transportable entries retain JSON byte parity.
+        return serializeV8(entry).byteLength;
+    }
+}
+function measureSessionEntriesLogicalBytes(entries) {
+    let logicalBytes = 0;
+    for (const entry of entries)
+        logicalBytes += measureSessionEntryLogicalBytes(entry);
+    return logicalBytes;
+}
+/**
+ * Measure durable tree content as the UTF-8 bytes of each independently
+ * serialized session entry. File headers and JSONL newlines are envelope bytes.
+ */
+export function calculateSessionManagerLogicalBytes(entries) {
+    return measureSessionEntriesLogicalBytes(entries);
+}
+function assertSessionTreeCapacity(sessionId, path, currentEntryCount, currentLogicalBytes, nextEntryCount, nextLogicalBytes) {
+    const limits = getSessionManagerCapacityLimits();
+    if (nextEntryCount > limits.maxEntries) {
+        throw sessionCapacityError("entries", sessionId, path, currentEntryCount, nextEntryCount, limits.maxEntries);
+    }
+    if (nextLogicalBytes > limits.maxLogicalBytes) {
+        throw sessionCapacityError("logical_bytes", sessionId, path, currentLogicalBytes, nextLogicalBytes, limits.maxLogicalBytes);
+    }
+}
+function measureSessionFileBytes(entries) {
+    let fileBytes = 0;
+    for (const entry of entries) {
+        fileBytes += Buffer.byteLength(serializeEntryJson(entry), "utf8") + 1;
+    }
+    return fileBytes;
+}
+function assertSessionFileSize(sessionId, path, current, requested) {
+    const limit = getSessionManagerCapacityLimits().maxFileBytes;
+    if (requested > limit) {
+        throw sessionCapacityError("file_bytes", sessionId, path, current, requested, limit);
+    }
+}
+function getFilesystemErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return undefined;
+    return typeof error.code === "string" ? error.code : undefined;
+}
+function waitForWindowsSessionRenameRetry(attempt) {
+    const delay = Math.min(2 ** attempt * 5, MAX_WINDOWS_SESSION_RENAME_DELAY_MS);
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+}
+function replaceSessionFile(tempPath, targetPath) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            sessionManagerPersistenceTestHooks?.beforeRenameAttempt?.(attempt);
+            renameSync(tempPath, targetPath);
+            return;
+        }
+        catch (error) {
+            const useWindowsRetries = process.platform === "win32" || sessionManagerPersistenceTestHooks?.simulateWindowsRenameRetries === true;
+            if (!useWindowsRetries ||
+                getFilesystemErrorCode(error) !== "EPERM" ||
+                attempt >= WINDOWS_SESSION_RENAME_RETRIES) {
+                throw error;
+            }
+            waitForWindowsSessionRenameRetry(attempt);
+        }
+    }
+}
+function fsyncSessionDirectory(targetPath) {
+    if (process.platform === "win32") {
+        // libuv cannot open a Windows directory for fsync. Re-open the replaced
+        // file and fsync it after rename so the replacement reaches stable storage.
+        const handle = openSync(targetPath, "r+");
+        try {
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+        return;
+    }
+    const handle = openSync(dirname(targetPath), "r");
+    try {
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+function serializeFileEntry(entry) {
+    return Buffer.from(`${serializeEntryJson(entry)}\n`);
+}
+function writeBufferFully(handle, buffer) {
+    let written = 0;
+    while (written < buffer.byteLength) {
+        const bytesWritten = writeSync(handle, buffer, written, buffer.byteLength - written);
+        if (bytesWritten === 0) {
+            throw new Error("Session file write made no progress");
+        }
+        written += bytesWritten;
+    }
+}
+function writeSessionFileAtomically(targetPath, entries) {
+    const header = entries.find((entry) => entry.type === "session");
+    const currentBytes = existsSync(targetPath) ? statSync(targetPath).size : 0;
+    assertSessionFileSize(header?.id ?? "<unresolved>", targetPath, currentBytes, measureSessionFileBytes(entries));
+    const tempPath = join(dirname(targetPath), `.${basename(targetPath)}.rewrite-${process.pid}-${randomUUID()}.tmp`);
+    let tempHandle;
+    let replaced = false;
+    let primaryError;
+    const cleanupErrors = [];
+    try {
+        tempHandle = openSync(tempPath, "wx", 0o600);
+        sessionManagerPersistenceTestHooks?.onAtomicRewriteStage?.("after_temp_open");
+        for (const entry of entries) {
+            writeBufferFully(tempHandle, serializeFileEntry(entry));
+        }
+        sessionManagerPersistenceTestHooks?.onAtomicRewriteStage?.("after_temp_write");
+        fsyncSync(tempHandle);
+        sessionManagerPersistenceTestHooks?.onAtomicRewriteStage?.("after_temp_fsync");
+        closeSync(tempHandle);
+        tempHandle = undefined;
+        replaceSessionFile(tempPath, targetPath);
+        replaced = true;
+        sessionManagerPersistenceTestHooks?.onAtomicRewriteStage?.("after_replace");
+        fsyncSessionDirectory(targetPath);
+        sessionManagerPersistenceTestHooks?.onAtomicRewriteStage?.("after_directory_fsync");
+    }
+    catch (error) {
+        primaryError = error;
+    }
+    finally {
+        if (tempHandle !== undefined) {
+            try {
+                closeSync(tempHandle);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (!replaced && existsSync(tempPath)) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+    }
+    if (primaryError !== undefined && cleanupErrors.length === 0) {
+        throw primaryError;
+    }
+    if (primaryError !== undefined || cleanupErrors.length > 0) {
+        throw new AggregateError(primaryError === undefined ? cleanupErrors : [primaryError, ...cleanupErrors], `Failed to atomically rewrite session file ${targetPath}`);
+    }
+}
+function persistedEntriesEqual(left, right) {
+    return isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+}
 class SessionHeaderScanLimitError extends Error {
     constructor(filePath) {
         super(`Session header exceeds ${MAX_SESSION_HEADER_SCAN_BYTES}-byte scan limit: ${filePath}`);
         this.name = "SessionHeaderScanLimitError";
     }
 }
-function parseSessionEntryLine(line) {
+export class SessionFileCorruptionError extends Error {
+    path;
+    line;
+    constructor(filePath, line, cause) {
+        super(`Malformed session JSONL at ${filePath}:${line}`, { cause });
+        this.name = "SessionFileCorruptionError";
+        this.path = filePath;
+        this.line = line;
+    }
+}
+function parseSessionEntryLineStrict(line, filePath, lineNumber) {
     if (!line.trim())
         return null;
     try {
         return JSON.parse(line);
     }
-    catch {
-        // Skip malformed lines
-        return null;
+    catch (error) {
+        throw new SessionFileCorruptionError(filePath, lineNumber, error);
     }
 }
 /** Exported for testing */
@@ -278,12 +588,17 @@ export function loadEntriesFromFile(filePath) {
     const resolvedFilePath = normalizePath(filePath);
     if (!existsSync(resolvedFilePath))
         return [];
+    const fileBytes = statSync(resolvedFilePath).size;
+    assertSessionFileSize("<unresolved>", resolvedFilePath, 0, fileBytes);
     const entries = [];
+    let treeEntryCount = 0;
+    let treeLogicalBytes = 0;
     const fd = openSync(resolvedFilePath, "r");
     try {
         const decoder = new StringDecoder("utf8");
         const buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE);
         let pending = "";
+        let lineNumber = 1;
         while (true) {
             const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
             if (bytesRead === 0)
@@ -292,18 +607,33 @@ export function loadEntriesFromFile(filePath) {
             let lineStart = 0;
             let newlineIndex = pending.indexOf("\n", lineStart);
             while (newlineIndex !== -1) {
-                const entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex));
-                if (entry)
+                const entry = parseSessionEntryLineStrict(pending.slice(lineStart, newlineIndex), resolvedFilePath, lineNumber);
+                if (entry) {
+                    if (entry.type !== "session") {
+                        const nextLogicalBytes = treeLogicalBytes + measureSessionEntryLogicalBytes(entry);
+                        assertSessionTreeCapacity(entries[0]?.type === "session" ? entries[0].id : "<unresolved>", resolvedFilePath, treeEntryCount, treeLogicalBytes, treeEntryCount + 1, nextLogicalBytes);
+                        treeEntryCount++;
+                        treeLogicalBytes = nextLogicalBytes;
+                    }
                     entries.push(entry);
+                }
                 lineStart = newlineIndex + 1;
+                lineNumber++;
                 newlineIndex = pending.indexOf("\n", lineStart);
             }
             pending = pending.slice(lineStart);
         }
         pending += decoder.end();
-        const finalEntry = parseSessionEntryLine(pending);
-        if (finalEntry)
+        const finalEntry = parseSessionEntryLineStrict(pending, resolvedFilePath, lineNumber);
+        if (finalEntry) {
+            if (finalEntry.type !== "session") {
+                const nextLogicalBytes = treeLogicalBytes + measureSessionEntryLogicalBytes(finalEntry);
+                assertSessionTreeCapacity(entries[0]?.type === "session" ? entries[0].id : "<unresolved>", resolvedFilePath, treeEntryCount, treeLogicalBytes, treeEntryCount + 1, nextLogicalBytes);
+                treeEntryCount++;
+                treeLogicalBytes = nextLogicalBytes;
+            }
             entries.push(finalEntry);
+        }
     }
     finally {
         closeSync(fd);
@@ -319,13 +649,13 @@ export function loadEntriesFromFile(filePath) {
 }
 /**
  * Inspect a physical line while searching for the first parsed session entry.
- * Blank and malformed lines are skipped to match loadEntriesFromFile().
+ * Blank lines are skipped; malformed JSON fails closed.
  * Returns undefined to keep scanning, null for a parsed non-header entry, or the header.
  */
-function parseSessionHeaderCandidate(line) {
+function parseSessionHeaderCandidate(line, filePath, lineNumber) {
     if (!line.trim())
         return undefined;
-    const entry = parseSessionEntryLine(line);
+    const entry = parseSessionEntryLineStrict(line, filePath, lineNumber);
     if (!entry)
         return undefined;
     if (entry.type !== "session" || typeof entry.id !== "string")
@@ -333,18 +663,21 @@ function parseSessionHeaderCandidate(line) {
     return entry;
 }
 function readSessionHeader(filePath) {
+    const fileBytes = statSync(filePath).size;
+    assertSessionFileSize("<unresolved>", filePath, 0, fileBytes);
     const fd = openSync(filePath, "r");
     try {
         const decoder = new StringDecoder("utf8");
         const buffer = Buffer.allocUnsafe(SESSION_HEADER_READ_BUFFER_SIZE);
         const lineChunks = [];
         let scannedBytes = 0;
+        let lineNumber = 1;
         while (scannedBytes < MAX_SESSION_HEADER_SCAN_BYTES) {
             const readLength = Math.min(buffer.length, MAX_SESSION_HEADER_SCAN_BYTES - scannedBytes);
             const bytesRead = readSync(fd, buffer, 0, readLength, null);
             if (bytesRead === 0) {
                 lineChunks.push(decoder.end());
-                return parseSessionHeaderCandidate(lineChunks.join("")) ?? null;
+                return parseSessionHeaderCandidate(lineChunks.join(""), filePath, lineNumber) ?? null;
             }
             scannedBytes += bytesRead;
             const chunk = decoder.write(buffer.subarray(0, bytesRead));
@@ -352,11 +685,12 @@ function readSessionHeader(filePath) {
             let newlineIndex = chunk.indexOf("\n", lineStart);
             while (newlineIndex !== -1) {
                 lineChunks.push(chunk.slice(lineStart, newlineIndex));
-                const header = parseSessionHeaderCandidate(lineChunks.join(""));
+                const header = parseSessionHeaderCandidate(lineChunks.join(""), filePath, lineNumber);
                 if (header !== undefined)
                     return header;
                 lineChunks.length = 0;
                 lineStart = newlineIndex + 1;
+                lineNumber++;
                 newlineIndex = chunk.indexOf("\n", lineStart);
             }
             lineChunks.push(chunk.slice(lineStart));
@@ -366,7 +700,7 @@ function readSessionHeader(filePath) {
         const probe = Buffer.allocUnsafe(1);
         if (readSync(fd, probe, 0, probe.length, null) === 0) {
             lineChunks.push(decoder.end());
-            return parseSessionHeaderCandidate(lineChunks.join("")) ?? null;
+            return parseSessionHeaderCandidate(lineChunks.join(""), filePath, lineNumber) ?? null;
         }
         throw new SessionHeaderScanLimitError(filePath);
     }
@@ -378,9 +712,10 @@ function readSessionHeaderForDiscovery(filePath) {
     try {
         return readSessionHeader(filePath);
     }
-    catch {
-        // Discovery is best-effort: unreadable or oversized files are not sessions,
-        // and one corrupt file must not prevent other sessions from being found.
+    catch (error) {
+        if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+            throw error;
+        // Discovery remains best-effort for transient filesystem failures.
         return null;
     }
 }
@@ -406,7 +741,9 @@ export function findMostRecentSession(sessionDir, cwd) {
             .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
         return files[0]?.path || null;
     }
-    catch {
+    catch (error) {
+        if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+            throw error;
         // Directory access and stat races make recent-session discovery unavailable.
         return null;
     }
@@ -440,18 +777,23 @@ function getMessageActivityTime(entry) {
 async function buildSessionInfo(filePath) {
     try {
         const stats = await stat(filePath);
+        assertSessionFileSize("<unresolved>", filePath, 0, stats.size);
         let header = null;
         let messageCount = 0;
         let firstMessage = "";
         const allMessages = [];
         let name;
         let lastActivityTime;
+        let treeEntryCount = 0;
+        let treeLogicalBytes = 0;
+        let lineNumber = 0;
         const rl = createInterface({
             input: createReadStream(filePath, { encoding: "utf8" }),
             crlfDelay: Infinity,
         });
         for await (const line of rl) {
-            const entry = parseSessionEntryLine(line);
+            lineNumber++;
+            const entry = parseSessionEntryLineStrict(line, filePath, lineNumber);
             if (!entry)
                 continue;
             if (!header) {
@@ -460,6 +802,12 @@ async function buildSessionInfo(filePath) {
                 header = entry;
                 continue;
             }
+            if (entry.type !== "session") {
+                const nextLogicalBytes = treeLogicalBytes + measureSessionEntryLogicalBytes(entry);
+                assertSessionTreeCapacity(header.id, filePath, treeEntryCount, treeLogicalBytes, treeEntryCount + 1, nextLogicalBytes);
+                treeEntryCount++;
+                treeLogicalBytes = nextLogicalBytes;
+            }
             // Extract session name (use latest, including explicit clears)
             if (entry.type === "session_info") {
                 name = entry.name?.trim() || undefined;
@@ -507,7 +855,9 @@ async function buildSessionInfo(filePath) {
             allMessagesText: allMessages.join(" "),
         };
     }
-    catch {
+    catch (error) {
+        if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+            throw error;
         return null;
     }
 }
@@ -526,7 +876,9 @@ async function buildSessionInfosWithConcurrency(files, onLoaded) {
             .then((info) => {
             results[index] = info;
         })
-            .catch(() => {
+            .catch((error) => {
+            if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+                throw error;
             results[index] = null;
         })
             .finally(() => {
@@ -540,7 +892,13 @@ async function buildSessionInfosWithConcurrency(files, onLoaded) {
             startNext();
         }
         if (inFlight.size > 0) {
-            await Promise.race(inFlight);
+            try {
+                await Promise.race(inFlight);
+            }
+            catch (error) {
+                await Promise.allSettled([...inFlight]);
+                throw error;
+            }
         }
     }
     return results;
@@ -565,7 +923,9 @@ async function listSessionsFromDir(dir, onProgress, progressOffset = 0, progress
             }
         }
     }
-    catch {
+    catch (error) {
+        if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+            throw error;
         // Return empty list on error
     }
     return sessions;
@@ -593,6 +953,11 @@ export class SessionManager {
     labelsById = new Map();
     labelTimestampsById = new Map();
     leafId = null;
+    treeEntryCount = 0;
+    treeLogicalBytes = 0;
+    treeHash = PI_SERVER_EMPTY_TREE_HASH;
+    treeHashError;
+    appendPersistenceFailure;
     constructor(cwd, sessionDir, sessionFile, persist, newSessionOptions, preloadedFileEntries) {
         this.cwd = resolvePath(cwd);
         this.sessionDir = normalizePath(sessionDir);
@@ -612,34 +977,51 @@ export class SessionManager {
         this._setSessionFile(sessionFile);
     }
     _setSessionFile(sessionFile, preloadedFileEntries) {
-        this.sessionFile = resolvePath(sessionFile);
-        if (existsSync(this.sessionFile)) {
-            this.fileEntries = preloadedFileEntries ?? loadEntriesFromFile(this.sessionFile);
+        const resolvedSessionFile = resolvePath(sessionFile);
+        if (existsSync(resolvedSessionFile)) {
+            const nextFileEntries = structuredClone(preloadedFileEntries ?? loadEntriesFromFile(resolvedSessionFile));
             // If file was empty, initialize it with a valid session header. If it was
             // non-empty but did not parse as a pi session, fail without modifying it.
-            if (this.fileEntries.length === 0) {
-                const explicitPath = this.sessionFile;
-                if (statSync(explicitPath).size > 0) {
-                    throw new Error(`Session file is not a valid pi session: ${explicitPath}`);
+            if (nextFileEntries.length === 0) {
+                if (statSync(resolvedSessionFile).size > 0) {
+                    throw new Error(`Session file is not a valid pi session: ${resolvedSessionFile}`);
                 }
-                this.newSession();
-                this.sessionFile = explicitPath;
-                this._rewriteFile();
+                const nextSessionId = createSessionId();
+                const header = {
+                    type: "session",
+                    version: CURRENT_SESSION_VERSION,
+                    id: nextSessionId,
+                    timestamp: new Date().toISOString(),
+                    cwd: this.cwd,
+                };
+                writeSessionFileAtomically(resolvedSessionFile, [header]);
+                this.sessionId = nextSessionId;
+                this.sessionFile = resolvedSessionFile;
+                this.fileEntries = [header];
+                this._buildIndex();
+                this.appendPersistenceFailure = undefined;
                 this.flushed = true;
                 return;
             }
-            const header = this.fileEntries.find((e) => e.type === "session");
-            this.sessionId = header?.id ?? createSessionId();
-            if (migrateToCurrentVersion(this.fileEntries)) {
-                this._rewriteFile();
+            const header = nextFileEntries.find((e) => e.type === "session");
+            const nextSessionId = header?.id ?? createSessionId();
+            const migrated = migrateToCurrentVersion(nextFileEntries);
+            const treeEntries = nextFileEntries.filter((entry) => entry.type !== "session");
+            validateSessionTreeShape(treeEntries);
+            assertSessionTreeCapacity(nextSessionId, resolvedSessionFile, 0, 0, treeEntries.length, measureSessionEntriesLogicalBytes(treeEntries));
+            if (migrated) {
+                writeSessionFileAtomically(resolvedSessionFile, nextFileEntries);
             }
+            this.sessionId = nextSessionId;
+            this.sessionFile = resolvedSessionFile;
+            this.fileEntries = nextFileEntries;
             this._buildIndex();
+            this.appendPersistenceFailure = undefined;
             this.flushed = true;
         }
         else {
-            const explicitPath = this.sessionFile;
             this.newSession();
-            this.sessionFile = explicitPath; // preserve explicit path from --session flag
+            this.sessionFile = resolvedSessionFile; // preserve explicit path from --session flag
         }
     }
     newSession(options) {
@@ -661,6 +1043,11 @@ export class SessionManager {
         this.labelsById.clear();
         this.labelTimestampsById.clear();
         this.leafId = null;
+        this.treeEntryCount = 0;
+        this.treeLogicalBytes = 0;
+        this.treeHash = PI_SERVER_EMPTY_TREE_HASH;
+        this.treeHashError = undefined;
+        this.appendPersistenceFailure = undefined;
         this.flushed = false;
         if (this.persist) {
             const fileTimestamp = timestamp.replace(/[:.]/g, "-");
@@ -669,15 +1056,26 @@ export class SessionManager {
         return this.sessionFile;
     }
     _buildIndex() {
+        const entries = this.fileEntries.filter((entry) => entry.type !== "session");
+        validateSessionTreeShape(entries);
+        const logicalBytes = measureSessionEntriesLogicalBytes(entries);
+        assertSessionTreeCapacity(this.sessionId, this.sessionFile, 0, 0, entries.length, logicalBytes);
         this.byId.clear();
         this.labelsById.clear();
         this.labelTimestampsById.clear();
         this.leafId = null;
+        this.treeEntryCount = 0;
+        this.treeLogicalBytes = 0;
+        this.treeHash = PI_SERVER_EMPTY_TREE_HASH;
+        this.treeHashError = undefined;
         for (const entry of this.fileEntries) {
             if (entry.type === "session")
                 continue;
+            this.treeEntryCount++;
+            this.treeLogicalBytes += measureSessionEntryLogicalBytes(entry);
             this.byId.set(entry.id, entry);
             this.leafId = entry.id;
+            this._updateTreeHash(entry);
             if (entry.type === "label") {
                 if (entry.label) {
                     this.labelsById.set(entry.targetId, entry.label);
@@ -690,17 +1088,32 @@ export class SessionManager {
             }
         }
     }
-    _rewriteFile() {
+    _updateTreeHash(entry) {
+        if (this.treeHash === undefined)
+            return;
+        try {
+            this.treeHash = appendPiServerTreeHash(this.treeHash, hashPiServerTreeEntry(entry));
+        }
+        catch (error) {
+            this.treeHash = undefined;
+            this.treeHashError = error;
+        }
+    }
+    _rewriteFile(entries = this.fileEntries) {
         if (!this.persist || !this.sessionFile)
             return;
-        const fd = openSync(this.sessionFile, "w");
+        if (this.appendPersistenceFailure !== undefined) {
+            throw new Error("Session persistence has an indeterminate prior failure; reopen the session before retrying", {
+                cause: this.appendPersistenceFailure,
+            });
+        }
         try {
-            for (const entry of this.fileEntries) {
-                writeFileSync(fd, `${JSON.stringify(entry)}\n`);
-            }
+            writeSessionFileAtomically(this.sessionFile, entries);
         }
-        finally {
-            closeSync(fd);
+        catch (error) {
+            this.appendPersistenceFailure = error;
+            const details = error instanceof Error ? error.message : String(error);
+            throw new Error(`Session file rewrite may have replaced ${this.sessionFile} without a durable in-memory commit; reopen the session before retrying: ${details}`, { cause: error });
         }
     }
     isPersisted() {
@@ -721,41 +1134,118 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
-    _persist(entry) {
-        if (!this.persist || !this.sessionFile)
+    /**
+     * Durably flush the persisted session file before an external acknowledgement.
+     * In-memory sessions and sessions without a materialized file have nothing to flush.
+     */
+    flushSessionFile() {
+        if (!this.persist || !this.sessionFile || !existsSync(this.sessionFile))
             return;
-        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
+        const handle = openSync(this.sessionFile, "r+");
+        try {
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+    }
+    _appendMaterializedEntry(entry) {
+        if (!this.sessionFile)
+            throw new Error("Cannot append without a session file");
+        const handle = openSync(this.sessionFile, fsConstants.O_WRONLY | fsConstants.O_APPEND);
+        let appendError;
+        try {
+            writeBufferFully(handle, serializeFileEntry(entry));
+            sessionManagerPersistenceTestHooks?.onAppendStage?.("after_append");
+            fsyncSync(handle);
+            sessionManagerPersistenceTestHooks?.onAppendStage?.("after_fsync");
+        }
+        catch (error) {
+            appendError = error;
+        }
+        try {
+            closeSync(handle);
+        }
+        catch (error) {
+            appendError =
+                appendError === undefined
+                    ? error
+                    : new AggregateError([appendError, error], `Failed to close session file ${this.sessionFile}`);
+        }
+        if (appendError !== undefined) {
+            this.appendPersistenceFailure = appendError;
+            throw new Error(`Session entry ${entry.id} may have reached disk but was not committed in memory; reopen the session before retrying`, { cause: appendError });
+        }
+    }
+    _persistBeforeCommit(entry, nextFileEntries) {
+        if (!this.persist || !this.sessionFile)
+            return this.flushed;
+        const hasAssistant = nextFileEntries.some((candidate) => {
+            return candidate.type === "message" && candidate.message.role === "assistant";
+        });
         if (!hasAssistant) {
-            if (this.flushed) {
-                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.flushed)
+                this._appendMaterializedEntry(entry);
+            return this.flushed;
+        }
+        if (this.flushed) {
+            this._appendMaterializedEntry(entry);
+            return true;
         }
+        try {
+            writeSessionFileAtomically(this.sessionFile, nextFileEntries);
+        }
+        catch (error) {
+            this.appendPersistenceFailure = error;
+            throw new Error(`Session entry ${entry.id} persistence failed before the in-memory commit; reopen the session before retrying`, { cause: error });
+        }
+        return true;
+    }
+    _preflightPersistEntry(entry) {
+        if (!this.persist || !this.sessionFile)
+            return;
+        const entryBytes = serializeFileEntry(entry).byteLength;
         if (!this.flushed) {
-            const fd = openSync(this.sessionFile, "wx");
+            assertSessionFileSize(this.sessionId, this.sessionFile, existsSync(this.sessionFile) ? statSync(this.sessionFile).size : 0, measureSessionFileBytes([...this.fileEntries, entry]));
+            return;
+        }
+        const currentBytes = existsSync(this.sessionFile) ? statSync(this.sessionFile).size : 0;
+        assertSessionFileSize(this.sessionId, this.sessionFile, currentBytes, currentBytes + entryBytes);
+    }
+    _preflightAppendEntry(entry) {
+        const nextLogicalBytes = this.treeLogicalBytes + measureSessionEntryLogicalBytes(entry);
+        assertSessionTreeCapacity(this.sessionId, this.sessionFile, this.treeEntryCount, this.treeLogicalBytes, this.treeEntryCount + 1, nextLogicalBytes);
+        this._preflightPersistEntry(entry);
+        return nextLogicalBytes;
+    }
+    _appendEntry(entry) {
+        if (this.appendPersistenceFailure !== undefined) {
+            throw new Error("Session append persistence has an indeterminate prior failure; reopen the session before retrying", {
+                cause: this.appendPersistenceFailure,
+            });
+        }
+        const nextLogicalBytes = this._preflightAppendEntry(entry);
+        const nextFileEntries = [...this.fileEntries, entry];
+        let nextTreeHash = this.treeHash;
+        let nextTreeHashError = this.treeHashError;
+        if (nextTreeHash !== undefined) {
             try {
-                for (const e of this.fileEntries) {
-                    writeFileSync(fd, `${JSON.stringify(e)}\n`);
-                }
+                nextTreeHash = appendPiServerTreeHash(nextTreeHash, hashPiServerTreeEntry(entry));
             }
-            finally {
-                closeSync(fd);
+            catch (error) {
+                nextTreeHash = undefined;
+                nextTreeHashError = error;
             }
-            this.flushed = true;
-        }
-        else {
-            appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
         }
-    }
-    _appendEntry(entry) {
+        const nextFlushed = this._persistBeforeCommit(entry, nextFileEntries);
         this.fileEntries.push(entry);
+        this.treeEntryCount++;
+        this.treeLogicalBytes = nextLogicalBytes;
         this.byId.set(entry.id, entry);
         this.leafId = entry.id;
-        this._persist(entry);
+        this.treeHash = nextTreeHash;
+        this.treeHashError = nextTreeHashError;
+        this.flushed = nextFlushed;
     }
     /** Append a message as child of current leaf, then advance leaf. Returns entry id.
      * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
@@ -794,9 +1284,12 @@ export class SessionManager {
             parentId = entry.id;
             return entry;
         });
-        this.fileEntries = [...retainedEntries, ...messageEntries];
+        const nextFileEntries = [...retainedEntries, ...messageEntries];
+        const nextTreeEntries = nextFileEntries.filter((entry) => entry.type !== "session");
+        assertSessionTreeCapacity(this.sessionId, this.sessionFile, this.treeEntryCount, this.treeLogicalBytes, nextTreeEntries.length, measureSessionEntriesLogicalBytes(nextTreeEntries));
+        this._rewriteFile(nextFileEntries);
+        this.fileEntries = nextFileEntries;
         this._buildIndex();
-        this._rewriteFile();
         this.flushed = this.persist;
     }
     replaceTree(entries, leafId) {
@@ -804,27 +1297,145 @@ export class SessionManager {
         if (!header) {
             throw new Error("Session header is missing");
         }
-        const ids = new Set();
-        for (const entry of entries) {
-            if (ids.has(entry.id)) {
-                throw new Error(`Duplicate session entry id ${entry.id}`);
-            }
-            ids.add(entry.id);
-        }
-        for (const entry of entries) {
-            if (entry.parentId !== null && !ids.has(entry.parentId)) {
-                throw new Error(`Parent entry ${entry.parentId} does not exist`);
-            }
-        }
-        if (leafId !== null && !ids.has(leafId)) {
+        const savedEntries = structuredClone(entries);
+        const nextEntryById = validateSessionTreeShape(savedEntries);
+        if (leafId !== null && !nextEntryById.has(leafId)) {
             throw new Error(`Leaf entry ${leafId} does not exist`);
         }
-        this.fileEntries = [header, ...entries.map((entry) => ({ ...entry }))];
+        const nextLogicalBytes = measureSessionEntriesLogicalBytes(savedEntries);
+        assertSessionTreeCapacity(this.sessionId, this.sessionFile, this.treeEntryCount, this.treeLogicalBytes, savedEntries.length, nextLogicalBytes);
+        const nextFileEntries = [header, ...savedEntries];
+        this._rewriteFile(nextFileEntries);
+        this.fileEntries = nextFileEntries;
         this._buildIndex();
         this.leafId = leafId;
-        this._rewriteFile();
         this.flushed = this.persist;
     }
+    /**
+     * Durably append one authoritative compaction entry without rewriting the
+     * existing session history. The caller must provide the exact local base
+     * identity used by the compaction request.
+     *
+     * Re-applying the exact already-durable entry is an idempotent no-op. Any
+     * other base, leaf, parent, or entry-id divergence fails closed.
+     */
+    appendCompactionEntry(entry, base) {
+        if (!Number.isSafeInteger(base.baseEntryCount) ||
+            base.baseEntryCount < 0 ||
+            (base.baseLeafId !== null && (typeof base.baseLeafId !== "string" || base.baseLeafId.length === 0)) ||
+            typeof base.baseTreeHash !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(base.baseTreeHash)) {
+            throw new Error("Compaction append base identity is invalid");
+        }
+        if (entry.type !== "compaction" ||
+            typeof entry.id !== "string" ||
+            entry.id.length === 0 ||
+            typeof entry.timestamp !== "string" ||
+            entry.timestamp.length === 0 ||
+            typeof entry.summary !== "string" ||
+            typeof entry.firstKeptEntryId !== "string" ||
+            entry.firstKeptEntryId.length === 0 ||
+            !Number.isFinite(entry.tokensBefore) ||
+            entry.tokensBefore < 0 ||
+            (entry.retainedTail !== undefined && !Array.isArray(entry.retainedTail))) {
+            throw new Error("Compaction entry is invalid");
+        }
+        let entryHash;
+        try {
+            entryHash = hashPiServerTreeEntry(entry);
+        }
+        catch (error) {
+            throw new Error(`Compaction entry ${entry.id} is not serializable`, { cause: error });
+        }
+        const currentTreeHash = this.treeHash;
+        if (currentTreeHash === undefined) {
+            throw new Error("Cannot validate compaction base because the local tree contains a non-serializable entry", {
+                cause: this.treeHashError,
+            });
+        }
+        const currentEntryCount = this.treeEntryCount;
+        if (currentEntryCount === base.baseEntryCount + 1) {
+            const existing = this.fileEntries.at(-1);
+            if (existing?.type === "compaction" &&
+                existing.id === entry.id &&
+                this.leafId === entry.id &&
+                currentTreeHash === appendPiServerTreeHash(base.baseTreeHash, entryHash) &&
+                persistedEntriesEqual(existing, entry)) {
+                if (this.persist && (!this.sessionFile || !this.flushed || !existsSync(this.sessionFile))) {
+                    throw new Error("Cannot verify an already-applied compaction without its materialized session file");
+                }
+                this.flushSessionFile();
+                return entry.id;
+            }
+            throw new Error(`Compaction entry ${entry.id} cannot be replayed because the local tree has a divergent entry after the requested base`);
+        }
+        if (currentEntryCount !== base.baseEntryCount) {
+            throw new Error(`Compaction append base entry count mismatch: expected ${base.baseEntryCount}, current ${currentEntryCount}`);
+        }
+        if (currentTreeHash !== base.baseTreeHash) {
+            throw new Error(`Compaction append base tree hash mismatch`);
+        }
+        if (this.leafId !== base.baseLeafId) {
+            throw new Error(`Compaction append base leaf mismatch: expected ${String(base.baseLeafId)}, current ${String(this.leafId)}`);
+        }
+        if (entry.parentId !== base.baseLeafId) {
+            throw new Error(`Compaction entry parent mismatch: expected ${String(base.baseLeafId)}, received ${String(entry.parentId)}`);
+        }
+        if (base.baseLeafId !== null && !this.byId.has(base.baseLeafId)) {
+            throw new Error(`Compaction append base leaf ${base.baseLeafId} does not exist`);
+        }
+        if (!this.byId.has(entry.firstKeptEntryId)) {
+            throw new Error(`Compaction first-kept entry ${entry.firstKeptEntryId} does not exist`);
+        }
+        if (this.byId.has(entry.id)) {
+            throw new Error(`Compaction entry id ${entry.id} already exists`);
+        }
+        if (this.appendPersistenceFailure !== undefined) {
+            throw new Error("Compaction append persistence has an indeterminate prior failure; reopen the session before retrying", { cause: this.appendPersistenceFailure });
+        }
+        const savedEntry = { ...entry };
+        const nextLogicalBytes = this.treeLogicalBytes + measureSessionEntryLogicalBytes(savedEntry);
+        assertSessionTreeCapacity(this.sessionId, this.sessionFile, this.treeEntryCount, this.treeLogicalBytes, this.treeEntryCount + 1, nextLogicalBytes);
+        const serializedEntry = serializeFileEntry(savedEntry);
+        if (this.persist) {
+            if (!this.sessionFile || !this.flushed || !existsSync(this.sessionFile)) {
+                throw new Error("Cannot durably append compaction before the session file is materialized");
+            }
+            const currentFileBytes = statSync(this.sessionFile).size;
+            assertSessionFileSize(this.sessionId, this.sessionFile, currentFileBytes, currentFileBytes + serializedEntry.byteLength);
+            const handle = openSync(this.sessionFile, fsConstants.O_WRONLY | fsConstants.O_APPEND);
+            let appendError;
+            try {
+                writeBufferFully(handle, serializedEntry);
+                sessionManagerPersistenceTestHooks?.onCompactionAppendStage?.("after_append");
+                fsyncSync(handle);
+                sessionManagerPersistenceTestHooks?.onCompactionAppendStage?.("after_fsync");
+            }
+            catch (error) {
+                appendError = error;
+            }
+            try {
+                closeSync(handle);
+            }
+            catch (error) {
+                appendError =
+                    appendError === undefined
+                        ? error
+                        : new AggregateError([appendError, error], `Failed to close session file ${this.sessionFile}`);
+            }
+            if (appendError !== undefined) {
+                this.appendPersistenceFailure = appendError;
+                throw new Error(`Compaction entry ${entry.id} may have reached disk but was not committed in memory; reopen the session before retrying`, { cause: appendError });
+            }
+        }
+        this.fileEntries.push(savedEntry);
+        this.treeEntryCount++;
+        this.treeLogicalBytes = nextLogicalBytes;
+        this.byId.set(savedEntry.id, savedEntry);
+        this.leafId = savedEntry.id;
+        this.treeHash = appendPiServerTreeHash(currentTreeHash, entryHash);
+        return savedEntry.id;
+    }
     /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
     appendThinkingLevelChange(thinkingLevel) {
         const entry = {
@@ -851,7 +1462,7 @@ export class SessionManager {
         return entry.id;
     }
     /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
-    appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook, usage) {
+    appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook, usage, retainedTail) {
         const entry = {
             type: "compaction",
             id: generateId(this.byId),
@@ -860,6 +1471,7 @@ export class SessionManager {
             summary,
             firstKeptEntryId,
             tokensBefore,
+            retainedTail,
             details,
             usage,
             fromHook,
@@ -1105,7 +1717,6 @@ export class SessionManager {
         if (branchFromId !== null && !this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
-        this.leafId = branchFromId;
         const entry = {
             type: "branch_summary",
             id: generateId(this.byId),
@@ -1162,62 +1773,42 @@ export class SessionManager {
                 labelsToWrite.push({ targetId, label, timestamp: this.labelTimestampsById.get(targetId) });
             }
         }
-        if (this.persist) {
-            // Build label entries
-            const lastEntryId = pathWithoutLabels[pathWithoutLabels.length - 1]?.id || null;
-            let parentId = lastEntryId;
-            const labelEntries = [];
-            for (const { targetId, label, timestamp: labelTimestamp } of labelsToWrite) {
-                const labelEntry = {
-                    type: "label",
-                    id: generateId(new Set(pathEntryIds)),
-                    parentId,
-                    timestamp: labelTimestamp,
-                    targetId,
-                    label,
-                };
-                pathEntryIds.add(labelEntry.id);
-                labelEntries.push(labelEntry);
-                parentId = labelEntry.id;
-            }
-            this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
-            this.sessionId = newSessionId;
-            this.sessionFile = newSessionFile;
-            this._buildIndex();
-            // Only write the file now if it contains an assistant message.
-            // Otherwise defer to _persist(), which creates the file on the
-            // first assistant response, matching the newSession() contract
-            // and avoiding the duplicate-header bug when _persist()'s
-            // no-assistant guard later resets flushed to false.
-            const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-            if (hasAssistant) {
-                this._rewriteFile();
-                this.flushed = true;
-            }
-            else {
-                this.flushed = false;
-            }
-            return newSessionFile;
-        }
-        // In-memory mode: replace current session with the path + labels
         const labelEntries = [];
+        const labelEntryIds = new Set(pathEntryIds);
         let parentId = pathWithoutLabels[pathWithoutLabels.length - 1]?.id || null;
         for (const { targetId, label, timestamp: labelTimestamp } of labelsToWrite) {
             const labelEntry = {
                 type: "label",
-                id: generateId(new Set([...pathEntryIds, ...labelEntries.map((e) => e.id)])),
+                id: generateId(labelEntryIds),
                 parentId,
                 timestamp: labelTimestamp,
                 targetId,
                 label,
             };
+            labelEntryIds.add(labelEntry.id);
             labelEntries.push(labelEntry);
             parentId = labelEntry.id;
         }
-        this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
+        const nextTreeEntries = [...pathWithoutLabels, ...labelEntries];
+        const nextFileEntries = [header, ...nextTreeEntries];
+        assertSessionTreeCapacity(newSessionId, this.persist ? newSessionFile : undefined, this.treeEntryCount, this.treeLogicalBytes, nextTreeEntries.length, measureSessionEntriesLogicalBytes(nextTreeEntries));
+        const hasAssistant = nextFileEntries.some((entry) => {
+            return entry.type === "message" && entry.message.role === "assistant";
+        });
+        if (this.persist) {
+            assertSessionFileSize(newSessionId, newSessionFile, existsSync(newSessionFile) ? statSync(newSessionFile).size : 0, measureSessionFileBytes(nextFileEntries));
+            if (hasAssistant) {
+                writeSessionFileAtomically(newSessionFile, nextFileEntries);
+            }
+        }
+        this.fileEntries = nextFileEntries;
         this.sessionId = newSessionId;
+        if (this.persist)
+            this.sessionFile = newSessionFile;
         this._buildIndex();
-        return undefined;
+        this.appendPersistenceFailure = undefined;
+        this.flushed = this.persist && hasAssistant;
+        return this.persist ? newSessionFile : undefined;
     }
     /**
      * Create a new session.
@@ -1293,10 +1884,6 @@ export class SessionManager {
         if (!sourceHeader) {
             throw new Error(`Cannot fork: source session has no header: ${resolvedSourcePath}`);
         }
-        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(resolvedTargetCwd);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
         // Create new session file with new ID but forked content
         if (options?.id !== undefined) {
             assertValidSessionId(options.id);
@@ -1304,6 +1891,7 @@ export class SessionManager {
         const newSessionId = options?.id ?? createSessionId();
         const timestamp = new Date().toISOString();
         const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDirPath(resolvedTargetCwd);
         const newSessionFile = join(dir, `${fileTimestamp}_${newSessionId}.jsonl`);
         // Write new header pointing to source as parent, with updated cwd
         const newHeader = {
@@ -1314,13 +1902,16 @@ export class SessionManager {
             cwd: resolvedTargetCwd,
             parentSession: resolvedSourcePath,
         };
-        writeFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`, { flag: "wx" });
-        // Copy all non-header entries from source
-        for (const entry of sourceEntries) {
-            if (entry.type !== "session") {
-                appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
-            }
+        const migratedSourceEntries = structuredClone(sourceEntries);
+        migrateToCurrentVersion(migratedSourceEntries);
+        const copiedEntries = migratedSourceEntries.filter((entry) => entry.type !== "session");
+        assertSessionTreeCapacity(newSessionId, newSessionFile, 0, 0, copiedEntries.length, measureSessionEntriesLogicalBytes(copiedEntries));
+        const nextFileEntries = [newHeader, ...copiedEntries];
+        assertSessionFileSize(newSessionId, newSessionFile, 0, measureSessionFileBytes(nextFileEntries));
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
         }
+        writeSessionFileAtomically(newSessionFile, nextFileEntries);
         return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);
     }
     /**
@@ -1381,7 +1972,9 @@ export class SessionManager {
             sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
             return sessions;
         }
-        catch {
+        catch (error) {
+            if (error instanceof SessionManagerCapacityError || error instanceof SessionFileCorruptionError)
+                throw error;
             return [];
         }
     }