spiracha 2.1.0 → 2.2.0

package/src/lib/cursor-recovery.ts

@@ -1,5 +1,8 @@
 import { Database } from 'bun:sqlite';
-import { rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { readdir, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { mapWithConcurrency } from './concurrency';
 import {
     findCursorTranscriptDirs,
     invalidateCursorDiscoveryCache,
@@ -16,8 +19,10 @@ import {
     type CursorWorkspaceBucket,
     type CursorWorkspaceGroup,
     getCursorGlobalDbPath,
+    getCursorProjectsDir,
     resolveCursorUserDir,
 } from './cursor-exporter-types';
+import { assertSafeCursorComposerId, buildCursorBubbleKeyLikePattern } from './cursor-id';
 
 type ComposerEntry = {
     composerId?: string;
@@ -49,6 +54,21 @@ export const isCursorRunning = async (): Promise<boolean> => {
 };
 
 const backupStamp = (): string => new Date().toISOString().replace(/[-:]/gu, '').replace(/\..+/u, '').replace('T', '-');
+const CURSOR_BACKUP_RETENTION_COUNT = 5;
+
+const writeRetainedCursorBackup = async (basePath: string, label: string, value: unknown): Promise<string> => {
+    const directory = path.dirname(basePath);
+    const filePrefix = `${path.basename(basePath)}.${label}.`;
+    const backupPath = `${basePath}.${label}.${backupStamp()}.${randomUUID()}.json`;
+    await Bun.write(backupPath, JSON.stringify(value));
+    const backups = (await readdir(directory))
+        .filter((entry) => entry.startsWith(filePrefix) && entry.endsWith('.json'))
+        .sort((left, right) => right.localeCompare(left));
+    await Promise.all(
+        backups.slice(CURSOR_BACKUP_RETENTION_COUNT).map((entry) => rm(path.join(directory, entry), { force: true })),
+    );
+    return backupPath;
+};
 
 // The Cursor global DB can be multiple gigabytes, so copying the whole file per operation is not
 // viable. We instead write small, targeted JSON backups of only the data each operation touches.
@@ -61,22 +81,20 @@ const backupComposerHeaders = async (globalDbPath: string): Promise<string> => {
         db.close();
     }
 
-    const backupPath = `${globalDbPath}.composerHeaders.${backupStamp()}.json`;
-    await Bun.write(backupPath, JSON.stringify(headers));
-    return backupPath;
+    return writeRetainedCursorBackup(globalDbPath, 'composerHeaders', headers);
 };
 
 const backupPrunedThreads = async (globalDbPath: string, composerIds: string[]): Promise<string> => {
     const db = openCursorReadonlyDb(globalDbPath);
     try {
         const dump = composerIds.map((composerId) => ({
-            bubbles: db.query('SELECT key, value FROM cursorDiskKV WHERE key LIKE ?').all(`bubbleId:${composerId}:%`),
+            bubbles: db
+                .query(`SELECT key, value FROM cursorDiskKV WHERE key LIKE ? ESCAPE '\\'`)
+                .all(buildCursorBubbleKeyLikePattern(composerId)),
             composerData: readJsonItemFromKv(db, `composerData:${composerId}`),
             composerId,
         }));
-        const backupPath = `${globalDbPath}.prunedThreads.${backupStamp()}.json`;
-        await Bun.write(backupPath, JSON.stringify(dump));
-        return backupPath;
+        return writeRetainedCursorBackup(globalDbPath, 'prunedThreads', dump);
     } finally {
         db.close();
     }
@@ -227,8 +245,8 @@ const relinkHeaders = (
 
 const countBubbles = (db: Database, composerId: string): number => {
     const row = db
-        .query('SELECT COUNT(*) AS count FROM cursorDiskKV WHERE key LIKE ?')
-        .get(`bubbleId:${composerId}:%`) as { count: number };
+        .query(`SELECT COUNT(*) AS count FROM cursorDiskKV WHERE key LIKE ? ESCAPE '\\'`)
+        .get(buildCursorBubbleKeyLikePattern(composerId)) as { count: number };
     return row.count;
 };
 
@@ -311,9 +329,7 @@ const backupTargetBucketComposerData = async (
     target: CursorWorkspaceBucket,
     snapshot: BucketComposerDataSnapshot,
 ): Promise<string> => {
-    const backupPath = `${target.dbPath}.composerData.${backupStamp()}.json`;
-    await Bun.write(backupPath, JSON.stringify(snapshot));
-    return backupPath;
+    return writeRetainedCursorBackup(target.dbPath, 'composerData', snapshot);
 };
 
 const buildTargetBucketComposerData = (existing: ComposerData, merged: ComposerEntry[]): ComposerData => {
@@ -394,7 +410,9 @@ const removeThreadFromBucket = (db: Database, composerIds: Set<string>): boolean
 };
 
 const pruneGlobalThread = (db: Database, composerId: string): { bubbles: number; composerData: number } => {
-    const bubbleResult = db.run('DELETE FROM cursorDiskKV WHERE key LIKE ?', [`bubbleId:${composerId}:%`]);
+    const bubbleResult = db.run(`DELETE FROM cursorDiskKV WHERE key LIKE ? ESCAPE '\\'`, [
+        buildCursorBubbleKeyLikePattern(composerId),
+    ]);
     const headResult = db.run('DELETE FROM cursorDiskKV WHERE key = ?', [`composerData:${composerId}`]);
     return { bubbles: bubbleResult.changes ?? 0, composerData: headResult.changes ?? 0 };
 };
@@ -420,6 +438,28 @@ export const pruneCursorThreads = async (
     apply: boolean,
     userDir = resolveCursorUserDir(),
 ): Promise<CursorPruneResult> => {
+    const projectsDir = path.resolve(getCursorProjectsDir(userDir));
+    const canonicalProjectsDir = await realpath(projectsDir).catch(() => projectsDir);
+    for (const thread of threads) {
+        assertSafeCursorComposerId(thread.composerId);
+        for (const transcriptDir of thread.transcriptDirs) {
+            const resolvedDir = path.resolve(transcriptDir);
+            const resolvedProjectsDir = path.dirname(path.dirname(path.dirname(resolvedDir)));
+            const canonicalDir = await realpath(resolvedDir).catch(() => resolvedDir);
+            const canonicalRelativePath = path.relative(canonicalProjectsDir, canonicalDir);
+            if (
+                path.basename(resolvedDir) !== thread.composerId ||
+                path.basename(path.dirname(resolvedDir)) !== 'agent-transcripts' ||
+                resolvedProjectsDir !== projectsDir ||
+                !canonicalRelativePath ||
+                canonicalRelativePath.startsWith(`..${path.sep}`) ||
+                path.isAbsolute(canonicalRelativePath)
+            ) {
+                throw new Error(`Unsafe Cursor transcript directory: ${transcriptDir}`);
+            }
+        }
+    }
+
     const composerIds = new Set(threads.map((thread) => thread.composerId));
     const globalDbPath = getCursorGlobalDbPath(userDir);
     const result: CursorPruneResult = {
@@ -444,8 +484,18 @@ export const pruneCursorThreads = async (
     }
 
     await backupPrunedThreads(globalDbPath, [...composerIds]);
-    await pruneGlobalThreads(globalDbPath, threads, composerIds, result);
-    await pruneWorkspaceBuckets(threads, composerIds, result, userDir);
+    const bucketMutation = await pruneWorkspaceBuckets(composerIds, userDir);
+    try {
+        await pruneGlobalThreads(globalDbPath, threads, composerIds, result);
+    } catch (error) {
+        try {
+            await bucketMutation.rollback();
+        } catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], 'Cursor deletion and bucket rollback both failed');
+        }
+        throw error;
+    }
+    result.workspaceBucketsUpdated = bucketMutation.updatedCount;
     await pruneTranscriptDirs(threads, result);
     invalidateCursorDiscoveryCache();
 
@@ -459,25 +509,49 @@ const pruneGlobalThreads = async (
     result: CursorPruneResult,
 ): Promise<void> => {
     const db = new Database(globalDbPath);
+    let transactionStarted = false;
     try {
+        db.exec('PRAGMA busy_timeout = 5000');
+        db.exec('BEGIN IMMEDIATE');
+        transactionStarted = true;
+        let bubblesDeleted = 0;
+        let composerDataDeleted = 0;
         for (const thread of threads) {
             const deleted = pruneGlobalThread(db, thread.composerId);
-            result.bubblesDeleted += deleted.bubbles;
-            result.composerDataDeleted += deleted.composerData;
+            bubblesDeleted += deleted.bubbles;
+            composerDataDeleted += deleted.composerData;
         }
 
-        result.headersRemoved = removeThreadHeaders(db, composerIds);
+        const headersRemoved = removeThreadHeaders(db, composerIds);
+        db.exec('COMMIT');
+        transactionStarted = false;
+        result.bubblesDeleted += bubblesDeleted;
+        result.composerDataDeleted += composerDataDeleted;
+        result.headersRemoved = headersRemoved;
+    } catch (error) {
+        if (transactionStarted) {
+            db.exec('ROLLBACK');
+        }
+        throw error;
     } finally {
         db.close();
     }
 };
 
-const pruneWorkspaceBuckets = async (
-    _threads: CursorThreadSummary[],
-    composerIds: Set<string>,
-    result: CursorPruneResult,
-    userDir: string,
-): Promise<void> => {
+const restoreBucketComposerData = (dbPath: string, snapshot: BucketComposerDataSnapshot): void => {
+    const db = new Database(dbPath);
+    try {
+        if (snapshot.exists) {
+            writeJsonItem(db, COMPOSER_DATA_KEY, snapshot.data);
+        } else {
+            db.run('DELETE FROM ItemTable WHERE key = ?', [COMPOSER_DATA_KEY]);
+        }
+    } finally {
+        db.close();
+    }
+};
+
+const pruneWorkspaceBuckets = async (composerIds: Set<string>, userDir: string) => {
     // Scan every bucket: a thread can live in more than one bucket's composer.composerData (e.g. the
     // current bucket plus the older bucket it was recovered from), so remove it from all of them.
     const groups = await listCursorWorkspaceGroups(userDir);
@@ -488,25 +562,61 @@ const pruneWorkspaceBuckets = async (
         }
     }
 
+    const snapshots = new Map<string, BucketComposerDataSnapshot>();
     for (const dbPath of dbPaths) {
-        const db = new Database(dbPath);
+        const db = openCursorReadonlyDb(dbPath);
         try {
-            if (removeThreadFromBucket(db, composerIds)) {
-                result.workspaceBucketsUpdated += 1;
-            }
+            const data = readJsonItem<ComposerData>(db, COMPOSER_DATA_KEY);
+            snapshots.set(dbPath, { data: data ?? {}, exists: data !== null });
         } finally {
             db.close();
         }
     }
-};
 
-const pruneTranscriptDirs = async (threads: CursorThreadSummary[], result: CursorPruneResult): Promise<void> => {
-    for (const thread of threads) {
-        for (const dir of thread.transcriptDirs) {
-            await rm(dir, { force: true, recursive: true });
-            result.transcriptDirsRemoved += 1;
+    const updatedPaths: string[] = [];
+    const rollback = async () => {
+        const rollbackFailures: unknown[] = [];
+        for (const dbPath of [...updatedPaths].reverse()) {
+            try {
+                restoreBucketComposerData(dbPath, snapshots.get(dbPath)!);
+            } catch (error) {
+                rollbackFailures.push(error);
+            }
+        }
+        if (rollbackFailures.length > 0) {
+            throw new AggregateError(rollbackFailures, 'Failed to restore Cursor workspace buckets');
         }
+    };
+
+    try {
+        for (const dbPath of dbPaths) {
+            const db = new Database(dbPath);
+            try {
+                if (removeThreadFromBucket(db, composerIds)) {
+                    updatedPaths.push(dbPath);
+                }
+            } finally {
+                db.close();
+            }
+        }
+    } catch (error) {
+        try {
+            await rollback();
+        } catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], 'Cursor bucket deletion and rollback both failed');
+        }
+        throw error;
     }
+
+    return { rollback, updatedCount: updatedPaths.length };
+};
+
+const pruneTranscriptDirs = async (threads: CursorThreadSummary[], result: CursorPruneResult): Promise<void> => {
+    const transcriptDirs = threads.flatMap((thread) => thread.transcriptDirs);
+    await mapWithConcurrency(transcriptDirs, 4, async (dir) => {
+        await rm(dir, { force: true, recursive: true });
+    });
+    result.transcriptDirsRemoved = transcriptDirs.length;
 };
 
 // Builds the minimal thread records needed to fully delete the given composer ids (bubble counts for
@@ -521,6 +631,7 @@ export const collectCursorThreadsForDeletion = async (
 
     try {
         for (const composerId of composerIds) {
+            assertSafeCursorComposerId(composerId);
             summaries.push({
                 bubbleBytes: 0,
                 bubbleCount: countBubbles(db, composerId),

package/src/lib/cursor-transcript-phase.ts

@@ -0,0 +1,40 @@
+import type { CursorBubble } from './cursor-exporter-types';
+
+export type CursorMessagePhase = 'commentary' | 'final_answer' | null;
+
+export const getFinalCursorAssistantTextBubbleIds = (bubbles: CursorBubble[]): Set<string> => {
+    const finalBubbleIds = new Set<string>();
+    let latestAssistantTextBubbleId: string | null = null;
+
+    const flushAssistantRun = () => {
+        if (latestAssistantTextBubbleId) {
+            finalBubbleIds.add(latestAssistantTextBubbleId);
+            latestAssistantTextBubbleId = null;
+        }
+    };
+
+    for (const bubble of bubbles) {
+        if (bubble.kind !== 'assistant') {
+            flushAssistantRun();
+            continue;
+        }
+
+        if (bubble.text.trim()) {
+            latestAssistantTextBubbleId = bubble.bubbleId;
+        }
+    }
+
+    flushAssistantRun();
+    return finalBubbleIds;
+};
+
+export const getCursorTextBubblePhase = (
+    bubble: CursorBubble,
+    finalAssistantTextBubbleIds: Set<string>,
+): CursorMessagePhase => {
+    if (bubble.kind !== 'assistant') {
+        return null;
+    }
+
+    return finalAssistantTextBubbleIds.has(bubble.bubbleId) ? 'final_answer' : 'commentary';
+};

package/src/lib/cursor-transcript.ts

@@ -5,6 +5,7 @@ import type {
     CursorThreadTranscript,
     CursorToolCall,
 } from './cursor-exporter-types';
+import { getCursorTextBubblePhase, getFinalCursorAssistantTextBubbleIds } from './cursor-transcript-phase';
 import {
     cleanExtractedText,
     cleanInlineTitle,
@@ -60,6 +61,9 @@ export const renderCursorToolCall = (toolCall: CursorToolCall, outputFormat: Exp
     if (toolCall.status) {
         lines.push(`Status: ${toolCall.status}`);
     }
+    if (toolCall.callId) {
+        lines.push(`Call ID: ${toolCall.callId}`);
+    }
 
     const args = prettyToolArguments(toolCall.argumentsText);
     if (args) {
@@ -79,7 +83,11 @@ const renderUserBubble = (bubble: CursorBubble, outputFormat: ExportFormat): str
     return text ? renderSection('User', text, outputFormat) : '';
 };
 
-const renderAssistantBubble = (bubble: CursorBubble, options: CursorExportOptions): string[] => {
+const renderAssistantBubble = (
+    bubble: CursorBubble,
+    options: CursorExportOptions,
+    finalAssistantTextBubbleIds: Set<string>,
+): string[] => {
     const blocks: string[] = [];
 
     if (options.includeCommentary && bubble.thinking?.trim()) {
@@ -90,7 +98,10 @@ const renderAssistantBubble = (bubble: CursorBubble, options: CursorExportOption
     }
 
     const text = cleanExtractedText(bubble.text).trim();
-    if (text) {
+    if (
+        text &&
+        (getCursorTextBubblePhase(bubble, finalAssistantTextBubbleIds) !== 'commentary' || options.includeCommentary)
+    ) {
         blocks.push(renderSection('Assistant', text, options.outputFormat));
     }
 
@@ -101,14 +112,18 @@ const renderAssistantBubble = (bubble: CursorBubble, options: CursorExportOption
     return blocks;
 };
 
-export const renderCursorBubble = (bubble: CursorBubble, options: CursorExportOptions): string[] => {
+export const renderCursorBubble = (
+    bubble: CursorBubble,
+    options: CursorExportOptions,
+    finalAssistantTextBubbleIds = getFinalCursorAssistantTextBubbleIds([bubble]),
+): string[] => {
     if (bubble.kind === 'user') {
         const block = renderUserBubble(bubble, options.outputFormat);
         return block ? [block] : [];
     }
 
     if (bubble.kind === 'assistant') {
-        return renderAssistantBubble(bubble, options);
+        return renderAssistantBubble(bubble, options, finalAssistantTextBubbleIds);
     }
 
     return [];
@@ -161,9 +176,10 @@ export const renderCursorTranscript = (
     transcript: CursorThreadTranscript,
     options: CursorExportOptions,
 ): string | null => {
+    const finalAssistantTextBubbleIds = getFinalCursorAssistantTextBubbleIds(transcript.bubbles);
     const sections: string[] = [];
     for (const bubble of transcript.bubbles) {
-        sections.push(...renderCursorBubble(bubble, options));
+        sections.push(...renderCursorBubble(bubble, options, finalAssistantTextBubbleIds));
     }
 
     if (sections.length === 0) {

package/src/lib/grok-db.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { chmod, readdir, rename, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { createConcurrencyLimiter, mapWithConcurrency } from './concurrency';
 import {
     type GrokSessionSummary,
@@ -12,15 +13,16 @@ import {
     resolveGrokHome,
     resolveGrokSessionsDir,
 } from './grok-exporter-types';
+import { getPortablePathBasename } from './portable-path';
 import {
     asNumber,
     asObject,
     asString,
     cleanExtractedText,
     cleanInlineTitle,
-    getPortablePathBasename,
     isWorkspacePathQuery,
     type JsonValue,
+    readDirectoryEntriesIfExists,
     readJsonlObjects,
     workspacePathMatchesQuery,
 } from './shared';
@@ -151,7 +153,7 @@ const readJsonObjectFile = async (filePath: string): Promise<Record<string, Json
 };
 
 const listJsonFiles = async (dirPath: string): Promise<string[]> => {
-    const entries = await readdir(dirPath, { withFileTypes: true }).catch(() => []);
+    const entries = await readDirectoryEntriesIfExists(dirPath);
     return entries
         .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
         .map((entry) => path.join(dirPath, entry.name))
@@ -253,7 +255,7 @@ const parseAssistantParts = (
     includeRawPayloads: boolean,
 ): GrokTranscriptPart[] => {
     const parts: GrokTranscriptPart[] = [];
-    const text = asString(raw.content ?? null) ?? '';
+    const text = textFromContentValue(raw.content);
     if (text.trim()) {
         parts.push({
             partId: `${entryId}:text`,
@@ -398,41 +400,73 @@ const readGrokChatHistory = async (
     }
 
     const requestFiles = await listJsonFiles(path.join(sessionDir, 'compaction_requests'));
-    const archivedHistory = (
+    const archivedHistories = (
         await Promise.all(
             requestFiles.map(async (filePath) => {
                 const request = await readJsonObjectFile(filePath);
-                return getJsonObjectList(request?.chat_history);
+                return {
+                    createdAtMs: parseTimestampMs(request?.created_at) ?? 0,
+                    events: getJsonObjectList(request?.chat_history),
+                    filePath,
+                };
             }),
         )
     )
-        .filter((history) => history.length > 0)
-        .sort((left, right) => right.length - left.length)[0];
+        .filter((history) => history.events.length > 0)
+        .sort((left, right) => left.createdAtMs - right.createdAtMs || left.filePath.localeCompare(right.filePath));
 
-    if (!archivedHistory) {
+    if (archivedHistories.length === 0) {
         return liveEvents;
     }
 
     const checkpointFiles = await listJsonFiles(path.join(sessionDir, 'compaction_checkpoints'));
-    const latestCheckpoint = (
+    const checkpoints = (
         await Promise.all(
             checkpointFiles.map(async (filePath) => {
                 const checkpoint = await readJsonObjectFile(filePath);
                 return {
                     compactedHistory: getJsonObjectList(checkpoint?.compacted_history),
                     createdAtMs: parseTimestampMs(checkpoint?.created_at) ?? 0,
+                    filePath,
                     promptIndex: asNumber(checkpoint?.prompt_index_at_compaction ?? null),
                 };
             }),
         )
-    ).sort((left, right) => right.createdAtMs - left.createdAtMs)[0];
+    ).sort((left, right) => left.createdAtMs - right.createdAtMs || left.filePath.localeCompare(right.filePath));
 
-    const compactedHistoryIsLivePrefix = latestCheckpoint?.compactedHistory.every(
-        (event, index) => JSON.stringify(event) === JSON.stringify(liveEvents[index]),
-    );
+    const isHistoryPrefix = (prefix: Record<string, JsonValue>[], history: Record<string, JsonValue>[]): boolean => {
+        return (
+            prefix.length > 0 &&
+            prefix.length <= history.length &&
+            prefix.every((event, index) => isDeepStrictEqual(event, history[index]))
+        );
+    };
+
+    let archivedHistory = [...archivedHistories[0]!.events];
+    for (const history of archivedHistories.slice(1)) {
+        const precedingCheckpoint = checkpoints
+            .filter(
+                (checkpoint) =>
+                    checkpoint.createdAtMs <= history.createdAtMs &&
+                    isHistoryPrefix(checkpoint.compactedHistory, history.events),
+            )
+            .at(-1);
+        if (precedingCheckpoint) {
+            archivedHistory.push(...history.events.slice(precedingCheckpoint.compactedHistory.length));
+        } else if (isHistoryPrefix(archivedHistory, history.events)) {
+            archivedHistory = [...history.events];
+        }
+    }
+
+    const latestCheckpoint = checkpoints.at(-1);
+
+    const compactedHistoryIsLivePrefix = isHistoryPrefix(latestCheckpoint?.compactedHistory ?? [], liveEvents);
+    const archivedHistoryIsLivePrefix = isHistoryPrefix(archivedHistory, liveEvents);
     const liveTailStart = compactedHistoryIsLivePrefix
         ? latestCheckpoint?.compactedHistory.length
-        : latestCheckpoint?.promptIndex;
+        : archivedHistoryIsLivePrefix
+          ? archivedHistory.length
+          : latestCheckpoint?.promptIndex;
     const liveTail = Number.isFinite(liveTailStart)
         ? liveEvents.slice(Math.max(0, Math.min(liveEvents.length, Math.floor(liveTailStart ?? 0))))
         : liveEvents;
@@ -662,23 +696,17 @@ const listSessionDirectoriesUnderWorkspace = async (
     root: string,
     directoryName: string,
 ): Promise<GrokSessionDirectory[]> => {
-    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
-    const directories: GrokSessionDirectory[] = [];
-
-    for (const entry of entries) {
-        if (!entry.isDirectory()) {
-            continue;
-        }
-
-        const entryPath = path.join(root, entry.name);
-        if (
-            (await pathExists(path.join(entryPath, 'summary.json'))) &&
-            (await pathExists(path.join(entryPath, 'chat_history.jsonl')))
-        ) {
-            directories.push({ directoryName, sessionDir: entryPath });
-        }
-        directories.push(...(await listSessionDirectoriesUnderWorkspace(entryPath, directoryName)));
-    }
+    const entries = await readDirectoryEntriesIfExists(root);
+    const fileNames = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+    const isSessionDirectory = fileNames.has('summary.json') && fileNames.has('chat_history.jsonl');
+    const childDirectories = entries.filter(
+        (entry) => entry.isDirectory() && (!isSessionDirectory || entry.name === 'subagents'),
+    );
+    const nested = await mapWithConcurrency(childDirectories, READ_CONCURRENCY, (entry) =>
+        listSessionDirectoriesUnderWorkspace(path.join(root, entry.name), directoryName),
+    );
+    const directories: GrokSessionDirectory[] = isSessionDirectory ? [{ directoryName, sessionDir: root }] : [];
+    directories.push(...nested.flat());
 
     return directories.sort((left, right) => left.sessionDir.localeCompare(right.sessionDir));
 };
@@ -818,6 +846,14 @@ export const listGrokSessionsForGroup = async (
     workspaceKey: string,
     sessionsDir = resolveGrokSessionsDir(),
 ): Promise<GrokSessionSummary[]> => {
+    const transcripts = await listGrokSessionTranscriptsForGroup(workspaceKey, sessionsDir);
+    return sortSessions(transcripts.map((transcript) => transcript.session));
+};
+
+export const listGrokSessionTranscriptsForGroup = async (
+    workspaceKey: string,
+    sessionsDir = resolveGrokSessionsDir(),
+): Promise<GrokSessionTranscript[]> => {
     const directoryName = getDirectoryNameFromWorkspaceKey(workspaceKey);
     if (!directoryName || !(await pathExists(sessionsDir))) {
         return [];
@@ -825,7 +861,13 @@ export const listGrokSessionsForGroup = async (
 
     const files = await listSessionDirectoriesForWorkspace(sessionsDir, directoryName);
     const transcripts = await readSessionDirectories(sessionsDir, files);
-    return sortSessions(transcripts.filter(hasConversationMessages).map((transcript) => transcript.session));
+    return transcripts
+        .filter(hasConversationMessages)
+        .sort(
+            (left, right) =>
+                compareNullableMsDesc(left.session.lastActiveAtMs, right.session.lastActiveAtMs) ||
+                left.session.title.localeCompare(right.session.title),
+        );
 };
 
 const locateSessionDirectory = async (sessionsDir: string, sessionId: string): Promise<GrokSessionDirectory | null> => {
@@ -844,7 +886,7 @@ const locateSessionDirectory = async (sessionsDir: string, sessionId: string): P
 };
 
 const listFilesRecursively = async (root: string): Promise<string[]> => {
-    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const entries = await readDirectoryEntriesIfExists(root);
     const files: string[] = [];
 
     for (const entry of entries) {
@@ -863,7 +905,7 @@ const listFilesRecursively = async (root: string): Promise<string[]> => {
 };
 
 const listDirectoriesRecursively = async (root: string): Promise<string[]> => {
-    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const entries = await readDirectoryEntriesIfExists(root);
     const directories: string[] = [];
 
     for (const entry of entries) {

package/src/lib/grok-transcript-phase.ts

@@ -1,6 +1,11 @@
 import type { GrokTranscriptEntry, GrokTranscriptPart } from './grok-exporter-types';
 
-export type GrokAssistantMessagePhase = 'commentary' | 'final_answer' | 'unknown';
+export type GrokAssistantMessagePhase = 'commentary' | 'final_answer' | null;
+
+const isGrokCommentaryEnvelope = (entry: GrokTranscriptEntry, part: GrokTranscriptPart): boolean => {
+    const text = part.text?.trim() ?? '';
+    return entry.role === 'system' || text.startsWith('<user_info>') || text.startsWith('<system-reminder>');
+};
 
 export const getFinalGrokAssistantTextPartIds = (entries: GrokTranscriptEntry[]): Set<string> => {
     const finalPartIds = new Set<string>();
@@ -44,8 +49,12 @@ export const getGrokTextPartPhase = (
     part: GrokTranscriptPart,
     finalTextPartIds: Set<string>,
 ): GrokAssistantMessagePhase => {
+    if (isGrokCommentaryEnvelope(entry, part)) {
+        return 'commentary';
+    }
+
     if (entry.role !== 'assistant') {
-        return 'unknown';
+        return null;
     }
 
     return finalTextPartIds.has(part.partId) ? 'final_answer' : 'commentary';