@pellux/goodvibes-tui 0.18.23 → 0.19.0

package/src/panels/agent-inspector-panel.ts

@@ -97,7 +97,7 @@ export class AgentInspectorPanel extends BasePanel {
   private cursorIndex = 0;
 
   // Refresh timer (active only while panel is active)
-  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private refreshTimerId: ReturnType<typeof setInterval> | null = null;
 
   // Row cache — cleared on markDirty(), computed once per render cycle
   private _cachedRows: DisplayRow[] | null = null;
@@ -131,7 +131,7 @@ export class AgentInspectorPanel extends BasePanel {
     this.cursorIndex = 0;
     this.timeline = [];
     this.markDirty();
-    this._refreshTimeline().catch(() => {});
+    this._refreshTimeline().catch((err) => { logger.debug('agent inspector timeline refresh failed', { err }); });
   }
 
   // -------------------------------------------------------------------------
@@ -149,6 +149,7 @@ export class AgentInspectorPanel extends BasePanel {
 
   override onDestroy(): void {
     this._stopRefresh();
+    super.onDestroy();
   }
 
   // -------------------------------------------------------------------------
@@ -461,16 +462,16 @@ export class AgentInspectorPanel extends BasePanel {
   }
 
   private _startRefresh(): void {
-    if (this.refreshTimer) return;
-    this.refreshTimer = setInterval(() => {
-      this._refreshTimeline().catch(() => {});
-    }, REFRESH_MS);
+    if (this.refreshTimerId) return;
+    this.refreshTimerId = this.registerTimer(setInterval(() => {
+      this._refreshTimeline().catch((err) => { logger.debug('agent inspector timeline refresh tick failed', { err }); });
+    }, REFRESH_MS));
   }
 
   private _stopRefresh(): void {
-    if (this.refreshTimer) {
-      clearInterval(this.refreshTimer);
-      this.refreshTimer = null;
+    if (this.refreshTimerId) {
+      this.clearTimer(this.refreshTimerId);
+      this.refreshTimerId = null;
     }
   }
 

package/src/panels/agent-logs-panel.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, watch, type FSWatcher } from 'fs';
+import { promises as fsPromises, watch, type FSWatcher } from 'fs';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
@@ -61,6 +61,7 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
 
   constructor(agentEvents: UiEventFeed<AgentEvent>, private readonly deps: AgentLogsPanelDeps) {
     super('agent-logs', 'Agents', 'A', 'agent');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.agentEvents = agentEvents;
     this._refreshAgents();
     this._startPolling();
@@ -256,14 +257,22 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   }
 
   private _pollCurrentAgent(): void {
+    void this._pollCurrentAgentAsync();
+  }
+
+  private async _pollCurrentAgentAsync(): Promise<void> {
     const agent = this._selectedAgent();
     if (!agent) return;
 
     const sessionFile = this._sessionFilePath(agent.id);
-    if (!existsSync(sessionFile)) return;
+    try {
+      await fsPromises.access(sessionFile);
+    } catch {
+      return;
+    }
 
     try {
-      const content = readFileSync(sessionFile, 'utf-8');
+      const content = await fsPromises.readFile(sessionFile, 'utf-8');
       if (content.length === this.lastFileSize) return;
       this.lastFileSize = content.length;
 
@@ -284,7 +293,9 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   private _watchAgent(agentId: string): void {
     this._stopWatcher();
     const sessionFile = this._sessionFilePath(agentId);
-    if (!existsSync(sessionFile)) return;
+    // Start watching immediately; the watcher setup itself is synchronous,
+    // the file-existence check is skipped to avoid blocking — if the file
+    // does not yet exist watch() will throw and we catch it below.
     try {
       this.fsWatcher = watch(sessionFile, () => {
         if (!this.paused) {
@@ -392,24 +403,33 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   }
 
   private _reloadAgent(agent: AgentRecord): void {
+    void this._reloadAgentAsync(agent);
+  }
+
+  private async _reloadAgentAsync(agent: AgentRecord): Promise<void> {
     const sessionFile = this._sessionFilePath(agent.id);
-    if (!existsSync(sessionFile)) {
+    try {
+      await fsPromises.access(sessionFile);
+    } catch {
       this.allEntries = [];
       this.filteredEntries = [];
       this.lastFileSize = 0;
+      this.markDirty();
       return;
     }
     try {
-      const content = readFileSync(sessionFile, 'utf-8');
+      const content = await fsPromises.readFile(sessionFile, 'utf-8');
       this.lastFileSize = content.length;
       this.allEntries = parseAgentJsonl(content);
       this._applyFilter();
       if (this.autoFollow) {
         this.selectedIndex = Math.max(0, this.filteredEntries.length - 1);
       }
+      this.markDirty();
     } catch {
       this.allEntries = [];
       this.filteredEntries = [];
+      this.markDirty();
     }
   }
 

package/src/panels/approval-panel.ts

@@ -33,6 +33,7 @@ export class ApprovalPanel extends ScrollableListPanel<ApprovalRow> {
 
   public constructor(policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>) {
     super('approval', 'Approval', 'A', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.policyRuntimeState = policyRuntimeState;
   }
 

package/src/panels/automation-control-panel.ts

@@ -45,6 +45,7 @@ export class AutomationControlPanel extends ScrollableListPanel<AutomationRun> {
 
   public constructor(readModel?: UiReadModel<UiAutomationSnapshot>) {
     super('automation', 'Automation', 'M', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }

package/src/panels/base-panel.ts

@@ -11,14 +11,54 @@ export abstract class BasePanel implements Panel {
   public isPinned = false;
   protected readonly componentHealthMonitor?: ComponentHealthMonitor;
 
+  // -------------------------------------------------------------------------
+  // Timer registry
+  // -------------------------------------------------------------------------
+
+  /** All timers registered via registerTimer(). Cleared automatically on onDestroy(). */
+  private readonly _timers: Set<ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>> = new Set();
+
+  /**
+   * Register a timer id (from setInterval or setTimeout) so it is
+   * automatically cleared when the panel is destroyed. Returns the id
+   * unchanged so the call can be chained inline:
+   *
+   * ```ts
+   * this.registerTimer(setInterval(() => this.refresh(), 5_000));
+   * ```
+   */
+  protected registerTimer<T extends ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>>(id: T): T {
+    this._timers.add(id);
+    return id;
+  }
+
+  /**
+   * Clear a specific timer and remove it from the registry.
+   * Safe to call with an id that was never registered or already cleared.
+   */
+  protected clearTimer(id: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>): void {
+    clearInterval(id as ReturnType<typeof setInterval>);
+    this._timers.delete(id);
+  }
+
   // -------------------------------------------------------------------------
   // I2: Error surface slot
   // -------------------------------------------------------------------------
 
-  /** Last error message to surface in the panel footer. Auto-cleared on next input. */
+  /**
+   * Last error message to surface in the panel footer.
+   * Auto-cleared on the next keystroke by `ScrollableListPanel.handleInput()` (and any
+   * subclass that calls `super.handleInput()` or manually calls `this.clearError()` at
+   * the start of its handler). BasePanel itself does NOT auto-clear — only subclasses
+   * that opt into the contract do.
+   */
   protected lastError: string | null = null;
 
-  /** Set a transient error message. Triggers a re-render. */
+  /**
+   * Set a transient error message. Triggers a re-render.
+   * The error will be auto-cleared on the next keystroke if the panel extends
+   * `ScrollableListPanel` (which calls `clearError()` at the top of `handleInput()`).
+   */
   protected setError(msg: string): void {
     this.lastError = msg;
     this.needsRender = true;
@@ -66,6 +106,32 @@ export abstract class BasePanel implements Panel {
     this.needsRender = true;
   }
 
+  /**
+   * Run an async operation with the panel's loading spinner visible.
+   * The spinner is always cleared on completion, whether the operation succeeds or throws
+   * (uses try/finally). Rethrows any error so callers can handle it or forward to setError.
+   *
+   * @param label Optional label shown next to the spinner.
+   * @param fn    The async work to run.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await this.withLoading('Loading diff…', () => this.fetchDiff());
+   * } catch (err) {
+   *   this.setError(summarizeError(err));
+   * }
+   * ```
+   */
+  protected async withLoading<T>(label: string | undefined, fn: () => Promise<T>): Promise<T> {
+    this.startLoading(label);
+    try {
+      return await fn();
+    } finally {
+      this.stopLoading();
+    }
+  }
+
   /**
    * Build a spinner Line for the loading state.
    * Returns null when loadingState is not 'loading'.
@@ -107,7 +173,17 @@ export abstract class BasePanel implements Panel {
 
   onActivate(): void { this.needsRender = true; }
   onDeactivate(): void {}
-  onDestroy(): void {}
+
+  /**
+   * Called when the panel is permanently removed. Subclasses should call
+   * `super.onDestroy()` to ensure all registered timers are cleared.
+   */
+  onDestroy(): void {
+    for (const id of this._timers) {
+      clearInterval(id as ReturnType<typeof setInterval>);
+    }
+    this._timers.clear();
+  }
 
   abstract render(width: number, height: number): Line[];
 
@@ -146,4 +222,33 @@ export abstract class BasePanel implements Panel {
   protected reportRenderDuration(durationMs: number, now: number = Date.now()): void {
     this.componentHealthMonitor?.recordRender(this.id, durationMs, now);
   }
+
+  /** Cache of the most recent lines produced by trackedRender. */
+  private _lastTrackedLines: Line[] = [];
+
+  /**
+   * Wrap a render body with canRenderNow throttle check, wall-clock timing,
+   * and automatic reportRenderDuration.
+   *
+   * When throttled, returns the previously cached lines (stale but correctly
+   * sized) rather than empty lines, avoiding a flicker on every skipped frame.
+   *
+   * Usage:
+   * ```ts
+   * render(width: number, height: number): Line[] {
+   *   return this.trackedRender(() => {
+   *     // expensive render logic
+   *     return lines;
+   *   });
+   * }
+   * ```
+   */
+  protected trackedRender(fn: () => Line[]): Line[] {
+    if (!this.canRenderNow()) return this._lastTrackedLines;
+    const start = Date.now();
+    const lines = fn();
+    this.reportRenderDuration(Date.now() - start);
+    this._lastTrackedLines = lines;
+    return lines;
+  }
 }

package/src/panels/communication-panel.ts

@@ -32,6 +32,7 @@ export class CommunicationPanel extends ScrollableListPanel<CommunicationRecord>
 
   public constructor(readModel?: UiReadModel<UiCommunicationSnapshot>) {
     super('communication', 'Communication', 'Y', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }

package/src/panels/context-visualizer-panel.ts

@@ -72,6 +72,7 @@ export class ContextVisualizerPanel extends BasePanel {
   }
 
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     if (height <= 0 || width <= 0) return [];
 
     const input = this.snapshot.input;
@@ -131,6 +132,7 @@ export class ContextVisualizerPanel extends BasePanel {
       ],
       palette: DEFAULT_PANEL_PALETTE,
     });
+    });
   }
 
   private _renderBar(width: number, barWidth: number, input: number, limit: number): Line {

package/src/panels/control-plane-panel.ts

@@ -43,6 +43,7 @@ export class ControlPlanePanel extends ScrollableListPanel<ControlPlaneClient> {
 
   public constructor(private readonly readModel?: UiReadModel<UiControlPlaneSnapshot>) {
     super('control-plane', 'Control Plane', 'C', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
 

package/src/panels/diff-panel.ts

@@ -345,6 +345,7 @@ export class DiffPanel extends BasePanel {
   // -------------------------------------------------------------------------
 
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     if (height <= 0 || width <= 0) return [];
 
     if (this.entries.length === 0) {
@@ -440,6 +441,7 @@ export class DiffPanel extends BasePanel {
       sections,
       footerLines: [this.renderStatusBar(width, entry)],
     });
+    });
   }
 
   // ── Tab bar ──────────────────────────────────────────────────────────────

package/src/panels/file-explorer-panel.ts

@@ -2,7 +2,7 @@
 // FileExplorerPanel — collapsible project tree view
 // ---------------------------------------------------------------------------
 
-import { readdirSync, statSync } from 'node:fs';
+import { promises as fsPromises } from 'node:fs';
 import { join, relative, basename } from 'node:path';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
@@ -120,6 +120,7 @@ export class FileExplorerPanel extends BasePanel {
   private rootPath: string;
   private readonly workingDirectory: string;
   private cacheValid: boolean = false;
+  private readyPromise: Promise<void> | null = null;
 
   // --- navigation ---
   private cursor: number = 0;
@@ -139,7 +140,9 @@ export class FileExplorerPanel extends BasePanel {
 
   override onActivate(): void {
     super.onActivate();
-    if (!this.cacheValid) this._buildTree();
+    if (!this.cacheValid) {
+      void this._buildTreeAsync();
+    }
   }
 
   override onDestroy(): void {
@@ -153,8 +156,7 @@ export class FileExplorerPanel extends BasePanel {
   /** Force a full tree refresh from disk. */
   refresh(): void {
     this.cacheValid = false;
-    this._buildTree();
-    this.markDirty();
+    void this._buildTreeAsync();
   }
 
   /** Currently focused node (or null). */
@@ -197,7 +199,6 @@ export class FileExplorerPanel extends BasePanel {
   // ── Render ─────────────────────────────────────────────────────────────────
 
   render(width: number, height: number): Line[] {
-    if (!this.cacheValid) this._buildTree();
     this.needsRender = false;
     const searchLine = this.searchMode
       ? `/ ${this.searchQuery}_`
@@ -324,14 +325,29 @@ export class FileExplorerPanel extends BasePanel {
 
   // ── Private: tree building ─────────────────────────────────────────────────
 
-  private _buildTree(): void {
-    this.root = this._scanDir(this.rootPath, 0);
-    this._rebuildFlat();
-    this.cacheValid = true;
-    this.markDirty();
+  private _buildTreeAsync(): Promise<void> {
+    const p = (async () => {
+      try {
+        await this.withLoading('Scanning directory\u2026', async () => {
+          this.root = await this._scanDirAsync(this.rootPath, 0);
+          this._rebuildFlat();
+          this.cacheValid = true;
+        });
+      } catch (err) {
+        this.setError(err instanceof Error ? err.message : String(err));
+      }
+      this.markDirty();
+    })();
+    this.readyPromise = p;
+    return p;
+  }
+
+  /** Resolves when the current tree build has settled. */
+  public awaitReady(): Promise<void> {
+    return this.readyPromise ?? Promise.resolve();
   }
 
-  private _scanDir(dirPath: string, depth: number): TreeNode {
+  private async _scanDirAsync(dirPath: string, depth: number): Promise<TreeNode> {
     const name = basename(dirPath);
     const node: TreeNode = {
       path: dirPath,
@@ -339,7 +355,7 @@ export class FileExplorerPanel extends BasePanel {
       isDir: true,
       depth,
       size: 0,
-      expanded: depth === 0, // root starts expanded
+      expanded: depth === 0,
       children: [],
       loaded: false,
     };
@@ -348,7 +364,7 @@ export class FileExplorerPanel extends BasePanel {
 
     let entries: string[];
     try {
-      entries = readdirSync(dirPath);
+      entries = await fsPromises.readdir(dirPath);
     } catch {
       return node;
     }
@@ -356,31 +372,35 @@ export class FileExplorerPanel extends BasePanel {
     node.loaded = true;
 
     // Sort: dirs first, then files, alphabetically within each group
-    const sorted = entries
-      .filter(e => !shouldSkip(e))
-      .sort((a, b) => {
-        let aIsDir = false;
-        let bIsDir = false;
-        try { aIsDir = statSync(join(dirPath, a)).isDirectory(); } catch { /* ignore */ }
-        try { bIsDir = statSync(join(dirPath, b)).isDirectory(); } catch { /* ignore */ }
-        if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
-        return a.localeCompare(b);
-      });
+    const filtered = entries.filter(e => !shouldSkip(e));
+    const statResults = await Promise.all(
+      filtered.map(async (e) => {
+        try {
+          const s = await fsPromises.stat(join(dirPath, e));
+          return { name: e, isDir: s.isDirectory(), size: s.size, stat: s };
+        } catch {
+          return { name: e, isDir: false, size: 0, stat: null };
+        }
+      }),
+    );
+
+    const sorted = statResults.sort((a, b) => {
+      if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
 
     for (const entry of sorted) {
-      const fullPath = join(dirPath, entry);
-      let stat;
-      try { stat = statSync(fullPath); } catch { continue; }
-
-      if (stat.isDirectory()) {
-        node.children.push(this._scanDir(fullPath, depth + 1));
+      if (entry.stat === null) continue;
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDir) {
+        node.children.push(await this._scanDirAsync(fullPath, depth + 1));
       } else {
         node.children.push({
           path: fullPath,
-          name: entry,
+          name: entry.name,
           isDir: false,
           depth: depth + 1,
-          size: stat.size,
+          size: entry.size,
           expanded: false,
           children: [],
           loaded: true,

package/src/panels/file-preview-panel.ts

@@ -1,4 +1,5 @@
-import * as fs from 'node:fs';
+import type { Stats } from 'node:fs';
+import { promises as fsPromises, readFileSync, statSync } from 'node:fs';
 import * as path from 'node:path';
 import type { Line, Cell } from '../types/grid.ts';
 import { createStyledCell, createEmptyLine } from '../types/grid.ts';
@@ -68,7 +69,7 @@ export class FilePreviewPanel extends BasePanel {
   // ─── Public API ─────────────────────────────────────────────────────────────
 
   /**
-   * Load a file into the preview. Reads synchronously (small files only).
+   * Load a file into the preview. Reads asynchronously.
    * Files larger than 100 KB show a warning instead of content.
    */
   openFile(filePath: string): void {
@@ -79,51 +80,72 @@ export class FilePreviewPanel extends BasePanel {
 
     this.filePath = filePath;
     this.oversized = false;
-    this.fileLines = [];
-    this.fenceTag = '';
+    this.fenceTag = extToFenceTag(filePath);
 
     // Restore scroll position for this file, or start at top
     this.scrollOffset = this.scrollMemory.get(filePath) ?? 0;
 
-    let stat: fs.Stats;
+    // Synchronously pre-populate fileLines for small files so that callers
+    // (e.g. syncSymbolOutlineFromPreview) can read getSource() immediately.
     try {
-      stat = fs.statSync(filePath);
+      const stat = statSync(filePath);
+      if (stat.size <= MAX_FILE_SIZE) {
+        const content = readFileSync(filePath, 'utf-8');
+        this.fileLines = content.split('\n');
+      } else {
+        this.fileLines = [];
+        this.oversized = true;
+      }
     } catch {
       this.fileLines = [`(cannot open: ${filePath})`];
-      this.markDirty();
-      return;
     }
 
-    if (stat.size > MAX_FILE_SIZE) {
-      this.oversized = true;
-      this.markDirty();
-      return;
-    }
+    void this._loadFileAsync(filePath);
+  }
 
-    let content: string;
+  private async _loadFileAsync(filePath: string): Promise<void> {
     try {
-      content = fs.readFileSync(filePath, 'utf-8');
-    } catch {
-      this.fileLines = [`(read error: ${filePath})`];
-      this.markDirty();
-      return;
-    }
-
-    this.fileLines = content.split('\n');
-    // Strip trailing empty line from final newline
-    if (this.fileLines.length > 0 && this.fileLines[this.fileLines.length - 1] === '') {
-      this.fileLines.pop();
-    }
-
-    this.fenceTag = extToFenceTag(filePath);
-
-    // Kick off async tree-sitter parse so subsequent renders get highlighting
-    if (this.fenceTag) {
-      this.syntaxHighlighter.highlight(content, this.fenceTag);
+      await this.withLoading('Loading…', async () => {
+        let stat: Stats;
+        try {
+          stat = await fsPromises.stat(filePath);
+        } catch {
+          this.fileLines = [`(cannot open: ${filePath})`];
+          return;
+        }
+
+        if (stat.size > MAX_FILE_SIZE) {
+          this.oversized = true;
+          return;
+        }
+
+        let content: string;
+        try {
+          content = await fsPromises.readFile(filePath, 'utf-8');
+        } catch {
+          this.fileLines = [`(read error: ${filePath})`];
+          return;
+        }
+
+        this.fileLines = content.split('\n');
+        // Strip trailing empty line from final newline
+        if (this.fileLines.length > 0 && this.fileLines[this.fileLines.length - 1] === '') {
+          this.fileLines.pop();
+        }
+
+        this.fenceTag = extToFenceTag(filePath);
+
+        // Kick off async tree-sitter parse so subsequent renders get highlighting
+        if (this.fenceTag) {
+          this.syntaxHighlighter.highlight(content, this.fenceTag);
+        }
+
+        // Clamp scroll in case the new file is shorter
+        this.clampScroll(0);
+      });
+    } catch (err) {
+      this.setError(err instanceof Error ? err.message : String(err));
     }
-
-    // Clamp scroll in case the new file is shorter
-    this.clampScroll(0);
     this.markDirty();
   }