@pellux/goodvibes-tui 0.26.0 → 0.28.0

package/src/renderer/panel-workspace-bar.ts

@@ -1,21 +1,26 @@
 import type { Line } from '../types/grid.ts';
 import type { WorkspaceTab } from '../panels/panel-manager.ts';
-import { renderTabStrip } from './tab-strip.ts';
+import { renderTabStrip, type TabHitRegion } from './tab-strip.ts';
+import { UI_TONES } from './ui-primitives.ts';
 
-const ACTIVE_FG = '#e2e8f0';
-const ACTIVE_BG = '#0f172a';
-const INACTIVE_FG = '#94a3b8';
-const SEPARATOR_FG = '238';
-const LABEL_FG = '#cbd5e1';
-const LABEL_BG = '#1e293b';
+// Theme tokens (no raw hex) — keeps the bar in sync with the shared palette.
+const ACTIVE_FG = UI_TONES.fg.primary;       // selected tab text
+const ACTIVE_BG = UI_TONES.bg.selected;      // selected tab fill (stronger contrast)
+const INACTIVE_FG = UI_TONES.fg.muted;       // unselected tabs
+const SEPARATOR_FG = UI_TONES.fg.dim;        // │ separators
+const LABEL_FG = UI_TONES.fg.secondary;      // PANELS prefix label
+const LABEL_BG = UI_TONES.bg.title;          // prefix label background when focused
+const FOCUS_ACCENT_FG = UI_TONES.state.active; // the one focused tab
 
 export function renderPanelWorkspaceBar(
   tabs: readonly WorkspaceTab[],
   width: number,
   focused: boolean,
+  onLayout?: (regions: readonly TabHitRegion[]) => void,
 ): Line {
   return renderTabStrip({
     width,
+    onLayout,
     tabs: tabs.map((tab) => ({
       // tab.active = selected in its own pane (drives highlighted background).
       // tab.focused = has keyboard focus (drives brighter text / focus indicator).
@@ -32,7 +37,8 @@ export function renderPanelWorkspaceBar(
       activeBold: focused,
       inactiveFg: INACTIVE_FG,
       separatorFg: SEPARATOR_FG,
-      labelFg: LABEL_FG,
+      // Accent the PANELS chip when focused so it ties to the focus border.
+      labelFg: focused ? FOCUS_ACCENT_FG : LABEL_FG,
       labelBg: focused ? LABEL_BG : '',
       labelBold: focused,
       overflowFg: SEPARATOR_FG,

package/src/renderer/process-modal.ts

@@ -1,6 +1,6 @@
 import { type Line } from '../types/grid.ts';
 import { ModalFactory } from './modal-factory.ts';
-import { formatDuration } from './modal-utils.ts';
+import { formatElapsed } from '../utils/format-elapsed.ts';
 import type { ProcessManager } from '@pellux/goodvibes-sdk/platform/tools';
 import type { AgentManager, AgentRecord } from '@pellux/goodvibes-sdk/platform/tools';
 import type { WrfcController } from '@pellux/goodvibes-sdk/platform/agents';
@@ -623,7 +623,7 @@ export function renderProcessModal(modal: ProcessModal, width: number, viewportH
       cancelled: '–',
     }[e.status] ?? '•';
     const typeTag = e.type === 'agent' ? '[agent]' : '[exec]';
-    const dur = formatDuration(e.elapsedMs);
+    const dur = formatElapsed(e.elapsedMs);
     const statusStr = e.streamSnippet ? `streaming  ${dur}` : `${e.status}  ${dur}`;
     const suffix = `  ${statusStr}`;
     const treePrefix = e.treePrefix ?? '';

package/src/renderer/progress.ts

@@ -1,6 +1,7 @@
 import { type Line } from '../types/grid.ts';
 import { UIFactory } from './ui-factory.ts';
 import { getDisplayWidth, padDisplayEnd } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 
 // Rich spinner frames (used by progress indicators)
 export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -51,8 +52,8 @@ export function renderTokenBar(
   const lines: Line[] = [];
 
   // Stats row
-  const usedK = used >= 1000 ? `${(used / 1000).toFixed(1)}k` : String(used);
-  const maxK = max >= 1000 ? `${(max / 1000).toFixed(1)}k` : String(max);
+  const usedK = abbreviateCount(used, { noM: true });
+  const maxK = abbreviateCount(max, { noM: true });
   const pct = max > 0 ? Math.min(100, Math.round((used / max) * 100)) : 0;
   const toolStr = toolCount > 0 ? `  tools:${toolCount}` : '';
   const statsText = ` ${model}  in:${usedK}/${maxK} (${pct}%)${toolStr}`;

package/src/renderer/tab-strip.ts

@@ -21,46 +21,148 @@ export interface TabStripStyle {
   readonly trailingFg?: string;
 }
 
+/** Absolute column range a rendered tab occupies, for click hit-testing. */
+export interface TabHitRegion {
+  /** Index into the original `tabs` array. */
+  readonly index: number;
+  /** First column (inclusive) the tab occupies on the line. */
+  readonly startCol: number;
+  /** Last column (exclusive) the tab occupies on the line. */
+  readonly endCol: number;
+}
+
 export interface TabStripConfig {
   readonly width: number;
   readonly tabs: readonly TabStripItem[];
   readonly style: TabStripStyle;
   readonly prefixLabel?: string;
   readonly suffixLabel?: string;
+  /** Right-side overflow glyph (more tabs after the window). Default '›'. */
   readonly overflowIndicator?: string;
+  /** Left-side overflow glyph (more tabs before the window). Default '‹'. */
+  readonly overflowIndicatorLeft?: string;
+  /**
+   * Optional callback invoked with the absolute column ranges of each rendered
+   * tab. Used by the compositor to hit-test mouse clicks onto tabs. Additive —
+   * the function still returns a `Line` so existing callers are unaffected.
+   */
+  readonly onLayout?: (regions: readonly TabHitRegion[]) => void;
+}
+
+const SEPARATOR = '│';
+
+interface WindowResult {
+  segments: StyledPanelSegment[];
+  /** Per-tab column ranges relative to the start of the tab block. */
+  regions: Array<{ index: number; startCol: number; endCol: number }>;
+  overflowLeft: boolean;
+  overflowRight: boolean;
 }
 
+/**
+ * Build the visible tab segments, windowed so the ACTIVE tab is always shown.
+ *
+ * Tabs are laid out left-to-right, but when they don't all fit we keep a
+ * contiguous window that contains the active tab and grow it outward (biased
+ * toward following tabs) until the budget is exhausted. Left/right overflow is
+ * reported so the caller can render `‹`/`›` indicators.
+ */
 function makeSegments(
   tabs: readonly TabStripItem[],
   style: TabStripStyle,
   maxWidth: number,
-): { segments: StyledPanelSegment[]; hasOverflow: boolean } {
-  const segments: StyledPanelSegment[] = [];
-  let used = 0;
-  let hasOverflow = false;
-  for (const tab of tabs) {
-    const separatorWidth = getDisplayWidth('│');
-    const labelText = tab.active ? `[${tab.label}]` : tab.label;
-    const labelWidth = getDisplayWidth(labelText);
-    const entryWidth = separatorWidth + labelWidth + 1;
-    if (used + entryWidth > maxWidth) {
-      hasOverflow = true;
-      break;
+  indicatorWidth: number,
+): WindowResult {
+  const empty: WindowResult = { segments: [], regions: [], overflowLeft: false, overflowRight: false };
+  if (tabs.length === 0 || maxWidth <= 0) return empty;
+
+  const sepWidth = getDisplayWidth(SEPARATOR);
+  // Per-tab entry width: leading separator + (bracketed if active) label + trailing space.
+  const labelText = (tab: TabStripItem) => (tab.active ? `[${tab.label}]` : tab.label);
+  const entryWidths = tabs.map((tab) => sepWidth + getDisplayWidth(labelText(tab)) + 1);
+
+  const activeIndex = Math.max(0, tabs.findIndex((t) => t.active));
+  const n = tabs.length;
+  const closing = sepWidth; // trailing │ after the last visible tab
+  const totalAll = entryWidths.reduce((a, b) => a + b, 0) + closing;
+
+  let start = activeIndex;
+  let end = activeIndex; // inclusive
+  let used = entryWidths[activeIndex] + closing;
+
+  if (totalAll <= maxWidth) {
+    // Everything fits — show all tabs, no windowing.
+    start = 0;
+    end = n - 1;
+  } else {
+    // Need windowing. Reserve room for indicators on whichever side still has
+    // hidden tabs; the reserve is recomputed each step so reaching an edge
+    // frees its indicator column.
+    const budget = maxWidth;
+    let leftDone = start === 0;
+    let rightDone = end === n - 1;
+    let preferRight = true;
+
+    const fits = (extra: number, nextStart: number, nextEnd: number) => {
+      const leftRes = nextStart > 0 ? indicatorWidth : 0;
+      const rightRes = nextEnd < n - 1 ? indicatorWidth : 0;
+      return used + extra + leftRes + rightRes <= budget;
+    };
+
+    while (!leftDone || !rightDone) {
+      const goRight = !rightDone && (preferRight || leftDone);
+      if (goRight) {
+        const ne = end + 1;
+        if (fits(entryWidths[ne], start, ne)) {
+          end = ne;
+          used += entryWidths[ne];
+          if (end === n - 1) rightDone = true;
+          preferRight = false;
+        } else {
+          rightDone = true;
+        }
+      } else if (!leftDone) {
+        const ns = start - 1;
+        if (fits(entryWidths[ns], ns, end)) {
+          start = ns;
+          used += entryWidths[ns];
+          if (start === 0) leftDone = true;
+          preferRight = true;
+        } else {
+          leftDone = true;
+        }
+      } else {
+        break;
+      }
     }
-    segments.push({ text: '│', fg: style.separatorFg });
+  }
+
+  const segments: StyledPanelSegment[] = [];
+  const regions: Array<{ index: number; startCol: number; endCol: number }> = [];
+  let col = 0;
+  for (let i = start; i <= end; i++) {
+    const tab = tabs[i];
+    const text = labelText(tab);
+    const entryStart = col;
+    segments.push({ text: SEPARATOR, fg: style.separatorFg });
     segments.push({
-      text: `${labelText} `,
+      text: `${text} `,
       fg: tab.active ? style.activeFg : style.inactiveFg,
       bg: tab.active ? style.activeBg : style.inactiveBg,
       bold: tab.active ? (style.activeBold ?? false) : false,
     });
-    used += entryWidth;
+    col += entryWidths[i];
+    regions.push({ index: i, startCol: entryStart, endCol: col });
   }
+  // Closing separator.
+  segments.push({ text: SEPARATOR, fg: style.separatorFg });
 
-  if (segments.length > 0 && used + getDisplayWidth('│') <= maxWidth) {
-    segments.push({ text: '│', fg: style.separatorFg });
-  }
-  return { segments, hasOverflow };
+  return {
+    segments,
+    regions,
+    overflowLeft: start > 0,
+    overflowRight: end < n - 1,
+  };
 }
 
 export function renderTabStrip(config: TabStripConfig): Line {
@@ -70,18 +172,18 @@ export function renderTabStrip(config: TabStripConfig): Line {
     style,
     prefixLabel,
     suffixLabel,
-  overflowIndicator = '›',
+    overflowIndicator = '›',
+    overflowIndicatorLeft = '‹',
+    onLayout,
   } = config;
 
+  const prefixWidth = prefixLabel ? getDisplayWidth(prefixLabel) + 1 : 0;
   const reservedSuffixWidth = suffixLabel ? getDisplayWidth(suffixLabel) : 0;
-  const reservedOverflowWidth = getDisplayWidth(overflowIndicator);
-  const maxTabWidth = Math.max(
-    0,
-    width
-      - (prefixLabel ? getDisplayWidth(prefixLabel) + 1 : 0)
-      - (suffixLabel ? reservedSuffixWidth : 0)
-      - reservedOverflowWidth,
+  const indicatorWidth = Math.max(
+    getDisplayWidth(overflowIndicator),
+    getDisplayWidth(overflowIndicatorLeft),
   );
+  const maxTabWidth = Math.max(0, width - prefixWidth - reservedSuffixWidth);
 
   const baseSegments: StyledPanelSegment[] = [];
   if (prefixLabel) {
@@ -94,15 +196,27 @@ export function renderTabStrip(config: TabStripConfig): Line {
     baseSegments.push({ text: ' ', fg: style.separatorFg });
   }
 
-  const { segments: tabSegments, hasOverflow } = makeSegments(tabs, style, maxTabWidth);
+  const { segments: tabSegments, regions, overflowLeft, overflowRight } =
+    makeSegments(tabs, style, maxTabWidth, indicatorWidth);
+
+  const leftSegments: StyledPanelSegment[] = [];
+  if (overflowLeft) {
+    leftSegments.push({ text: overflowIndicatorLeft, fg: style.overflowFg ?? style.separatorFg });
+  }
+
   const suffixSegments: StyledPanelSegment[] = [];
-  if (hasOverflow) suffixSegments.push({ text: overflowIndicator, fg: style.overflowFg ?? style.separatorFg });
+  if (overflowRight) {
+    suffixSegments.push({ text: overflowIndicator, fg: style.overflowFg ?? style.separatorFg });
+  }
   if (suffixLabel) {
-    suffixSegments.push({
-      text: suffixLabel,
-      fg: style.trailingFg ?? style.inactiveFg,
-    });
+    suffixSegments.push({ text: suffixLabel, fg: style.trailingFg ?? style.inactiveFg });
+  }
+
+  // Report absolute hit regions: prefix + optional left indicator, then tabs.
+  if (onLayout) {
+    const offset = prefixWidth + (overflowLeft ? getDisplayWidth(overflowIndicatorLeft) : 0);
+    onLayout(regions.map((r) => ({ index: r.index, startCol: offset + r.startCol, endCol: offset + r.endCol })));
   }
 
-  return buildStyledPanelLine(width, [...baseSegments, ...tabSegments, ...suffixSegments]);
+  return buildStyledPanelLine(width, [...baseSegments, ...leftSegments, ...tabSegments, ...suffixSegments]);
 }

package/src/renderer/ui-factory.ts

@@ -6,6 +6,8 @@ import type { GitHeaderInfo } from './git-status.ts';
 import { renderConversationFragment, renderConversationStatusLine, type ConversationStatusSegment } from './conversation-surface.ts';
 import { GLYPHS } from './ui-primitives.ts';
 import { formatElapsed } from '../utils/format-elapsed.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
+import { computeContextUsage } from '../core/context-usage.ts';
 
 /** Number of frames before the animated gradient completes one full cycle. */
 const GRADIENT_CYCLE_FRAMES = 50;
@@ -30,11 +32,7 @@ function buildGitSegment(gitInfo: GitHeaderInfo): { text: string; width: number
 
 /** Format a number: up to 999, then 1.0k, 1.0M, 1.0B, 1.0T */
 function fmtNum(n: number): string {
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return (n / 1000).toFixed(1) + 'k';
-  if (n < 1_000_000_000) return (n / 1_000_000).toFixed(1) + 'M';
-  if (n < 1_000_000_000_000) return (n / 1_000_000_000).toFixed(1) + 'B';
-  return (n / 1_000_000_000_000).toFixed(1) + 'T';
+  return abbreviateCount(n, { bSuffix: true });
 }
 
 /**
@@ -312,7 +310,7 @@ export class UIFactory {
       const label = '   Context Usage: ';
       const suffix = ` [ ${fmtNum(ctxTokens)} / ${fmtNum(contextWindow)} ]`;
       const barWidth = Math.max(10, Math.min(30, width - getDisplayWidth(label) - getDisplayWidth(suffix) - 8));
-      const ctxPct = Math.min(1, ctxTokens / contextWindow);
+      const ctxPct = computeContextUsage(ctxTokens, contextWindow).clampedRatio;
       // Clamp threshold to [0..1]; undefined/0 means no threshold marker.
       const thresholdFraction = (compactThreshold !== undefined && compactThreshold > 0)
         ? Math.min(1, compactThreshold)

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

@@ -112,6 +112,7 @@ export type CreateBootstrapCommandContextOptions = {
   activatePlan: (planId: string, task: string) => void;
   completeModelSelectionSideEffect?: () => void;
   sessionLineageTracker?: import('@pellux/goodvibes-sdk/platform/core').SessionLineageTracker;
+  wrfcController?: import('@pellux/goodvibes-sdk/platform/agents').WrfcController;
   componentHealthMonitor: import('@/runtime/index.ts').ComponentHealthMonitor;
 };
 
@@ -164,6 +165,7 @@ export function createBootstrapCommandContext(
     webhookNotifier,
     sessionMemoryStore,
     sessionLineageTracker,
+    wrfcController,
     changeTracker,
     planManager,
     adaptivePlanner,
@@ -219,6 +221,7 @@ export function createBootstrapCommandContext(
     sessionManager,
     sessionMemoryStore,
     sessionLineageTracker,
+    wrfcController,
     changeTracker,
   });
   const provider = createBootstrapCommandProviderSection({

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

@@ -107,6 +107,7 @@ export interface BootstrapCommandSectionOptions {
   readonly webhookNotifier?: import('@pellux/goodvibes-sdk/platform/integrations').WebhookNotifier;
   readonly sessionMemoryStore?: import('@pellux/goodvibes-sdk/platform/core').SessionMemoryStore;
   readonly sessionLineageTracker?: import('@pellux/goodvibes-sdk/platform/core').SessionLineageTracker;
+  readonly wrfcController?: import('@pellux/goodvibes-sdk/platform/agents').WrfcController;
   readonly changeTracker?: import('@pellux/goodvibes-sdk/platform/sessions').SessionChangeTracker;
   readonly agentManager?: ShellAgentManagerService;
   readonly modeManager?: ShellModeManagerService;
@@ -299,7 +300,7 @@ export function createBootstrapCommandActions(
 export function createBootstrapCommandSessionSection(
   options: Pick<
     BootstrapCommandSectionOptions,
-    'conversation' | 'runtime' | 'sessionManager' | 'sessionMemoryStore' | 'sessionLineageTracker' | 'changeTracker'
+    'conversation' | 'runtime' | 'sessionManager' | 'sessionMemoryStore' | 'sessionLineageTracker' | 'wrfcController' | 'changeTracker'
   >,
 ): BootstrapCommandSessionSection {
   return {
@@ -308,6 +309,7 @@ export function createBootstrapCommandSessionSection(
     sessionManager: options.sessionManager,
     sessionMemoryStore: options.sessionMemoryStore,
     sessionLineageTracker: options.sessionLineageTracker,
+    wrfcController: options.wrfcController,
     changeTracker: options.changeTracker,
   };
 }

package/src/runtime/bootstrap-core.ts

@@ -399,50 +399,50 @@ export async function initializeBootstrapCore(
   });
 
   const renderRequestRef = { value: (): void => {} };
-  // R1: Coalescing render scheduler — collapses N same-microtask requestRender() calls into 1.
-  // Also enforces a 16ms minimum interval to cap at ~60fps during streaming.
+  // R1: Coalescing render scheduler — collapses N requestRender() calls into 1
+  // and enforces a 16ms minimum interval to cap repaints at ~60fps.
+  //
+  // renderScheduled stays set for the ENTIRE window (until run() executes), so
+  // requestRender() calls that arrive on later event-loop ticks within the same
+  // 16ms window are coalesced into the one already-pending tail render instead
+  // of each queuing their own setTimeout. (The streaming hot path drives its own
+  // direct repaints and does not flow through this scheduler.)
   let renderScheduled = false;
   let lastRenderTime = 0;
   const RENDER_INTERVAL_MS = 16;
+  // run() performs the actual render. It clears renderScheduled FIRST — even if
+  // the render callback throws — otherwise a single render exception would wedge
+  // the entire TUI (no future requestRender() call would schedule anything). The
+  // renderer is expected to surface failures via its own error path; we log at
+  // error so the next requestRender() can still reschedule.
+  const run = (): void => {
+    renderScheduled = false;
+    lastRenderTime = Date.now();
+    try {
+      renderRequestRef.value();
+    } catch (err) {
+      logger.error('Render threw; next requestRender will reschedule', { error: String(err) });
+    }
+  };
   const requestRender = (): void => {
     if (renderScheduled) return;
     renderScheduled = true;
     setImmediate(() => {
-      // Error Handling: the scheduler flag MUST be cleared even if the render
-      // callback throws; otherwise a single render exception would wedge the
-      // entire TUI (no future requestRender() call would schedule anything).
-      renderScheduled = false;
-      const now = Date.now();
-      const elapsed = now - lastRenderTime;
-      try {
-        if (elapsed < RENDER_INTERVAL_MS) {
-          // Too soon — debounce to the tail of the current 16ms window
-          const delay = RENDER_INTERVAL_MS - elapsed;
-          setTimeout(() => {
-            try {
-              lastRenderTime = Date.now();
-              renderRequestRef.value();
-            } catch (err) {
-              // Throttled-render error: swallow but log at error so the next
-              // requestRender() call can still schedule. The renderer itself
-              // is expected to surface failures via its own error path.
-              logger.error('Throttled render threw; next requestRender will reschedule', { error: String(err) });
-            }
-          }, delay);
-        } else {
-          lastRenderTime = now;
-          renderRequestRef.value();
-        }
-      } catch (err) {
-        logger.error('Immediate render threw; next requestRender will reschedule', { error: String(err) });
+      const elapsed = Date.now() - lastRenderTime;
+      if (elapsed < RENDER_INTERVAL_MS) {
+        // Too soon — debounce to the tail of the current 16ms window. The flag
+        // stays set until run() fires, so window-local requests coalesce here.
+        setTimeout(run, RENDER_INTERVAL_MS - elapsed);
+      } else {
+        run();
       }
     });
   };
   const permissionPromptRef = {
     requestPermission: (async () => ({ approved: false, remember: false })) as PermissionRequestHandler,
   };
-  void approvalBroker.start();
-  void sharedSessionBroker.start();
+  approvalBroker.start().catch((err) => logger.warn('approval broker start failed at bootstrap', { err }));
+  sharedSessionBroker.start().catch((err) => logger.warn('shared session broker start failed at bootstrap', { err }));
   const runtimeSessionIdRef = { value: userSessionId };
   const wrfcBuffer = new WrfcPreRouterBuffer();
   // Smart ref: setting .value auto-flushes the pre-router buffer so events

package/src/runtime/bootstrap-shell.ts

@@ -240,6 +240,7 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     webhookNotifier: services.webhookNotifier,
     sessionMemoryStore: services.sessionMemoryStore,
     sessionLineageTracker: services.sessionLineageTracker,
+    wrfcController: services.wrfcController,
     changeTracker: services.sessionChangeTracker,
     planManager: services.planManager,
     adaptivePlanner: services.adaptivePlanner,

package/src/runtime/onboarding/apply.ts

@@ -17,6 +17,7 @@ import type {
   OnboardingApplyRequest,
   OnboardingApplyResult,
 } from './types.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 function getNow(deps: Pick<OnboardingApplyDependencies, 'clock'>): number {
   return deps.clock?.() ?? Date.now();
@@ -116,7 +117,7 @@ async function runRollbacks(rollbacks: readonly RollbackAction[]): Promise<reado
     try {
       await rollback();
     } catch (error) {
-      errors.push(error instanceof Error ? error.message : String(error));
+      errors.push(summarizeError(error));
     }
   }
   return errors;
@@ -523,7 +524,7 @@ function prevalidateApplyRequest(
     } catch (error) {
       errors.push({
         kind: operation.kind,
-        message: error instanceof Error ? error.message : String(error),
+        message: summarizeError(error),
       });
     }
   }
@@ -595,7 +596,7 @@ export async function applyOnboardingRequest(
         errors.push({
           kind: operation.kind,
           message: [
-            error instanceof Error ? error.message : String(error),
+            summarizeError(error),
             ...rollbackErrors.map((rollbackError) => `rollback: ${rollbackError}`),
           ].join('; '),
         });

package/src/runtime/onboarding/snapshot.ts

@@ -14,6 +14,7 @@ import type {
   OnboardingSnapshotState,
   OnboardingSurfaceRecord,
 } from './types.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 function sortUnique(values: readonly string[]): string[] {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
@@ -100,7 +101,7 @@ async function buildServicesSnapshot(
       issues: [
         {
           area: 'services',
-          message: error instanceof Error ? error.message : String(error),
+          message: summarizeError(error),
         },
       ],
     };
@@ -147,7 +148,7 @@ async function buildServicesSnapshot(
         } satisfies OnboardingServiceState,
         issue: {
           area: 'services',
-          message: `${name}: ${error instanceof Error ? error.message : String(error)}`,
+          message: `${name}: ${summarizeError(error)}`,
         } satisfies OnboardingSnapshotCollectionIssue,
       };
     }
@@ -244,7 +245,7 @@ async function loadOptionalSnapshot<T>(
       value: fallback,
       issue: {
         area,
-        message: error instanceof Error ? error.message : String(error),
+        message: summarizeError(error),
       },
     };
   }