@pellux/goodvibes-tui 1.19.6 → 1.20.1

package/src/core/conversation-line-cache.ts

@@ -323,7 +323,7 @@ export class MessageLineCache {
     // turn under a single collapsible header (see conversation-tool-groups.ts).
     // Computed once per pass, over the same slice+offset appendConversationMessages
     // would see, so both entry points fold identically.
-    const toolGroupMembership = computeToolGroupMembership(messages, msgIndexOffset);
+    const toolGroupMembership = computeToolGroupMembership(messages, msgIndexOffset, width);
     const renderContext: ConversationRenderContext = { ...context, completedToolCallIds, toolGroupMembership };
 
     const touched = new Set<number>();

package/src/core/conversation-rendering.ts

@@ -1,6 +1,6 @@
 import { UIFactory } from '../renderer/ui-factory.ts';
 import { renderMarkdownTracked } from '../renderer/markdown.ts';
-import { renderDiffView } from '../renderer/diff-view.ts';
+import { isDiffContent, renderExpandedToolResultLines } from '../renderer/tool-result-expanded-lines.ts';
 import { activeTheme, activeUiTones } from '../renderer/theme.ts';
 import { renderToolCallBlock } from '../renderer/tool-call.ts';
 import { summarizeToolResult } from '../renderer/tool-result-summary.ts';
@@ -207,8 +207,34 @@ export function renderConversationAssistantMessage(
     const thinkingStartLine = context.history.getLineCount();
     const thinkingBlockIdx = context.blockRegistry.length;
     const thinkingCollapseKey = `msg_${msgIdx}_thinking`;
-    const thinkingLines = renderThinkingBlock(message.reasoningContent, width);
-    context.history.addLines(thinkingLines);
+    // Collapsed by default, like every other collapsible block — Tab (or the
+    // block-actions menu) expands it via the same collapseKey the BlockMeta
+    // below registers. Previously this key was registered but never
+    // consulted: the toggle existed but did nothing.
+    const isThinkingCollapsed = context.collapseState.has(thinkingCollapseKey)
+      ? context.collapseState.get(thinkingCollapseKey)!
+      : true;
+    if (!context.collapseState.has(thinkingCollapseKey)) {
+      context.collapseState.set(thinkingCollapseKey, true);
+    }
+    if (isThinkingCollapsed) {
+      const thinkingLineCount = message.reasoningContent.split('\n').length;
+      const rendered = renderConversationCollapsedFragment(
+        `thinking · ${thinkingLineCount} line${thinkingLineCount === 1 ? '' : 's'}`,
+        width,
+        {
+          prefix: ' ▌ ',
+          prefixFg: T.reasoningAccent,
+          text: '244',
+          bodyBg: T.collapsedBodyBg,
+          dim: true,
+        },
+      );
+      context.history.addLines(rendered);
+    } else {
+      const thinkingLines = renderThinkingBlock(message.reasoningContent, width);
+      context.history.addLines(thinkingLines);
+    }
     context.history.addLine(createEmptyLine(width));
     const thinkingRenderedLines = context.history.getLineCount() - thinkingStartLine;
     context.blockRegistry.push({
@@ -340,6 +366,30 @@ export function isFoldedGroupMember(
   return membership !== undefined && !membership.isFirst && (collapseState.get(membership.groupKey) ?? true);
 }
 
+/**
+ * Dedupe a group's per-member tool names into a compact, honest summary —
+ * "read×3 exec write" rather than either a bare count or a full repeated
+ * list. Truncates with an honest "…+N more" tail rather than silently
+ * dropping names once the list gets long.
+ */
+function summarizeToolNames(names: readonly string[]): string {
+  const counts = new Map<string, number>();
+  const order: string[] = [];
+  for (const name of names) {
+    if (!counts.has(name)) {
+      counts.set(name, 0);
+      order.push(name);
+    }
+    counts.set(name, counts.get(name)! + 1);
+  }
+  const MAX_SHOWN = 4;
+  const parts = order.map((name) => (counts.get(name)! > 1 ? `${name}×${counts.get(name)}` : name));
+  if (parts.length > MAX_SHOWN) {
+    return `${parts.slice(0, MAX_SHOWN).join(' ')} …+${parts.length - MAX_SHOWN} more`;
+  }
+  return parts.join(' ');
+}
+
 /**
  * Render the synthetic header line for a folded run of >=2 tool-result
  * messages: one line + one BlockMeta (type 'tool_group'), shared by every
@@ -363,6 +413,7 @@ function renderToolGroupHeader(
 
   const blockIdx = context.blockRegistry.length;
   const startLine = context.history.getLineCount();
+  const toolNamesSummary = summarizeToolNames(membership.toolNames);
   context.history.addLine(renderConversationEventLine(width, {
     marker: GLYPHS.surface.altCursor,
     markerFg: T.toolAccent,
@@ -371,6 +422,7 @@ function renderToolGroupHeader(
     detailFg: '244',
   }, [
     { text: ` ${membership.toolCount} tool${membership.toolCount === 1 ? '' : 's'} `, fg: T.toolAccent },
+    ...(toolNamesSummary ? [{ text: ` ${toolNamesSummary} `, fg: T.toolNameFg }] : []),
     { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${membership.totalLines} line${membership.totalLines === 1 ? '' : 's'} `, fg: '244', dim: true },
   ]));
 
@@ -380,7 +432,7 @@ function renderToolGroupHeader(
     type: 'tool_group',
     startLine,
     lineCount: 1,
-    rawContent: `${membership.toolCount} tool result${membership.toolCount === 1 ? '' : 's'} folded (${membership.totalLines} line${membership.totalLines === 1 ? '' : 's'} total)`,
+    rawContent: `${membership.toolCount} tool result${membership.toolCount === 1 ? '' : 's'} folded (${toolNamesSummary}, ${membership.totalLines} line${membership.totalLines === 1 ? '' : 's'} total)`,
     groupMemberIndexes: membership.memberIndexes,
   });
 
@@ -409,14 +461,18 @@ export function renderConversationToolMessage(
   const blockIdx = context.blockRegistry.length;
   const startLine = context.history.getLineCount();
   const contentLines = message.content.split('\n');
-  const lineCount = contentLines.length;
-  const hasDiffHeader = contentLines.some((l) => l.startsWith('--- ')) && contentLines.some((l) => l.startsWith('+++ '));
-  const hasHunk = contentLines.some((l) => l.startsWith('@@ '));
-  const isDiff = hasDiffHeader && hasHunk;
+  const isDiff = isDiffContent(message.content);
   const blockType: 'diff' | 'tool' = isDiff ? 'diff' : 'tool';
   // Parsed once, ahead of the collapse check, so it's available for the
   // block-registry meta merge below regardless of collapsed/expanded state.
   const diffParse = isDiff ? parseDiffForApply(message.content) : undefined;
+  // The EXPANDED render, computed unconditionally (even while collapsed) so
+  // the header's "N lines" badge always names what Tab would actually reveal
+  // — a raw JSON blob that pretty-prints to 50 lines must say 50, not 1, even
+  // while it's still folded. Reused below as the actual body when expanded,
+  // so this is never rendered twice.
+  const expandedLines = renderExpandedToolResultLines(message.content, width);
+  const lineCount = expandedLines.length;
 
   // Human one-line summary for tool results (write/read/exec/edit): shown as the
   // collapsed line so the transcript reads "wrote foo.txt (532 B)" instead of a
@@ -485,22 +541,11 @@ export function renderConversationToolMessage(
       dim: true,
     });
     context.history.addLines(rendered);
-  } else if (isDiff) {
-    // No filename banner: the diff text's own --- / +++ headers already
-    // identify the file (matches the pre-v0.9.6 call site in tool-call.ts).
-    context.history.addLines(renderDiffView(message.content, width));
   } else {
-    let contentToRender = message.content;
-    const trimmed = contentToRender.trimStart();
-    if ((trimmed.startsWith('{') || trimmed.startsWith('[')) && contentToRender.length < 100_000) {
-      try {
-        const parsed = JSON.parse(contentToRender);
-        contentToRender = `\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``;
-      } catch {
-        // Leave invalid JSON as-is.
-      }
-    }
-    context.history.addLines(renderMarkdownTracked(contentToRender, width).lines);
+    // Diff or plain result — either way this is exactly `expandedLines`,
+    // already computed above (and already what the header's line count is
+    // honest about), so there is nothing left to render here.
+    context.history.addLines(expandedLines);
   }
 
   const renderedLineCount = context.history.getLineCount() - startLine;
@@ -511,6 +556,7 @@ export function renderConversationToolMessage(
     startLine,
     lineCount: renderedLineCount,
     rawContent: message.content,
+    toolName: message.toolName,
   };
 
   if (isDiff && diffParse) {
@@ -545,7 +591,7 @@ export function appendConversationMessages(
   // unless the caller already supplied membership (the line-cache path
   // computes it once per renderInto call and threads it through).
   const toolGroupMembership = renderContext.toolGroupMembership
-    ?? computeToolGroupMembership(messages, msgIndexOffset);
+    ?? computeToolGroupMembership(messages, msgIndexOffset, width);
   const groupedContext: ConversationRenderContext = renderContext.toolGroupMembership !== undefined
     ? renderContext
     : { ...renderContext, toolGroupMembership };

package/src/core/conversation-tool-groups.ts

@@ -21,6 +21,7 @@
  */
 
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import { renderExpandedToolResultLines } from '../renderer/tool-result-expanded-lines.ts';
 
 type Message = ConversationMessageSnapshot;
 
@@ -44,10 +45,15 @@ export interface ToolGroupMembership {
   readonly isFirst: boolean;
   /** Matched tool-result messages in the group (the header's "N tools"). */
   readonly toolCount: number;
-  /** Sum of each member's raw content line count (the header's "N lines") —
-   *  the same count each member already shows on its own "N lines" badge, so
-   *  the group total is honest by construction, not an estimate. */
+  /** Sum of each member's EXPANDED render line count (the header's "N lines") —
+   *  the same post-render count each member's own "N lines" badge shows, so
+   *  the group total matches what expanding every member actually reveals,
+   *  not a raw-content estimate (a folded JSON result can pretty-print to far
+   *  more lines than its raw content has). */
   readonly totalLines: number;
+  /** Each member's tool name, in order (falls back to 'tool' when a result
+   *  carries no name) — the header dedupes these into e.g. "read×3 exec". */
+  readonly toolNames: readonly string[];
   /**
    * Absolute indexes of every tool-result message in the group, in order —
    * the same list for every member. Carried onto the group's BlockMeta so a
@@ -58,10 +64,6 @@ export interface ToolGroupMembership {
   readonly memberIndexes: readonly number[];
 }
 
-function rawLineCount(content: string): number {
-  return content.split('\n').length;
-}
-
 /**
  * Scan `messages` for assistant-message runs of >=2 consecutive matching
  * tool-result messages. A run breaks on the first message that isn't a
@@ -103,19 +105,28 @@ export function detectToolGroups(
   return groups;
 }
 
-/** Build the per-tool-message membership lookup used by the renderer/cache. */
+/** Build the per-tool-message membership lookup used by the renderer/cache.
+ *  `width` must match the width the transcript is actually rendered at — it
+ *  feeds the same expanded-render line count each member's own badge uses
+ *  (see renderExpandedToolResultLines), so the group total is never computed
+ *  against a different width than what the member badges show. */
 export function buildToolGroupMembership(
   groups: readonly ToolGroup[],
   messages: readonly Message[],
   indexOffset: number,
+  width: number,
 ): ReadonlyMap<number, ToolGroupMembership> {
   const membership = new Map<number, ToolGroupMembership>();
   for (const group of groups) {
     const groupKey = `group_${group.assistantIdx}`;
     let totalLines = 0;
+    const toolNames: string[] = [];
     for (const absIdx of group.toolMessageIndexes) {
       const message = messages[absIdx - indexOffset];
-      if (message && message.role === 'tool') totalLines += rawLineCount(message.content);
+      if (message && message.role === 'tool') {
+        totalLines += renderExpandedToolResultLines(message.content, width).length;
+        toolNames.push(message.toolName ?? 'tool');
+      }
     }
     group.toolMessageIndexes.forEach((absIdx, idx) => {
       membership.set(absIdx, {
@@ -123,6 +134,7 @@ export function buildToolGroupMembership(
         isFirst: idx === 0,
         toolCount: group.toolMessageIndexes.length,
         totalLines,
+        toolNames,
         memberIndexes: group.toolMessageIndexes,
       });
     });
@@ -134,6 +146,7 @@ export function buildToolGroupMembership(
 export function computeToolGroupMembership(
   messages: readonly Message[],
   indexOffset = 0,
+  width = 80,
 ): ReadonlyMap<number, ToolGroupMembership> {
-  return buildToolGroupMembership(detectToolGroups(messages, indexOffset), messages, indexOffset);
+  return buildToolGroupMembership(detectToolGroups(messages, indexOffset), messages, indexOffset, width);
 }

package/src/core/conversation-types.ts

@@ -39,4 +39,13 @@ export type BlockMeta = Omit<SdkBlockMeta, 'type'> & {
    * individually while the group stays collapsed.
    */
   groupMemberIndexes?: readonly number[];
+  /**
+   * The tool call's name, when this block renders a 'tool' result (or is the
+   * header of a 'tool_group' whose members share a run — the header carries
+   * the first member's name). Used to name the block honestly in action
+   * receipts (e.g. "tool result: exec") — see describeBlockForReceipt in
+   * handler-content-actions.ts. Undefined for non-tool block types and for
+   * standalone tool results with no recorded name.
+   */
+  toolName?: string;
 };

package/src/core/conversation-user-receipts.ts

@@ -0,0 +1,42 @@
+/**
+ * conversation-user-receipts.ts — tracks which system-role message indices
+ * are a direct receipt for an explicit user action (e.g. answering the
+ * startup recovery modal's Resume/Keep/Remove choice), as opposed to ambient
+ * boot chatter (provider registration, the resume notice, etc.). Kept in its
+ * own file so ConversationManager (core/conversation.ts) — already near its
+ * line-count gate — doesn't have to carry the bookkeeping inline.
+ *
+ * ConversationManager.rebuildHistory()'s splash-vs-transcript check consults
+ * this via ConversationManager.addUserActionReceipt(): a receipt the user is
+ * actively waiting on must displace the splash the way a user message does,
+ * while quiet startup plumbing keeps rendering underneath it. Indices mirror
+ * messageKindRegistry's own lifecycle — cleared on resetAll(), purged for
+ * indices an undo() frees for reuse, deleted when a later add overwrites the
+ * same recycled index with a non-receipt message.
+ */
+export class UserReceiptIndices {
+  private readonly indices = new Set<number>();
+
+  add(index: number): void {
+    this.indices.add(index);
+  }
+
+  delete(index: number): void {
+    this.indices.delete(index);
+  }
+
+  has(index: number): boolean {
+    return this.indices.has(index);
+  }
+
+  clear(): void {
+    this.indices.clear();
+  }
+
+  /** Drop every tracked index >= minIndex — mirrors undo()'s tail-splice. */
+  purgeFrom(minIndex: number): void {
+    for (const key of this.indices) {
+      if (key >= minIndex) this.indices.delete(key);
+    }
+  }
+}

package/src/core/conversation.ts

@@ -14,6 +14,7 @@ import {
 } from '@pellux/goodvibes-sdk/platform/core';
 import type { BlockMeta } from './conversation-types.ts';
 import { MessageLineCache } from './conversation-line-cache.ts';
+import { UserReceiptIndices } from './conversation-user-receipts.ts';
 import {
   addConversationSplashScreen,
   conversationTextToLines,
@@ -139,6 +140,8 @@ export class ConversationManager extends SdkConversationManager {
   private errorLineRegistry: number[] = [];
   /** Maps message index → SystemMessageKind for system-role messages. */
   private messageKindRegistry: Map<number, SystemMessageKind> = new Map();
+  /** See conversation-user-receipts.ts. */
+  private userReceiptIndices = new UserReceiptIndices();
   /** Streaming block start line in history buffer (for incremental streaming update). */
   private streamingStartLine = -1;
   /**
@@ -221,25 +224,21 @@ export class ConversationManager extends SdkConversationManager {
     // stale kind (e.g. 'operational') and silently mis-classify the new message.
     const nextIndex = this.getMessageSnapshot().length;
     this.messageKindRegistry.delete(nextIndex);
+    this.userReceiptIndices.delete(nextIndex);
     super.addSystemMessage(content);
     this.markDirty();
   }
 
   /**
-   * addTypedSystemMessage - Add a system message with an explicit kind tag.
-   * The kind is stored in messageKindRegistry (keyed by the message index that
-   * will be assigned after the push) so that renderConversationSystemMessage
-   * can use it instead of text-based pattern matching.
-   *
-   * Called by SystemMessageRouter.routeTypedSystemMessage when routing to the
-   * conversation surface. Falls back to addSystemMessage for callers that do
-   * not have kind information.
+   * addTypedSystemMessage - System message with an explicit kind tag, stored
+   * in messageKindRegistry. `isUserReceipt` (conversation-user-receipts.ts)
+   * additionally marks it for rebuildHistory()'s splash check — only for a
+   * direct receipt to an explicit user action, never ambient boot chatter.
    */
-  public addTypedSystemMessage(content: string, kind: SystemMessageKind): void {
-    // getMessageSnapshot().length is the index this message will receive after
-    // addSystemMessage appends it to the messages array.
+  public addTypedSystemMessage(content: string, kind: SystemMessageKind, opts?: { isUserReceipt?: boolean }): void {
     const nextIndex = this.getMessageSnapshot().length;
     this.messageKindRegistry.set(nextIndex, kind);
+    if (opts?.isUserReceipt) this.userReceiptIndices.add(nextIndex); else this.userReceiptIndices.delete(nextIndex);
     super.addSystemMessage(content);
     this.markDirty();
   }
@@ -256,6 +255,7 @@ export class ConversationManager extends SdkConversationManager {
       for (const key of this.messageKindRegistry.keys()) {
         if (key >= postUndoCount) this.messageKindRegistry.delete(key);
       }
+      this.userReceiptIndices.purgeFrom(postUndoCount);
       this.markDirty();
     }
     return result;
@@ -357,6 +357,7 @@ export class ConversationManager extends SdkConversationManager {
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
     this.messageKindRegistry = new Map();
+    this.userReceiptIndices.clear();
     this.streamingStartLine = -1;
     this._displayFromMessageIndex = 0; // full reset — show everything on next render
   }
@@ -478,12 +479,14 @@ export class ConversationManager extends SdkConversationManager {
     const displayStart = this._displayFromMessageIndex;
     const visibleSnapshot = displayStart > 0 ? renderSnapshot.slice(displayStart) : renderSnapshot;
 
-    // Tool messages ARE rendered (as collapsed blocks); this filter is only
-    // for determining whether to show the splash screen (tool-only messages
-    // don't count as visible conversation content for splash purposes).
-    const displayMessages = visibleSnapshot.filter(
-      (m) => m.role !== 'tool' && m.role !== 'system',
-    );
+    // Tool/system messages aren't visible splash-purposes content, except a
+    // system message in userReceiptIndices. visibleSnapshot mirrors the
+    // snapshot 1:1 (only front-sliced), so index i is absolute displayStart+i.
+    const displayMessages = visibleSnapshot.filter((m, i) => {
+      if (m.role === 'tool') return false;
+      if (m.role === 'system') return this.userReceiptIndices.has(displayStart + i);
+      return true;
+    });
 
     if (displayMessages.length === 0 && displayStart === 0 && !this.suppressSplash) {
       this.addSplashScreen(width);

package/src/core/rewind-turn-anchors.ts

@@ -23,9 +23,8 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+import type { SessionSurface } from '@/runtime/index.ts';
 
-const { getUserSessionsDir } = operations;
 
 /** One recorded turn boundary — the rewind coordinator's per-turn anchor. */
 export interface TurnAnchor {
@@ -87,18 +86,18 @@ export function clearTurnAnchors(sessionId: string): void {
 // --- Cross-resume persistence -------------------------------------------------
 //
 // The TUI mirrors the in-memory registry to a sidecar next to the session file.
-// Surface is always 'tui' (the sessions the TUI reads/writes live under the same
-// scoped directory), matching how the session JSONL itself is persisted.
-const ANCHOR_SIDECAR_SURFACE = 'tui';
+// The directory comes off the caller's SessionSurface (`surface.sessionsDir`),
+// the same handle the session JSONL itself is written through — so the sidecar
+// and its session can never end up in different directories.
 const ANCHOR_SIDECAR_VERSION = 1;
 
 /** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
-function anchorSidecarPath(sessionId: string, workingDirectory: string): string | null {
-  if (!sessionId || !workingDirectory) return null;
+function anchorSidecarPath(sessionId: string, surface: SessionSurface): string | null {
+  if (!sessionId || !surface.sessionsDir) return null;
   // A sessionId is a filename component; refuse anything with path separators so
   // a malformed id can never escape the sessions directory.
   if (/[\\/]/.test(sessionId)) return null;
-  return join(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), `${sessionId}.anchors.json`);
+  return join(surface.sessionsDir, `${sessionId}.anchors.json`);
 }
 
 function isTurnAnchor(value: unknown): value is TurnAnchor {
@@ -118,13 +117,13 @@ function isTurnAnchor(value: unknown): value is TurnAnchor {
  * torn write must never break the turn that triggered it. Called after each
  * `recordTurnAnchor` at TURN_COMPLETED.
  */
-export function persistTurnAnchors(sessionId: string, workingDirectory: string): void {
-  const path = anchorSidecarPath(sessionId, workingDirectory);
+export function persistTurnAnchors(sessionId: string, surface: SessionSurface): void {
+  const path = anchorSidecarPath(sessionId, surface);
   if (!path) return;
   const list = registry.get(sessionId) ?? [];
   if (list.length === 0) return; // nothing to mirror yet
   try {
-    mkdirSync(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), { recursive: true });
+    mkdirSync(surface.sessionsDir, { recursive: true });
     const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
     const tmp = `${path}.tmp-${process.pid}`;
     writeFileSync(tmp, payload);
@@ -140,8 +139,8 @@ export function persistTurnAnchors(sessionId: string, workingDirectory: string):
  * unreadable). Idempotent via `recordTurnAnchor`'s per-turnId dedup, so a resume
  * that later re-records the same turn keeps a single entry.
  */
-export function restoreTurnAnchors(sessionId: string, workingDirectory: string): number {
-  const path = anchorSidecarPath(sessionId, workingDirectory);
+export function restoreTurnAnchors(sessionId: string, surface: SessionSurface): number {
+  const path = anchorSidecarPath(sessionId, surface);
   if (!path || !existsSync(path)) return 0;
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8')) as { anchors?: unknown };

package/src/core/session-recovery.ts

@@ -35,6 +35,7 @@
 import { journalPathFor, openTranscriptJournal, replayJournal } from './transcript-journal.ts';
 import type { ConversationManager } from './conversation.ts';
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import type { SessionSurface } from '@/runtime/index.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -145,9 +146,65 @@ export function replayJournalIntoConversation(
  */
 export function replayJournalForSession(
   options: Omit<ReplayIntoConversationOptions, 'journalPath'> & {
-    readonly homeDirectory: string;
+    readonly surface: SessionSurface;
   },
 ): ReplayIntoConversationResult {
-  const journalPath = journalPathFor(options.homeDirectory, options.sessionId);
+  const journalPath = journalPathFor(options.surface, options.sessionId);
   return replayJournalIntoConversation({ ...options, journalPath });
 }
+
+// ─── Prompted crash-snapshot restore ────────────────────────────────────────
+
+/** What a crash-recovery snapshot carries back from disk. */
+export interface RecoverySnapshotPayload {
+  readonly messages: Array<Record<string, unknown>>;
+  readonly title?: string | undefined;
+  readonly titleSource?: string | undefined;
+  readonly timestamp?: number | undefined;
+}
+
+export interface ApplyRecoverySnapshotResult {
+  /** Messages the conversation holds once the snapshot (plus any journal tail) is in place. */
+  readonly messageCount: number;
+  /** Journal records that post-dated the snapshot and were folded in on top of it. */
+  readonly journalReplay: ReplayIntoConversationResult;
+}
+
+/**
+ * Apply a crash-recovery snapshot the user explicitly asked to resume.
+ *
+ * This is deliberately the same sequence `resumeSessionCore` runs for a saved
+ * session — reset, fromJSON, rebuildHistory, then fold in any journal records
+ * newer than the snapshot — with one difference: the messages come from the
+ * recovery file the SDK just handed back (`consumeRecovery`) instead of the
+ * session store, because a session that crashed before its first clean save
+ * has no entry in the store to load. Nothing here decides WHETHER to restore;
+ * the caller has already asked the user (see runtime/recovery-prompt.ts).
+ */
+export function applyRecoverySnapshot(options: {
+  readonly snapshot: RecoverySnapshotPayload;
+  readonly sessionId: string;
+  readonly conversation: ConversationManager;
+  readonly surface: SessionSurface;
+  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
+}): ApplyRecoverySnapshotResult {
+  const { snapshot, sessionId, conversation, surface, persistSnapshot } = options;
+
+  conversation.resetAll();
+  conversation.fromJSON({
+    messages: snapshot.messages as never[],
+    title: snapshot.title,
+    titleSource: snapshot.titleSource as never,
+  });
+  conversation.rebuildHistory();
+
+  const journalReplay = replayJournalForSession({
+    surface,
+    sessionId,
+    snapshotTimestamp: snapshot.timestamp ?? 0,
+    conversation,
+    persistSnapshot,
+  });
+
+  return { messageCount: conversation.getMessageCount(), journalReplay };
+}