@pellux/goodvibes-tui 0.18.20 → 0.19.0

package/src/panels/watchers-panel.ts

@@ -1,6 +1,6 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
-import { BasePanel } from './base-panel.ts';
+import { ScrollableListPanel } from './scrollable-list-panel.ts';
 import type { UiReadModel, UiWatchersSnapshot } from '../runtime/ui-read-models.ts';
 import { truncateDisplay } from '../utils/terminal-width.ts';
 import {
@@ -10,8 +10,7 @@ import {
   buildPanelLine,
   buildPanelWorkspace,
   DEFAULT_PANEL_PALETTE,
-  resolvePrimaryScrollableSection,
-  type PanelWorkspaceSection,
+  type PanelPalette,
 } from './polish.ts';
 
 const C = {
@@ -51,14 +50,15 @@ function formatTime(value?: number): string {
   return new Date(value).toLocaleString();
 }
 
-export class WatchersPanel extends BasePanel {
+type WatcherEntry = UiWatchersSnapshot['watchers'][number];
+
+export class WatchersPanel extends ScrollableListPanel<WatcherEntry> {
   private readonly readModel?: UiReadModel<UiWatchersSnapshot>;
   private readonly unsub: (() => void) | null;
-  private selectedIndex = 0;
-  private scrollOffset = 0;
 
   public constructor(readModel?: UiReadModel<UiWatchersSnapshot>) {
     super('watchers', 'Watchers', 'W', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
@@ -67,29 +67,38 @@ export class WatchersPanel extends BasePanel {
     this.unsub?.();
   }
 
-  public handleInput(key: string): boolean {
-    const watchers = this.watchers();
-    if (watchers.length === 0) return false;
-    if (key === 'up' || key === 'k') {
-      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
-      this.markDirty();
-      return true;
-    }
-    if (key === 'down' || key === 'j') {
-      this.selectedIndex = Math.min(watchers.length - 1, this.selectedIndex + 1);
-      this.markDirty();
-      return true;
-    }
-    return false;
+  protected override getPalette(): PanelPalette {
+    return C;
   }
 
-  private watchers() {
+  protected getItems(): readonly WatcherEntry[] {
     if (!this.readModel) return [];
-    return [...this.readModel.getSnapshot().watchers];
+    return this.readModel.getSnapshot().watchers;
+  }
+
+  protected renderItem(watcher: WatcherEntry, _index: number, selected: boolean, width: number): Line {
+    const bg = selected ? C.selectBg : undefined;
+    return buildPanelLine(width, [
+      [' ', C.label, bg],
+      [watcher.state.padEnd(10), stateColor(watcher.state), bg],
+      [` ${truncateDisplay(watcher.label, 18).padEnd(18)}`, C.value, bg],
+      [` ${String(watcher.sourceStatus ?? 'unknown').padEnd(10)}`, sourceStatusColor(watcher.sourceStatus), bg],
+      [` ${truncateDisplay(formatLag(watcher.sourceLagMs), Math.max(0, width - 43))}`, C.dim, bg],
+    ]);
+  }
+
+  protected override getEmptyStateMessage(): string {
+    return ' No watchers registered.';
+  }
+
+  protected override getEmptyStateActions(): Array<{ command: string; summary: string }> {
+    return [
+      { command: '/schedule list', summary: 'review automation that will consume watcher events' },
+      { command: '/services auth-review', summary: 'validate integration credentials before enabling remote watchers' },
+    ];
   }
 
   public render(width: number, height: number): Line[] {
-    this.needsRender = false;
     const intro = 'Managed watchers and source health used to trigger automation, refresh routes, and surface degraded upstream conditions.';
 
     if (!this.readModel) {
@@ -112,130 +121,73 @@ export class WatchersPanel extends BasePanel {
     }
 
     const snapshot = this.readModel.getSnapshot();
-    const watchers = this.watchers();
-    const summarySection: PanelWorkspaceSection = {
-      title: 'Posture',
-      lines: [
-        buildKeyValueLine(width, [
-          { label: 'watchers', value: String(snapshot.totalWatchers), valueColor: snapshot.totalWatchers > 0 ? C.info : C.dim },
-          { label: 'active', value: String(snapshot.activeWatcherIds.length), valueColor: snapshot.activeWatcherIds.length > 0 ? C.ok : C.dim },
-          { label: 'degraded', value: String(snapshot.totalDegraded), valueColor: snapshot.totalDegraded > 0 ? C.warn : C.dim },
-          { label: 'lagged', value: String(snapshot.totalLagged), valueColor: snapshot.totalLagged > 0 ? C.warn : C.dim },
-        ], C),
-        buildGuidanceLine(width, '/schedule list', 'verify jobs consuming these sources and use daemon APIs for watcher lifecycle control', C),
-      ],
-    };
+    const watchers = this.getItems();
+
+    const headerLines: Line[] = [
+      buildKeyValueLine(width, [
+        { label: 'watchers', value: String(snapshot.totalWatchers), valueColor: snapshot.totalWatchers > 0 ? C.info : C.dim },
+        { label: 'active', value: String(snapshot.activeWatcherIds.length), valueColor: snapshot.activeWatcherIds.length > 0 ? C.ok : C.dim },
+        { label: 'degraded', value: String(snapshot.totalDegraded), valueColor: snapshot.totalDegraded > 0 ? C.warn : C.dim },
+        { label: 'lagged', value: String(snapshot.totalLagged), valueColor: snapshot.totalLagged > 0 ? C.warn : C.dim },
+      ], C),
+      buildGuidanceLine(width, '/schedule list', 'verify jobs consuming these sources and use daemon APIs for watcher lifecycle control', C),
+    ];
 
     if (watchers.length === 0) {
-      const workspace = buildPanelWorkspace(width, height, {
+      return this.renderList(width, height, {
         title: 'Watchers',
-        intro,
-        sections: [
-          summarySection,
-          {
-            lines: buildEmptyState(
-              width,
-              ' No watchers registered.',
-              'Register daemon watchers or enable polling/integration sources to populate this control room.',
-              [
-                { command: '/schedule list', summary: 'review automation that will consume watcher events' },
-                { command: '/services auth-review', summary: 'validate integration credentials before enabling remote watchers' },
-              ],
-              C,
-            ),
-          },
-        ],
-        palette: C,
+        header: headerLines,
+        emptyMessage: ' No watchers registered.',
       });
-      while (workspace.length < height) workspace.push(createEmptyLine(width));
-      return workspace;
     }
 
-    this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, watchers.length - 1));
+    this.clampSelection();
     const selected = watchers[this.selectedIndex]!;
 
-    const detailSection: PanelWorkspaceSection = {
-      title: 'Selected Watcher',
-      lines: [
-        buildPanelLine(width, [
-          ['  Watcher: ', C.label],
-          [selected.label, C.value],
-          ['  Kind: ', C.label],
-          [selected.kind, C.info],
-        ]),
-        buildPanelLine(width, [
-          ['  State: ', C.label],
-          [selected.state, stateColor(selected.state)],
-          ['  Source: ', C.label],
-          [selected.source.kind, C.value],
-        ]),
-        buildPanelLine(width, [
-          ['  Source status: ', C.label],
-          [selected.sourceStatus ?? 'unknown', sourceStatusColor(selected.sourceStatus)],
-          ['  Lag: ', C.label],
-          [formatLag(selected.sourceLagMs), selected.sourceLagMs ? C.warn : C.dim],
-        ]),
-        buildPanelLine(width, [
-          ['  Heartbeat: ', C.label],
-          [formatTime(selected.lastHeartbeatAt), C.dim],
-          ['  Checkpoint: ', C.label],
-          [truncateDisplay(selected.lastCheckpoint ?? 'n/a', Math.max(0, width - 38)), C.dim],
-        ]),
-        ...(selected.degradedReason ? [
-          buildPanelLine(width, [
-            ['  Reason: ', C.label],
-            [truncateDisplay(selected.degradedReason, Math.max(0, width - 11)), C.warn],
-          ]),
-        ] : []),
-        ...(selected.lastError ? [
-          buildPanelLine(width, [
-            ['  Error: ', C.label],
-            [truncateDisplay(selected.lastError, Math.max(0, width - 10)), C.error],
-          ]),
-        ] : []),
-      ],
-    };
-
-    const resolvedWatchers = resolvePrimaryScrollableSection(width, height, {
-      intro,
-      footerLines: [buildPanelLine(width, [['  Up/Down move through watchers', C.dim]])],
-      palette: C,
-      beforeSections: [summarySection],
-      section: {
-        title: 'Watchers',
-        scrollableLines: watchers.map((watcher, absolute) => {
-          const bg = absolute === this.selectedIndex ? C.selectBg : undefined;
-          return buildPanelLine(width, [
-            [' ', C.label, bg],
-            [watcher.state.padEnd(10), stateColor(watcher.state), bg],
-            [` ${truncateDisplay(watcher.label, 18).padEnd(18)}`, C.value, bg],
-            [` ${String(watcher.sourceStatus ?? 'unknown').padEnd(10)}`, sourceStatusColor(watcher.sourceStatus), bg],
-            [` ${truncateDisplay(formatLag(watcher.sourceLagMs), Math.max(0, width - 43))}`, C.dim, bg],
-          ]);
-        }),
-        selectedIndex: this.selectedIndex,
-        scrollOffset: this.scrollOffset,
-        guardRows: 1,
-        minRows: 5,
-        appendWindowSummary: { dimColor: C.dim },
-      },
-      afterSections: [detailSection],
-    });
-    this.scrollOffset = resolvedWatchers.scrollOffset;
-
-    const sections: PanelWorkspaceSection[] = [
-      summarySection,
-      resolvedWatchers.section,
-      detailSection,
+    const footerLines: Line[] = [
+      buildPanelLine(width, [
+        ['  Watcher: ', C.label],
+        [selected.label, C.value],
+        ['  Kind: ', C.label],
+        [selected.kind, C.info],
+      ]),
+      buildPanelLine(width, [
+        ['  State: ', C.label],
+        [selected.state, stateColor(selected.state)],
+        ['  Source: ', C.label],
+        [selected.source.kind, C.value],
+      ]),
+      buildPanelLine(width, [
+        ['  Source status: ', C.label],
+        [selected.sourceStatus ?? 'unknown', sourceStatusColor(selected.sourceStatus)],
+        ['  Lag: ', C.label],
+        [formatLag(selected.sourceLagMs), selected.sourceLagMs ? C.warn : C.dim],
+      ]),
+      buildPanelLine(width, [
+        ['  Heartbeat: ', C.label],
+        [formatTime(selected.lastHeartbeatAt), C.dim],
+        ['  Checkpoint: ', C.label],
+        [truncateDisplay(selected.lastCheckpoint ?? 'n/a', Math.max(0, width - 38)), C.dim],
+      ]),
     ];
-    const lines = buildPanelWorkspace(width, height, {
+    if (selected.degradedReason) {
+      footerLines.push(buildPanelLine(width, [
+        ['  Reason: ', C.label],
+        [truncateDisplay(selected.degradedReason, Math.max(0, width - 11)), C.warn],
+      ]));
+    }
+    if (selected.lastError) {
+      footerLines.push(buildPanelLine(width, [
+        ['  Error: ', C.label],
+        [truncateDisplay(selected.lastError, Math.max(0, width - 10)), C.error],
+      ]));
+    }
+    footerLines.push(buildPanelLine(width, [['  Up/Down move through watchers', C.dim]]));
+
+    return this.renderList(width, height, {
       title: 'Watchers',
-      intro,
-      sections,
-      footerLines: [buildPanelLine(width, [['  Up/Down move through watchers', C.dim]])],
-      palette: C,
+      header: headerLines,
+      footer: footerLines,
     });
-    while (lines.length < height) lines.push(createEmptyLine(width));
-    return lines.slice(0, height);
   }
 }

package/src/panels/worktree-panel.ts

@@ -29,6 +29,7 @@ export class WorktreePanel extends ScrollableListPanel<WorktreeStatusRecord> {
 
   public constructor(worktreeRegistry: WorktreeRegistry) {
     super('worktrees', 'Worktrees', 'W', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.worktreeRegistry = worktreeRegistry;
     void this.refresh();
   }

package/src/panels/wrfc-panel.ts

@@ -170,6 +170,7 @@ export class WrfcPanel extends BasePanel {
   // Render
   // -------------------------------------------------------------------------
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     const activeCount  = this.chains.filter(c => !['passed', 'failed'].includes(c.state)).length;
     const passedCount  = this.chains.filter(c => c.state === 'passed').length;
     const failedCount  = this.chains.filter(c => c.state === 'failed').length;
@@ -275,6 +276,7 @@ export class WrfcPanel extends BasePanel {
       ],
       palette: DEFAULT_PANEL_PALETTE,
     });
+    });
   }
 
   // -------------------------------------------------------------------------

package/src/renderer/agent-detail-modal.ts

@@ -53,11 +53,11 @@ export class AgentDetailModal {
     this.active = true;
     this.logEntries = [];
     this.logTotal = 0;
-    this.loadLog().catch(() => {});
+    this.loadLog().catch((err) => { logger.debug('agent detail log load failed', { err }); });
     // Auto-refresh log every 500ms while modal is open
     if (this.refreshTimer) clearInterval(this.refreshTimer);
     this.refreshTimer = setInterval(() => {
-      this.loadLog().then(() => this.onRefresh?.()).catch(() => {});
+      this.loadLog().then(() => this.onRefresh?.()).catch((err) => { logger.debug('agent detail log refresh tick failed', { err }); });
     }, 500);
   }
 

package/src/renderer/ansi-sanitize.ts

@@ -0,0 +1,76 @@
+/**
+ * ANSI sanitizer for untrusted content entering the renderer.
+ *
+ * The TUI grid renders content character-by-character via writeStyledText,
+ * which already drops zero-width characters (including ESC \x1b) by checking
+ * display width. However, that is incidental protection — not a contract.
+ * This module provides explicit, intentional sanitization.
+ *
+ * Strategy:
+ * - STRIP all non-SGR escape sequences (cursor moves, OSC, BEL, alt-screen,
+ *   DECSET/private mode, and any other CSI/ESC sequences).
+ * - PRESERVE SGR color/style codes (\x1b[<params>m) — used legitimately by
+ *   the TUI's own colorized output paths.
+ * - STRIP bare BEL (\x07) characters.
+ *
+ * Safe SGR pattern: \x1b[ followed by digits/semicolons, ending in 'm'.
+ * Everything else that starts with \x1b is dangerous and stripped.
+ */
+
+// Matches safe SGR sequences: ESC [ <digits/semicolons> m
+const SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
+
+// Matches ALL CSI sequences: ESC [ ... <final byte 0x40-0x7E>
+const CSI_SEQUENCE = /\x1b\[[\x20-\x3f]*[\x40-\x7e]/g;
+
+// Matches OSC sequences: ESC ] ... (ESC \ or BEL)
+const OSC_SEQUENCE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+
+// Matches other ESC sequences (ESC + single character that is not '[' or ']')
+const ESC_OTHER = /\x1b[^\[\]]/g;
+
+// Matches standalone BEL
+const BEL = /\x07/g;
+
+/**
+ * Strip dangerous ANSI escape sequences from untrusted content.
+ *
+ * Preserves SGR color codes (\x1b[<n>m). Removes:
+ * - Cursor movement CSI sequences (\x1b[<n>A/B/C/D, \x1b[H, etc.)
+ * - OSC sequences (\x1b]...\x07 or \x1b]...\x1b\\)
+ * - Alt-screen and DECSET private mode (\x1b[?...h/l)
+ * - Any other CSI or ESC sequences
+ * - Bare BEL (\x07)
+ *
+ * @param input - Raw string that may contain ANSI escape sequences
+ * @returns Sanitized string safe for grid rendering
+ */
+export function stripDangerousAnsi(input: string): string {
+  // Step 1: Extract and preserve SGR sequences by replacing them with placeholders,
+  // then strip all other escape sequences, then restore SGR sequences.
+  // This approach avoids complex negative lookahead regexes.
+
+  // Collect SGR sequences and replace with unique markers
+  const sgrTokens: string[] = [];
+  const withPlaceholders = input.replace(SGR_PATTERN, (match) => {
+    const idx = sgrTokens.length;
+    sgrTokens.push(match);
+    return `\x00SGR${idx}\x00`;
+  });
+
+  // Strip all remaining dangerous sequences
+  let sanitized = withPlaceholders
+    .replace(CSI_SEQUENCE, '')   // removes cursor moves, alt-screen, DECSET, etc.
+    .replace(OSC_SEQUENCE, '')   // removes OSC
+    .replace(ESC_OTHER, '')      // removes remaining ESC+char sequences
+    .replace(/\x1b/g, '')        // removes any leftover bare ESC
+    .replace(BEL, '');           // removes BEL
+
+  // Restore SGR sequences from placeholders
+  sanitized = sanitized.replace(/\x00SGR(\d+)\x00/g, (_match, idxStr) => {
+    const idx = parseInt(idxStr, 10);
+    return sgrTokens[idx] ?? '';
+  });
+
+  return sanitized;
+}

package/src/renderer/buffer.ts

@@ -2,17 +2,34 @@ import { type Line, type Cell, createEmptyLine, createEmptyCell } from '../types
 
 /**
  * TerminalBuffer - Represents a 2D grid of styled cells.
+ * Tracks a per-row dirty bitmap so the diff engine can skip rows that were
+ * never written in the current frame.
  */
 export class TerminalBuffer {
   public cells: Line[];
+  /** dirtyRows[y] is true if row y was written since the last reset(). */
+  public dirtyRows: boolean[];
 
   constructor(public width: number, public height: number) {
     this.cells = Array.from({ length: height }, () => createEmptyLine(width));
+    this.dirtyRows = new Array(height).fill(false);
   }
 
   public setCell(x: number, y: number, cell: Partial<Cell>): void {
     if (y >= 0 && y < this.height && x >= 0 && x < this.width) {
-      this.cells[y][x] = { ...this.cells[y][x], ...cell };
+      // No-op guard: skip the dirty mark and allocation if every field in `cell`
+      // already matches the current cell value (idempotent write).
+      const current = this.cells[y][x]!;
+      let changed = false;
+      for (const k in cell) {
+        if ((cell as unknown as Record<string, unknown>)[k] !== (current as unknown as Record<string, unknown>)[k]) {
+          changed = true;
+          break;
+        }
+      }
+      if (!changed) return;
+      this.cells[y][x] = { ...current, ...cell };
+      this.dirtyRows[y] = true;
     }
   }
 
@@ -23,30 +40,35 @@ export class TerminalBuffer {
   public blitLine(row: number, line: Line): void {
     if (row >= 0 && row < this.height) {
       this.cells[row] = [...line];
+      this.dirtyRows[row] = true;
     }
   }
 
   public clone(): TerminalBuffer {
     const newBuf = new TerminalBuffer(this.width, this.height);
     newBuf.cells = this.cells.map(line => line.map(cell => ({ ...cell })));
+    newBuf.dirtyRows = [...this.dirtyRows];
     return newBuf;
   }
 
   /**
    * Reset all cells in-place to empty, reusing this buffer instance.
    * If dimensions changed, reallocates cells array.
+   * Always clears the dirty bitmap.
    */
   public reset(width: number, height: number): void {
     if (width !== this.width || height !== this.height) {
       this.width = width;
       this.height = height;
       this.cells = Array.from({ length: height }, () => createEmptyLine(width));
+      this.dirtyRows = new Array(height).fill(false);
     } else {
       for (let y = 0; y < this.height; y++) {
         const row = this.cells[y]!;
         for (let x = 0; x < this.width; x++) {
           row[x] = createEmptyCell();
         }
+        this.dirtyRows[y] = false;
       }
     }
   }

package/src/renderer/diff.ts

@@ -29,6 +29,14 @@ export class DiffEngine {
     let output = '';
     
     for (let y = 0; y < newBuffer.height; y++) {
+      // Skip rows that were not written in either the old or new buffer.
+      // If neither side touched the row, both must match the prior frame:
+      // old row was never written this frame (clean) and new row is also
+      // clean, so the on-screen content is still correct. No diff needed.
+      const newDirty = newBuffer.dirtyRows[y] ?? false;
+      const oldDirty = oldBuffer ? (oldBuffer.dirtyRows[y] ?? false) : true;
+      if (!newDirty && !oldDirty) continue;
+
       for (let x = 0; x < newBuffer.width; x++) {
         const oldCell = oldBuffer?.getCell(x, y);
         const newCell = newBuffer.cells[y]?.[x];

package/src/renderer/help-overlay.ts

@@ -10,6 +10,7 @@ import type { SlashCommand } from '../input/command-registry.ts';
 import type { KeybindingsManager } from '../input/keybindings.ts';
 import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
 import { getVisibleWindow } from './surface-layout.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
 
 function toModalSections(rows: readonly string[]): import('./modal-factory.ts').ModalSection[] {
   return rows.map((row) => {
@@ -64,36 +65,55 @@ export function renderHelpOverlay(
     '',
   ];
 
-  const commandRows: string[] = [
-    '  Quick Start',
-    '  ' + '\u2500'.repeat(40),
-    '  /setup onboarding     Guided first-run review and environment posture',
-    '  /cockpit              Unified runtime control room',
-    '  /settings             Settings and config browser',
-    '',
-    '  Build And Operate',
-    '  ' + '\u2500'.repeat(40),
-    '  /provider             Choose provider or model family',
-    '  /subscription         Review provider logins and subscriptions',
-    '  /marketplace open     Browse plugins, skills, and packs',
-    '  /remote setup         Review remote, bridge, and tunnel flows',
-    '  /sandbox review       Inspect secure execution posture',
-    '',
-    '  Review And Govern',
-    '  ' + '\u2500'.repeat(40),
-    '  /security             Security review workspace',
-    '  /policy               Simulation, lint, and preflight review',
-    '  /incident             Incident workspace and export flows',
-    '  /knowledge            Durable knowledge and review queue',
-    '',
-    '  Power Surfaces',
-    '  ' + '\u2500'.repeat(40),
-    '  /hooks                Hook workbench and runtime activity',
-    '  /orchestration        Graph and recursive-agent control room',
-    '  /communication        Structured agent communication workspace',
-    '  /tasks                Task surface for list/show/pause/resume/output',
+  // Featured commands shown in the Quick Start section.
+  // Each entry is [commandName, subcommandOrArgHint, description].
+  // Commands not registered in the live registry are omitted at render time.
+  const FEATURED_COMMANDS: Array<[name: string, argHint: string, desc: string]> = [
+    ['setup',        'onboarding', 'Guided first-run review and environment posture'],
+    ['cockpit',      '',           'Unified runtime control room'],
+    ['settings',     '',           'Settings and config browser'],
+    ['provider',     '',           'Choose provider or model family'],
+    ['subscription', '',           'Review provider logins and subscriptions'],
+    ['marketplace',  'open',       'Browse plugins, skills, and packs'],
+    ['remote',       'setup',      'Review remote, bridge, and tunnel flows'],
+    ['sandbox',      'review',     'Inspect secure execution posture'],
+    ['security',     '',           'Security review workspace'],
+    ['policy',       '',           'Simulation, lint, and preflight review'],
+    ['incident',     '',           'Incident workspace and export flows'],
+    ['knowledge',    '',           'Durable knowledge and review queue'],
+    ['hooks',        '',           'Hook workbench and runtime activity'],
+    ['orchestration','',           'Graph and recursive-agent control room'],
+    ['communication','',           'Structured agent communication workspace'],
+    ['tasks',        '',           'Task surface for list/show/pause/resume/output'],
   ];
 
+  // Build command rows from featured list, filtering out unregistered commands.
+  function featuredRow(name: string, argHint: string, desc: string): string {
+    const invocation = argHint ? `/${name} ${argHint}` : `/${name}`;
+    return `  ${invocation.padEnd(23)}  ${desc}`;
+  }
+
+  const quickStartRows: string[] = [];
+  try {
+    for (const [name, argHint, desc] of FEATURED_COMMANDS) {
+      if (!hasCommand(name)) continue; // omit if not in live registry
+      quickStartRows.push(featuredRow(name, argHint, desc));
+    }
+  } catch (err) {
+    // A plugin command getter threw during registry traversal. Fall back to an
+    // unfiltered quick-start list so /help remains reachable.
+    logger.warn(`[help-overlay] registry traversal error during command filter; using unfiltered list: ${err}`);
+    quickStartRows.length = 0;
+    for (const [name, argHint, desc] of FEATURED_COMMANDS) {
+      quickStartRows.push(featuredRow(name, argHint, desc));
+    }
+  }
+
+  const commandRows: string[] = [];
+  if (quickStartRows.length > 0) {
+    commandRows.push('  Quick Start', '  ' + '\u2500'.repeat(40), ...quickStartRows, '');
+  }
+
   if (commands && commands.length > 0) {
     commandRows.push('', '  Available Slash Commands', '  ' + '\u2500'.repeat(40));
     const preferred = ['setup', 'cockpit', 'settings', 'provider', 'subscription', 'marketplace', 'remote', 'sandbox', 'security', 'policy', 'incident', 'knowledge', 'hooks', 'orchestration', 'communication', 'tasks'];