@myagentroam/agent 0.9.116 → 0.9.117

package/dist/session/jsonl-store.js

@@ -7,6 +7,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { MarAgentError } from '../error.js';
 import { todoItemsFromSnapshot } from '../tools/todo.js';
 import { contextGcBaseFromRecords, contextGcBaseSequence, contextGcMinimumUsageGrowth, contextGcSourceProjectionHash, latestValidContextGcCheckpoint, normalizeContextGcReplacements, parseContextGcCheckpoint, sameContextGcBase, validateContextGcCheckpoint } from './context-gc-checkpoint.js';
+import { beginSessionStorageTransaction, isUnjournaledTransactionFile, recoverSessionStorageTransaction } from './transaction-recovery.js';
 const MAX_SEGMENT_BYTES = 16 * 1024 * 1024;
 const REVERSE_READ_CHUNK_BYTES = 64 * 1024;
 const MAX_INPUT_IMAGES = 5;
@@ -15,6 +16,7 @@ const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
 const MAX_CONTEXTUAL_WORLD_STATE_BYTES = 8 * 1024 * 1024;
 const CONTEXTUAL_WORLD_STATE_FILE = 'context-world-state.json';
 const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+/** SDK-owned JSONL history with per-HOME in-process sharing and cross-process file locks. */
 export class JsonlSessionStore {
     static #instances = new Map();
     static #opening = new Map();
@@ -47,17 +49,104 @@ export class JsonlSessionStore {
             JsonlSessionStore.#opening.delete(root);
         }
     }
+    /** Create a missing index only without Session directories; recover journals and marked creations. */
     static async #openExclusive(root) {
-        await mkdir(join(root, 'sessions'), { recursive: true });
-        let index = { version: 1, revision: 0, sessions: [] };
+        const directory = join(root, 'sessions');
+        const path = join(directory, 'index.json');
+        await mkdir(directory, { recursive: true });
+        const release = await acquireFileLock(join(directory, 'index.lock'));
+        let index;
         try {
-            index = JSON.parse(await readFile(join(root, 'sessions', 'index.json'), 'utf8'));
+            const disk = await readSessionIndex(path);
+            if (disk)
+                index = disk;
+            else {
+                const entries = await readdir(directory, { withFileTypes: true });
+                if (entries.some((entry) => entry.isDirectory()))
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+                index = { version: 1, revision: 0, sessions: [] };
+                await persistSessionIndex(path, index);
+            }
         }
