@xopcai/xopc 0.0.29 → 0.0.31

package/dist/src/session/store.js

@@ -3,16 +3,21 @@ import { init_session_key, parseSessionKey } from "../routing/session-key.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { FILENAMES, init_paths, resolveSessionsDir } from "../config/paths.js";
+import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
+import { buildSessionContextForLlm, isTranscriptContextEntry, mergeLlmMessagesPreservingContextRows } from "./session-context-for-llm.js";
+import { buildTranscriptEnvelope, parseStoredTranscriptJson } from "./transcript-format.js";
 import { invalidateSessionSearchIndexCache } from "./search-index-cache.js";
 import { resolveSessionShardRelativePath } from "./shard-path.js";
 import "./types.js";
 import { SessionCompactor } from "../agent/memory/compaction.js";
 import { SlidingWindow } from "../agent/memory/window.js";
-import { cleanTrailingErrors, hasProblematicMessages } from "../agent/memory/message-sanitizer.js";
+import { normalizeCompactionCheckpointId } from "./compaction-checkpoints.js";
 import { basename, join } from "path";
 import { existsSync } from "fs";
-import { mkdir, readFile, readdir, stat, unlink, writeFile } from "fs/promises";
+import { copyFile, mkdir, readFile, readdir, stat, unlink } from "fs/promises";
+import { randomUUID } from "node:crypto";
 //#region src/session/store.ts
+init_write_file_atomic();
 init_paths();
 init_agent_scope();
 init_session_key();
@@ -20,6 +25,8 @@ init_logger();
 const log = createLogger("SessionStore");
 const INDEX_VERSION = "1.0";
 const DEFAULT_LIMIT = 50;
