@sammorrowdrums/mcpi 0.70.9 → 0.85.0-bootstrap.0

package/dist/core/session-manager.js

@@ -1,14 +1,22 @@
+import { uuidv7 } from "@sammorrowdrums/mcpi-ai";
 import { randomUUID } from "crypto";
-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, statSync, writeFileSync, } from "fs";
-import { readdir, readFile, stat } from "fs/promises";
+import { appendFileSync, closeSync, createReadStream, existsSync, mkdirSync, openSync, readdirSync, readSync, statSync, writeFileSync, } from "fs";
+import { readdir, stat } from "fs/promises";
 import { join, resolve } from "path";
-import { v7 as uuidv7 } from "uuid";
-import { getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
+import { createInterface } from "readline";
+import { StringDecoder } from "string_decoder";
+import { APP_NAME, getSessionsDir } from "../config.js";
+import { normalizePath, resolvePath } from "../utils/paths.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "./messages.js";
 export const CURRENT_SESSION_VERSION = 3;
 function createSessionId() {
     return uuidv7();
 }
+export function assertValidSessionId(id) {
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(id)) {
+        throw new Error("Session id must be non-empty, contain only alphanumeric characters, '-', '_', and '.', and start and end with an alphanumeric character");
+    }
+}
 /** Generate a unique short ID (8 hex chars, collision-checked) */
 function generateId(byId) {
     for (let i = 0; i < 100; i++) {
@@ -104,46 +112,40 @@ export function getLatestCompactionEntry(entries) {
     }
     return null;
 }
-/**
- * Build the session context from entries using tree traversal.
- * If leafId is provided, walks from that entry to root.
- * Handles compaction and branch summaries along the path.
- */
-export function buildSessionContext(entries, leafId, byId) {
-    // Build uuid index if not available
-    if (!byId) {
-        byId = new Map();
-        for (const entry of entries) {
-            byId.set(entry.id, entry);
-        }
+function buildEntryIndex(entries, byId) {
+    if (byId)
+        return byId;
+    const index = new Map();
+    for (const entry of entries) {
+        index.set(entry.id, entry);
     }
-    // Find leaf
+    return index;
+}
+function buildSessionPath(entries, leafId, byId) {
+    const index = buildEntryIndex(entries, byId);
     let leaf;
     if (leafId === null) {
-        // Explicitly null - return no messages (navigated to before first entry)
-        return { messages: [], thinkingLevel: "off", model: null };
+        return [];
     }
     if (leafId) {
-        leaf = byId.get(leafId);
+        leaf = index.get(leafId);
     }
+    leaf ??= entries[entries.length - 1];
     if (!leaf) {
-        // Fallback to last entry (when leafId is undefined)
-        leaf = entries[entries.length - 1];
-    }
-    if (!leaf) {
-        return { messages: [], thinkingLevel: "off", model: null };
+        return [];
     }
-    // Walk from leaf to root, collecting path
     const path = [];
     let current = leaf;
     while (current) {
-        path.unshift(current);
-        current = current.parentId ? byId.get(current.parentId) : undefined;
+        path.push(current);
+        current = current.parentId ? index.get(current.parentId) : undefined;
     }
-    // Extract settings and find compaction
+    path.reverse();
+    return path;
+}
+function getSessionContextSettings(path) {
     let thinkingLevel = "off";
     let model = null;
-    let compaction = null;
     for (const entry of path) {
         if (entry.type === "thinking_level_change") {
             thinkingLevel = entry.thinkingLevel;
@@ -154,86 +156,157 @@ export function buildSessionContext(entries, leafId, byId) {
         else if (entry.type === "message" && entry.message.role === "assistant") {
             model = { provider: entry.message.provider, modelId: entry.message.model };
         }
-        else if (entry.type === "compaction") {
-            compaction = entry;
-        }
     }
-    // Build messages and collect corresponding entries
-    // When there's a compaction, we need to:
-    // 1. Emit summary first (entry = compaction)
-    // 2. Emit kept messages (from firstKeptEntryId up to compaction)
-    // 3. Emit messages after compaction
-    const messages = [];
-    const appendMessage = (entry) => {
-        if (entry.type === "message") {
-            messages.push(entry.message);
-        }
-        else if (entry.type === "custom_message") {
-            messages.push(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));
-        }
-    };
-    if (compaction) {
-        // Emit summary first
-        messages.push(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)
-        let foundFirstKept = false;
-        for (let i = 0; i < compactionIdx; i++) {
-            const entry = path[i];
-            if (entry.id === compaction.firstKeptEntryId) {
-                foundFirstKept = true;
-            }
-            if (foundFirstKept) {
-                appendMessage(entry);
-            }
+    return { thinkingLevel, model };
+}
+/**
+ * Project one selected session entry into LLM/runtime messages.
+ * Plain custom entries are display/state entries and do not participate in context.
+ */
+export function sessionEntryToContextMessages(entry) {
+    if (entry.type === "message") {
+        const message = entry.message;
+        // Session files are parsed without validation; old versions, forks, or
+        // hand-edited files can contain messages with null/missing content.
+        if ((message.role === "user" || message.role === "assistant" || message.role === "toolResult") &&
+            message.content == null) {
+            return [{ ...message, content: [] }];
         }
-        // Emit messages after compaction
-        for (let i = compactionIdx + 1; i < path.length; i++) {
-            const entry = path[i];
-            appendMessage(entry);
+        return [message];
+    }
+    if (entry.type === "custom_message") {
+        return [
+            createCustomMessage(entry.customType, entry.content ?? [], entry.display, entry.details, entry.timestamp),
+        ];
+    }
+    if (entry.type === "branch_summary" && entry.summary) {
+        return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
+    }
+    if (entry.type === "compaction") {
+        return [createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp)];
+    }
+    return [];
+}
+/**
+ * Build the active, compaction-aware session entry list.
+ *
+ * This follows the current leaf path. If the path contains compaction entries,
+ * the latest compaction is represented by the compaction entry itself, followed
+ * by the kept entries starting at firstKeptEntryId and all entries after the
+ * compaction entry. Older summarized entries are omitted.
+ */
+export function buildContextEntries(entries, leafId, byId) {
+    const path = buildSessionPath(entries, leafId, byId);
+    let compaction = null;
+    for (const entry of path) {
+        if (entry.type === "compaction") {
+            compaction = entry;
         }
     }
-    else {
-        // No compaction - emit all messages, handle branch summaries and custom messages
-        for (const entry of path) {
-            appendMessage(entry);
+    if (!compaction) {
+        return path;
+    }
+    const compactionIdx = path.findIndex((entry) => entry.id === compaction.id);
+    if (compactionIdx < 0) {
+        return path;
+    }
+    const contextEntries = [compaction];
+    let foundFirstKept = false;
+    for (let i = 0; i < compactionIdx; i++) {
+        const entry = path[i];
+        if (entry.id === compaction.firstKeptEntryId) {
+            foundFirstKept = true;
+        }
+        if (foundFirstKept) {
+            contextEntries.push(entry);
         }
     }
+    contextEntries.push(...path.slice(compactionIdx + 1));
+    return contextEntries;
+}
+/**
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
+ */
+export function buildSessionContext(entries, leafId, byId) {
+    const path = buildSessionPath(entries, leafId, byId);
+    const { thinkingLevel, model } = getSessionContextSettings(path);
+    const messages = buildContextEntries(entries, leafId, byId).flatMap(sessionEntryToContextMessages);
     return { messages, thinkingLevel, model };
 }
 /**
  * Compute the default session directory for a cwd.
- * Encodes cwd into a safe directory name under ~/.pi/agent/sessions/.
+ * Encodes cwd into a safe directory name under the mcpi state sessions directory.
  */
-export function getDefaultSessionDir(cwd, agentDir = getDefaultAgentDir()) {
-    const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
-    const sessionDir = join(agentDir, "sessions", safePath);
+function getDefaultSessionDirPath(cwd, agentDir) {
+    const resolvedCwd = resolvePath(cwd);
+    const resolvedSessionsDir = agentDir ? join(resolvePath(agentDir), "sessions") : getSessionsDir();
+    const safePath = `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+    return join(resolvedSessionsDir, safePath);
+}
+export function getDefaultSessionDir(cwd, agentDir) {
+    const sessionDir = getDefaultSessionDirPath(cwd, agentDir);
     if (!existsSync(sessionDir)) {
         mkdirSync(sessionDir, { recursive: true });
     }
     return sessionDir;
 }
+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;
+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) {
+    if (!line.trim())
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        // Skip malformed lines
+        return null;
+    }
+}
 /** Exported for testing */
 export function loadEntriesFromFile(filePath) {
-    if (!existsSync(filePath))
+    const resolvedFilePath = normalizePath(filePath);
+    if (!existsSync(resolvedFilePath))
         return [];
-    const content = readFileSync(filePath, "utf8");
     const entries = [];
-    const lines = content.trim().split("\n");
-    for (const line of lines) {
-        if (!line.trim())
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            entries.push(entry);
-        }
-        catch {
-            // Skip malformed lines
+    const fd = openSync(resolvedFilePath, "r");
+    try {
+        const decoder = new StringDecoder("utf8");
+        const buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE);
+        let pending = "";
+        while (true) {
+            const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            pending += decoder.write(buffer.subarray(0, bytesRead));
+            let lineStart = 0;
+            let newlineIndex = pending.indexOf("\n", lineStart);
+            while (newlineIndex !== -1) {
+                const entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex));
+                if (entry)
+                    entries.push(entry);
+                lineStart = newlineIndex + 1;
+                newlineIndex = pending.indexOf("\n", lineStart);
+            }
+            pending = pending.slice(lineStart);
         }
+        pending += decoder.end();
+        const finalEntry = parseSessionEntryLine(pending);
+        if (finalEntry)
+            entries.push(finalEntry);
+    }
+    finally {
+        closeSync(fd);
     }
     // Validate session header
     if (entries.length === 0)
@@ -244,34 +317,97 @@ export function loadEntriesFromFile(filePath) {
     }
     return entries;
 }
-function isValidSessionFile(filePath) {
+/**
+ * Inspect a physical line while searching for the first parsed session entry.
+ * Blank and malformed lines are skipped to match loadEntriesFromFile().
+ * Returns undefined to keep scanning, null for a parsed non-header entry, or the header.
+ */
+function parseSessionHeaderCandidate(line) {
+    if (!line.trim())
+        return undefined;
+    const entry = parseSessionEntryLine(line);
+    if (!entry)
+        return undefined;
+    if (entry.type !== "session" || typeof entry.id !== "string")
+        return null;
+    return entry;
+}
+function readSessionHeader(filePath) {
+    const fd = openSync(filePath, "r");
     try {
-        const fd = openSync(filePath, "r");
-        const buffer = Buffer.alloc(512);
-        const bytesRead = readSync(fd, buffer, 0, 512, 0);
+        const decoder = new StringDecoder("utf8");
+        const buffer = Buffer.allocUnsafe(SESSION_HEADER_READ_BUFFER_SIZE);
+        const lineChunks = [];
+        let scannedBytes = 0;
+        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;
+            }
+            scannedBytes += bytesRead;
+            const chunk = decoder.write(buffer.subarray(0, bytesRead));
+            let lineStart = 0;
+            let newlineIndex = chunk.indexOf("\n", lineStart);
+            while (newlineIndex !== -1) {
+                lineChunks.push(chunk.slice(lineStart, newlineIndex));
+                const header = parseSessionHeaderCandidate(lineChunks.join(""));
+                if (header !== undefined)
+                    return header;
+                lineChunks.length = 0;
+                lineStart = newlineIndex + 1;
+                newlineIndex = chunk.indexOf("\n", lineStart);
+            }
+            lineChunks.push(chunk.slice(lineStart));
+        }
+        // Probe for EOF so a final header without a newline is allowed when it ends
+        // exactly at the scan limit. Any additional byte exceeds the bounded scan.
+        const probe = Buffer.allocUnsafe(1);
+        if (readSync(fd, probe, 0, probe.length, null) === 0) {
+            lineChunks.push(decoder.end());
+            return parseSessionHeaderCandidate(lineChunks.join("")) ?? null;
+        }
+        throw new SessionHeaderScanLimitError(filePath);
+    }
+    finally {
         closeSync(fd);
-        const firstLine = buffer.toString("utf8", 0, bytesRead).split("\n")[0];
-        if (!firstLine)
-            return false;
-        const header = JSON.parse(firstLine);
-        return header.type === "session" && typeof header.id === "string";
+    }
+}
+function readSessionHeaderForDiscovery(filePath) {
+    try {
+        return readSessionHeader(filePath);
     }
     catch {
-        return false;
+        // Discovery is best-effort: unreadable or oversized files are not sessions,
+        // and one corrupt file must not prevent other sessions from being found.
+        return null;
     }
 }
+function getSessionHeaderCwd(header) {
+    const cwd = header.cwd;
+    return typeof cwd === "string" ? cwd : undefined;
+}
+function sessionCwdMatches(cwd, resolvedCwd) {
+    return cwd !== undefined && cwd !== "" && resolvePath(cwd) === resolvedCwd;
+}
 /** Exported for testing */
-export function findMostRecentSession(sessionDir) {
+export function findMostRecentSession(sessionDir, cwd) {
+    const resolvedSessionDir = normalizePath(sessionDir);
+    const resolvedCwd = cwd ? resolvePath(cwd) : undefined;
     try {
-        const files = readdirSync(sessionDir)
+        const files = readdirSync(resolvedSessionDir)
             .filter((f) => f.endsWith(".jsonl"))
-            .map((f) => join(sessionDir, f))
-            .filter(isValidSessionFile)
-            .map((path) => ({ path, mtime: statSync(path).mtime }))
+            .map((f) => join(resolvedSessionDir, f))
+            .map((path) => ({ path, header: readSessionHeaderForDiscovery(path) }))
+            .filter((file) => file.header !== null &&
+            (!resolvedCwd || sessionCwdMatches(getSessionHeaderCwd(file.header), resolvedCwd)))
+            .map(({ path }) => ({ path, mtime: statSync(path).mtime }))
             .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
         return files[0]?.path || null;
     }
     catch {
+        // Directory access and stat races make recent-session discovery unavailable.
         return null;
     }
 }
@@ -288,73 +424,53 @@ function extractTextContent(message) {
         .map((block) => block.text)
         .join(" ");
 }
-function getLastActivityTime(entries) {
-    let lastActivityTime;
-    for (const entry of entries) {
-        if (entry.type !== "message")
-            continue;
-        const message = entry.message;
-        if (!isMessageWithContent(message))
-            continue;
-        if (message.role !== "user" && message.role !== "assistant")
-            continue;
-        const msgTimestamp = message.timestamp;
-        if (typeof msgTimestamp === "number") {
-            lastActivityTime = Math.max(lastActivityTime ?? 0, msgTimestamp);
-            continue;
-        }
-        const entryTimestamp = entry.timestamp;
-        if (typeof entryTimestamp === "string") {
-            const t = new Date(entryTimestamp).getTime();
-            if (!Number.isNaN(t)) {
-                lastActivityTime = Math.max(lastActivityTime ?? 0, t);
-            }
-        }
-    }
-    return lastActivityTime;
-}
-function getSessionModifiedDate(entries, header, statsMtime) {
-    const lastActivityTime = getLastActivityTime(entries);
-    if (typeof lastActivityTime === "number" && lastActivityTime > 0) {
-        return new Date(lastActivityTime);
+function getMessageActivityTime(entry) {
+    const message = entry.message;
+    if (!isMessageWithContent(message))
+        return undefined;
+    if (message.role !== "user" && message.role !== "assistant")
+        return undefined;
+    const msgTimestamp = message.timestamp;
+    if (typeof msgTimestamp === "number") {
+        return msgTimestamp;
     }
-    const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : NaN;
-    return !Number.isNaN(headerTime) ? new Date(headerTime) : statsMtime;
+    const t = new Date(entry.timestamp).getTime();
+    return Number.isNaN(t) ? undefined : t;
 }
 async function buildSessionInfo(filePath) {
     try {
-        const content = await readFile(filePath, "utf8");
-        const entries = [];
-        const lines = content.trim().split("\n");
-        for (const line of lines) {
-            if (!line.trim())
-                continue;
-            try {
-                entries.push(JSON.parse(line));
-            }
-            catch {
-                // Skip malformed lines
-            }
-        }
-        if (entries.length === 0)
-            return null;
-        const header = entries[0];
-        if (header.type !== "session")
-            return null;
         const stats = await stat(filePath);
+        let header = null;
         let messageCount = 0;
         let firstMessage = "";
         const allMessages = [];
         let name;
-        for (const entry of entries) {
+        let lastActivityTime;
+        const rl = createInterface({
+            input: createReadStream(filePath, { encoding: "utf8" }),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const entry = parseSessionEntryLine(line);
+            if (!entry)
+                continue;
+            if (!header) {
+                if (entry.type !== "session")
+                    return null;
+                header = entry;
+                continue;
+            }
             // Extract session name (use latest, including explicit clears)
             if (entry.type === "session_info") {
-                const infoEntry = entry;
-                name = infoEntry.name?.trim() || undefined;
+                name = entry.name?.trim() || undefined;
             }
             if (entry.type !== "message")
                 continue;
             messageCount++;
+            const activityTime = getMessageActivityTime(entry);
+            if (typeof activityTime === "number") {
+                lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
+            }
             const message = entry.message;
             if (!isMessageWithContent(message))
                 continue;
@@ -368,9 +484,16 @@ async function buildSessionInfo(filePath) {
                 firstMessage = textContent;
             }
         }
+        if (!header)
+            return null;
         const cwd = typeof header.cwd === "string" ? header.cwd : "";
         const parentSessionPath = header.parentSession;
-        const modified = getSessionModifiedDate(entries, header, stats.mtime);
+        const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : NaN;
+        const modified = typeof lastActivityTime === "number" && lastActivityTime > 0
+            ? new Date(lastActivityTime)
+            : !Number.isNaN(headerTime)
+                ? new Date(headerTime)
+                : stats.mtime;
         return {
             path: filePath,
             id: header.id,
@@ -388,6 +511,40 @@ async function buildSessionInfo(filePath) {
         return null;
     }
 }
+const MAX_CONCURRENT_SESSION_INFO_LOADS = 10;
+async function buildSessionInfosWithConcurrency(files, onLoaded) {
+    const results = new Array(files.length).fill(null);
+    const inFlight = new Set();
+    let nextIndex = 0;
+    const startNext = () => {
+        const index = nextIndex++;
+        const file = files[index];
+        if (!file)
+            return;
+        let task;
+        task = buildSessionInfo(file)
+            .then((info) => {
+            results[index] = info;
+        })
+            .catch(() => {
+            results[index] = null;
+        })
+            .finally(() => {
+            inFlight.delete(task);
+            onLoaded();
+        });
+        inFlight.add(task);
+    };
+    while (nextIndex < files.length || inFlight.size > 0) {
+        while (nextIndex < files.length && inFlight.size < MAX_CONCURRENT_SESSION_INFO_LOADS) {
+            startNext();
+        }
+        if (inFlight.size > 0) {
+            await Promise.race(inFlight);
+        }
+    }
+    return results;
+}
 async function listSessionsFromDir(dir, onProgress, progressOffset = 0, progressTotal) {
     const sessions = [];
     if (!existsSync(dir)) {
@@ -398,12 +555,10 @@ async function listSessionsFromDir(dir, onProgress, progressOffset = 0, progress
         const files = dirEntries.filter((f) => f.endsWith(".jsonl")).map((f) => join(dir, f));
         const total = progressTotal ?? files.length;
         let loaded = 0;
-        const results = await Promise.all(files.map(async (file) => {
-            const info = await buildSessionInfo(file);
+        const results = await buildSessionInfosWithConcurrency(files, () => {
             loaded++;
             onProgress?.(progressOffset + loaded, total);
-            return info;
-        }));
+        });
         for (const info of results) {
             if (info) {
                 sessions.push(info);
@@ -438,29 +593,35 @@ export class SessionManager {
     labelsById = new Map();
     labelTimestampsById = new Map();
     leafId = null;
-    constructor(cwd, sessionDir, sessionFile, persist) {
-        this.cwd = cwd;
-        this.sessionDir = sessionDir;
+    constructor(cwd, sessionDir, sessionFile, persist, newSessionOptions, preloadedFileEntries) {
+        this.cwd = resolvePath(cwd);
+        this.sessionDir = normalizePath(sessionDir);
         this.persist = persist;
-        if (persist && sessionDir && !existsSync(sessionDir)) {
-            mkdirSync(sessionDir, { recursive: true });
+        if (persist && this.sessionDir && !existsSync(this.sessionDir)) {
+            mkdirSync(this.sessionDir, { recursive: true });
         }
         if (sessionFile) {
-            this.setSessionFile(sessionFile);
+            this._setSessionFile(sessionFile, preloadedFileEntries);
         }
         else {
-            this.newSession();
+            this.newSession(newSessionOptions);
         }
     }
     /** Switch to a different session file (used for resume and branching) */
     setSessionFile(sessionFile) {
-        this.sessionFile = resolve(sessionFile);
+        this._setSessionFile(sessionFile);
+    }
+    _setSessionFile(sessionFile, preloadedFileEntries) {
+        this.sessionFile = resolvePath(sessionFile);
         if (existsSync(this.sessionFile)) {
-            this.fileEntries = loadEntriesFromFile(this.sessionFile);
-            // If file was empty or corrupted (no valid header), truncate and start fresh
-            // to avoid appending messages without a session header (which breaks the session)
+            this.fileEntries = preloadedFileEntries ?? loadEntriesFromFile(this.sessionFile);
+            // If file was empty, initialize it with a valid session header. If it was
+            // non-empty but did not parse as an mcpi 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 ${APP_NAME} session: ${explicitPath}`);
+                }
                 this.newSession();
                 this.sessionFile = explicitPath;
                 this._rewriteFile();
@@ -482,6 +643,9 @@ export class SessionManager {
         }
     }
     newSession(options) {
+        if (options?.id !== undefined) {
+            assertValidSessionId(options.id);
+        }
         this.sessionId = options?.id ?? createSessionId();
         const timestamp = new Date().toISOString();
         const header = {
@@ -495,6 +659,7 @@ export class SessionManager {
         this.fileEntries = [header];
         this.byId.clear();
         this.labelsById.clear();
+        this.labelTimestampsById.clear();
         this.leafId = null;
         this.flushed = false;
         if (this.persist) {
@@ -528,8 +693,15 @@ export class SessionManager {
     _rewriteFile() {
         if (!this.persist || !this.sessionFile)
             return;
-        const content = `${this.fileEntries.map((e) => JSON.stringify(e)).join("\n")}\n`;
-        writeFileSync(this.sessionFile, content);
+        const fd = openSync(this.sessionFile, "w");
+        try {
+            for (const entry of this.fileEntries) {
+                writeFileSync(fd, `${JSON.stringify(entry)}\n`);
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
     }
     isPersisted() {
         return this.persist;
@@ -540,6 +712,9 @@ export class SessionManager {
     getSessionDir() {
         return this.sessionDir;
     }
+    usesDefaultSessionDir() {
+        return this.sessionDir === getDefaultSessionDirPath(this.cwd);
+    }
     getSessionId() {
         return this.sessionId;
     }
@@ -551,13 +726,24 @@ export class SessionManager {
             return;
         const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
         if (!hasAssistant) {
-            // Mark as not flushed so when assistant arrives, all entries get written
-            this.flushed = false;
+            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) {
-            for (const e of this.fileEntries) {
-                appendFileSync(this.sessionFile, `${JSON.stringify(e)}\n`);
+            const fd = openSync(this.sessionFile, "wx");
+            try {
+                for (const e of this.fileEntries) {
+                    writeFileSync(fd, `${JSON.stringify(e)}\n`);
+                }
+            }
+            finally {
+                closeSync(fd);
             }
             this.flushed = true;
         }
@@ -614,7 +800,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) {
+    appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook, usage) {
         const entry = {
             type: "compaction",
             id: generateId(this.byId),
@@ -624,6 +810,7 @@ export class SessionManager {
             firstKeptEntryId,
             tokensBefore,
             details,
+            usage,
             fromHook,
         };
         this._appendEntry(entry);
@@ -644,12 +831,13 @@ export class SessionManager {
     }
     /** Append a session info entry (e.g., display name). Returns entry id. */
     appendSessionInfo(name) {
+        const sanitizedName = name.replace(/[\r\n]+/g, " ").trim();
         const entry = {
             type: "session_info",
             id: generateId(this.byId),
             parentId: this.leafId,
             timestamp: new Date().toISOString(),
-            name: name.trim(),
+            name: sanitizedName,
         };
         this._appendEntry(entry);
         return entry.id;
@@ -757,11 +945,19 @@ export class SessionManager {
         const startId = fromId ?? this.leafId;
         let current = startId ? this.byId.get(startId) : undefined;
         while (current) {
-            path.unshift(current);
+            path.push(current);
             current = current.parentId ? this.byId.get(current.parentId) : undefined;
         }
+        path.reverse();
         return path;
     }
+    /**
+     * Build the active, compaction-aware entry list for context/rendering.
+     * Uses tree traversal from current leaf.
+     */
+    buildContextEntries() {
+        return buildContextEntries(this.getEntries(), this.leafId, this.byId);
+    }
     /**
      * Build the session context (what gets sent to the LLM).
      * Uses tree traversal from current leaf.
@@ -854,7 +1050,7 @@ export class SessionManager {
      * Same as branch(), but also appends a branch_summary entry that captures
      * context from the abandoned conversation path.
      */
-    branchWithSummary(branchFromId, summary, details, fromHook) {
+    branchWithSummary(branchFromId, summary, details, fromHook, usage) {
         if (branchFromId !== null && !this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
@@ -867,6 +1063,7 @@ export class SessionManager {
             fromId: branchFromId ?? "root",
             summary,
             details,
+            usage,
             fromHook,
         };
         this._appendEntry(entry);
@@ -883,8 +1080,17 @@ export class SessionManager {
         if (path.length === 0) {
             throw new Error(`Entry ${leafId} not found`);
         }
-        // Filter out LabelEntry from path - we'll recreate them from the resolved map
-        const pathWithoutLabels = path.filter((e) => e.type !== "label");
+        // Filter out LabelEntry from path - we'll recreate them from the resolved map.
+        // Because labels are real tree entries, later entries can be children of labels;
+        // removing labels requires re-chaining the retained path to avoid orphaned subtrees.
+        const pathWithoutLabels = [];
+        let pathParentId = null;
+        for (const entry of path) {
+            if (entry.type === "label")
+                continue;
+            pathWithoutLabels.push({ ...entry, parentId: pathParentId });
+            pathParentId = entry.id;
+        }
         const newSessionId = createSessionId();
         const timestamp = new Date().toISOString();
         const fileTimestamp = timestamp.replace(/[:.]/g, "-");
@@ -965,11 +1171,11 @@ export class SessionManager {
     /**
      * Create a new session.
      * @param cwd Working directory (stored in session header)
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.pi/agent/sessions/<encoded-cwd>/).
+     * @param sessionDir Optional session directory. If omitted, uses the mcpi state sessions directory.
      */
-    static create(cwd, sessionDir) {
-        const dir = sessionDir ?? getDefaultSessionDir(cwd);
-        return new SessionManager(cwd, dir, undefined, true);
+    static create(cwd, sessionDir, options) {
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(cwd);
+        return new SessionManager(cwd, dir, undefined, true, options);
     }
     /**
      * Open a specific session file.
@@ -978,30 +1184,45 @@ export class SessionManager {
      * @param cwdOverride Optional cwd override instead of the session header cwd.
      */
     static open(path, sessionDir, cwdOverride) {
-        // Extract cwd from session header if possible, otherwise use process.cwd()
-        const entries = loadEntriesFromFile(path);
-        const header = entries.find((e) => e.type === "session");
-        const cwd = cwdOverride ?? header?.cwd ?? process.cwd();
+        const resolvedPath = resolvePath(path);
+        let header = null;
+        let preloadedFileEntries;
+        if (cwdOverride === undefined && existsSync(resolvedPath)) {
+            try {
+                header = readSessionHeader(resolvedPath);
+            }
+            catch (error) {
+                if (!(error instanceof SessionHeaderScanLimitError))
+                    throw error;
+                // The bounded scan is only a discovery optimization. A full load remains
+                // authoritative for legacy files with very large headers or prefixes.
+                preloadedFileEntries = loadEntriesFromFile(resolvedPath);
+                const firstEntry = preloadedFileEntries[0];
+                header = firstEntry?.type === "session" ? firstEntry : null;
+            }
+        }
+        const cwd = cwdOverride ?? (header ? getSessionHeaderCwd(header) : undefined) ?? process.cwd();
         // If no sessionDir provided, derive from file's parent directory
-        const dir = sessionDir ?? resolve(path, "..");
-        return new SessionManager(cwd, dir, path, true);
+        const dir = sessionDir ? normalizePath(sessionDir) : resolve(resolvedPath, "..");
+        return new SessionManager(cwd, dir, resolvedPath, true, undefined, preloadedFileEntries);
     }
     /**
      * Continue the most recent session, or create new if none.
      * @param cwd Working directory
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.pi/agent/sessions/<encoded-cwd>/).
+     * @param sessionDir Optional session directory. If omitted, uses the mcpi state sessions directory.
      */
     static continueRecent(cwd, sessionDir) {
-        const dir = sessionDir ?? getDefaultSessionDir(cwd);
-        const mostRecent = findMostRecentSession(dir);
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(cwd);
+        const filterCwd = sessionDir !== undefined && dir !== getDefaultSessionDirPath(cwd);
+        const mostRecent = findMostRecentSession(dir, filterCwd ? cwd : undefined);
         if (mostRecent) {
             return new SessionManager(cwd, dir, mostRecent, true);
         }
         return new SessionManager(cwd, dir, undefined, true);
     }
     /** Create an in-memory session (no file persistence) */
-    static inMemory(cwd = process.cwd()) {
-        return new SessionManager(cwd, "", undefined, false);
+    static inMemory(cwd = process.cwd(), options) {
+        return new SessionManager(cwd, "", undefined, false, options);
     }
     /**
      * Fork a session from another project directory into the current project.
@@ -1010,21 +1231,26 @@ export class SessionManager {
      * @param targetCwd Target working directory (where the new session will be stored)
      * @param sessionDir Optional session directory. If omitted, uses default for targetCwd.
      */
-    static forkFrom(sourcePath, targetCwd, sessionDir) {
-        const sourceEntries = loadEntriesFromFile(sourcePath);
+    static forkFrom(sourcePath, targetCwd, sessionDir, options) {
+        const resolvedSourcePath = resolvePath(sourcePath);
+        const resolvedTargetCwd = resolvePath(targetCwd);
+        const sourceEntries = loadEntriesFromFile(resolvedSourcePath);
         if (sourceEntries.length === 0) {
-            throw new Error(`Cannot fork: source session file is empty or invalid: ${sourcePath}`);
+            throw new Error(`Cannot fork: source session file is empty or invalid: ${resolvedSourcePath}`);
         }
         const sourceHeader = sourceEntries.find((e) => e.type === "session");
         if (!sourceHeader) {
-            throw new Error(`Cannot fork: source session has no header: ${sourcePath}`);
+            throw new Error(`Cannot fork: source session has no header: ${resolvedSourcePath}`);
         }
-        const dir = sessionDir ?? getDefaultSessionDir(targetCwd);
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(resolvedTargetCwd);
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
         }
         // Create new session file with new ID but forked content
-        const newSessionId = createSessionId();
+        if (options?.id !== undefined) {
+            assertValidSessionId(options.id);
+        }
+        const newSessionId = options?.id ?? createSessionId();
         const timestamp = new Date().toISOString();
         const fileTimestamp = timestamp.replace(/[:.]/g, "-");
         const newSessionFile = join(dir, `${fileTimestamp}_${newSessionId}.jsonl`);
@@ -1034,42 +1260,49 @@ export class SessionManager {
             version: CURRENT_SESSION_VERSION,
             id: newSessionId,
             timestamp,
-            cwd: targetCwd,
-            parentSession: sourcePath,
+            cwd: resolvedTargetCwd,
+            parentSession: resolvedSourcePath,
         };
-        appendFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`);
+        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`);
             }
         }
-        return new SessionManager(targetCwd, dir, newSessionFile, true);
+        return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);
     }
     /**
      * List all sessions for a directory.
      * @param cwd Working directory (used to compute default session directory)
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.pi/agent/sessions/<encoded-cwd>/).
+     * @param sessionDir Optional session directory. If omitted, uses the mcpi state sessions directory.
      * @param onProgress Optional callback for progress updates (loaded, total)
      */
     static async list(cwd, sessionDir, onProgress) {
-        const dir = sessionDir ?? getDefaultSessionDir(cwd);
-        const sessions = await listSessionsFromDir(dir, onProgress);
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(cwd);
+        const filterCwd = sessionDir !== undefined && dir !== getDefaultSessionDirPath(cwd);
+        const resolvedCwd = resolvePath(cwd);
+        const sessions = (await listSessionsFromDir(dir, onProgress)).filter((session) => !filterCwd || sessionCwdMatches(session.cwd, resolvedCwd));
         sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
         return sessions;
     }
-    /**
-     * List all sessions across all project directories.
-     * @param onProgress Optional callback for progress updates (loaded, total)
-     */
-    static async listAll(onProgress) {
+    static async listAll(sessionDirOrOnProgress, onProgress) {
+        const customSessionDir = typeof sessionDirOrOnProgress === "string" ? normalizePath(sessionDirOrOnProgress) : undefined;
+        const progress = typeof sessionDirOrOnProgress === "function" ? sessionDirOrOnProgress : onProgress;
+        if (customSessionDir) {
+            const sessions = await listSessionsFromDir(customSessionDir, progress);
+            sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+            return sessions;
+        }
         const sessionsDir = getSessionsDir();
         try {
             if (!existsSync(sessionsDir)) {
                 return [];
             }
             const entries = await readdir(sessionsDir, { withFileTypes: true });
-            const dirs = entries.filter((e) => e.isDirectory()).map((e) => join(sessionsDir, e.name));
+            const dirs = entries
+                .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+                .map((entry) => join(sessionsDir, entry.name));
             // Count total files first for accurate progress
             let totalFiles = 0;
             const dirFiles = [];
@@ -1087,12 +1320,10 @@ export class SessionManager {
             let loaded = 0;
             const sessions = [];
             const allFiles = dirFiles.flat();
-            const results = await Promise.all(allFiles.map(async (file) => {
-                const info = await buildSessionInfo(file);
+            const results = await buildSessionInfosWithConcurrency(allFiles, () => {
                 loaded++;
-                onProgress?.(loaded, totalFiles);
-                return info;
-            }));
+                progress?.(loaded, totalFiles);
+            });
             for (const info of results) {
                 if (info) {
                     sessions.push(info);