-        catch {
-            // A missing index starts empty; JSONL remains authoritative for explicit session reads.
+        finally {
+            await release();
+        }
+        for (const session of index.sessions) {
+            const directory = join(root, 'sessions', session.id);
+            let names;
+            try {
+                names = await readdir(directory);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            if (!names.includes('storage-transaction.json') &&
+                !names.some(isUnjournaledTransactionFile) &&
+                !names.some((name) => /^context-world-state\.json\.\d+\.[0-9a-f-]+\.(?:rollback|clear)-backup$/u.test(name)))
+                continue;
+            let releaseSession;
+            try {
+                releaseSession = await acquireFileLock(join(directory, 'lock'), 'Session already has a writer.', 0);
+            }
+            catch (error) {
+                if (error instanceof MarAgentError && error.code === 'MAR_AGENT_SESSION_LOCKED')
+                    continue;
+                throw error;
+            }
+            try {
+                // The index may have changed while waiting for the Session lock.
+                const latest = await readSessionIndex(path);
+                const current = latest?.sessions.find((item) => item.id === session.id);
+                if (!current)
+                    continue;
+                await recoverSessionStorageTransaction(directory, current.storageTransactionId);
+                await recoverContextualWorldStateTransactions(root, current);
+            }
+            finally {
+                await releaseSession();
+            }
+        }
+        // A creation marker distinguishes our unpublished directories from unrelated files.
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/iu.test(entry.name))
+                continue;
+            const candidate = join(directory, entry.name);
+            const marker = join(candidate, 'publication-pending');
+            try {
+                if (!(await lstat(marker)).isFile())
+                    continue;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            let releaseSession;
+            try {
+                releaseSession = await acquireFileLock(join(candidate, 'lock'), 'Session already has a writer.', 0);
+            }
+            catch (error) {
+                if (error instanceof MarAgentError && error.code === 'MAR_AGENT_SESSION_LOCKED')
+                    continue;
+                throw error;
+            }
+            let unpublished = false;
+            try {
+                const latest = await readSessionIndex(path);
+                if (!latest)
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+                unpublished = !latest.sessions.some((session) => session.id === entry.name);
+                if (!unpublished)
+                    await rm(marker, { force: true });
+            }
+            finally {
+                await releaseSession();
+            }
+            if (unpublished)
+                await rm(candidate, { recursive: true, force: true });
         }
-        for (const session of index.sessions)
-            await recoverContextualWorldStateTransactions(root, session);
         return {
             root,
             index,
@@ -65,60 +154,103 @@ export class JsonlSessionStore {
             references: 1,
             closed: false,
             indexDirty: false,
+            dirtySessionVersions: new Map(),
+            pendingPublishIds: new Set(),
             segments: new Map()
         };
     }
-    async #saveIndex(deletedIds) {
+    /** Merge dirty metadata with disk membership; only createdIds publish locally new entries. */
+    async #saveIndex(deletedIds, createdIds = []) {
         const release = await acquireFileLock(join(this.#shared.root, 'sessions', 'index.lock'));
         const path = join(this.#shared.root, 'sessions', 'index.json');
-        const temporary = `${path}.${randomUUID()}.tmp`;
         try {
-            let disk = { version: 1, revision: 0, sessions: [] };
-            try {
-                disk = JSON.parse(await readFile(path, 'utf8'));
-            }
-            catch {
-                // The first index transaction starts from an empty disk snapshot.
-            }
+            const disk = await readSessionIndex(path);
+            if (!disk)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+            const dirty = new Map(this.#shared.dirtySessionVersions);
             const sessions = new Map(disk.sessions.map((session) => [session.id, session]));
+            const created = new Set(createdIds);
             for (const session of this.#shared.index.sessions) {
                 const current = sessions.get(session.id);
-                if (!current || current.lastActivityAt <= session.lastActivityAt)
-                    sessions.set(session.id, session);
+                // Disk membership is authoritative: a stale in-memory snapshot cannot revive a deletion.
+                if (created.has(session.id) || (current && dirty.has(session.id)))
+                    sessions.set(session.id, structuredClone(session));
             }
             for (const deletedId of typeof deletedIds === 'string' ? [deletedIds] : (deletedIds ?? []))
                 sessions.delete(deletedId);
-            this.#shared.index = {
+            const updated = {
                 version: 1,
                 revision: Math.max(disk.revision, this.#shared.index.revision) + 1,
                 sessions: [...sessions.values()]
             };
-            await writeFile(temporary, JSON.stringify(this.#shared.index), { mode: 0o600 });
-            await rename(temporary, path);
-            this.#shared.indexDirty = false;
+            await persistSessionIndex(path, updated);
+            for (const [id, version] of dirty) {
+                // A different creation still needs its own index transaction to publish its directory.
+                if (this.#shared.pendingPublishIds.has(id) && !created.has(id))
+                    continue;
+                if (this.#shared.dirtySessionVersions.get(id) === version)
+                    this.#shared.dirtySessionVersions.delete(id);
+            }
+            for (const id of created)
+                this.#shared.pendingPublishIds.delete(id);
+            const pending = this.#shared.index.sessions.filter((session) => this.#shared.dirtySessionVersions.has(session.id) &&
+                (sessions.has(session.id) || this.#shared.pendingPublishIds.has(session.id)));
+            const replacements = new Map(pending.map((session) => [session.id, session]));
+            const published = new Set(updated.sessions.map((session) => session.id));
+            this.#shared.index = {
+                ...updated,
+                sessions: [
+                    ...updated.sessions.map((session) => replacements.get(session.id) ?? session),
+                    ...pending.filter((session) => !published.has(session.id))
+                ]
+            };
+            this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
         }
         finally {
-            await rm(temporary, { force: true });
             await release();
         }
     }
     async #refreshIndex() {
-        try {
-            const disk = JSON.parse(await readFile(join(this.#shared.root, 'sessions', 'index.json'), 'utf8'));
-            if (disk.revision <= this.#shared.index.revision)
-                return;
-            const local = new Map(this.#shared.index.sessions.map((session) => [session.id, session]));
-            for (const session of disk.sessions) {
+        const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json'));
+        if (!disk)
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+        // A local unflushed revision may exceed another writer's committed revision.
+        // Always refresh membership from disk, then overlay only our pending changes.
+        const local = new Map(this.#shared.index.sessions.map((session) => [session.id, session]));
+        const published = new Set(disk.sessions.map((session) => session.id));
+        this.#shared.index = {
+            ...disk,
+            revision: this.#shared.indexDirty || this.#shared.pendingPublishIds.size > 0
+                ? Math.max(disk.revision, this.#shared.index.revision)
+                : disk.revision,
+            sessions: disk.sessions
+                .map((session) => {
                 const current = local.get(session.id);
-                if (!current || current.lastActivityAt < session.lastActivityAt)
-                    local.set(session.id, session);
-            }
-            this.#shared.index = { ...disk, sessions: [...local.values()] };
+                return current && this.#shared.dirtySessionVersions.has(session.id) ? current : session;
+            })
+                .concat(this.#shared.index.sessions.filter((session) => this.#shared.pendingPublishIds.has(session.id) && !published.has(session.id)))
+        };
+    }
+    /** Hold the new Session lock and mark its directory until JSONL and index publication finish. */
+    async #beginUnpublishedSession(sessionId) {
+        const directory = join(this.#shared.root, 'sessions', sessionId);
+        await mkdir(directory);
+        const release = await acquireFileLock(join(directory, 'lock'), 'Session already has a writer.', 0);
+        try {
+            await writeFile(join(directory, 'publication-pending'), '1', {
+                mode: 0o600,
+                flag: 'wx',
+                flush: true
+            });
         }
-        catch {
-            // A concurrent atomic replace can only leave the previous valid in-memory snapshot visible.
+        catch (error) {
+            await release();
+            await rm(directory, { recursive: true, force: true });
+            throw error;
         }
+        return { directory, release };
     }
+    /** Append the durable creation record before making this Session visible in the index. */
     async createSession(input) {
         this.#assertOpen();
         const id = randomUUID();
@@ -135,24 +267,66 @@ export class JsonlSessionStore {
             resume: { version: 1, todoRevision: 0 },
             segments: []
         };
-        await mkdir(join(this.#shared.root, 'sessions', id), { recursive: true });
+        const publication = await this.#beginUnpublishedSession(id);
         this.#shared.segments.set(id, 1);
-        this.#shared.index = {
-            version: 1,
-            revision: this.#shared.index.revision + 1,
-            sessions: [meta, ...this.#shared.index.sessions]
-        };
-        await this.#saveIndex();
-        await this.append(id, {
-            type: 'session.created',
-            payload: {
-                title: meta.title,
-                workspace: meta.workspace,
-                automaticTitle: input.title === undefined,
-                source: meta.source
+        this.#shared.pendingSessions.set(id, meta);
+        let discard = false;
+        try {
+            try {
+                await this.append(id, {
+                    type: 'session.created',
+                    payload: {
+                        title: meta.title,
+                        workspace: meta.workspace,
+                        automaticTitle: input.title === undefined,
+                        source: meta.source
+                    }
+                });
             }
-        });
-        return meta;
+            catch (error) {
+                this.#shared.pendingSessions.delete(id);
+                this.#shared.segments.delete(id);
+                discard = true;
+                throw error;
+            }
+            this.#shared.pendingSessions.delete(id);
+            this.#shared.index.sessions.unshift(meta);
+            this.#shared.pendingPublishIds.add(id);
+            this.#markIndexDirty(id);
+            try {
+                await this.#saveIndex(undefined, [id]);
+            }
+            catch (error) {
+                // A failed lock release can follow a committed index rename; do not unpublish that Session.
+                // If the index cannot be read, leave the disk marker for recovery and keep the original error.
+                const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json')).catch(() => undefined);
+                if (disk?.sessions.some((session) => session.id === id)) {
+                    this.#shared.pendingPublishIds.delete(id);
+                    this.#shared.dirtySessionVersions.delete(id);
+                    this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
+                }
+                else {
+                    // Keep the marker until disk membership can be checked during recovery.
+                    this.#shared.index.sessions = this.#shared.index.sessions.filter((item) => item.id !== id);
+                    this.#shared.segments.delete(id);
+                    this.#shared.pendingPublishIds.delete(id);
+                    this.#shared.dirtySessionVersions.delete(id);
+                    this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
+                    throw error;
+                }
+            }
+            await rm(join(publication.directory, 'publication-pending'), { force: true });
+            return meta;
+        }
+        finally {
+            try {
+                await publication.release();
+            }
+            finally {
+                if (discard)
+                    await rm(publication.directory, { recursive: true, force: true });
+            }
+        }
     }
     sessionDirectory(sessionId) {
         this.#assertOpen();
@@ -212,6 +386,7 @@ export class JsonlSessionStore {
             await rm(temporary, { force: true });
         }
     }
+    /** Mark each image pending before publication; turn.user or lease recovery resolves ownership. */
     async persistInputImages(sessionId, images) {
         this.#assertOpen();
         if (images.length === 0)
@@ -221,6 +396,7 @@ export class JsonlSessionStore {
         const directory = join(this.sessionDirectory(sessionId), 'input_images');
         await mkdir(directory, { recursive: true, mode: 0o700 });
         const written = [];
+        const pending = [];
         let temporary;
         let totalBytes = 0;
         try {
@@ -244,6 +420,9 @@ export class JsonlSessionStore {
                 finally {
                     await handle.close();
                 }
+                const marker = join(directory, `.${fileName}.pending`);
+                await writeFile(marker, '', { mode: 0o600, flag: 'wx', flush: true });
+                pending.push(marker);
                 await rename(temporary, join(directory, fileName));
                 temporary = undefined;
                 written.push(fileName);
@@ -260,6 +439,7 @@ export class JsonlSessionStore {
         catch (error) {
             if (temporary !== undefined)
                 await rm(temporary, { force: true }).catch(() => undefined);
+            await Promise.all(pending.map((marker) => rm(marker, { force: true })));
             await Promise.all(written.map((fileName) => rm(join(directory, fileName), { force: true }).catch(() => undefined)));
             throw error;
         }
@@ -309,13 +489,6 @@ export class JsonlSessionStore {
             dataBase64: data.toString('base64')
         };
     }
-    async removeInputImages(sessionId, images) {
-        this.#assertOpen();
-        const directory = join(this.sessionDirectory(sessionId), 'input_images');
-        await Promise.all(images.flatMap((image) => validInputImageFileName(image.fileName)
-            ? [rm(join(directory, image.fileName), { force: true })]
-            : []));
-    }
     async forkSession(sourceSessionId, input) {
         this.#assertOpen();
         const release = await this.acquireSessionLease(sourceSessionId);
@@ -342,9 +515,10 @@ export class JsonlSessionStore {
                 resume: { version: 1, todoRevision: 0 },
                 segments: []
             };
-            await mkdir(join(this.#shared.root, 'sessions', target.id), { recursive: true });
+            const publication = await this.#beginUnpublishedSession(target.id);
             this.#shared.segments.set(target.id, 1);
             this.#shared.pendingSessions.set(target.id, target);
+            let discard = false;
             try {
                 await this.append(target.id, {
                     type: 'session.created',
@@ -376,8 +550,10 @@ export class JsonlSessionStore {
                     revision: this.#shared.index.revision + 1,
                     sessions: [target, ...this.#shared.index.sessions]
                 };
-                this.#shared.indexDirty = true;
-                await this.#saveIndex();
+                this.#shared.pendingPublishIds.add(target.id);
+                this.#markIndexDirty(target.id);
+                await this.#saveIndex(undefined, [target.id]);
+                await rm(join(publication.directory, 'publication-pending'), { force: true });
                 return {
                     id: target.id,
                     title: target.title,
@@ -389,25 +565,43 @@ export class JsonlSessionStore {
             }
             catch (error) {
                 this.#shared.pendingSessions.delete(target.id);
+                const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json'));
+                if (disk?.sessions.some((session) => session.id === target.id))
+                    return {
+                        id: target.id,
+                        title: target.title,
+                        workspace: target.workspace,
+                        createdAt: target.createdAt,
+                        lastActivityAt: target.createdAt,
+                        source: target.source
+                    };
                 const publishedIndex = this.#shared.index.sessions.findIndex((item) => item.id === target.id);
                 if (publishedIndex >= 0) {
                     this.#shared.index.sessions.splice(publishedIndex, 1);
                     this.#shared.index.revision++;
-                    this.#shared.indexDirty = true;
-                    await this.#saveIndex([target.id]).catch(() => undefined);
+                    this.#shared.pendingPublishIds.delete(target.id);
+                    this.#shared.dirtySessionVersions.delete(target.id);
+                    this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
                 }
                 this.#shared.segments.delete(target.id);
-                await rm(join(this.#shared.root, 'sessions', target.id), {
-                    recursive: true,
-                    force: true
-                }).catch(() => undefined);
+                discard = true;
                 throw error;
             }
+            finally {
+                try {
+                    await publication.release();
+                }
+                finally {
+                    if (discard)
+                        await rm(publication.directory, { recursive: true, force: true });
+                }
+            }
         }
         finally {
             await release();
         }
     }
+    /** Replace history under a journal; the indexed transaction ID decides the commit side. */
     async rollbackSession(sessionId, input) {
         this.#assertOpen();
         const release = await this.acquireSessionLease(sessionId);
@@ -442,9 +636,21 @@ export class JsonlSessionStore {
                 path,
                 backup: `${path}.${transactionId}.rollback-backup`
             }));
+            const transaction = {
+                version: 1,
+                id: transactionId,
+                kind: 'rollback',
+                originalSegments: originalPaths.map((path) => basename(path)),
+                stagedSegments: staged.files.map((item) => ({
+                    path: basename(item.path),
+                    temporary: basename(item.temporaryPath)
+                })),
+                sidecarBackup: basename(contextualWorldStateBackup)
+            };
             const installedPaths = [];
             let committed = false;
             try {
+                await beginSessionStorageTransaction(this.sessionDirectory(sessionId), transaction);
                 contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(generatedImageFileNames(retained)), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(inputImageReferencesFromRecords(retained).map((image) => image.fileName)), transactionId);
@@ -459,21 +665,16 @@ export class JsonlSessionStore {
                 meta.title = retainedSessionTitle(retained, meta.title);
                 meta.lastActivityAt = completedAt;
                 meta.nextSequence = targetNextSequence;
+                meta.storageTransactionId = transactionId;
                 meta.automaticTitlePending = state.automaticTitlePending;
                 meta.resume = state.resume;
                 meta.segments = staged.segments;
                 this.#shared.segments.set(sessionId, staged.segments.at(-1)?.number ?? 1);
                 this.#shared.index.revision++;
-                this.#shared.indexDirty = true;
+                this.#markIndexDirty(sessionId);
                 await this.#saveIndex();
                 committed = true;
-                if (contextualWorldStateStaged)
-                    await rm(contextualWorldStateBackup, { force: true });
-                await Promise.all([
-                    ...backups.map((item) => rm(item.backup, { force: true }).catch(() => undefined)),
-                    ...generatedTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined)),
-                    ...inputTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined))
-                ]).catch(() => undefined);
+                await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), transactionId);
                 return {
                     id: meta.id,
                     title: meta.title,
@@ -484,6 +685,14 @@ export class JsonlSessionStore {
                 };
             }
             catch (error) {
+                if (!committed) {
+                    committed = await this.#storageTransactionCommitted(sessionId, transactionId);
+                    if (committed) {
+                        this.#shared.dirtySessionVersions.delete(sessionId);
+                        this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
+                        await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), transactionId);
+                    }
+                }
                 if (!committed) {
                     await Promise.all(installedPaths.map((path) => rm(path, { force: true }))).catch(() => undefined);
                     await restoreRenamedFiles(backups.map((item) => ({ from: item.backup, to: item.path })));
@@ -498,7 +707,8 @@ export class JsonlSessionStore {
                         this.#shared.segments.delete(sessionId);
                     else
                         this.#shared.segments.set(sessionId, originalSegment);
-                    this.#shared.indexDirty = true;
+                    this.#markIndexDirty(sessionId);
+                    await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), originalMeta.storageTransactionId);
                 }
                 throw error;
             }
@@ -526,6 +736,7 @@ export class JsonlSessionStore {
         });
         meta.title = normalized;
     }
+    /** Reset history with the same recovery journal while preserving the Session identity. */
     async clearSession(sessionId) {
         this.#assertOpen();
         const release = await this.acquireSessionLease(sessionId);
@@ -568,9 +779,21 @@ export class JsonlSessionStore {
                 path,
                 backup: `${path}.${transactionId}.clear-backup`
             }));
+            const transaction = {
+                version: 1,
+                id: transactionId,
+                kind: 'clear',
+                originalSegments: originalPaths.map((path) => basename(path)),
+                stagedSegments: staged.files.map((item) => ({
+                    path: basename(item.path),
+                    temporary: basename(item.temporaryPath)
+                })),
+                sidecarBackup: basename(contextualWorldStateBackup)
+            };
             const installedPaths = [];
             let committed = false;
             try {
+                await beginSessionStorageTransaction(this.sessionDirectory(sessionId), transaction);
                 contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(), transactionId);
@@ -582,20 +805,15 @@ export class JsonlSessionStore {
                 }
                 meta.lastActivityAt = clearedAt;
                 meta.nextSequence = 2;
+                meta.storageTransactionId = transactionId;
                 meta.resume = { version: 1, todoRevision: 0 };
                 meta.segments = staged.segments;
                 this.#shared.segments.set(sessionId, 1);
                 this.#shared.index.revision++;
-                this.#shared.indexDirty = true;
+                this.#markIndexDirty(sessionId);
                 await this.#saveIndex();
                 committed = true;
-                if (contextualWorldStateStaged)
-                    await rm(contextualWorldStateBackup, { force: true });
-                await Promise.all([
-                    ...backups.map((item) => rm(item.backup, { force: true }).catch(() => undefined)),
-                    ...generatedTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined)),
-                    ...inputTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined))
-                ]).catch(() => undefined);
+                await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), transactionId);
                 return {
                     id: meta.id,
                     title: meta.title,
@@ -606,6 +824,14 @@ export class JsonlSessionStore {
                 };
             }
             catch (error) {
+                if (!committed) {
+                    committed = await this.#storageTransactionCommitted(sessionId, transactionId);
+                    if (committed) {
+                        this.#shared.dirtySessionVersions.delete(sessionId);
+                        this.#shared.indexDirty = this.#shared.dirtySessionVersions.size > 0;
+                        await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), transactionId);
+                    }
+                }
                 if (!committed) {
                     await Promise.all(installedPaths.map((path) => rm(path, { force: true }))).catch(() => undefined);
                     await restoreRenamedFiles(backups.map((item) => ({ from: item.backup, to: item.path })));
@@ -620,7 +846,8 @@ export class JsonlSessionStore {
                         this.#shared.segments.delete(sessionId);
                     else
                         this.#shared.segments.set(sessionId, originalSegment);
-                    this.#shared.indexDirty = true;
+                    this.#markIndexDirty(sessionId);
+                    await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), originalMeta.storageTransactionId);
                 }
                 throw error;
             }
@@ -657,7 +884,7 @@ export class JsonlSessionStore {
         const record = {
             schemaVersion: 1,
             recordId: randomUUID(),
-            sequence: meta.nextSequence++,
+            sequence: meta.nextSequence,
             timestamp: input.timestamp ?? new Date().toISOString(),
             sessionId,
             ...(input.executionId ? { executionId: input.executionId } : {}),
@@ -681,12 +908,28 @@ export class JsonlSessionStore {
         }
         const handle = await open(path, 'a', 0o600);
         try {
-            await handle.write(serialized);
+            const bytes = Buffer.from(serialized);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+                if (bytesWritten === 0)
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session append is incomplete.');
+                offset += bytesWritten;
+            }
             await handle.sync();
         }
         finally {
             await handle.close();
         }
+        meta.nextSequence++;
+        if (record.type === 'turn.user' &&
+            isObject(record.payload) &&
+            Array.isArray(record.payload.images))
+            for (const image of record.payload.images)
+                if (isObject(image) &&
+                    typeof image.fileName === 'string' &&
+                    validInputImageFileName(image.fileName))
+                    await rm(join(this.sessionDirectory(sessionId), 'input_images', `.${image.fileName}.pending`), { force: true }).catch(() => undefined);
         const segmentMetadata = meta.segments ?? (meta.segments = []);
         const known = segmentMetadata.find((item) => item.number === segment);
         if (known) {
@@ -704,7 +947,7 @@ export class JsonlSessionStore {
         this.#applyRecordToResumeIndex(meta, record);
         if (published) {
             this.#shared.index.revision++;
-            this.#shared.indexDirty = true;
+            this.#markIndexDirty(sessionId);
         }
         return record;
     }
@@ -760,6 +1003,7 @@ export class JsonlSessionStore {
             throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC projection boundary is invalid.');
         return hash;
     }
+    /** Recheck a planned GC checkpoint against authoritative records before appending it. */
     async commitContextGc(sessionId, draft) {
         this.#assertOpen();
         const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
@@ -873,6 +1117,7 @@ export class JsonlSessionStore {
             ...(input.turnId ? { turnId: input.turnId } : {})
         });
     }
+    /** Recover files under the sole writer lock; flush dirty index state before releasing it. */
     async acquireSessionLease(sessionId) {
         this.#assertOpen();
         await this.#refreshIndex();
@@ -881,6 +1126,15 @@ export class JsonlSessionStore {
         const path = join(this.#shared.root, 'sessions', sessionId, 'lock');
         const release = await acquireFileLock(path, 'Session already has a writer.', 0);
         try {
+            const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json'));
+            if (!disk)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+            const current = disk.sessions.find((item) => item.id === sessionId);
+            if (!current)
+                throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+            await recoverSessionStorageTransaction(this.sessionDirectory(sessionId), current.storageTransactionId);
+            await recoverContextualWorldStateTransactions(this.#shared.root, current);
+            await this.#refreshIndex();
             await this.#reconcileTail(sessionId);
         }
         catch (error) {
@@ -1011,7 +1265,7 @@ export class JsonlSessionStore {
             meta.automaticTitlePending = state.automaticTitlePending;
             meta.resume = state.resume;
             this.#shared.index.revision++;
-            this.#shared.indexDirty = true;
+            this.#markIndexDirty(meta.id);
         }
         return {
             automaticTitlePending: state.automaticTitlePending,
@@ -1055,6 +1309,14 @@ export class JsonlSessionStore {
         if (this.#leaseClosed || this.#shared.closed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Session store is closed.');
     }
+    #markIndexDirty(sessionId) {
+        this.#shared.indexDirty = true;
+        this.#shared.dirtySessionVersions.set(sessionId, (this.#shared.dirtySessionVersions.get(sessionId) ?? 0) + 1);
+    }
+    async #storageTransactionCommitted(sessionId, transactionId) {
+        const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json'));
+        return (disk?.sessions.some((session) => session.id === sessionId && session.storageTransactionId === transactionId) ?? false);
+    }
     #segmentPath(sessionId, segment) {
         return join(this.#shared.root, 'sessions', sessionId, `events-${String(segment).padStart(6, '0')}.jsonl`);
     }
@@ -1083,27 +1345,30 @@ export class JsonlSessionStore {
         this.#shared.segments.set(sessionId, segment);
         return segment;
     }
+    /** Repair the last segment and pending images under the lease, then sync sequence metadata. */
     async #reconcileTail(sessionId) {
         const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
         const paths = await this.#segmentPaths(sessionId);
         const latestPath = paths.at(-1);
+        await repairSegmentTail(latestPath);
         const records = await readRecords(latestPath);
+        await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.read(sessionId));
         const last = records.at(-1);
         const match = /events-(\d{6})\.jsonl$/.exec(latestPath);
         const segment = Number(match?.[1] ?? 1);
         this.#shared.segments.set(sessionId, segment);
         if (last === undefined)
-            return;
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
         const bytes = (await stat(latestPath)).size;
         const firstSequence = records[0].sequence;
         const known = meta.segments?.find((item) => item.number === segment);
         const titleRecord = records.findLast((record) => record.type === 'session.title.updated' &&
             typeof record.payload.title === 'string');
         const recoveredTitle = titleRecord?.payload?.title;
-        const changed = meta.nextSequence <= last.sequence ||
+        const changed = meta.nextSequence !== last.sequence + 1 ||
             known?.bytes !== bytes ||
             (recoveredTitle !== undefined && meta.title !== recoveredTitle);
-        meta.nextSequence = Math.max(meta.nextSequence, last.sequence + 1);
+        meta.nextSequence = last.sequence + 1;
         if (recoveredTitle !== undefined)
             meta.title = recoveredTitle;
         meta.lastActivityAt =
@@ -1121,7 +1386,7 @@ export class JsonlSessionStore {
             delete meta.automaticTitlePending;
             delete meta.resume;
             this.#shared.index.revision++;
-            this.#shared.indexDirty = true;
+            this.#markIndexDirty(sessionId);
         }
     }
     async close() {
@@ -1137,6 +1402,47 @@ export class JsonlSessionStore {
         JsonlSessionStore.#instances.delete(this.#shared.root);
     }
 }
+async function readSessionIndex(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (value?.version !== 1 ||
+            !Number.isSafeInteger(value.revision) ||
+            value.revision < 0 ||
+            !Array.isArray(value.sessions) ||
+            value.sessions.some((session) => typeof session?.id !== 'string' ||
+                !/^[0-9a-f-]{36}$/iu.test(session.id) ||
+                typeof session.title !== 'string' ||
+                typeof session.workspace !== 'string' ||
+                typeof session.createdAt !== 'string' ||
+                typeof session.lastActivityAt !== 'string' ||
+                !Number.isSafeInteger(session.nextSequence) ||
+                session.nextSequence < 1))
+            throw new Error('invalid index shape');
+        return value;
+    }
+    catch (cause) {
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is corrupt.', { cause });
+    }
+}
+async function persistSessionIndex(path, index) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(index), { mode: 0o600, flag: 'wx', flush: true });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
 async function sessionDirectoryExists(path) {
     try {
         await lstat(path);
@@ -1668,6 +1974,67 @@ async function readRecords(path) {
     }
     return records;
 }
+/** A pending marker is removable only after the committed JSONL references are checked. */
+async function recoverPendingInputImages(sessionDirectory, readHistory) {
+    const directory = join(sessionDirectory, 'input_images');
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pending = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.pending$/iu.test(name));
+    const temporary = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.[0-9a-f-]{36}\.tmp$/iu.test(name));
+    if (pending.length === 0 && temporary.length === 0)
+        return;
+    const referenced = pending.length === 0
+        ? new Set()
+        : new Set(inputImageReferencesFromRecords(await readHistory()).map((image) => image.fileName));
+    for (const name of pending) {
+        const fileName = name.slice(1, -'.pending'.length);
+        if (!referenced.has(fileName))
+            await rm(join(directory, fileName), { force: true });
+        await rm(join(directory, name), { force: true });
+    }
+    for (const name of temporary)
+        await rm(join(directory, name), { force: true });
+}
+/** Repair only the final record under the Session writer lock; never skip middle damage. */
+async function repairSegmentTail(path) {
+    const data = await readFile(path);
+    if (data.length === 0 || data.at(-1) === 10)
+        return;
+    const boundary = data.lastIndexOf(10);
+    let complete = false;
+    try {
+        const record = JSON.parse(data.subarray(boundary + 1).toString('utf8'));
+        complete =
+            record?.schemaVersion === 1 &&
+                Number.isSafeInteger(record.sequence) &&
+                typeof record.sessionId === 'string' &&
+                typeof record.type === 'string';
+    }
+    catch {
+        // An interrupted final line is discarded before another record can be appended.
+    }
+    const handle = await open(path, 'r+');
+    try {
+        if (complete) {
+            const { bytesWritten } = await handle.write(Buffer.from('\n'), 0, 1, data.length);
+            if (bytesWritten !== 1)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tail repair is incomplete.');
+        }
+        else
+            await handle.truncate(boundary + 1);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
 async function readRecordPageFromTail(path, beforeSequence, limit) {
     const handle = await open(path, 'r');
     try {
@@ -1750,28 +2117,54 @@ function segmentNumberFromPath(path) {
 async function acquireFileLock(path, message = 'Session index is busy.', waitMs = 5000) {
     const deadline = Date.now() + waitMs;
     for (;;) {
+        let handle;
         try {
-            const handle = await open(path, 'wx', 0o600);
-            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
-            let released = false;
-            return async () => {
-                if (released)
-                    return;
-                released = true;
-                await handle.close();
-                await rm(path, { force: true });
-            };
+            handle = await open(path, 'wx', 0o600);
         }
         catch (cause) {
+            if (cause.code !== 'EEXIST')
+                throw cause;
             if (await removeDeadOwner(path))
                 continue;
             if (Date.now() >= deadline)
                 throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', message, { cause });
             await delay(25 + Math.floor(Math.random() * 25));
+            continue;
+        }
+        try {
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        }
+        catch (error) {
+            try {
+                await handle.close();
+            }
+            finally {
+                await rm(path, { force: true });
+            }
+            throw error;
         }
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            await handle.close();
+            await rm(path, { force: true });
+        };
     }
 }
 async function removeDeadOwner(path) {
+    const reclaimerPath = `${path}.reclaim`;
+    let reclaimer;
+    try {
+        // Only one process may unlink a dead owner's path; all other contenders wait.
+        reclaimer = await open(reclaimerPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
     try {
         const owner = JSON.parse(await readFile(path, 'utf8'));
         if (typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid))
@@ -1790,4 +2183,12 @@ async function removeDeadOwner(path) {
     catch {
         return false;
     }
+    finally {
+        try {
+            await reclaimer.close();
+        }
+        finally {
+            await rm(reclaimerPath, { force: true });
+        }
+    }
 }