@prestyj/cli 5.10.0 → 5.12.0

package/dist/core/session-manager.js

@@ -5,6 +5,7 @@ import crypto from "node:crypto";
 import { environmentSecrets, redactValue, } from "@prestyj/ai";
 import { log } from "./logger.js";
 import { encodeCwd } from "./encode-cwd.js";
+import { getUserSessionPrompt } from "./session-preview.js";
 import { archiveColdSession, archiveSessionPath, cleanupOldSessionTemps, COLD_SESSION_AGE_DAYS, emptyStorageNormalizationMetrics, hydrateSessionEntry, isSessionPath, normalizeSessionEntryForStorage, openSessionReadStream, plainSessionPath, resolveSessionPath, sessionAssetDir, thawSessionArchive, } from "./session-storage.js";
 export const DISPLAY_ITEM_CUSTOM_KIND = "display_item";
 export const TURN_METRIC_CUSTOM_KIND = "turn_metric";
@@ -71,12 +72,29 @@ export const AUTOPILOT_MARKER_CUSTOM_KIND = "autopilot_marker";
  *  so the LLM never sees it, anchored by `afterMessageCount` so the host can
  *  interleave it back into the transcript on resume. */
 export const APP_MARKER_CUSTOM_KIND = "app_transcript_marker";
+/**
+ * Run journal — a matched pair of custom entries bracketing every provider run.
+ *
+ * Same not-on-the-DAG treatment as Nolan turns (`parentId: null`): the model never
+ * sees them, and they can't race the message branch's leaf pointer. A
+ * `run_started` with no matching `run_finished` is the on-disk signature of a
+ * run that died mid-flight — the host surfaces it on load instead of silently
+ * resuming work whose tools already half-mutated the repo.
+ *
+ * `generation` is the `RunLifecycle` generation, so the pairing inherits that
+ * class's generation-safety: a stale run cannot close a newer one's journal.
+ */
+export const RUN_STARTED_CUSTOM_KIND = "run_started";
+export const RUN_FINISHED_CUSTOM_KIND = "run_finished";
 function isCompletedItemLike(value) {
     return (typeof value === "object" &&
         value !== null &&
         typeof value.kind === "string" &&
         typeof value.id === "string");
 }
