@pellux/goodvibes-tui 1.19.6 → 1.20.0

package/src/renderer/help-overlay.ts

@@ -1,7 +1,9 @@
 /**
  * renderHelpOverlay — renders the help overlay with keyboard shortcuts and slash commands.
  *
- * Toggle with `?` key or `/help` command.
+ * Opened via `/commands`. `?` and `/help` open the searchable command
+ * browser (a selection modal that runs the picked command) instead — they
+ * are a different, complementary surface, not this one.
  */
 
 import { type Line } from '../types/grid.ts';
@@ -68,22 +70,27 @@ export function renderHelpOverlay(
   const shortcutRows: string[] = [
     '  Core Navigation',
     '  ' + '\u2500'.repeat(40),
-    `  ${'Up / Down'.padEnd(20)}  Scroll / history recall`,
+    `  ${'Up / Down'.padEnd(20)}  Recall input history; Down at bottom focuses the process indicator`,
     `  ${'PageUp / PageDn'.padEnd(20)}  Scroll by full page`,
     `  ${kb('search').padEnd(20)}  Search conversation (Ctrl+F)`,
     '',
     '  Prompt And Editing',
     '  ' + '\u2500'.repeat(40),
-    `  ${'Enter'.padEnd(20)}  Submit message`,
+    `  ${'Enter'.padEnd(20)}  Submit message (composer empty: open the block-actions menu)`,
     `  ${'Shift+Enter'.padEnd(20)}  Insert newline`,
     `  ${kb('paste').padEnd(20)}  Paste (image priority)`,
     `  ${(kb('undo') + ' / ' + kb('redo')).padEnd(20)}  Undo / redo`,
+    shortcutLine('(paste >8 lines)', 'Folds to [TEXT: pN, M lines] — /pastes previews it before you submit'),
     '',
     '  Overlays And Panels',
     '  ' + '\u2500'.repeat(40),
-    shortcutLine('?', 'Toggle help'),
-    shortcutLine('/shortcuts', 'Full keyboard shortcuts'),
-    shortcutLine('Tab', 'Swap focus between input and workspace'),
+    shortcutLine('?  or  /help', 'Open the command browser (search & run any command)'),
+    shortcutLine('/commands', 'This reference: keyboard shortcuts + full command list'),
+    shortcutLine('/shortcuts', 'Keyboard-shortcuts-only reference (a separate, generated overlay)'),
+    // Precedence (highest first): a visible panel workspace claims Tab for
+    // focus-swap; failing that, a partial path under the cursor claims it for
+    // completion; only then does it fall through to collapse/expand.
+    shortcutLine('Tab', 'Panel focus-swap, else path-complete, else collapse/expand block'),
     ...panelBindingRows,
     '',
     // The shared in-panel contract every workspace panel honors. These are not
@@ -149,7 +156,7 @@ export function renderHelpOverlay(
     ['sessions',    'Browse and resume saved sessions'],
     ['save',        'Save the current session'],
     ['compact',     'Compact the conversation history'],
-    ['clear',       'Clear the conversation'],
+    ['clear',       'Clear the conversation display (keeps LLM context)'],
     ['keybindings', 'List and customize key bindings'],
     ['panel',       'Open, focus, or manage panels'],
   ];
@@ -197,10 +204,11 @@ export function renderHelpOverlay(
     }
   } else if (!hasCommand('help')) {
     commandRows.push('', '  Essentials', '  ' + '\u2500'.repeat(40));
-    commandRows.push('  /help               Show this help overlay');
+    commandRows.push('  /commands           Show this help overlay');
+    commandRows.push('  /help               Browse & run any command');
     commandRows.push('  /shortcuts          Keyboard shortcut reference');
     commandRows.push('  /model              Select LLM model');
-    commandRows.push('  /clear              Clear conversation');
+    commandRows.push('  /clear              Clear the conversation display (keeps LLM context)');
   }
 
   const allRows = [...shortcutRows, ...commandRows];
@@ -255,61 +263,69 @@ export function renderShortcutsOverlay(
     return `  ${keyCol}  ${desc}`;
   }
 
-  // Helper: get the label for a bindable action, falling back to literal string.
-  const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
+  // Keys that are real, but not KeyAction entries in keybindingsManager
+  // (context-dependent chords, or literal characters rather than bindable
+  // actions) \u2014 a maintained table rather than hand-picked getAll() calls, so
+  // adding a new KeyAction automatically shows up below without anyone
+  // remembering to also add a row for it here.
+  const HARDCODED_ROWS: ReadonlyArray<[key: string, desc: string]> = [
+    ['Up / Down', 'Recall input history; Down at bottom focuses the process indicator'],
+    ['PageUp / PageDn', 'Scroll by full page'],
+    ['Home / End', 'Jump to start / end of line'],
+    ['n / N (search)', 'Next / previous match'],
+    ['Mouse wheel', 'Scroll conversation or hovered panel'],
+    ['Enter', 'Submit message (composer empty: open the block-actions menu)'],
+    ['Shift+Enter', 'Insert newline'],
+    ['@', 'Open file picker'],
+    ['/', 'Slash command mode'],
+    ['Esc', 'Close overlay / cancel generation / clear prompt (context-dependent)'],
+    ['Shift+Tab', 'Cycle permission mode (auto-approve / prompt / manual)'],
+    ['F2', 'Open the Fleet panel'],
+    ['?  or  /help', 'Open the command browser (search & run any command)'],
+    // Precedence (highest first): panel focus-swap, else path-completion,
+    // else collapse/expand \u2014 see the Panels section's Tab row below for the
+    // full chain; this row is the "what does it do here" short form.
+    ['Tab', 'Collapse/expand block (composer empty \u2014 see Panels: Tab for full precedence)'],
+  ];
+
+  const IN_PANEL_ROWS: ReadonlyArray<[key: string, desc: string]> = [
+    ['j / k', 'Move selection down / up'],
+    ['g / G', 'Jump to top / bottom'],
+    ['/', 'Filter the list'],
+  ];
+
+  // Generated from the live keybindings table (default bindings AND any user
+  // overrides) so this listing can never drift from what a key actually
+  // does \u2014 no action is hand-picked, none can be silently missed.
+  const allBindings = keybindingsManager.getAll();
+  const panelActionRows = allBindings
+    .filter((entry) => entry.action.startsWith('panel-'))
+    .map((entry) => row(entry.combos.map((c) => keybindingsManager.formatCombo(c)).join(', '), entry.description));
+  const otherActionRows = allBindings
+    .filter((entry) => !entry.action.startsWith('panel-'))
+    .map((entry) => row(entry.combos.map((c) => keybindingsManager.formatCombo(c)).join(', '), entry.description));
 
   const allRows: string[] = [
-    '  Navigation',
-    '  ' + '\u2500'.repeat(40),
-    row('Up / Down', 'Scroll / history recall'),
-    row('PageUp / PageDn', 'Scroll by full page'),
-    row('Home / End', 'Jump to start / end of line'),
-    row(kb('search'), 'Search conversation'),
-    row('n / N (search)', 'Next / previous match'),
-    row('Mouse wheel', 'Scroll conversation or hovered panel'),
-    '',
-    '  Editing',
+    '  Navigation & Editing',
     '  ' + '\u2500'.repeat(40),
-    row('Enter', 'Submit message'),
-    row('Shift+Enter', 'Insert newline'),
-    row('@', 'Open file picker'),
-    row('/', 'Slash command mode'),
-    row(kb('paste'), 'Paste (image priority)'),
-    row(`${kb('undo')} / ${kb('redo')}`, 'Undo / redo'),
-    row(kb('clear-prompt'), 'Clear prompt'),
-    row(kb('delete-word'), 'Delete word backward'),
-    row(kb('kill-line'), 'Kill to end of line'),
-    row(kb('apply-diff-line-start'), 'Apply diff / line start'),
-    row(kb('next-error-line-end'), 'Next error / line end'),
+    ...HARDCODED_ROWS.map(([key, desc]) => row(key, desc)),
     '',
-    '  Actions',
+    '  Actions & Shortcuts (customize via /keybindings)',
     '  ' + '\u2500'.repeat(40),
-    row('Tab', 'Collapse/expand block'),
-    row(kb('bookmark'), 'Bookmark block'),
-    row(kb('block-copy'), 'Copy block to clipboard'),
-    row(kb('block-save'), 'Save block to file'),
-    row(kb('copy-selection'), 'Copy selection'),
-    row('F2', 'Open the Fleet panel'),
-    row('?', 'Help overlay'),
-    row(`${kb('clear-cancel')} x2`, 'Exit'),
+    ...otherActionRows,
     '',
     '  Panels',
     '  ' + '\u2500'.repeat(40),
-    row('Tab', 'Swap focus between input and panel workspace'),
-    row(kb('panel-picker'), 'Open / focus / hide panel workspace'),
-    row(kb('panel-tab-next'), 'Next workspace panel tab'),
-    row(kb('panel-tab-prev'), 'Previous workspace panel tab'),
-    row(`${kb('panel-tab-1')}\u2026${kb('panel-tab-9')}`, 'Jump to workspace tab 1-9'),
-    row(kb('panel-focus-toggle'), 'Swap focus between top / bottom pane'),
-    row(kb('panel-close'), 'Close active panel'),
-    row(kb('panel-close-all'), 'Close all panels'),
-    row(kb('panel-ops'), 'Open and focus the Fleet panel'),
+    // Full Tab precedence, stated once here as the authoritative chain: a
+    // visible panel workspace claims Tab for focus-swap first; failing that,
+    // a partial path under the cursor claims it for completion; only then
+    // does it fall through to collapse/expand (the Actions section's row).
+    row('Tab', 'Panel focus-swap (1st) > path-complete (2nd) > collapse/expand block (3rd)'),
+    ...panelActionRows,
     '',
     '  In-Panel Controls',
     '  ' + '\u2500'.repeat(40),
-    row('j / k', 'Move selection down / up'),
-    row('g / G', 'Jump to top / bottom'),
-    row('/', 'Filter the list'),
+    ...IN_PANEL_ROWS.map(([key, desc]) => row(key, desc)),
     '',
     `  Config: /keybindings to list and customize`,
   ];

package/src/renderer/selection-modal-overlay.ts

@@ -69,6 +69,41 @@ function rowCostFor(item: SelectionItem, remaining: number): number {
   return 1 + (computeDetailLayout(item, remaining).wrappedDetail?.length ?? 0);
 }
 
+const MODAL_MARGIN = 4;
+const MODAL_MAX_WIDTH = 72;
+const INDICATOR_WIDTH = 2;
+/** Rows kept clear between the box and the top/bottom of the terminal. */
+const VIEWPORT_INSET_ROWS = 2;
+
+/**
+ * Rows the box spends on its own frame, counted as they are actually pushed
+ * below: top and bottom border, the title, the section row (a search label,
+ * search input and divider when the modal searches), the "Results" header and
+ * the footer hint. `chromeRows` is the budget-math constant the surface
+ * metrics subtract from a total; this is the physical count, and it is what
+ * decides how tall the box may really grow.
+ */
+function frameRowsFor(modal: SelectionModal): number {
+  return modal.allowSearch ? 8 : 6;
+}
+
+/**
+ * Physical rows every row of the list needs, category headers included — the
+ * height the box would have to give the list for nothing to be scrolled away.
+ */
+function totalContentRowsFor(modal: SelectionModal, remaining: number): number {
+  let rows = 0;
+  let lastCategory: string | undefined;
+  for (const item of modal.filteredItems) {
+    if (item.category && item.category !== lastCategory) {
+      lastCategory = item.category;
+      rows += 1;
+    }
+    rows += rowCostFor(item, remaining);
+  }
+  return rows;
+}
+
 /**
  * Render the selection modal as Line[] for overlay in the viewport.
  */
@@ -79,9 +114,29 @@ export function renderSelectionModalOverlay(
 ): Line[] {
   const lines: Line[] = [];
   const chromeRows = modal.allowSearch ? 5 : 4;
+  // Width does not depend on the row budget, so the box layout is settled
+  // first: the list's real height can only be measured once the wrap width is
+  // known. `createOverlayBoxLayout` resolves the requested max width the same
+  // way `getOverlaySurfaceMetrics` does, so both agree on the box.
+  const layout = createOverlayBoxLayout(width, MODAL_MARGIN, MODAL_MAX_WIDTH);
+  const remaining = layout.innerWidth - INDICATOR_WIDTH;
+
+  // Size to content before falling back to the viewport's height ratio. When
+  // every row (and its wrapped detail) fits in the space the terminal
+  // actually has, ask for exactly that many rows, so a short list is never
+  // split behind a "(n below)" hint with screen still empty below the box —
+  // a two-item question in particular must always show both its answers. A
+  // list genuinely taller than the terminal keeps the ratio-derived budget
+  // and scrolls as before.
+  const neededContentRows = totalContentRowsFor(modal, remaining);
+  const fittableContentRows = viewportHeight - VIEWPORT_INSET_ROWS - frameRowsFor(modal);
+  const growToFitTotalRows = neededContentRows > 0 && neededContentRows <= fittableContentRows
+    ? neededContentRows + chromeRows
+    : undefined;
+
   const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
-    margin: 4,
-    maxWidth: 72,
+    margin: MODAL_MARGIN,
+    maxWidth: MODAL_MAX_WIDTH,
     chromeRows,
     minContentRows: 6,
     // Modals size to content: items whose detail wraps onto extra lines can
@@ -89,8 +144,11 @@ export function renderSelectionModalOverlay(
     // ceiling grows with the viewport rather than staying pinned at a small
     // constant (still bounded — never larger than the terminal can show).
     maxContentRows: Math.max(10, viewportHeight - chromeRows - 4),
+    // A floor only. The shared budget keeps its own target and ceiling, so a
+    // modal whose content is shorter than that target is unaffected: this can
+    // raise the budget to fit the list, never lower it.
+    minTotalRows: growToFitTotalRows,
   });
-  const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
 
   lines.push(createOverlayFilledBorderLine(width, layout, OVERLAY_GLYPHS.topLeft, OVERLAY_GLYPHS.horizontal, OVERLAY_GLYPHS.topRight, BORDER_FG, DEFAULT_OVERLAY_PALETTE.titleBg));
 
@@ -143,8 +201,6 @@ export function renderSelectionModalOverlay(
     putText(line, layout.margin + 2, layout.innerWidth, fitDisplay(message, layout.innerWidth), { fg: MUTED_FG, dim: true });
     lines.push(line);
   } else {
-    const indicatorWidth = 2;
-    const remaining = layout.innerWidth - indicatorWidth;
     const rowBudget = Math.max(1, metrics.contentRows);
 
     // Row-budget-aware windowing: rather than assuming one physical row per
@@ -210,12 +266,12 @@ export function renderSelectionModalOverlay(
       const detailLayout = computeDetailLayout(item, remaining);
       const labelWidth = detailLayout.labelWidth;
       const labelLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
-        putText(labelLine, layout.margin + 2, indicatorWidth, indicator, {
+        putText(labelLine, layout.margin + 2, INDICATOR_WIDTH, indicator, {
           fg: isSelected ? TITLE_FG : MUTED_FG,
           bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           bold: isSelected,
         });
-      putText(labelLine, layout.margin + 2 + indicatorWidth, labelWidth, fitDisplay(truncateDisplay(item.label, labelWidth), labelWidth), {
+      putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH, labelWidth, fitDisplay(truncateDisplay(item.label, labelWidth), labelWidth), {
         fg: labelColor,
         bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
         bold: isSelected,
@@ -223,11 +279,11 @@ export function renderSelectionModalOverlay(
       if (item.detail) {
         if (detailLayout.wrappedDetail === null) {
           // Fits beside the label at a readable width — no truncation needed.
-          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth, 2, '  ', {
+          putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH + labelWidth, 2, '  ', {
             fg: BODY_FG,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
-          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth + 2, detailLayout.detailWidth, fitDisplay(item.detail, detailLayout.detailWidth), {
+          putText(labelLine, layout.margin + 2 + INDICATOR_WIDTH + labelWidth + 2, detailLayout.detailWidth, fitDisplay(item.detail, detailLayout.detailWidth), {
             fg: detailColor,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
@@ -238,7 +294,7 @@ export function renderSelectionModalOverlay(
           lines.push(labelLine);
           for (const detailLineText of detailLayout.wrappedDetail) {
             const detailLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
-            putText(detailLine, layout.margin + 2 + indicatorWidth, remaining, fitDisplay(detailLineText, remaining), {
+            putText(detailLine, layout.margin + 2 + INDICATOR_WIDTH, remaining, fitDisplay(detailLineText, remaining), {
               fg: detailColor,
               bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
               dim: !isSelected,

package/src/renderer/shell-surface.ts

@@ -53,6 +53,14 @@ export interface ShellFooterBuildOptions {
    * below the context pressure hint.
    */
   readonly scriptableStatusLine?: string | null;
+  /**
+   * The one-key retry/switch-model affordance's transient hint text (see
+   * retry-affordance.ts). Rendered as its own line ABOVE the context
+   * pressure hint while armed; present here only means "show it now" — the
+   * caller is responsible for passing null the instant it disarms, so this
+   * is a time-bounded status line, never a lingering claim.
+   */
+  readonly retryHint?: string | null;
   /**
    * Compact footer posture for short terminals (~<30 rows). Collapses the
    * footer to its essentials (prompt box + token/cost line + help) and drops
@@ -173,6 +181,13 @@ export function buildShellFooter(
       const hintLine = UIFactory.stringToLine(options.contextStatusHint, options.width, { fg: DIM_STATUS_FG });
       lines.unshift(hintLine);
     }
+    // Retry affordance — topmost of the passive hint lines while armed (an
+    // actionable, time-bounded prompt outranks the passive status hints
+    // below it); simply absent the instant it disarms.
+    if (options.retryHint) {
+      const retryLine = UIFactory.stringToLine(options.retryHint, options.width, { fg: DIM_STATUS_FG, bold: true });
+      lines.unshift(retryLine);
+    }
   }
   lastRenderedFooterHeight = { compact: options.compact ?? false, height: lines.length };
   return { lines, height: lines.length };

package/src/renderer/tool-result-expanded-lines.ts

@@ -0,0 +1,48 @@
+/**
+ * tool-result-expanded-lines.ts — the single source of truth for how many
+ * screen lines a tool-result message's EXPANDED form actually renders to.
+ *
+ * Tool-result content gets pretty-printed (JSON.stringify(parsed, null, 2))
+ * or diff-rendered before display, so the raw message's `content.split('\n')`
+ * length is not what the user sees once expanded — a one-line JSON blob can
+ * pretty-print to 50 lines. Both the per-block "N lines" badge
+ * (conversation-rendering.ts) and the folded-group total (conversation-tool-
+ * groups.ts) must count the SAME post-render lines, or the two disagree with
+ * each other and both can disagree with what Tab actually reveals.
+ */
+
+import type { Line } from '../types/grid.ts';
+import { renderMarkdownTracked } from './markdown.ts';
+import { renderDiffView } from './diff-view.ts';
+
+/** True when `content` looks like a unified diff (matches the detection used
+ *  by renderConversationToolMessage to pick the diff block type). */
+export function isDiffContent(content: string): boolean {
+  const contentLines = content.split('\n');
+  const hasDiffHeader = contentLines.some((l) => l.startsWith('--- ')) && contentLines.some((l) => l.startsWith('+++ '));
+  const hasHunk = contentLines.some((l) => l.startsWith('@@ '));
+  return hasDiffHeader && hasHunk;
+}
+
+/**
+ * Render a tool result's content exactly as its EXPANDED form would appear in
+ * the transcript (diff view for diffs; pretty-printed JSON, when parseable,
+ * for everything else). The caller decides whether to actually display these
+ * lines or just count them.
+ */
+export function renderExpandedToolResultLines(content: string, width: number): Line[] {
+  if (isDiffContent(content)) {
+    return renderDiffView(content, width);
+  }
+  let contentToRender = 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 — falls through to the plain markdown render below.
+    }
+  }
+  return renderMarkdownTracked(contentToRender, width).lines;
+}

package/src/renderer/ui-factory.ts

@@ -624,7 +624,7 @@ export class UIFactory {
     // them; keep the elapsed timer since "how long the approval has waited" is honest.
     const speedSuffix = (!approvalPending && tokenSpeed !== undefined && tokenSpeed > 0) ? ` (${Math.round(tokenSpeed)} tok/s)` : '';
     const elapsedSuffix = elapsedMs !== undefined ? ` (${formatElapsed(elapsedMs)})` : '';
-    const ttftSuffix = (!approvalPending && ttftMs !== undefined && ttftMs > 0) ? ` ttft:${ttftMs}ms` : '';
+    const ttftSuffix = (!approvalPending && ttftMs !== undefined && ttftMs > 0) ? ` (first token ${formatElapsed(ttftMs)})` : '';
     const text = `  ${spinner} ${phrase}${speedSuffix}${elapsedSuffix}${ttftSuffix} `;
 
     const textWidth = Math.max(1, getDisplayWidth(text) - 1);

package/src/runtime/bootstrap-command-context.ts

@@ -30,7 +30,7 @@ import type { HookWorkbench } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { WorktreeRegistry } from '@/runtime/index.ts';
 import type { SandboxSessionRegistry } from '@/runtime/index.ts';
 import type { UiReadModels } from './ui-read-models.ts';
-import type { ShellPathService } from '@/runtime/index.ts';
+import type { ShellPathService, SessionSurface } from '@/runtime/index.ts';
 import type {
   ShellAgentManagerService,
   ShellAutomationManagerRuntimeService,
@@ -76,6 +76,8 @@ export type CreateBootstrapCommandContextOptions = {
   policyRuntimeState: PolicyRuntimeState;
   readModels: UiReadModels;
   shellPaths: ShellPathService;
+  /** The runtime's declare-once session-storage handle (runtime/services.ts). */
+  surface: SessionSurface;
   remoteRuntime?: RemoteCommandService;
   planRuntime?: PlanRuntimeService;
   fileUndoManager: FileUndoManager;
@@ -163,6 +165,7 @@ export function createBootstrapCommandContext(
     policyRuntimeState,
     readModels,
     shellPaths,
+    surface,
     remoteRuntime,
     planRuntime,
     fileUndoManager,
@@ -277,6 +280,7 @@ export function createBootstrapCommandContext(
     benchmarkStore,
   });
   const workspace = createBootstrapCommandWorkspaceSection({
+    surface,
     keybindingsManager,
     fileUndoManager,
     workspaceCheckpointManager,

package/src/runtime/bootstrap-command-parts.ts

@@ -32,7 +32,7 @@ import type { HookWorkbench } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { WorktreeRegistry } from '@/runtime/index.ts';
 import type { SandboxSessionRegistry } from '@/runtime/index.ts';
 import type { UiReadModels } from './ui-read-models.ts';
-import type { ShellPathService } from '@/runtime/index.ts';
+import type { ShellPathService, SessionSurface } from '@/runtime/index.ts';
 import type {
   ShellAgentManagerService,
   ShellAutomationManagerRuntimeService,
@@ -95,6 +95,8 @@ export interface BootstrapCommandSectionOptions {
   readonly policyRuntimeState: PolicyRuntimeState;
   readonly readModels: UiReadModels;
   readonly shellPaths: ShellPathService;
+  /** The runtime's declare-once session-storage handle (runtime/services.ts). */
+  readonly surface: SessionSurface;
   readonly fileUndoManager: FileUndoManager;
   readonly workspaceCheckpointManager?: WorkspaceCheckpointManager;
   readonly gatewayMethods?: GatewayMethodCatalog;
@@ -372,12 +374,13 @@ export function createBootstrapCommandProviderSection(
 export function createBootstrapCommandWorkspaceSection(
   options: Pick<
     BootstrapCommandSectionOptions,
-    'keybindingsManager' | 'fileUndoManager' | 'workspaceCheckpointManager' | 'gatewayMethods' | 'workspaceTrustManager' | 'workspaceRegistrationManager' | 'panelManager' | 'profileManager' | 'bookmarkManager'
+    'surface' | 'keybindingsManager' | 'fileUndoManager' | 'workspaceCheckpointManager' | 'gatewayMethods' | 'workspaceTrustManager' | 'workspaceRegistrationManager' | 'panelManager' | 'profileManager' | 'bookmarkManager'
     | 'projectPlanningService' | 'projectPlanningProjectId' | 'workPlanStore'
   >,
   shellServices: BootstrapCommandShellServices,
 ): BootstrapCommandWorkspaceSection {
   return {
+    surface: options.surface,
     keybindingsManager: options.keybindingsManager,
     fileUndoManager: options.fileUndoManager,
     workspaceCheckpointManager: options.workspaceCheckpointManager,

package/src/runtime/bootstrap-core.ts

@@ -350,7 +350,7 @@ export async function initializeBootstrapCore(
 
   const toolRegistry = new ToolRegistry();
   const { fileCache, projectIndex } = registerAllTools(toolRegistry, {
-    surfaceRoot: 'tui',
+    surfaceRoot: services.surface.surfaceRoot,
     localhostFetchApproval: services.localhostFetchApproval, // loopback-fetch ask, built once in the services composition
     execPromptAnswerHandler: services.execPromptAnswerHandler, // terminal prompt-answer path, built once in the services composition
     fileUndoManager: services.fileUndoManager,
@@ -384,7 +384,7 @@ export async function initializeBootstrapCore(
   });
   // Note: installWrfcAgentToolGuard is called after routeOrBuffer is defined (further below) so the onTrace callback routes guard decisions through the pre-router buffer.
   services.agentOrchestrator.setDependencies({
-    surfaceRoot: 'tui',
+    surfaceRoot: services.surface.surfaceRoot,
     // setDependencies is a wholesale replace: re-install the prompt-answer handler and the loopback-fetch ask here or this rewire silently drops them.
     execPromptAnswerHandler: services.execPromptAnswerHandler,
     localhostFetchApproval: services.localhostFetchApproval,
@@ -507,7 +507,7 @@ export async function initializeBootstrapCore(
 
   // ── WRFC chain persistence ──────────────────────────────────────────────────────────
   const wrfcPersistence = createWrfcPersistence({
-    snapshotPath: join(workingDir, '.goodvibes', 'tui', 'wrfc-chains.json'),
+    snapshotPath: join(workingDir, '.goodvibes', services.surface.surfaceRoot, 'wrfc-chains.json'),
     getSystemMessageRouter: () => systemMessageRouterRef.value,
     controller: services.wrfcController,
   });

package/src/runtime/bootstrap-hook-bridge.ts

@@ -14,7 +14,8 @@ import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-import { replayJournalForSession } from '../core/session-recovery.ts';
+import { resumeSessionCore } from '../core/session-resume-core.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
 
 export interface ResumeSessionOptions {
   readonly runtimeBus: RuntimeEventBus;
@@ -31,77 +32,94 @@ export interface ResumeSessionOptions {
   readonly hookDispatcher: HookDispatcher;
   readonly sessionManager: SessionManager;
   readonly panelManager: PanelManager;
+  /** The app's declare-once session-storage handle — the same one /session resume threads. */
+  readonly surface: SessionSurface;
+  /**
+   * Multi-instance guard for this seam. Resolves false when the operator
+   * declines to fork a session another terminal still has open. Optional so a
+   * host without a modal surface keeps the seam's original behavior.
+   */
+  readonly confirmLiveResume?: (sessionId: string) => Promise<boolean>;
   readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
   readonly providerRegistry: Pick<ProviderRegistry, 'get' | 'getCurrentModel' | 'getForModel' | 'require' | 'resolveModelPricing'>;
-  readonly homeDirectory: string;
   /** See CommandSessionServices.hydrateSessionUsage (command-registry.ts). */
   readonly hydrateSessionUsage?: () => void;
+  /**
+   * Reselects the resumed session's saved model through the live provider
+   * registry (matches session-workflow.ts's `/session resume` reselection
+   * fallback — see core/session-resume-core.ts). Optional so a caller without
+   * a provider API wired still gets the direct-assignment behavior this seam
+   * always had.
+   */
+  readonly selectModel?: (model: string) => Promise<{ readonly registryKey: string; readonly providerId: string }>;
 }
 
-export function createResumeSessionHandler(options: ResumeSessionOptions): (sessionId: string) => void {
-  return (sessionId: string): void => {
+/**
+ * Delegates the mechanical resume sequence to resumeSessionCore (the same
+ * routine session-workflow.ts's `/session resume` calls) so the two seams
+ * cannot diverge on restoreTurnAnchors, resetAll-before-fromJSON, model
+ * reselection, or the modal-redirect panel-reopen skip — see
+ * core/session-resume-core.ts's header doc for the full list of divergences
+ * this closes. Everything below the resumeSessionCore call is plumbing only
+ * this seam performs (hook fire, session-spine mirror, shared-broker
+ * reopen, last-session pointer) plus this seam's own log/render idiom.
+ */
+export function createResumeSessionHandler(options: ResumeSessionOptions): (sessionId: string) => Promise<void> {
+  return async (sessionId: string): Promise<void> => {
     try {
-      const { messages, meta } = options.sessionManager.load(sessionId);
+      // Multi-instance safety, matching what `/session resume` already does
+      // for the text path: never fork a session another terminal is holding
+      // open without the operator saying so.
+      if (options.confirmLiveResume && !(await options.confirmLiveResume(sessionId))) {
+        options.conversation.log('Resume cancelled — the session is still open in another terminal.', { fg: '244' });
+        options.requestRender();
+        return;
+      }
+      // Pre-read purely for the emitSessionResumed announcement's turnCount,
+      // which reports the raw saved-snapshot size — resumeSessionCore performs
+      // its own load() right after this (SessionManager.load is a cheap JSONL
+      // parse; the tiny duplicate read keeps this announcement's meaning
+      // unchanged rather than repurposing it to a post-replay count).
+      const { messages: rawMessages } = options.sessionManager.load(sessionId);
       emitSessionResumed(options.runtimeBus, {
         sessionId: options.runtime.sessionId,
         traceId: `${options.runtime.sessionId}:session-resume:${sessionId}`,
         source: 'bootstrap',
       }, {
         sessionId,
-        turnCount: messages.length,
-      });
-      options.conversation.fromJSON({
-        messages: messages as Parameters<typeof options.conversation.fromJSON>[0]['messages'],
-        title: meta.title,
-        titleSource: meta.titleSource,
+        turnCount: rawMessages.length,
       });
-      options.runtime.sessionId = sessionId;
-      replayJournalForSession({
-        homeDirectory: options.homeDirectory,
-        sessionId,
-        snapshotTimestamp: meta.timestamp ?? 0,
+
+      const outcome = await resumeSessionCore(sessionId, {
+        sessionManager: options.sessionManager,
         conversation: options.conversation,
-        persistSnapshot: (replayedMessages) => {
-          options.sessionManager.save(sessionId, replayedMessages as never[], {
-            title: options.conversation.title || meta.title,
-            model: meta.model,
-            provider: meta.provider,
-            timestamp: Date.now(),
-            titleSource: meta.titleSource,
-            returnContext: meta.returnContext,
-          });
-        },
+        runtime: options.runtime,
+        surface: options.surface,
+        panelManager: options.panelManager,
+        selectModel: options.selectModel,
+        hydrateSessionUsage: options.hydrateSessionUsage,
       });
-      // Hydrate the footer's token counters from the resumed history now that
-      // fromJSON()/journal replay are both applied — before requestRender() below.
-      options.hydrateSessionUsage?.();
+      const { meta, panels } = outcome;
+
       options.onSessionIdChanged?.(sessionId);
-      if (meta?.model) options.runtime.model = meta.model;
-      if (meta?.provider) options.runtime.provider = meta.provider;
       options.writeLastSessionPointer(sessionId);
       void options.sharedSessionBroker.reopenSession(sessionId).catch((err) => { logger.debug('session broker reopen session failed', { err }); });
       // Fire-and-forget spine mirror (reopen:true — the user resume verb).
       options.sessionSpine.reopen({ sessionId, project: options.project, title: options.conversation.title || meta.title });
       options.conversation.log(`Resumed session: ${sessionId}`, { fg: '135' });
-      const reopenedPanels: string[] = [];
-      if (meta.returnContext?.openPanels?.length) {
-        for (const panelId of meta.returnContext.openPanels.slice(0, 4)) {
-          try {
-            options.panelManager.open(panelId);
-            reopenedPanels.push(panelId);
-          } catch {
-            // Ignore unavailable panels during restore.
-          }
-        }
-        if (reopenedPanels.length > 0) options.panelManager.show();
+      if (panels.movedToModal.length > 0) {
+        options.conversation.log(`Resume: ${panels.movedToModal.join(', ')} moved to a modal — reopen via its command instead of as a panel.`, { fg: '244' });
+      }
+      if (panels.notReopened.length > 0) {
+        options.conversation.log(`Resume: …and ${panels.notReopened.length} more not reopened (/panels to open)`, { fg: '244' });
       }
       const returnContextMode = getReturnContextMode(options.configManager);
       if (returnContextMode !== 'off' && meta.returnContext) {
         for (const line of formatReturnContextForDisplay(meta.returnContext)) {
           options.conversation.log(`Resume: ${line}`, { fg: '244' });
         }
-        if (reopenedPanels.length > 0) {
-          options.conversation.log(`Resume: Reopened panels: ${reopenedPanels.join(', ')}`, { fg: '244' });
+        if (panels.reopened.length > 0) {
+          options.conversation.log(`Resume: Reopened panels: ${panels.reopened.join(', ')}`, { fg: '244' });
         }
         if ((meta.returnContext.remoteRunners?.length ?? 0) > 0) {
           options.conversation.log(`Resume: Remote re-entry -> /remote recover ${meta.returnContext.remoteRunners![0]}`, { fg: '244' });