@pellux/goodvibes-tui 1.19.6 → 1.20.0

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/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 };
+}

package/src/core/session-resume-core.ts

@@ -0,0 +1,206 @@
+/**
+ * session-resume-core.ts — the ONE resume routine both resume seams call.
+ *
+ * Two independent call sites used to duplicate (and diverge from) this
+ * sequence: `/session resume` (session-workflow.ts) and the panel/session-
+ * browser resume (bootstrap-hook-bridge.ts's `createResumeSessionHandler`).
+ * Divergences found by audit:
+ *   - the panel seam skipped `restoreTurnAnchors` (message-anchored /rewind
+ *     silently had no anchors after a panel resume)
+ *   - the panel seam skipped `conversation.resetAll()` before `fromJSON()`
+ *   - the panel seam skipped the `selectModel` reselection fallback (it set
+ *     `runtime.model` straight from the saved meta, never re-resolving
+ *     through the live provider registry)
+ *   - the panel seam duplicated the panel-reopen loop WITHOUT the
+ *     modal-redirect skip, so a MIGRATE-TO-MODAL id could pop a modal
+ *     mid-resume
+ *
+ * Both seams now call this module so those four behaviors (plus the
+ * panel-reopen-cap honesty note) are guaranteed identical by construction,
+ * not by copy-paste discipline between two files.
+ *
+ * Callers own everything ABOVE and AROUND this core sequence: printing or
+ * logging the outcome in their own idiom (`ctx.print` vs `conversation.log`),
+ * and any extra plumbing that only one seam performs (hookDispatcher.fire,
+ * sessionSpine.reopen, sharedSessionBroker.reopenSession,
+ * writeLastSessionPointer — all bootstrap-hook-bridge-only, pre-existing
+ * asymmetries out of this module's scope).
+ */
+import type { SessionManager, SessionMeta } from '@pellux/goodvibes-sdk/platform/sessions';
+import type { SessionSurface } from '@/runtime/index.ts';
+import type { ConversationManager } from './conversation.ts';
+import { restoreTurnAnchors } from './rewind-turn-anchors.ts';
+import { replayJournalForSession, type ReplayIntoConversationResult } from './session-recovery.ts';
+
+export interface SessionResumeRuntime {
+  sessionId: string;
+  model: string;
+  provider: string;
+}
+
+export interface SessionResumePanelManager {
+  open(id: string): unknown;
+  show(): void;
+  getModalRedirect(id: string): string | undefined;
+}
+
+export interface SessionResumeDeps {
+  readonly sessionManager: Pick<SessionManager, 'load' | 'save'>;
+  readonly conversation: ConversationManager;
+  readonly runtime: SessionResumeRuntime;
+  /**
+   * The app's declare-once session-storage handle. Both resume seams pass the
+   * SAME one the runtime writes through, so the anchor sidecar and the
+   * transcript journal this routine reads are guaranteed to be the files the
+   * live session actually wrote — the scope can no longer be re-guessed per
+   * seam.
+   */
+  readonly surface: SessionSurface;
+  readonly panelManager: SessionResumePanelManager;
+  /**
+   * Reselects the saved model through the live provider registry, falling
+   * back to the raw saved id on failure (a saved model may no longer exist
+   * locally). Omit to use the saved id directly without reselection.
+   */
+  readonly selectModel?: (model: string) => Promise<{ readonly registryKey: string; readonly providerId: string }>;
+  readonly hydrateSessionUsage?: () => void;
+  /**
+   * Deliberate cap on how many saved panels are reopened at once — resuming
+   * into a workspace crowded with every panel that happened to be open is
+   * its own kind of surprise. Overflow beyond the cap is reported in the
+   * outcome (`panels.notReopened`), never silently dropped. Defaults to 4.
+   */
+  readonly panelReopenLimit?: number;
+}
+
+export interface PanelReopenOutcome {
+  readonly reopened: readonly string[];
+  readonly movedToModal: readonly string[];
+  /** Saved panel ids beyond `panelReopenLimit` — not attempted, honestly reported (see /panels to open the rest). */
+  readonly notReopened: readonly string[];
+}
+
+export interface SessionResumeOutcome {
+  readonly meta: SessionMeta;
+  readonly resumedMessageCount: number;
+  readonly restoredAnchorCount: number;
+  readonly journalReplay: ReplayIntoConversationResult;
+  readonly panels: PanelReopenOutcome;
+}
+
+/**
+ * Exported so both session-workflow.ts's standalone `reopenPanelsFromReturnContext`
+ * (kept for its existing direct unit-test coverage — see
+ * session-workflow-panel-restore.test.ts) and `resumeSessionCore` below share
+ * the exact same default cap.
+ */
+export const DEFAULT_PANEL_REOPEN_LIMIT = 4;
+
+export function reopenPanelsWithModalSkip(
+  panelManager: SessionResumePanelManager,
+  openPanelIds: readonly string[] | undefined,
+  limit: number,
+): PanelReopenOutcome {
+  if (!openPanelIds || openPanelIds.length === 0) return { reopened: [], movedToModal: [], notReopened: [] };
+  const within = openPanelIds.slice(0, limit);
+  const overflow = openPanelIds.slice(limit);
+  const reopened: string[] = [];
+  const movedToModal: string[] = [];
+  for (const panelId of within) {
+    // A MIGRATE-TO-MODAL id has no panel to restore — a modal is not part of
+    // the saved panel layout. Skip it (don't pop a modal mid-resume) and note
+    // it once, rather than firing open() and revealing an empty workspace.
+    if (panelManager.getModalRedirect(panelId) !== undefined) {
+      movedToModal.push(panelId);
+      continue;
+    }
+    try {
+      panelManager.open(panelId);
+      reopened.push(panelId);
+    } catch {
+      // Ignore unknown or currently unavailable panel ids during resume.
+    }
+  }
+  if (reopened.length > 0) panelManager.show();
+  return { reopened, movedToModal, notReopened: overflow };
+}
+
+/**
+ * The canonical resume sequence: load, reset + restore the conversation,
+ * restore rewind anchors, replay any post-snapshot journal records, hydrate
+ * footer usage, reselect the model, and reopen saved panels (modal-redirect
+ * aware, cap honestly reported).
+ */
+export async function resumeSessionCore(sessionId: string, deps: SessionResumeDeps): Promise<SessionResumeOutcome> {
+  const { meta, messages } = deps.sessionManager.load(sessionId);
+
+  deps.conversation.resetAll();
+  deps.conversation.fromJSON({
+    messages: messages as never[],
+    title: meta.title,
+    titleSource: meta.titleSource,
+  });
+  deps.conversation.rebuildHistory();
+  deps.runtime.sessionId = sessionId;
+
+  // Restore this session's message-anchored rewind anchors from its sidecar
+  // so /rewind works identically before and after the resume — the in-memory
+  // registry is process-local, so a fresh process starts with none for the
+  // loaded session.
+  const restoredAnchorCount = restoreTurnAnchors(sessionId, deps.surface);
+
+  // Journal replay: recover turns that post-date the loaded snapshot.
+  const journalReplay = replayJournalForSession({
+    surface: deps.surface,
+    sessionId,
+    snapshotTimestamp: meta.timestamp ?? 0,
+    conversation: deps.conversation,
+    persistSnapshot: (replayedMessages) => {
+      deps.sessionManager.save(sessionId, replayedMessages as never[], {
+        title: deps.conversation.title || meta.title,
+        model: meta.model,
+        provider: meta.provider,
+        timestamp: Date.now(),
+        titleSource: meta.titleSource,
+        returnContext: meta.returnContext,
+        // Machinery: this write exists only to durably close the journal gap
+        // the replay just filled. The user's own save/fork/rename acts stamp
+        // 'user' at their own call sites (session-workflow.ts).
+        saveSource: 'auto',
+      });
+    },
+  });
+
+  // Hydrate the footer's token counters from the resumed (+ journal-replayed)
+  // history now, before the caller renders.
+  deps.hydrateSessionUsage?.();
+
+  if (meta.model) {
+    if (deps.selectModel) {
+      try {
+        const selected = await deps.selectModel(meta.model);
+        deps.runtime.model = selected.registryKey;
+        deps.runtime.provider = selected.providerId;
+      } catch {
+        deps.runtime.model = meta.model; // model may not exist locally
+      }
+    } else {
+      deps.runtime.model = meta.model;
+    }
+  }
+  if (meta.provider) deps.runtime.provider = meta.provider;
+
+  const panels = reopenPanelsWithModalSkip(
+    deps.panelManager,
+    meta.returnContext?.openPanels,
+    deps.panelReopenLimit ?? DEFAULT_PANEL_REOPEN_LIMIT,
+  );
+
+  return {
+    meta,
+    resumedMessageCount: deps.conversation.getMessageCount(),
+    restoredAnchorCount,
+    journalReplay,
+    panels,
+  };
+}