+const COMPACTION_COORDINATION_DIR = ".compaction-coordination";
+const CORRUPT_LEASE_STALE_MS = 60_000;
+const LEASE_POLL_MS = 50;
 // ── Session Manager ────────────────────────────────────────
 export class SessionManager {
     static activePathsByRoot = new Map();
@@ -88,6 +106,115 @@ export class SessionManager {
     constructor(sessionsDir) {
         this.sessionsDir = path.resolve(sessionsDir);
     }
+    coordinationKey(conversationId) {
+        return crypto.createHash("sha256").update(conversationId).digest("hex");
+    }
+    coordinationRoot() {
+        return path.join(this.sessionsDir, COMPACTION_COORDINATION_DIR);
+    }
+    async leaseOwner(lockPath) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf-8"));
+            return typeof parsed.token === "string" &&
+                typeof parsed.pid === "number" &&
+                typeof parsed.createdAt === "string"
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    processIsAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== "ESRCH";
+        }
+    }
+    async waitForLease(signal) {
+        if (signal?.aborted)
+            throw new DOMException("Aborted", "AbortError");
+        await new Promise((resolve, reject) => {
+            const finish = () => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            const timer = setTimeout(finish, LEASE_POLL_MS);
+            const onAbort = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            timer.unref?.();
+        });
+    }
+    /** Serialize compaction work across processes for one logical conversation. */
+    async withCompactionLease(conversationId, signal, work) {
+        const root = this.coordinationRoot();
+        await fs.mkdir(root, { recursive: true });
+        const lockPath = path.join(root, `${this.coordinationKey(conversationId)}.lock`);
+        const token = crypto.randomUUID();
+        while (true) {
+            try {
+                await fs.mkdir(lockPath);
+                const owner = {
+                    token,
+                    pid: process.pid,
+                    createdAt: new Date().toISOString(),
+                };
+                await fs.writeFile(path.join(lockPath, "owner.json"), JSON.stringify(owner), "utf-8");
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const owner = await this.leaseOwner(lockPath);
+                const stat = await fs.stat(lockPath).catch(() => null);
+                const corruptAndOld = !owner && stat !== null && Date.now() - stat.mtimeMs > CORRUPT_LEASE_STALE_MS;
+                const deadOwner = owner !== null && !this.processIsAlive(owner.pid);
+                if (deadOwner || corruptAndOld) {
+                    await fs.rm(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+                await this.waitForLease(signal);
+            }
+        }
+        try {
+            return await work();
+        }
+        finally {
+            const owner = await this.leaseOwner(lockPath);
+            if (owner?.token === token)
+                await fs.rm(lockPath, { recursive: true, force: true });
+        }
+    }
+    async readCompactionAttemptState(conversationId) {
+        const statePath = path.join(this.coordinationRoot(), `${this.coordinationKey(conversationId)}.state.json`);
+        try {
+            const state = JSON.parse(await fs.readFile(statePath, "utf-8"));
+            return typeof state.fingerprint === "string" &&
+                typeof state.policyKey === "string" &&
+                ["success", "failed", "noop"].includes(state.outcome) &&
+                typeof state.updatedAt === "string"
+                ? state
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeCompactionAttemptState(conversationId, state) {
+        const root = this.coordinationRoot();
+        await fs.mkdir(root, { recursive: true });
+        const statePath = path.join(root, `${this.coordinationKey(conversationId)}.state.json`);
+        const temporaryPath = `${statePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+        await fs.writeFile(temporaryPath, JSON.stringify(state), "utf-8");
+        await fs.rename(temporaryPath, statePath);
+    }
     /**
      * Session persistence must never crash a live session. Disk-full (ENOSPC),
      * permission, or quota errors during transcript writes are reported once
@@ -124,6 +251,12 @@ export class SessionManager {
             version: 2,
             id,
             conversationId: options?.conversationId ?? id,
+            generation: options?.generation ?? 0,
+            ...(options?.parentSessionId ? { parentSessionId: options.parentSessionId } : {}),
+            ...(options?.sourceFingerprint ? { sourceFingerprint: options.sourceFingerprint } : {}),
+            ...(typeof options?.retainedMessageCount === "number"
+                ? { retainedMessageCount: options.retainedMessageCount }
+                : {}),
             ...(safePreview ? { preview: safePreview } : {}),
             timestamp,
             cwd,
@@ -163,48 +296,119 @@ export class SessionManager {
     async load(sessionPath) {
         // Resuming is a write operation, so transparently thaw a gzip archive and
         // return the effective plain path every future append must use.
-        const effectivePath = await thawSessionArchive(sessionPath);
-        const { stream } = await openSessionReadStream(effectivePath);
+        const canonicalPath = (await this.resolveCanonicalSession(sessionPath)) ?? sessionPath;
+        const effectivePath = await thawSessionArchive(canonicalPath);
+        return this.loadPhysicalCheckpoint(effectivePath);
+    }
+    /**
+     * Load the contiguous checkpoint ancestry ending at the canonical newest file.
+     *
+     * The returned order is oldest → newest. A missing, corrupt, cyclic, or
+     * cross-conversation parent stops traversal at the oldest readable checkpoint,
+     * allowing display callers to retain that checkpoint's compaction summary as a
+     * fallback. Parent archives are read in place rather than thawed because this
+     * API is for history reconstruction, not resuming writes.
+     */
+    async loadCheckpointChain(sessionPath) {
+        const requestedSummary = await this.readSessionSummary(sessionPath);
+        // A resumed session can compact under a different cwd than its parent (for
+        // example, a remote ACP client reconnecting from another workspace). The
+        // physical ancestry is therefore machine-wide, not confined to the newest
+        // checkpoint's encoded-cwd directory.
+        const directories = await this.storageDirectories();
+        const candidates = (await Promise.all(directories.map((directory) => this.sessionCandidates(directory)))).flat();
+        const summaries = (await Promise.all(candidates.map((candidate) => this.readSessionSummary(candidate)))).filter((summary) => summary !== null);
+        const requestedIdentity = requestedSummary?.conversationId ??
+            summaries.find((summary) => summary.id === sessionPath)?.conversationId;
+        const newestSummary = requestedIdentity
+            ? summaries
+                .filter((summary) => summary.conversationId === requestedIdentity)
+                .sort((left, right) => SessionManager.compareCheckpoints(right, left))[0]
+            : undefined;
+        const newestPath = newestSummary?.path ?? sessionPath;
+        // Resuming the newest checkpoint is a write operation, so thaw only that
+        // generation. Historical parents stay archived and read-only.
+        const newest = await this.loadPhysicalCheckpoint(await thawSessionArchive(newestPath));
+        const newestConversationId = newest.header.conversationId ?? newest.header.id;
+        const byPhysicalId = new Map(summaries.map((summary) => [summary.id, summary.path]));
+        const newestResolvedPath = path.resolve(newest.path);
+        const visited = new Set([newest.header.id]);
+        const chain = [newest];
+        let current = newest;
+        while (current.header.parentSessionId) {
+            const parentId = current.header.parentSessionId;
+            if (visited.has(parentId))
+                break;
+            const parentPath = byPhysicalId.get(parentId);
+            if (!parentPath || path.resolve(parentPath) === newestResolvedPath)
+                break;
+            try {
+                const parent = await this.loadPhysicalCheckpoint(parentPath, true);
+                if ((parent.header.conversationId ?? parent.header.id) !== newestConversationId)
+                    break;
+                visited.add(parentId);
+                chain.unshift(parent);
+                current = parent;
+            }
+            catch {
+                break;
+            }
+        }
+        return chain;
+    }
+    async loadPhysicalCheckpoint(sessionPath, rejectMalformedLines = false) {
+        const effectivePath = await resolveSessionPath(sessionPath);
+        const { stream, close } = await openSessionReadStream(effectivePath);
         let header = null;
         const entries = [];
         const rl = createInterface({ input: stream, crlfDelay: Infinity });
-        for await (const line of rl) {
-            if (!line)
-                continue;
-            try {
-                const parsed = JSON.parse(line);
-                if (parsed.type === "session") {
-                    if (parsed.version === 2) {
-                        header = parsed;
+        // rejectMalformedLines can throw mid-transcript; close() on the way out.
+        try {
+            for await (const line of rl) {
+                if (!line)
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed.type === "session") {
+                        if (parsed.version === 2) {
+                            header = parsed;
+                        }
+                        else {
+                            const v1 = parsed;
+                            header = {
+                                type: "session",
+                                version: 2,
+                                id: v1.id,
+                                conversationId: v1.id,
+                                generation: 0,
+                                timestamp: v1.timestamp,
+                                cwd: v1.cwd,
+                                provider: v1.provider,
+                                model: v1.model,
+                                leafId: null,
+                            };
+                        }
+                        continue;
                     }
-                    else {
-                        const v1 = parsed;
-                        header = {
-                            type: "session",
-                            version: 2,
-                            id: v1.id,
-                            conversationId: v1.id,
-                            timestamp: v1.timestamp,
-                            cwd: v1.cwd,
-                            provider: v1.provider,
-                            model: v1.model,
-                            leafId: null,
-                        };
+                    const entry = parsed;
+                    if (entry.type === "message" && !entry.id) {
+                        entry.id = crypto.randomUUID();
+                        entry.parentId = null;
                     }
-                    continue;
+                    entries.push(await hydrateSessionEntry(entry, effectivePath));
                 }
-                const entry = parsed;
-                if (entry.type === "message" && !entry.id) {
-                    entry.id = crypto.randomUUID();
-                    entry.parentId = null;
+                catch (error) {
+                    if (rejectMalformedLines)
+                        throw error;
+                    // Skip malformed JSON lines — cold migration preserves their raw bytes
+                    // so a future recovery tool still has a chance to repair them.
                 }
-                entries.push(await hydrateSessionEntry(entry, effectivePath));
-            }
-            catch {
-                // Skip malformed JSON lines — cold migration preserves their raw bytes
-                // so a future recovery tool still has a chance to repair them.
             }
         }
+        finally {
+            rl.close();
+            close();
+        }
         if (!header) {
             throw new Error(`Invalid session file: no header found in ${sessionPath}`);
         }
@@ -213,30 +417,50 @@ export class SessionManager {
     async readSessionInfo(candidatePath) {
         try {
             const resolvedPath = await resolveSessionPath(candidatePath);
-            const { stream } = await openSessionReadStream(resolvedPath);
+            const { stream, close } = await openSessionReadStream(resolvedPath);
             const rl = createInterface({ input: stream, crlfDelay: Infinity });
             let first = null;
             let messageCount = 0;
             let lastActivity = null;
-            for await (const line of rl) {
-                if (!line)
-                    continue;
-                try {
-                    const parsed = JSON.parse(line);
-                    if (!first) {
-                        if (parsed.type !== "session")
-                            break;
-                        first = parsed;
+            let preview;
+            try {
+                for await (const line of rl) {
+                    if (!line)
+                        continue;
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (!first) {
+                            if (parsed.type !== "session")
+                                break;
+                            first = parsed;
+                            // v2 headers usually carry the preview already; when they do,
+                            // nothing below has to look for one.
+                            preview = parsed.preview?.trim() || undefined;
+                        }
+                        else if (parsed.type === "message") {
+                            messageCount += 1;
+                            if (parsed.timestamp)
+                                lastActivity = parsed.timestamp;
+                            // Recover a title for the sessions whose header predates `preview`.
+                            // Free here: this pass already reads every line. `getUserSessionPrompt`
+                            // rejects compaction summaries and autopilot/status injections, so a
+                            // session is titled by what its user actually asked.
+                            if (!preview && parsed.message?.role === "user") {
+                                preview =
+                                    getUserSessionPrompt(parsed.message.content, parsed.message.provenance)
+                                        ?.replace(/\s+/g, " ")
+                                        .trim() || undefined;
+                            }
+                        }
                     }
-                    else if (parsed.type === "message") {
-                        messageCount += 1;
-                        if (parsed.timestamp)
-                            lastActivity = parsed.timestamp;
+                    catch {
+                        // Skip malformed lines while retaining readable entries around them.
                     }
                 }
-                catch {
-                    // Skip malformed lines while retaining readable entries around them.
-                }
+            }
+            finally {
+                rl.close();
+                close();
             }
             if (!first || first.type !== "session")
                 return null;
@@ -245,11 +469,13 @@ export class SessionManager {
                 conversationId: first.version === 2
                     ? (first.conversationId ?? first.id)
                     : first.id,
+                generation: first.version === 2 ? (first.generation ?? 0) : 0,
                 path: resolvedPath,
                 timestamp: first.timestamp,
                 lastActivity: lastActivity ?? first.timestamp,
                 cwd: first.cwd,
                 messageCount,
+                ...(preview ? { preview: preview.slice(0, 100) } : {}),
             };
         }
         catch {
@@ -266,9 +492,95 @@ export class SessionManager {
         }
         return files.filter(isSessionPath).map((file) => path.join(directory, file));
     }
-    async list(cwd) {
-        const candidates = await this.sessionCandidates(this.dirForCwd(cwd));
-        const summaries = await Promise.all(candidates.map((file) => this.readSessionInfo(file)));
+    /**
+     * Read just enough of a session file to summarize it.
+     *
+     * Stops at the first user prompt (or the first message, when the header
+     * already carries a preview) instead of parsing the whole transcript — this
+     * is what makes listing every session on the machine cheap. Files whose
+     * first user message is far down (long tool runs before the user speaks)
+     * are capped rather than allowed to stall the list.
+     */
+    async readSessionSummary(candidatePath) {
+        try {
+            const resolvedPath = await resolveSessionPath(candidatePath);
+            const { stream, close } = await openSessionReadStream(resolvedPath);
+            const rl = createInterface({ input: stream, crlfDelay: Infinity });
+            let first = null;
+            let preview;
+            let hasMessages = false;
+            let lines = 0;
+            const MAX_SCAN_LINES = 500;
+            try {
+                for await (const line of rl) {
+                    if (!line)
+                        continue;
+                    if (++lines > MAX_SCAN_LINES)
+                        break;
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (!first) {
+                            if (parsed.type !== "session")
+                                break;
+                            first = parsed;
+                            preview = parsed.preview?.trim() || undefined;
+                        }
+                        else if (parsed.type === "message") {
+                            hasMessages = true;
+                            // Header preview + any message: done. Otherwise keep scanning for
+                            // the first user-authored prompt to title by.
+                            if (preview)
+                                break;
+                            if (parsed.message?.role === "user") {
+                                preview =
+                                    getUserSessionPrompt(parsed.message.content, parsed.message.provenance)
+                                        ?.replace(/\s+/g, " ")
+                                        .trim() || undefined;
+                                if (preview)
+                                    break;
+                            }
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines while retaining readable entries around them.
+                    }
+                }
+            }
+            finally {
+                // close() destroys the gunzip AND its source. Destroying only the
+                // stream orphans the underlying fd — this listing runs over every
+                // session on the machine, so that leaked one fd per archive per call.
+                rl.close();
+                close();
+            }
+            if (!first || first.type !== "session")
+                return null;
+            const stat = await fs.stat(resolvedPath);
+            return {
+                id: first.id,
+                conversationId: first.version === 2
+                    ? (first.conversationId ?? first.id)
+                    : first.id,
+                generation: first.version === 2 ? (first.generation ?? 0) : 0,
+                path: resolvedPath,
+                timestamp: first.timestamp,
+                lastActivity: stat.mtime.toISOString(),
+                cwd: first.cwd,
+                hasMessages,
+                ...(preview ? { preview: preview.slice(0, 100) } : {}),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Keep the newest file per conversation and sort newest first.
+     *
+     * A conversation can span several files (compaction forks a fresh one), so
+     * without this collapse a resumed thread appears once per checkpoint.
+     */
+    static dedupeByConversation(summaries) {
         const byConversation = new Map();
         const seenResolvedPaths = new Set();
         for (const summary of summaries) {
@@ -276,25 +588,109 @@ export class SessionManager {
                 continue;
             seenResolvedPaths.add(summary.path);
             const current = byConversation.get(summary.conversationId);
-            if (!current || summary.lastActivity > current.lastActivity) {
-                const { conversationId: _conversationId, ...info } = summary;
-                byConversation.set(summary.conversationId, info);
+            if (!current || SessionManager.compareCheckpoints(summary, current) > 0) {
+                byConversation.set(summary.conversationId, summary);
             }
         }
-        return [...byConversation.values()].sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
+        return [...byConversation.values()]
+            .sort((a, b) => b.lastActivity.localeCompare(a.lastActivity) ||
+            b.timestamp.localeCompare(a.timestamp) ||
+            b.path.localeCompare(a.path))
+            .map(({ conversationId: _conversationId, generation: _generation, ...info }) => info);
+    }
+    static compareCheckpoints(left, right) {
+        return ((left.generation ?? 0) - (right.generation ?? 0) ||
+            left.lastActivity.localeCompare(right.lastActivity) ||
+            left.timestamp.localeCompare(right.timestamp) ||
+            left.path.localeCompare(right.path));
+    }
+    async list(cwd) {
+        return this.summarize(await this.sessionCandidates(this.dirForCwd(cwd)));
+    }
+    /**
+     * One project's sessions, newest first, using the early-exit summary read.
+     *
+     * For callers that render a list rather than exact message counts — on a
+     * project with hundreds of sessions this is the difference between instant
+     * and a noticeable stall.
+     */
+    async listSummaries(cwd) {
+        const candidates = await this.sessionCandidates(this.dirForCwd(cwd));
+        const summaries = await Promise.all(candidates.map((file) => this.readSessionSummary(file)));
+        return SessionManager.dedupeByConversation(summaries);
+    }
+    /**
+     * Every session on this machine, across every project, newest first.
+     *
+     * A remote client is not browsing one checkout the way the TUI is — it is
+     * asking "what have I been working on?", and the answer spans projects. Each
+     * entry carries its own `cwd`, so the caller can group by project. Uses the
+     * early-exit summary read, because "every session on the machine" is exactly
+     * where a full parse of each file becomes a multi-second stall.
+     */
+    async listAllSummaries() {
+        const directories = await this.storageDirectories();
+        const candidates = await Promise.all(directories.map((directory) => this.sessionCandidates(directory)));
+        const summaries = await Promise.all(candidates.flat().map((file) => this.readSessionSummary(file)));
+        return SessionManager.dedupeByConversation(summaries);
+    }
+    /**
+     * Summarize session files, keeping the newest file per conversation.
+     *
+     * A conversation can span several files (compaction forks a fresh one), so
+     * without this collapse a resumed thread appears once per checkpoint.
+     */
+    async summarize(candidates) {
+        const summaries = await Promise.all(candidates.map((file) => this.readSessionInfo(file)));
+        return SessionManager.dedupeByConversation(summaries);
     }
     async getMostRecent(cwd) {
         const sessions = await this.list(cwd);
         return sessions.find((session) => session.messageCount > 0)?.path ?? null;
     }
+    /** Resolve an id, conversation id, or stale physical path to the newest checkpoint. */
+    async resolveCanonicalSession(requested, cwd) {
+        const looksLikePath = path.isAbsolute(requested) || requested.includes(path.sep) || isSessionPath(requested);
+        let candidates;
+        let requestedSummary = null;
+        if (looksLikePath) {
+            requestedSummary = await this.readSessionSummary(requested);
+            if (!requestedSummary)
+                return null;
+            candidates = await this.sessionCandidates(path.dirname(requestedSummary.path));
+        }
+        else if (cwd) {
+            candidates = await this.sessionCandidates(this.dirForCwd(cwd));
+        }
+        else {
+            const directories = await this.storageDirectories();
+            candidates = (await Promise.all(directories.map((dir) => this.sessionCandidates(dir)))).flat();
+        }
+        const summaries = (await Promise.all(candidates.map((candidate) => this.readSessionSummary(candidate)))).filter((summary) => summary !== null);
+        if (requestedSummary && !summaries.some((summary) => summary.path === requestedSummary?.path)) {
+            summaries.push(requestedSummary);
+        }
+        const identityMatches = requestedSummary
+            ? [requestedSummary]
+            : summaries.filter((summary) => summary.id === requested || summary.conversationId === requested);
+        if (identityMatches.length === 0)
+            return null;
+        const requestedIdentity = identityMatches.sort((a, b) => SessionManager.compareCheckpoints(b, a))[0].conversationId;
+        const checkpoints = summaries.filter((summary) => summary.conversationId === requestedIdentity);
+        return (checkpoints.sort((a, b) => SessionManager.compareCheckpoints(b, a))[0]?.path ??
+            identityMatches[0].path);
+    }
     async findById(cwd, sessionId) {
-        const candidates = await this.sessionCandidates(this.dirForCwd(cwd));
-        for (const candidate of candidates) {
-            const summary = await this.readSessionInfo(candidate);
-            if (summary?.id === sessionId || summary?.conversationId === sessionId)
-                return summary.path;
+        return this.resolveCanonicalSession(sessionId, cwd);
+    }
+    /** Locate and canonicalize a session identity across every project directory. */
+    async findAnyById(sessionId, cwd) {
+        if (cwd) {
+            const local = await this.resolveCanonicalSession(sessionId, cwd);
+            if (local)
+                return local;
         }
-        return null;
+        return this.resolveCanonicalSession(sessionId);
     }
     async storageDirectories() {
         let entries;
@@ -305,7 +701,7 @@ export class SessionManager {
             return [];
         }
         return entries
-            .filter((entry) => entry.isDirectory())
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
             .map((entry) => path.join(this.sessionsDir, entry.name));
     }
     async logicalSessionBases(directory) {
@@ -471,6 +867,84 @@ export class SessionManager {
         };
         await this.appendEntry(sessionPath, entry);
     }
+    /** Open the run journal for one `RunLifecycle` generation. */
+    async appendRunStarted(sessionPath, payload) {
+        await this.appendEntry(sessionPath, {
+            type: "custom",
+            kind: RUN_STARTED_CUSTOM_KIND,
+            id: crypto.randomUUID(),
+            parentId: null,
+            timestamp: new Date().toISOString(),
+            data: payload,
+        });
+    }
+    /** Close the run journal for one generation. Its absence marks a crashed run. */
+    async appendRunFinished(sessionPath, payload) {
+        await this.appendEntry(sessionPath, {
+            type: "custom",
+            kind: RUN_FINISHED_CUSTOM_KIND,
+            id: crypto.randomUUID(),
+            parentId: null,
+            timestamp: new Date().toISOString(),
+            data: payload,
+        });
+    }
+    /**
+     * Reconstruct the run journal in file order, pairing each `run_started` with
+     * the `run_finished` carrying the same generation.
+     *
+     * Generations are NOT unique across a session file. `RunLifecycle` counts
+     * from zero per instance, and a resumed session builds a fresh one — so the
+     * first run after every app restart is generation 1 again. Pairing therefore
+     * tracks only the runs still OPEN: a `run_finished` closes its generation and
+     * releases the number, and a later `run_started` reusing it opens a new run.
+     *
+     * Without that release, a crash in a resumed session was invisible: the
+     * reused `run_started` looked like a duplicate and was dropped, which is
+     * exactly the case this journal exists to catch.
+     *
+     * A repeat `run_started` for a generation that is still open IS ignored, so a
+     * truncated or replayed log reports one unfinished run — never a phantom pile.
+     */
+    getRunJournal(entries) {
+        const runs = [];
+        const openByGeneration = new Map();
+        for (const entry of entries) {
+            if (entry.type !== "custom")
+                continue;
+            if (entry.kind === RUN_STARTED_CUSTOM_KIND) {
+                const p = entry.data;
+                if (p?.version !== 1 || typeof p.generation !== "number")
+                    continue;
+                if (openByGeneration.has(p.generation))
+                    continue;
+                const run = {
+                    generation: p.generation,
+                    startedAt: typeof p.startedAt === "string" ? p.startedAt : entry.timestamp,
+                    afterMessageCount: typeof p.afterMessageCount === "number" ? p.afterMessageCount : 0,
+                };
+                openByGeneration.set(p.generation, run);
+                runs.push(run);
+                continue;
+            }
+            if (entry.kind === RUN_FINISHED_CUSTOM_KIND) {
+                const p = entry.data;
+                if (p?.version !== 1 || typeof p.generation !== "number")
+                    continue;
+                const run = openByGeneration.get(p.generation);
+                if (!run || !p.outcome)
+                    continue;
+                run.outcome = p.outcome;
+                // Closed — the number is free for the next app run to reuse.
+                openByGeneration.delete(p.generation);
+            }
+        }
+        return runs;
+    }
+    /** Runs that opened the journal but never closed it — i.e. crashed mid-flight. */
+    getUnfinishedRuns(entries) {
+        return this.getRunJournal(entries).filter((run) => run.outcome === undefined);
+    }
     async updateLeaf(sessionPath, leafId) {
         try {
             const writablePath = await thawSessionArchive(sessionPath);
@@ -540,11 +1014,36 @@ export class SessionManager {
             return isCompletedItemLike(item) ? [item] : [];
         });
     }
+    /**
+     * Walk entries in file order, tracking how many branch (non-system) messages
+     * have been written so far, and hand each custom entry that count. This is
+     * the independent position estimate behind {@link RecordedPosition}.
+     */
+    mapCustomEntriesInFileOrder(entries, leafId, project) {
+        // Only branch messages count — an off-branch fork's entries are not part of
+        // the restored transcript the anchors are measured against.
+        const onBranch = leafId
+            ? new Set(this.getBranch(entries, leafId).map((e) => e.id))
+            : new Set(entries.map((e) => e.id));
+        const out = [];
+        let messagesSoFar = 0;
+        for (const entry of entries) {
+            if (entry.type === "message") {
+                if (onBranch.has(entry.id) && entry.message.role !== "system")
+                    messagesSoFar++;
+                continue;
+            }
+            if (entry.type !== "custom")
+                continue;
+            out.push(...project(entry, messagesSoFar));
+        }
+        return out;
+    }
     /** Read all persisted Nolan turns in file order. Returns them regardless of
      *  branch (Nolan turns are not chained into the DAG), validated + normalized. */
-    getNolanTurns(entries) {
-        return entries.flatMap((entry) => {
-            if (entry.type !== "custom" || entry.kind !== NOLAN_TURN_CUSTOM_KIND)
+    getNolanTurns(entries, leafId) {
+        return this.mapCustomEntriesInFileOrder(entries, leafId, (entry, recordedAfterMessageCount) => {
+            if (entry.kind !== NOLAN_TURN_CUSTOM_KIND)
                 return [];
             const p = entry.data;
             if (p?.version === 1 && typeof p.question === "string" && typeof p.reply === "string") {
@@ -554,6 +1053,7 @@ export class SessionManager {
                         question: p.question,
                         reply: p.reply,
                         afterMessageCount: typeof p.afterMessageCount === "number" ? p.afterMessageCount : 0,
+                        recordedAfterMessageCount,
                     },
                 ];
             }
@@ -562,9 +1062,9 @@ export class SessionManager {
     }
     /** Read all persisted app transcript markers in file order, validated +
      *  normalized (same not-on-the-DAG treatment as Nolan turns). */
-    getAppMarkers(entries) {
-        return entries.flatMap((entry) => {
-            if (entry.type !== "custom" || entry.kind !== APP_MARKER_CUSTOM_KIND)
+    getAppMarkers(entries, leafId) {
+        return this.mapCustomEntriesInFileOrder(entries, leafId, (entry, recordedAfterMessageCount) => {
+            if (entry.kind !== APP_MARKER_CUSTOM_KIND)
                 return [];
             const p = entry.data;
             const kind = p?.kind;
@@ -574,13 +1074,17 @@ export class SessionManager {
                     kind === "error" ||
                     kind === "user_hint" ||
                     kind === "compaction" ||
-                    kind === "agent_handoff")) {
+                    kind === "agent_handoff" ||
+                    kind === "model_switch" ||
+                    kind === "import" ||
+                    kind === "interrupted_run")) {
                 return [
                     {
                         version: 1,
                         kind,
                         afterMessageCount: typeof p.afterMessageCount === "number" ? p.afterMessageCount : 0,
                         data: typeof p.data === "object" && p.data !== null ? p.data : {},
+                        recordedAfterMessageCount,
                     },
                 ];
             }
@@ -598,9 +1102,9 @@ export class SessionManager {
     }
     /** Read all persisted autopilot markers in file order, validated + normalized
      *  (same not-on-the-DAG treatment as Nolan turns). */
-    getAutopilotMarkers(entries) {
-        return entries.flatMap((entry) => {
-            if (entry.type !== "custom" || entry.kind !== AUTOPILOT_MARKER_CUSTOM_KIND)
+    getAutopilotMarkers(entries, leafId) {
+        return this.mapCustomEntriesInFileOrder(entries, leafId, (entry, recordedAfterMessageCount) => {
+            if (entry.kind !== AUTOPILOT_MARKER_CUSTOM_KIND)
                 return [];
             const p = entry.data;
             const phase = p?.phase;
@@ -617,6 +1121,7 @@ export class SessionManager {
                         ...(typeof p.reason === "string" ? { reason: p.reason } : {}),
                         ...(typeof p.body === "string" ? { body: p.body } : {}),
                         afterMessageCount: typeof p.afterMessageCount === "number" ? p.afterMessageCount : 0,
+                        recordedAfterMessageCount,
                     },
                 ];
             }