@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/services/session-memory.js

@@ -0,0 +1,81 @@
+/**
+ * Session Memory service — automatic session memory maintenance.
+ *
+ * Extracts and maintains conversation context as persistent memory
+ * entries that survive across sessions.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const MEMORY_DIR = join(homedir(), ".code-shell", "session-memories");
+/**
+ * Save a session memory entry.
+ */
+export function saveSessionMemory(entry) {
+    mkdirSync(MEMORY_DIR, { recursive: true });
+    const file = join(MEMORY_DIR, `${entry.sessionId}.json`);
+    writeFileSync(file, JSON.stringify(entry, null, 2), "utf-8");
+}
+/**
+ * Load a session memory by session ID.
+ */
+export function loadSessionMemory(sessionId) {
+    const file = join(MEMORY_DIR, `${sessionId}.json`);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List all session memories, most recent first.
+ */
+export function listSessionMemories(limit = 50) {
+    if (!existsSync(MEMORY_DIR))
+        return [];
+    const files = readdirSync(MEMORY_DIR)
+        .filter((f) => f.endsWith(".json"))
+        .sort()
+        .reverse()
+        .slice(0, limit);
+    const entries = [];
+    for (const file of files) {
+        try {
+            const entry = JSON.parse(readFileSync(join(MEMORY_DIR, file), "utf-8"));
+            entries.push(entry);
+        }
+        catch { }
+    }
+    return entries;
+}
+/**
+ * Search session memories by keyword.
+ */
+export function searchSessionMemories(query) {
+    const all = listSessionMemories(200);
+    const q = query.toLowerCase();
+    return all.filter((m) => m.summary.toLowerCase().includes(q) ||
+        m.keyTopics.some((t) => t.toLowerCase().includes(q)) ||
+        m.decisions.some((d) => d.toLowerCase().includes(q)));
+}
+/**
+ * Build a prompt for extracting session memory from a conversation.
+ */
+export function buildSessionMemoryPrompt(messages) {
+    const text = messages
+        .map((m) => `[${m.role}]: ${m.content.slice(0, 2000)}`)
+        .join("\n\n");
+    return `Extract a concise session memory from this conversation:
+
+${text.slice(0, 30000)}
+
+Respond with JSON:
+{
+  "summary": "One paragraph summarizing what was discussed and accomplished",
+  "keyTopics": ["topic1", "topic2", ...],
+  "decisions": ["decision1", "decision2", ...]
+}`;
+}

package/dist/session/file-history.d.ts

@@ -0,0 +1,41 @@
+/**
+ * File history — automatic backup of files before modifications.
+ *
+ * Stores snapshots in the session directory under file-history/.
+ * Supports restoring files to a previous state.
+ */
+export interface FileSnapshot {
+    filePath: string;
+    timestamp: number;
+    backupPath: string;
+    hash: string;
+    size: number;
+}
+export declare class FileHistory {
+    private readonly historyDir;
+    private snapshots;
+    constructor(sessionDir: string);
+    /**
+     * Save a snapshot of a file before it is modified.
+     * Returns the snapshot record, or null if the file doesn't exist.
+     */
+    saveSnapshot(filePath: string): FileSnapshot | null;
+    /**
+     * Get all snapshots for a specific file.
+     */
+    getSnapshots(filePath: string): FileSnapshot[];
+    /**
+     * Restore a file to a specific snapshot.
+     */
+    restore(snapshot: FileSnapshot): boolean;
+    /**
+     * Restore a file to its most recent snapshot.
+     */
+    restoreLatest(filePath: string): boolean;
+    /**
+     * Get all tracked files.
+     */
+    getTrackedFiles(): string[];
+    private saveIndex;
+    static loadFromDir(sessionDir: string): FileHistory;
+}

package/dist/session/file-history.js

@@ -0,0 +1,115 @@
+/**
+ * File history — automatic backup of files before modifications.
+ *
+ * Stores snapshots in the session directory under file-history/.
+ * Supports restoring files to a previous state.
+ */
+import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+export class FileHistory {
+    historyDir;
+    snapshots = [];
+    constructor(sessionDir) {
+        this.historyDir = join(sessionDir, "file-history");
+        mkdirSync(this.historyDir, { recursive: true });
+    }
+    /**
+     * Save a snapshot of a file before it is modified.
+     * Returns the snapshot record, or null if the file doesn't exist.
+     */
+    saveSnapshot(filePath) {
+        const absPath = resolve(filePath);
+        if (!existsSync(absPath))
+            return null;
+        try {
+            const content = readFileSync(absPath);
+            const hash = createHash("md5").update(content).digest("hex");
+            // Check if we already have this exact version
+            const existing = this.snapshots.find((s) => s.filePath === absPath && s.hash === hash);
+            if (existing)
+                return existing;
+            // Create backup
+            const timestamp = Date.now();
+            const safeName = absPath.replace(/[/\\:]/g, "_").slice(-100);
+            const backupPath = join(this.historyDir, `${timestamp}_${safeName}`);
+            copyFileSync(absPath, backupPath);
+            const snapshot = {
+                filePath: absPath,
+                timestamp,
+                backupPath,
+                hash,
+                size: content.length,
+            };
+            this.snapshots.push(snapshot);
+            // Write index
+            this.saveIndex();
+            return snapshot;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get all snapshots for a specific file.
+     */
+    getSnapshots(filePath) {
+        const absPath = resolve(filePath);
+        return this.snapshots
+            .filter((s) => s.filePath === absPath)
+            .sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Restore a file to a specific snapshot.
+     */
+    restore(snapshot) {
+        try {
+            if (!existsSync(snapshot.backupPath))
+                return false;
+            // Save current state before restoring
+            this.saveSnapshot(snapshot.filePath);
+            copyFileSync(snapshot.backupPath, snapshot.filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Restore a file to its most recent snapshot.
+     */
+    restoreLatest(filePath) {
+        const snapshots = this.getSnapshots(filePath);
+        if (snapshots.length === 0)
+            return false;
+        return this.restore(snapshots[0]);
+    }
+    /**
+     * Get all tracked files.
+     */
+    getTrackedFiles() {
+        return [...new Set(this.snapshots.map((s) => s.filePath))];
+    }
+    saveIndex() {
+        try {
+            const indexPath = join(this.historyDir, "index.json");
+            writeFileSync(indexPath, JSON.stringify(this.snapshots, null, 2), "utf-8");
+        }
+        catch {
+            // Silent fail
+        }
+    }
+    static loadFromDir(sessionDir) {
+        const history = new FileHistory(sessionDir);
+        const indexPath = join(history.historyDir, "index.json");
+        if (existsSync(indexPath)) {
+            try {
+                history.snapshots = JSON.parse(readFileSync(indexPath, "utf-8"));
+            }
+            catch {
+                // Start fresh
+            }
+        }
+        return history;
+    }
+}

package/dist/session/memory.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Memory system — persistent cross-session memory.
+ *
+ * Stores structured memory entries as individual markdown files under a base
+ * directory. Resolution order for the base directory:
+ *   1. explicit `baseDir` constructor arg
+ *   2. CODE_SHELL_HOME env var
+ *   3. ~/.code-shell
+ *
+ * Two scopes are isolated on disk:
+ *   - user/    Things the user explicitly asked to remember, plus the legacy
+ *              auto-extracted entries (extract-memories output). LLM may
+ *              only modify these through permission-gated tool calls.
+ *   - dream/   The dream pipeline's workspace. The LLM is free to add /
+ *              merge / delete entries here; user/ is read-only to dream.
+ *
+ * MEMORY.md is the index file (one per scope).
+ *
+ * Deletes are SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
+ * rather than removed, so accidental deletions are recoverable.
+ */
+export type MemoryScope = "user" | "dream";
+export interface MemoryEntry {
+    name: string;
+    description: string;
+    type: "user" | "feedback" | "project" | "reference";
+    content: string;
+    fileName: string;
+    scope: MemoryScope;
+}
+export interface MemoryManagerOptions {
+    /** Project root path; when set, memories are scoped under projects/<hash>/memory. */
+    projectDir?: string;
+    /** Override the base directory (~/.code-shell by default). Takes precedence over env. */
+    baseDir?: string;
+    /** Which scope this manager operates on. Defaults to "user". */
+    scope?: MemoryScope;
+}
+export declare function resolveMemoryBaseDir(override?: string): string;
+export declare class MemoryManager {
+    private readonly baseDir;
+    /** Root containing both scope subdirs (the "memory" dir per project/global). */
+    private readonly memoryRoot;
+    private readonly scope;
+    /** Scope-specific directory: <memoryRoot>/<scope>. */
+    private readonly memoryDir;
+    private readonly indexPath;
+    private indexCache;
+    constructor(options?: MemoryManagerOptions | string);
+    getMemoryDir(): string;
+    getScope(): MemoryScope;
+    /**
+     * Save a memory entry. Creates the file and updates the index.
+     */
+    save(entry: Omit<MemoryEntry, "fileName" | "scope">): string;
+    /**
+     * Load all memory entries.
+     */
+    loadAll(): MemoryEntry[];
+    /**
+     * Load a single memory file.
+     */
+    private loadFile;
+    /**
+     * Soft-delete a memory by name or filename — moves the file into
+     * <baseDir>/memory-trash/<ISO>/<scope>/ instead of unlinking it. The user
+     * can recover by moving it back; we never hard-delete from this code path.
+     */
+    delete(nameOrFile: string): boolean;
+    /**
+     * Get the MEMORY.md index content for injection into prompts.
+     */
+    getIndex(): string;
+    /**
+     * Build a prompt-friendly summary of all memories. Includes BOTH scopes
+     * (user + dream) regardless of the manager's own scope, since prompts
+     * should surface every memory the LLM might care about. Entries are
+     * tagged with their origin so the model can tell user-owned from
+     * dream-generated.
+     */
+    buildMemoryContext(): string;
+    /**
+     * Load every entry belonging to the given scope, without changing the
+     * manager's own scope. Used by buildMemoryContext to merge user + dream
+     * in one pass and by tools that need cross-scope visibility.
+     */
+    loadScope(scope: MemoryScope): MemoryEntry[];
+    private loadFileFromDir;
+    /**
+     * Move pre-scope flat-layout entries (entries that lived directly under
+     * <memoryRoot>/ before user/dream split) into <memoryRoot>/user/. Runs at
+     * most once per directory — subsequent constructions find no flat .md
+     * files and return immediately.
+     */
+    private migrateFlatLayout;
+    /**
+     * Lazy-build the in-memory index from disk on first use, then
+     * keep it in sync incrementally via save/delete. Avoids the
+     * O(N²) re-read of every memory file on every save.
+     */
+    private ensureIndexCache;
+    private writeIndex;
+    private slugify;
+}

package/dist/session/memory.js

@@ -0,0 +1,310 @@
+/**
+ * Memory system — persistent cross-session memory.
+ *
+ * Stores structured memory entries as individual markdown files under a base
+ * directory. Resolution order for the base directory:
+ *   1. explicit `baseDir` constructor arg
+ *   2. CODE_SHELL_HOME env var
+ *   3. ~/.code-shell
+ *
+ * Two scopes are isolated on disk:
+ *   - user/    Things the user explicitly asked to remember, plus the legacy
+ *              auto-extracted entries (extract-memories output). LLM may
+ *              only modify these through permission-gated tool calls.
+ *   - dream/   The dream pipeline's workspace. The LLM is free to add /
+ *              merge / delete entries here; user/ is read-only to dream.
+ *
+ * MEMORY.md is the index file (one per scope).
+ *
+ * Deletes are SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
+ * rather than removed, so accidental deletions are recoverable.
+ */
+import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, renameSync, statSync, } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export function resolveMemoryBaseDir(override) {
+    if (override)
+        return override;
+    const fromEnv = process.env.CODE_SHELL_HOME;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return join(homedir(), ".code-shell");
+}
+export class MemoryManager {
+    baseDir;
+    /** Root containing both scope subdirs (the "memory" dir per project/global). */
+    memoryRoot;
+    scope;
+    /** Scope-specific directory: <memoryRoot>/<scope>. */
+    memoryDir;
+    indexPath;
+    // Per-instance cache of {fileName -> {name, description}} so the
+    // index can be rewritten without re-reading every memory file
+    // every time a single entry is saved/deleted (the previous code
+    // path called loadAll() on every save, giving O(N²) total I/O).
+    // null = "not initialized yet, fall back to disk on next access."
+    indexCache = null;
+    constructor(options) {
+        // Back-compat: old signature was `new MemoryManager(projectDir?: string)`.
+        const opts = typeof options === "string" ? { projectDir: options } : (options ?? {});
+        this.baseDir = resolveMemoryBaseDir(opts.baseDir);
+        this.scope = opts.scope ?? "user";
+        if (opts.projectDir) {
+            const projectHash = opts.projectDir.replace(/[/\\:]/g, "-").replace(/^-/, "");
+            this.memoryRoot = join(this.baseDir, "projects", projectHash, "memory");
+        }
+        else {
+            this.memoryRoot = join(this.baseDir, "memory");
+        }
+        this.memoryDir = join(this.memoryRoot, this.scope);
+        this.indexPath = join(this.memoryDir, "MEMORY.md");
+        mkdirSync(this.memoryDir, { recursive: true });
+        // One-shot migration: if memoryRoot contains *.md files directly (pre-scope
+        // layout), move them into user/. Idempotent — once migrated, the root has
+        // no flat .md files and this becomes a no-op.
+        this.migrateFlatLayout();
+    }
+    getMemoryDir() { return this.memoryDir; }
+    getScope() { return this.scope; }
+    /**
+     * Save a memory entry. Creates the file and updates the index.
+     */
+    save(entry) {
+        const fileName = this.slugify(entry.name) + ".md";
+        const filePath = join(this.memoryDir, fileName);
+        const content = `---\n` +
+            `name: ${entry.name}\n` +
+            `description: ${entry.description}\n` +
+            `type: ${entry.type}\n` +
+            `---\n\n` +
+            `${entry.content}\n`;
+        writeFileSync(filePath, content, "utf-8");
+        // Incremental index update. Initialize the cache on first
+        // save by paying one loadAll() — every save after that just
+        // mutates the cache and rewrites MEMORY.md.
+        const cache = this.ensureIndexCache();
+        cache.set(fileName, { name: entry.name, description: entry.description });
+        this.writeIndex(cache);
+        return fileName;
+    }
+    /**
+     * Load all memory entries.
+     */
+    loadAll() {
+        if (!existsSync(this.memoryDir))
+            return [];
+        const files = readdirSync(this.memoryDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+        const entries = [];
+        for (const file of files) {
+            const entry = this.loadFile(file);
+            if (entry)
+                entries.push(entry);
+        }
+        return entries;
+    }
+    /**
+     * Load a single memory file.
+     */
+    loadFile(fileName) {
+        const filePath = join(this.memoryDir, fileName);
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const raw = readFileSync(filePath, "utf-8");
+            const frontmatterMatch = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+            if (!frontmatterMatch)
+                return null;
+            const frontmatter = frontmatterMatch[1];
+            const content = frontmatterMatch[2].trim();
+            const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim() ?? fileName;
+            const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim() ?? "";
+            const type = (frontmatter.match(/type:\s*(.+)/)?.[1]?.trim() ?? "project");
+            return { name, description, type, content, fileName, scope: this.scope };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Soft-delete a memory by name or filename — moves the file into
+     * <baseDir>/memory-trash/<ISO>/<scope>/ instead of unlinking it. The user
+     * can recover by moving it back; we never hard-delete from this code path.
+     */
+    delete(nameOrFile) {
+        const entries = this.loadAll();
+        const entry = entries.find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        if (!entry)
+            return false;
+        try {
+            const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const trashDir = join(this.baseDir, "memory-trash", stamp, this.scope);
+            mkdirSync(trashDir, { recursive: true });
+            renameSync(join(this.memoryDir, entry.fileName), join(trashDir, entry.fileName));
+            const cache = this.ensureIndexCache();
+            cache.delete(entry.fileName);
+            this.writeIndex(cache);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the MEMORY.md index content for injection into prompts.
+     */
+    getIndex() {
+        if (!existsSync(this.indexPath))
+            return "";
+        return readFileSync(this.indexPath, "utf-8");
+    }
+    /**
+     * Build a prompt-friendly summary of all memories. Includes BOTH scopes
+     * (user + dream) regardless of the manager's own scope, since prompts
+     * should surface every memory the LLM might care about. Entries are
+     * tagged with their origin so the model can tell user-owned from
+     * dream-generated.
+     */
+    buildMemoryContext() {
+        const userEntries = this.scope === "user"
+            ? this.loadAll()
+            : this.loadScope("user");
+        const dreamEntries = this.scope === "dream"
+            ? this.loadAll()
+            : this.loadScope("dream");
+        if (userEntries.length === 0 && dreamEntries.length === 0)
+            return "";
+        const lines = [];
+        if (userEntries.length > 0) {
+            lines.push("## User memories (you own these — needs permission to modify)");
+            for (const e of userEntries) {
+                lines.push(`- [${e.type}] ${e.name}: ${e.description}`);
+            }
+        }
+        if (dreamEntries.length > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push("## Dream memories (auto-consolidated workspace — freely modifiable)");
+            for (const e of dreamEntries) {
+                lines.push(`- [${e.type}] ${e.name}: ${e.description}`);
+            }
+        }
+        return (`# Persistent Memory\n\n` +
+            `The following memories from previous sessions may be relevant:\n\n` +
+            lines.join("\n") +
+            `\n\nTo read a specific memory, look under ${this.memoryRoot}/{user,dream}/`);
+    }
+    /**
+     * Load every entry belonging to the given scope, without changing the
+     * manager's own scope. Used by buildMemoryContext to merge user + dream
+     * in one pass and by tools that need cross-scope visibility.
+     */
+    loadScope(scope) {
+        const dir = join(this.memoryRoot, scope);
+        if (!existsSync(dir))
+            return [];
+        const files = readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+        const entries = [];
+        for (const file of files) {
+            const e = this.loadFileFromDir(dir, file, scope);
+            if (e)
+                entries.push(e);
+        }
+        return entries;
+    }
+    loadFileFromDir(dir, fileName, scope) {
+        const filePath = join(dir, fileName);
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const raw = readFileSync(filePath, "utf-8");
+            const frontmatterMatch = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+            if (!frontmatterMatch)
+                return null;
+            const frontmatter = frontmatterMatch[1];
+            const content = frontmatterMatch[2].trim();
+            const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim() ?? fileName;
+            const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim() ?? "";
+            const type = (frontmatter.match(/type:\s*(.+)/)?.[1]?.trim() ?? "project");
+            return { name, description, type, content, fileName, scope };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Move pre-scope flat-layout entries (entries that lived directly under
+     * <memoryRoot>/ before user/dream split) into <memoryRoot>/user/. Runs at
+     * most once per directory — subsequent constructions find no flat .md
+     * files and return immediately.
+     */
+    migrateFlatLayout() {
+        if (!existsSync(this.memoryRoot))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(this.memoryRoot);
+        }
+        catch {
+            return;
+        }
+        const flatFiles = entries.filter((f) => {
+            if (!f.endsWith(".md"))
+                return false;
+            try {
+                return statSync(join(this.memoryRoot, f)).isFile();
+            }
+            catch {
+                return false;
+            }
+        });
+        if (flatFiles.length === 0)
+            return;
+        const userDir = join(this.memoryRoot, "user");
+        mkdirSync(userDir, { recursive: true });
+        for (const file of flatFiles) {
+            const src = join(this.memoryRoot, file);
+            const dst = join(userDir, file);
+            if (existsSync(dst))
+                continue; // don't clobber
+            try {
+                renameSync(src, dst);
+            }
+            catch {
+                // best-effort migration; partial failure leaves user with a hybrid
+                // layout but loadScope("user") will still pick up whatever moved.
+            }
+        }
+    }
+    /**
+     * Lazy-build the in-memory index from disk on first use, then
+     * keep it in sync incrementally via save/delete. Avoids the
+     * O(N²) re-read of every memory file on every save.
+     */
+    ensureIndexCache() {
+        if (this.indexCache !== null)
+            return this.indexCache;
+        const cache = new Map();
+        for (const entry of this.loadAll()) {
+            cache.set(entry.fileName, { name: entry.name, description: entry.description });
+        }
+        this.indexCache = cache;
+        return cache;
+    }
+    writeIndex(cache) {
+        const lines = [];
+        for (const [fileName, meta] of cache) {
+            lines.push(`- [${meta.name}](${fileName}) — ${meta.description}`);
+        }
+        const content = lines.length > 0
+            ? lines.join("\n") + "\n"
+            : "(no memories stored)\n";
+        writeFileSync(this.indexPath, content, "utf-8");
+    }
+    slugify(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, "")
+            .slice(0, 60);
+    }
+}

package/dist/session/session-manager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session lifecycle manager.
+ */
+import type { SessionState } from "../types.js";
+import { Transcript } from "./transcript.js";
+export interface SessionBundle {
+    state: SessionState;
+    transcript: Transcript;
+}
+export declare class SessionManager {
+    private readonly sessionsDir;
+    constructor(storageDir?: string);
+    /**
+     * Create a new on-disk session. If `explicitSessionId` is passed, use
+     * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
+     * "tui-main" and expect us to honor it). Otherwise generate one with
+     * nanoid. Either way the on-disk directory is materialized and the
+     * state.json + transcript.jsonl files are written before return.
+     */
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string): SessionBundle;
+    /**
+     * Whether a session directory exists on disk. Used by ChatSession-driven
+     * cold starts to decide between resume vs create-with-explicit-sid
+     * without catching SessionError.
+     */
+    exists(sessionId: string): boolean;
+    resume(sessionId: string): SessionBundle;
+    saveState(state: SessionState): void;
+    /**
+     * Fork a session from a specific point.
+     * Creates a new session that shares events up to the given turn,
+     * then diverges independently.
+     */
+    fork(sourceSessionId: string, forkAtTurn?: number): SessionBundle;
+    list(limit?: number): SessionListEntry[];
+}
+export type SessionListEntry = SessionState & {
+    preview?: string;
+    /** Last activity time — transcript mtime, falling back to startedAt. */
+    lastActiveAt: number;
+};