+/** Pre-compaction transcript snapshots per session file (same directory as `{safeKey}.json`). */
+const MAX_COMPACTION_CHECKPOINTS = 15;
 var SessionStore = class {
 	sessionsDir;
 	archiveDir;
@@ -29,6 +36,9 @@ var SessionStore = class {
 	indexDirty = false;
 	window;
 	compactor;
+	/** Serialize index + transcript mutations (reentrant for nested store calls). */
+	storeMutationChain = Promise.resolve();
+	storeMutationDepth = 0;
 	constructor(options, windowConfig, compactionConfig) {
 		const agentId = options.agentId ?? resolveDefaultAgentId(options.config);
 		this.sessionsDir = options.sessionsDir ?? resolveSessionsDir(options.config, agentId);
@@ -58,6 +68,77 @@ var SessionStore = class {
 			metaPath: join(dir, `${safeKey}.meta.json`)
 		};
 	}
+	invalidateIndexCache() {
+		this.indexCache = null;
+		this.indexCacheTime = 0;
+	}
+	/**
+	* Serialize mutations that touch the sessions index or transcript paths.
+	* Reentrant: nested calls (e.g. applyCompaction → saveMessages) run inline without deadlocking.
+	*/
+	async runStoreMutation(fn) {
+		if (this.storeMutationDepth > 0) return fn();
+		const run = this.storeMutationChain.then(async () => {
+			this.storeMutationDepth++;
+			try {
+				return await fn();
+			} finally {
+				this.storeMutationDepth--;
+			}
+		});
+		this.storeMutationChain = run.then(() => void 0).catch(() => void 0);
+		return run;
+	}
+	checkpointBasenamePrefix(safeKey) {
+		return `${safeKey}.compaction-backup.`;
+	}
+	async pruneCompactionCheckpoints(dir, safeKey) {
+		const prefix = this.checkpointBasenamePrefix(safeKey);
+		let names;
+		try {
+			names = await readdir(dir);
+		} catch {
+			return;
+		}
+		const candidates = names.filter((n) => n.startsWith(prefix) && n.endsWith(".json"));
+		if (candidates.length <= MAX_COMPACTION_CHECKPOINTS) return;
+		const stats = await Promise.all(candidates.map(async (name) => {
+			const p = join(dir, name);
+			try {
+				return {
+					p,
+					mtimeMs: (await stat(p)).mtimeMs
+				};
+			} catch {
+				return {
+					p,
+					mtimeMs: 0
+				};
+			}
+		}));
+		stats.sort((a, b) => a.mtimeMs - b.mtimeMs);
+		const removeCount = stats.length - MAX_COMPACTION_CHECKPOINTS;
+		for (let i = 0; i < removeCount; i++) try {
+			await unlink(stats[i].p);
+		} catch {}
+	}
+	/** Best-effort copy of the current transcript before compaction replaces it. */
+	async captureCompactionCheckpointIfExists(key, jsonPath) {
+		if (!existsSync(jsonPath)) return;
+		const safeKey = this.sanitizeKey(key);
+		const dir = join(this.sessionsDir, resolveSessionShardRelativePath(key));
+		const backupPath = join(dir, `${this.checkpointBasenamePrefix(safeKey)}${randomUUID()}.json`);
+		try {
+			await copyFile(jsonPath, backupPath);
+			await this.pruneCompactionCheckpoints(dir, safeKey);
+		} catch (err) {
+			log.warn({
+				err,
+				key,
+				jsonPath
+			}, "Compaction checkpoint copy failed (continuing)");
+		}
+	}
 	/**
 	* Get sessions by agent ID
 	*/
@@ -110,7 +191,7 @@ var SessionStore = class {
 	async saveIndex() {
 		if (!this.indexCache) return;
 		this.indexCache.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
-		await writeFile(this.indexFile, JSON.stringify(this.indexCache, null, 2));
+		await writeTextAtomic(this.indexFile, JSON.stringify(this.indexCache, null, 2));
 		this.indexDirty = false;
 		try {
 			const stats = await stat(this.indexFile);
@@ -120,36 +201,39 @@ var SessionStore = class {
 		}
 	}
 	async rebuildIndex() {
-		log.info("Rebuilding session index...");
-		const sessions = [];
-		const files = await this.scanSessionFiles();
-		for (const file of files) if (file.endsWith(".json") && !file.endsWith(".meta.json")) {
-			const stem = basename(file, ".json");
-			const key = this.fileNameToKey(stem);
+		return this.runStoreMutation(async () => {
+			log.info("Rebuilding session index...");
+			const sessions = [];
+			const files = await this.scanSessionFiles();
+			for (const file of files) if (file.endsWith(".json") && !file.endsWith(".meta.json")) {
+				const stem = basename(file, ".json");
+				if (stem.includes(".compaction-backup.")) continue;
+				const key = this.fileNameToKey(stem);
+				try {
+					const metadata = await this.scanSessionFile(key);
+					if (metadata) sessions.push(metadata);
+				} catch (err) {
+					log.warn({
+						key,
+						err
+					}, "Failed to scan session file");
+				}
+			}
+			this.indexCache = {
+				version: INDEX_VERSION,
+				lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+				sessions
+			};
+			await this.saveIndex();
 			try {
-				const metadata = await this.scanSessionFile(key);
-				if (metadata) sessions.push(metadata);
-			} catch (err) {
-				log.warn({
-					key,
-					err
-				}, "Failed to scan session file");
+				const stats = await stat(this.indexFile);
+				this.indexCacheTime = stats.mtime.getTime();
+			} catch {
+				this.indexCacheTime = Date.now();
 			}
-		}
-		this.indexCache = {
-			version: INDEX_VERSION,
-			lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
-			sessions
-		};
-		await this.saveIndex();
-		try {
-			const stats = await stat(this.indexFile);
-			this.indexCacheTime = stats.mtime.getTime();
-		} catch {
-			this.indexCacheTime = Date.now();
-		}
-		log.info({ count: sessions.length }, "Session index rebuilt");
-		return this.indexCache;
+			log.info({ count: sessions.length }, "Session index rebuilt");
+			return this.indexCache;
+		});
 	}
 	async scanSessionFiles() {
 		const out = [];
@@ -166,17 +250,25 @@ var SessionStore = class {
 				if (ent.isDirectory()) {
 					if (ent.name === "archive") continue;
 					await walk(childRel);
-				} else if (ent.name.endsWith(".json") && ent.name !== FILENAMES.SESSIONS_INDEX && !ent.name.endsWith(".meta.json")) out.push(childRel);
+				} else if (ent.name.endsWith(".json") && ent.name !== FILENAMES.SESSIONS_INDEX && !ent.name.endsWith(".meta.json") && !ent.name.includes(".compaction-backup.")) out.push(childRel);
 			}
 		};
 		await walk("");
 		return out;
 	}
 	async scanSessionFile(key) {
-		const messages = await this.loadMessages(key);
-		if (messages.length === 0) return null;
 		const { jsonPath } = this.sessionPathsForKey(key);
+		let raw;
+		try {
+			raw = await readFile(jsonPath, "utf-8");
+		} catch {
+			return null;
+		}
+		const { messages, envelope } = parseStoredTranscriptJson(raw);
+		if (messages.length === 0) return null;
 		const stats = await stat(jsonPath);
+		const sessionStartedAt = envelope?.createdAt ?? stats.birthtime.toISOString();
+		const lastInteractionAt = envelope?.updatedAt ?? stats.mtime.toISOString();
 		const { channel, chatId } = this.parseSessionKey(key);
 		const routing = this.extractRoutingFromKey(key, channel);
 		const isCronSession = channel === "cron";
@@ -193,6 +285,9 @@ var SessionStore = class {
 			compactedCount: 0,
 			sourceChannel: channel,
 			sourceChatId: chatId,
+			...envelope?.id ? { transcriptId: envelope.id } : {},
+			sessionStartedAt,
+			lastInteractionAt,
 			routing,
 			...isCronSession ? {
 				sessionType: "cron",
@@ -270,66 +365,100 @@ var SessionStore = class {
 			hasMore: offset + limit < total
 		};
 	}
-	async get(key) {
+	async get(key, options) {
 		const metadata = await this.getMetadata(key);
 		if (!metadata) return null;
 		const messages = await this.loadMessages(key);
+		let transcriptSummary;
+		if (options?.includeTranscriptSummary) {
+			const env = await this.loadTranscriptDocument(key);
+			if (env) transcriptSummary = {
+				id: env.id,
+				version: env.version,
+				createdAt: env.createdAt,
+				updatedAt: env.updatedAt,
+				compactionCount: env.compactions?.length ?? 0
+			};
+		}
+		let transcriptRows;
+		if (options?.includeTranscriptRows) transcriptRows = await this.loadTranscriptRows(key);
 		return {
 			...metadata,
-			messages: this.convertMessages(messages)
+			messages: this.convertMessages(messages),
+			...transcriptSummary ? { transcriptSummary } : {},
+			...transcriptRows !== void 0 ? { transcriptRows } : {}
 		};
 	}
+	/** Full on-disk transcript rows (LLM messages + optional `kind: 'context'`). */
+	async loadTranscriptRows(key) {
+		const { jsonPath } = this.sessionPathsForKey(key);
+		try {
+			return parseStoredTranscriptJson(await readFile(jsonPath, "utf-8")).rows;
+		} catch {
+			return [];
+		}
+	}
 	async getMetadata(key) {
-		const index = await this.loadIndex();
-		const metadata = index.sessions.find((s) => s.key === key);
+		const metadata = (await this.loadIndex()).sessions.find((s) => s.key === key);
 		if (!metadata) {
 			const scanned = await this.scanSessionFile(key);
-			if (scanned) {
-				index.sessions.push(scanned);
+			if (!scanned) return null;
+			await this.runStoreMutation(async () => {
+				this.invalidateIndexCache();
+				const fresh = await this.loadIndex();
+				if (fresh.sessions.some((s) => s.key === key)) return;
+				fresh.sessions.push(scanned);
 				this.indexDirty = true;
-				return scanned;
-			}
-			return null;
+				await this.saveIndex();
+				invalidateSessionSearchIndexCache();
+			});
+			return scanned;
 		}
 		return metadata;
 	}
 	async updateMetadata(key, updates) {
-		const index = await this.loadIndex();
-		const idx = index.sessions.findIndex((s) => s.key === key);
-		if (idx === -1) throw new Error(`Session not found: ${key}`);
-		index.sessions[idx] = {
-			...index.sessions[idx],
-			...updates,
-			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		this.indexDirty = true;
-		await this.saveIndex();
-		log.debug({
-			key,
-			updates
-		}, "Session metadata updated");
-	}
-	async delete(key) {
-		const index = await this.loadIndex();
-		const idx = index.sessions.findIndex((s) => s.key === key);
-		const primary = this.sessionPathsForKey(key);
-		for (const p of [primary.jsonPath]) try {
-			await unlink(p);
-		} catch (err) {
-			if (err.code !== "ENOENT") throw err;
-		}
-		for (const p of [primary.metaPath]) try {
-			await unlink(p);
-		} catch (err) {
-			if (err.code !== "ENOENT") throw err;
-		}
-		if (idx !== -1) {
-			index.sessions.splice(idx, 1);
+		return this.runStoreMutation(async () => {
+			this.invalidateIndexCache();
+			const index = await this.loadIndex();
+			const idx = index.sessions.findIndex((s) => s.key === key);
+			if (idx === -1) throw new Error(`Session not found: ${key}`);
+			index.sessions[idx] = {
+				...index.sessions[idx],
+				...updates,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
 			this.indexDirty = true;
 			await this.saveIndex();
-		}
-		log.info({ key }, "Session deleted");
-		return true;
+			log.debug({
+				key,
+				updates
+			}, "Session metadata updated");
+		});
+	}
+	async delete(key) {
+		return this.runStoreMutation(async () => {
+			this.invalidateIndexCache();
+			const index = await this.loadIndex();
+			const idx = index.sessions.findIndex((s) => s.key === key);
+			const primary = this.sessionPathsForKey(key);
+			for (const p of [primary.jsonPath]) try {
+				await unlink(p);
+			} catch (err) {
+				if (err.code !== "ENOENT") throw err;
+			}
+			for (const p of [primary.metaPath]) try {
+				await unlink(p);
+			} catch (err) {
+				if (err.code !== "ENOENT") throw err;
+			}
+			if (idx !== -1) {
+				index.sessions.splice(idx, 1);
+				this.indexDirty = true;
+				await this.saveIndex();
+			}
+			log.info({ key }, "Session deleted");
+			return true;
+		});
 	}
 	async deleteMany(keys) {
 		const success = [];
@@ -366,17 +495,7 @@ var SessionStore = class {
 		const primary = this.sessionPathsForKey(key);
 		const readAndNormalize = async (path) => {
 			try {
-				const data = await readFile(path, "utf-8");
-				const messages = JSON.parse(data);
-				if (hasProblematicMessages(messages)) {
-					const cleaned = cleanTrailingErrors(messages);
-					if (cleaned.length !== messages.length) log.info({
-						key,
-						original: messages.length,
-						cleaned: cleaned.length
-					}, "Cleaned problematic messages on load");
-					return cleaned;
-				}
+				const { messages } = parseStoredTranscriptJson(await readFile(path, "utf-8"));
 				return messages;
 			} catch {
 				return null;
@@ -392,6 +511,17 @@ var SessionStore = class {
 		return [];
 	}
 	/**
+	* Load the versioned transcript document (stable id, compaction history), or null if missing/invalid.
+	*/
+	async loadTranscriptDocument(key) {
+		const { jsonPath } = this.sessionPathsForKey(key);
+		try {
+			return parseStoredTranscriptJson(await readFile(jsonPath, "utf-8")).envelope;
+		} catch {
+			return null;
+		}
+	}
+	/**
 	* Find the most recent archived session file for a given key.
 	* Archived files have format: {safeKey}.{timestamp}.json
 	*/
@@ -400,7 +530,7 @@ var SessionStore = class {
 		const shardDir = join(this.archiveDir, resolveSessionShardRelativePath(sessionKey));
 		const scanDir = async (dir) => {
 			try {
-				const matchingFiles = (await readdir(dir)).filter((f) => f.startsWith(`${safeKey}.`) && f.endsWith(".json") && !f.endsWith(".meta.json")).sort().reverse();
+				const matchingFiles = (await readdir(dir)).filter((f) => f.startsWith(`${safeKey}.`) && f.endsWith(".json") && !f.endsWith(".meta.json") && !f.includes(".compaction-backup.")).sort().reverse();
 				if (matchingFiles.length === 0) return null;
 				return join(dir, matchingFiles[0]);
 			} catch {
@@ -411,10 +541,24 @@ var SessionStore = class {
 		if (inShard) return inShard;
 		return await scanDir(this.archiveDir);
 	}
-	async saveMessages(key, messages) {
+	/**
+	* Persist transcript JSON + merge session row into the index. Caller must hold {@link runStoreMutation} (or be nested under it).
+	* Transcript is stored as a versioned document (pi-style header) with stable {@link XopcSessionTranscriptV1.id}.
+	*/
+	async writeSessionTranscriptFromStoredRows(key, storedRows, options) {
 		const { dir, jsonPath } = this.sessionPathsForKey(key);
 		await mkdir(dir, { recursive: true });
-		await writeFile(jsonPath, JSON.stringify(messages, null, 2));
+		let previous = null;
+		try {
+			previous = parseStoredTranscriptJson(await readFile(jsonPath, "utf-8")).envelope;
+		} catch {}
+		const doc = buildTranscriptEnvelope({
+			storedRows,
+			previous,
+			appendCompaction: options?.appendCompaction
+		});
+		await writeTextAtomic(jsonPath, JSON.stringify(doc, null, 2));
+		const llmMessages = buildSessionContextForLlm(storedRows);
 		const index = await this.loadIndex();
 		const existingIdx = index.sessions.findIndex((s) => s.key === key);
 		const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -428,10 +572,13 @@ var SessionStore = class {
 				...prev,
 				sourceChannel: channel,
 				sourceChatId: chatId,
-				messageCount: messages.length,
-				estimatedTokens: this.estimateTokens(messages),
+				messageCount: llmMessages.length,
+				estimatedTokens: this.estimateTokens(llmMessages),
 				updatedAt: now,
 				lastAccessedAt: now,
+				transcriptId: doc.id,
+				sessionStartedAt: prev.sessionStartedAt ?? doc.createdAt,
+				lastInteractionAt: now,
 				routing: routing || prev.routing,
 				...isCronSession ? {
 					sessionType: "cron",
@@ -449,8 +596,8 @@ var SessionStore = class {
 				} : {},
 				stats: {
 					...prev.stats,
-					messageCount: messages.length,
-					tokenCount: this.estimateTokens(messages),
+					messageCount: llmMessages.length,
+					tokenCount: this.estimateTokens(llmMessages),
 					lastTurnAt: Date.now()
 				}
 			};
@@ -461,8 +608,11 @@ var SessionStore = class {
 			createdAt: now,
 			updatedAt: now,
 			lastAccessedAt: now,
-			messageCount: messages.length,
-			estimatedTokens: this.estimateTokens(messages),
+			transcriptId: doc.id,
+			sessionStartedAt: doc.createdAt,
+			lastInteractionAt: now,
+			messageCount: llmMessages.length,
+			estimatedTokens: this.estimateTokens(llmMessages),
 			compactedCount: 0,
 			sourceChannel: channel,
 			sourceChatId: chatId,
@@ -476,8 +626,8 @@ var SessionStore = class {
 				customData: { heartbeatTarget: chatId }
 			} : {},
 			stats: {
-				messageCount: messages.length,
-				tokenCount: this.estimateTokens(messages),
+				messageCount: llmMessages.length,
+				tokenCount: this.estimateTokens(llmMessages),
 				lastTurnAt: Date.now()
 			}
 		});
@@ -485,6 +635,43 @@ var SessionStore = class {
 		await this.saveIndex();
 		invalidateSessionSearchIndexCache();
 	}
+	async writeSessionTranscriptAndUpdateIndex(key, messages, options) {
+		const { jsonPath } = this.sessionPathsForKey(key);
+		let storedRows = messages;
+		try {
+			const parsed = parseStoredTranscriptJson(await readFile(jsonPath, "utf-8"));
+			if (parsed.rows.some((r) => isTranscriptContextEntry(r))) storedRows = mergeLlmMessagesPreservingContextRows(parsed.rows, messages);
+		} catch {}
+		await this.writeSessionTranscriptFromStoredRows(key, storedRows, options);
+	}
+	/**
+	* Append a persisted-only transcript row (`kind: 'context'`), visible on disk and in session search
+	* after stripping, but never returned from {@link loadMessages}.
+	*/
+	async appendTranscriptContextEntry(key, entry) {
+		return this.runStoreMutation(async () => {
+			this.invalidateIndexCache();
+			const { jsonPath } = this.sessionPathsForKey(key);
+			let rows = [];
+			try {
+				rows = parseStoredTranscriptJson(await readFile(jsonPath, "utf-8")).rows;
+			} catch {}
+			const row = {
+				kind: "context",
+				id: typeof entry.id === "string" ? entry.id : void 0,
+				text: typeof entry.text === "string" ? entry.text : void 0,
+				data: entry.data,
+				createdAt: entry.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+			};
+			await this.writeSessionTranscriptFromStoredRows(key, [...rows, row], {});
+		});
+	}
+	async saveMessages(key, messages) {
+		return this.runStoreMutation(async () => {
+			this.invalidateIndexCache();
+			await this.writeSessionTranscriptAndUpdateIndex(key, messages);
+		});
+	}
 	/**
 	* Get window stats for messages
 	*/
@@ -513,16 +700,27 @@ var SessionStore = class {
 	*/
 	async applyCompaction(key, messages, result) {
 		const compacted = this.compactor.applyCompaction(messages, result);
-		await this.saveMessages(key, compacted);
-		const metadata = await this.getMetadata(key);
-		if (metadata) await this.updateMetadata(key, { compactedCount: metadata.compactedCount + 1 });
-		log.info({
-			key,
-			tokensBefore: result.tokensBefore,
-			tokensAfter: result.tokensAfter,
-			keptMessages: compacted.length
-		}, "Session compacted");
-		return compacted;
+		return this.runStoreMutation(async () => {
+			this.invalidateIndexCache();
+			const { jsonPath } = this.sessionPathsForKey(key);
+			await this.captureCompactionCheckpointIfExists(key, jsonPath);
+			await this.writeSessionTranscriptAndUpdateIndex(key, compacted, { appendCompaction: {
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				summary: result.summary,
+				firstKeptIndex: result.firstKeptIndex,
+				tokensBefore: result.tokensBefore,
+				tokensAfter: result.tokensAfter
+			} });
+			const metadata = await this.getMetadata(key);
+			if (metadata) await this.updateMetadata(key, { compactedCount: metadata.compactedCount + 1 });
+			log.info({
+				key,
+				tokensBefore: result.tokensBefore,
+				tokensAfter: result.tokensAfter,
+				keptMessages: compacted.length
+			}, "Session compacted");
+			return compacted;
+		});
 	}
 	/**
 	* Compact session with LLM summary
@@ -545,6 +743,81 @@ var SessionStore = class {
 			lastCompactionAt: void 0
 		};
 	}
+	/**
+	* List pre-compaction transcript snapshots for a session (newest first).
+	*/
+	async listCompactionCheckpoints(key) {
+		const safeKey = this.sanitizeKey(key);
+		const dir = join(this.sessionsDir, resolveSessionShardRelativePath(key));
+		const prefix = this.checkpointBasenamePrefix(safeKey);
+		let names;
+		try {
+			names = await readdir(dir);
+		} catch {
+			return [];
+		}
+		const files = names.filter((n) => n.startsWith(prefix) && n.endsWith(".json"));
+		const valid = (await Promise.all(files.map(async (name) => {
+			const p = join(dir, name);
+			try {
+				const s = await stat(p);
+				const id = name.slice(prefix.length, -5);
+				if (!normalizeCompactionCheckpointId(id)) return null;
+				return {
+					id: normalizeCompactionCheckpointId(id),
+					sizeBytes: s.size,
+					modifiedAt: new Date(s.mtimeMs).toISOString()
+				};
+			} catch {
+				return null;
+			}
+		}))).filter((r) => r !== null);
+		valid.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+		return valid;
+	}
+	/**
+	* Metadata for a single compaction checkpoint file.
+	*/
+	async getCompactionCheckpointDetail(key, checkpointId) {
+		const id = normalizeCompactionCheckpointId(checkpointId);
+		if (!id) return null;
+		const safeKey = this.sanitizeKey(key);
+		const cpPath = join(join(this.sessionsDir, resolveSessionShardRelativePath(key)), `${this.checkpointBasenamePrefix(safeKey)}${id}.json`);
+		if (!existsSync(cpPath)) return null;
+		try {
+			const { messages } = parseStoredTranscriptJson(await readFile(cpPath, "utf-8"));
+			const s = await stat(cpPath);
+			return {
+				id,
+				sizeBytes: s.size,
+				modifiedAt: new Date(s.mtimeMs).toISOString(),
+				messageCount: messages.length
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Restore main transcript from a pre-compaction snapshot (then re-wrap + index sync).
+	* Does not delete the checkpoint file.
+	*/
+	async restoreCompactionCheckpoint(key, checkpointId) {
+		const id = normalizeCompactionCheckpointId(checkpointId);
+		if (!id) throw new Error("Invalid checkpoint id");
+		return this.runStoreMutation(async () => {
+			const safeKey = this.sanitizeKey(key);
+			const cpPath = join(join(this.sessionsDir, resolveSessionShardRelativePath(key)), `${this.checkpointBasenamePrefix(safeKey)}${id}.json`);
+			if (!existsSync(cpPath)) throw new Error(`Checkpoint not found: ${id}`);
+			const { jsonPath } = this.sessionPathsForKey(key);
+			await copyFile(cpPath, jsonPath);
+			const messages = await this.loadMessages(key);
+			await this.writeSessionTranscriptAndUpdateIndex(key, messages);
+			log.info({
+				key,
+				checkpointId: id
+			}, "Session transcript restored from compaction checkpoint");
+		});
+	}
 	/** Alias for delete */
 	async deleteSession(key) {
 		return this.delete(key);
@@ -568,15 +841,20 @@ var SessionStore = class {
 			return this.extractTextContent(m.content).toLowerCase().includes(keywordLower);
 		}));
 	}
+	/**
+	* JSON export includes API-shaped `messages` (LLM-only) plus `transcriptRows` (full on-disk order).
+	*/
 	async exportSession(key, format) {
 		const detail = await this.get(key);
 		if (!detail) throw new Error(`Session not found: ${key}`);
 		if (format === "json") {
+			const transcriptRows = await this.loadTranscriptRows(key);
 			const exportData = {
 				version: INDEX_VERSION,
 				exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				metadata: detail,
-				messages: detail.messages
+				messages: detail.messages,
+				transcriptRows
 			};
 			return JSON.stringify(exportData, null, 2);
 		} else {
@@ -707,45 +985,49 @@ var SessionStore = class {
 		});
 	}
 	async moveToArchive(key) {
-		const safeKey = this.sanitizeKey(key);
-		const primary = this.sessionPathsForKey(key);
-		const sourcePath = existsSync(primary.jsonPath) ? primary.jsonPath : null;
-		if (!sourcePath) return;
-		const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-		const archiveShard = join(this.archiveDir, resolveSessionShardRelativePath(key));
-		await mkdir(archiveShard, { recursive: true });
-		const targetPath = join(archiveShard, `${safeKey}.${timestamp}.json`);
-		try {
-			await writeFile(targetPath, await readFile(sourcePath, "utf-8"));
-			await unlink(sourcePath);
-			const metaSource = primary.metaPath;
-			const metaTarget = join(archiveShard, `${safeKey}.${timestamp}.meta.json`);
+		return this.runStoreMutation(async () => {
+			const safeKey = this.sanitizeKey(key);
+			const primary = this.sessionPathsForKey(key);
+			const sourcePath = existsSync(primary.jsonPath) ? primary.jsonPath : null;
+			if (!sourcePath) return;
+			const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+			const archiveShard = join(this.archiveDir, resolveSessionShardRelativePath(key));
+			await mkdir(archiveShard, { recursive: true });
+			const targetPath = join(archiveShard, `${safeKey}.${timestamp}.json`);
 			try {
-				await writeFile(metaTarget, await readFile(metaSource, "utf-8"));
-				await unlink(metaSource);
-			} catch {}
-		} catch (err) {
-			if (err.code !== "ENOENT") throw err;
-		}
+				await writeTextAtomic(targetPath, await readFile(sourcePath, "utf-8"));
+				await unlink(sourcePath);
+				const metaSource = primary.metaPath;
+				const metaTarget = join(archiveShard, `${safeKey}.${timestamp}.meta.json`);
+				try {
+					await writeTextAtomic(metaTarget, await readFile(metaSource, "utf-8"));
+					await unlink(metaSource);
+				} catch {}
+			} catch (err) {
+				if (err.code !== "ENOENT") throw err;
+			}
+		});
 	}
 	async moveFromArchive(key) {
-		const sourcePath = await this.findMostRecentArchive(key);
-		if (!sourcePath) return;
-		const primary = this.sessionPathsForKey(key);
-		await mkdir(primary.dir, { recursive: true });
-		const targetPath = primary.jsonPath;
-		try {
-			await writeFile(targetPath, await readFile(sourcePath, "utf-8"));
-			await unlink(sourcePath);
-			const metaSource = sourcePath.replace(".json", ".meta.json");
-			const metaTarget = primary.metaPath;
+		return this.runStoreMutation(async () => {
+			const sourcePath = await this.findMostRecentArchive(key);
+			if (!sourcePath) return;
+			const primary = this.sessionPathsForKey(key);
+			await mkdir(primary.dir, { recursive: true });
+			const targetPath = primary.jsonPath;
 			try {
-				await writeFile(metaTarget, await readFile(metaSource, "utf-8"));
-				await unlink(metaSource);
-			} catch {}
-		} catch (err) {
-			if (err.code !== "ENOENT") throw err;
-		}
+				await writeTextAtomic(targetPath, await readFile(sourcePath, "utf-8"));
+				await unlink(sourcePath);
+				const metaSource = sourcePath.replace(".json", ".meta.json");
+				const metaTarget = primary.metaPath;
+				try {
+					await writeTextAtomic(metaTarget, await readFile(metaSource, "utf-8"));
+					await unlink(metaSource);
+				} catch {}
+			} catch (err) {
+				if (err.code !== "ENOENT") throw err;
+			}
+		});
 	}
 };
 //#endregion