@pellux/goodvibes-tui 0.27.0 → 0.29.0

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

@@ -6,6 +6,7 @@ import type { Line } from '../types/grid.ts';
 import { BasePanel } from './base-panel.ts';
 import type { ToolEvent, TurnEvent } from '@/runtime/index.ts';
 import type { UiEventFeed } from '../runtime/ui-events.ts';
+import type { PanelIntegrationContext } from './types.ts';
 import {
   buildEmptyState,
   buildPanelLine,
@@ -16,7 +17,9 @@ import {
   extendPalette,
   type PanelWorkspaceSection,
 } from './polish.ts';
+import { type ConfirmState, handleConfirmInput, renderConfirmLines } from './confirm-state.ts';
 import { truncateDisplay } from '../utils/terminal-width.ts';
+import { formatDuration } from '../utils/format-duration.ts';
 
 // Panel-specific accents only; shared tones come from DEFAULT_PANEL_PALETTE so
 // theme changes propagate. selectedBg->selectBg, errorFg->bad are shared keys.
@@ -32,15 +35,23 @@ interface ToolCallRecord {
   callId: string;
   tool: string;
   args: Record<string, unknown>;
+  /** Wall-clock time the call was received from the LLM (queued, not yet executing). */
   startMs: number;
+  /**
+   * Real execution-start time from TOOL_EXECUTING.startedAt — used for duration
+   * math when present so displayed durations reflect actual run time rather
+   * than time spent in permission/hook queueing. Falls back to `startMs` when
+   * a call completes without ever reaching TOOL_EXECUTING (e.g. denied before
+   * execution).
+   */
+  execStartMs?: number;
   endMs?: number;
   result?: unknown;
   error?: string;
+  cancelled?: boolean;
   expanded: boolean;
   approved?: boolean;
   outputClass?: string;
-  policyAction?: string;
-  spillBackend?: string;
   resultSummary?: string;
 }
 
@@ -56,14 +67,12 @@ function shortTime(ms: number): string {
 }
 
 function formatMs(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+  return formatDuration(ms);
 }
 
 function truncateJson(val: unknown, maxLen = 120): string {
   const s = JSON.stringify(val) ?? 'null';
-  return s.length > maxLen ? s.slice(0, maxLen - 1) + '\u2026' : s;
+  return truncateDisplay(s, maxLen);
 }
 
 function summarizeResult(result: unknown): string | undefined {
@@ -73,7 +82,7 @@ function summarizeResult(result: unknown): string | undefined {
   const record = result as Record<string, unknown>;
   if (typeof record.preview === 'string' && record.preview.trim()) {
     const compact = record.preview.replace(/\s+/g, ' ').trim();
-    return compact.length > 72 ? `${compact.slice(0, 69)}\u2026` : compact;
+    return truncateDisplay(compact, 72);
   }
   if (typeof record.kind === 'string' && typeof record.byteSize === 'number') {
     return `${record.kind} (${record.byteSize}B)`;
@@ -81,6 +90,20 @@ function summarizeResult(result: unknown): string | undefined {
   return undefined;
 }
 
+function statusLabel(rec: ToolCallRecord): string {
+  if (rec.endMs === undefined) return 'running';
+  if (rec.cancelled) return 'cancelled';
+  if (rec.error) return 'error';
+  return 'completed';
+}
+
+function statusColor(rec: ToolCallRecord): string {
+  if (rec.endMs === undefined) return DEFAULT_PANEL_PALETTE.warn;
+  if (rec.cancelled) return DEFAULT_PANEL_PALETTE.dim;
+  if (rec.error) return DEFAULT_PANEL_PALETTE.bad;
+  return DEFAULT_PANEL_PALETTE.good;
+}
+
 function detectOutputClass(tool: string, args: Record<string, unknown>): string {
   const name = tool.toLowerCase();
   if (name.includes('read') || name.includes('find') || name.includes('inspect') || name.includes('grep')) return 'read';
@@ -98,6 +121,10 @@ export class ToolInspectorPanel extends BasePanel {
   private scrollOffset = 0;
   private autoScroll = true;
   private _flatCache: FlatRow[] | null = null;
+  /** Pending confirm for 'c' clear — destructive (drops call history), so it goes through the project-standard confirm contract. */
+  private _confirm: ConfirmState<'clear'> | null = null;
+  /** Set by handleInput('a') when the selected call is awaiting a permission decision; consumed by handlePanelIntegrationAction. */
+  private _pendingApprovalJump = false;
 
   constructor(
     private readonly toolEvents: UiEventFeed<ToolEvent>,
@@ -125,39 +152,89 @@ export class ToolInspectorPanel extends BasePanel {
   }
 
   handleInput(key: string): boolean {
+    const confirmResult = handleConfirmInput(this._confirm, key);
+    if (confirmResult === 'confirmed') {
+      this.records = [];
+      this._confirm = null;
+      this.markDirty();
+      return true;
+    }
+    if (confirmResult === 'cancelled') {
+      this._confirm = null;
+      this.markDirty();
+      return true;
+    }
+    if (confirmResult === 'absorbed') return true;
+
     switch (key) {
       case 'up':       this._move(-1);           this.autoScroll = false; return true;
       case 'down':     this._move(1);            return true;
       case 'pageup':   this._move(-10);          this.autoScroll = false; return true;
       case 'pagedown': this._move(10);           return true;
       case 'return':   this._toggleExpand();     return true;
-      case 'c':        this.records = []; this.markDirty(); return true;
+      case 'c': {
+        if (this.records.length === 0) return false;
+        this._confirm = { subject: 'clear', label: `${this.records.length} tool call${this.records.length === 1 ? '' : 's'}`, verb: 'Clear' };
+        this.markDirty();
+        return true;
+      }
       case 'g':        this.autoScroll = true;   this.markDirty(); return true;
       case 'f':        this._cycleFilter();      return true;
+      case 'a': {
+        const rec = this._selectedRecord();
+        if (!rec || rec.approved !== undefined || rec.endMs !== undefined) return false;
+        this._pendingApprovalJump = true;
+        return true;
+      }
       default:         return false;
     }
   }
 
+  /**
+   * Cross-panel hook — invoked immediately after handleInput('a') returns true
+   * for a call still awaiting a permission decision. Jumps to the Approval
+   * panel; the actual PanelManager reference is only available here.
+   */
+  handlePanelIntegrationAction(_key: string, ctx: PanelIntegrationContext): boolean {
+    if (!this._pendingApprovalJump) return false;
+    this._pendingApprovalJump = false;
+    ctx.panelManager.open('approval');
+    return true;
+  }
+
   render(width: number, height: number): Line[] {
     if (height <= 0 || width <= 0) return [];
 
     const running = this.records.filter(r => r.endMs === undefined).length;
+    const distinctTools = new Set(this.records.map((r) => r.tool)).size;
     const filterLabel = this.filterMode === 'all' ? '' : ` [${this.filterMode}]`;
     const title = ` Tools [${this.records.length} calls${running > 0 ? `, ${running} running` : ''}]${filterLabel}`;
-    const footerLines = [
-      buildPanelLine(width, [
-        [' Up/Down', DEFAULT_PANEL_PALETTE.info],
-        [' scroll', DEFAULT_PANEL_PALETTE.dim],
-        ['   Enter', DEFAULT_PANEL_PALETTE.info],
-        [' expand', DEFAULT_PANEL_PALETTE.dim],
-        ['   f', DEFAULT_PANEL_PALETTE.info],
-        [' filter', DEFAULT_PANEL_PALETTE.dim],
-        ['   c', DEFAULT_PANEL_PALETTE.info],
-        [' clear', DEFAULT_PANEL_PALETTE.dim],
-        ['   g', DEFAULT_PANEL_PALETTE.info],
-        [' end', DEFAULT_PANEL_PALETTE.dim],
-      ]),
+    // Context-aware footer: only advertise keys that do something in the current
+    // state — filter needs >1 tool, clear/end need at least one call.
+    const footerSegments: Array<[string, string, string?]> = [
+      [' Up/Down', DEFAULT_PANEL_PALETTE.info], [' scroll', DEFAULT_PANEL_PALETTE.dim],
+      ['   Enter', DEFAULT_PANEL_PALETTE.info], [' expand', DEFAULT_PANEL_PALETTE.dim],
     ];
+    if (distinctTools > 1) {
+      footerSegments.push(['   f', DEFAULT_PANEL_PALETTE.info], [' filter', DEFAULT_PANEL_PALETTE.dim]);
+    }
+    if (this.records.length > 0) {
+      footerSegments.push(['   c', DEFAULT_PANEL_PALETTE.info], [' clear', DEFAULT_PANEL_PALETTE.dim]);
+      footerSegments.push(['   g', DEFAULT_PANEL_PALETTE.info], [this.autoScroll ? ' end (live)' : ' jump to end', DEFAULT_PANEL_PALETTE.dim]);
+    }
+    const selectedRecordForFooter = this._selectedRecord();
+    if (selectedRecordForFooter && selectedRecordForFooter.approved === undefined && selectedRecordForFooter.endMs === undefined) {
+      footerSegments.push(['   a', DEFAULT_PANEL_PALETTE.info], [' review approval', DEFAULT_PANEL_PALETTE.dim]);
+    }
+    const footerLines = [buildPanelLine(width, footerSegments)];
+
+    if (this._confirm) {
+      return buildPanelWorkspace(width, height, {
+        title,
+        sections: [{ title: 'Confirmation', lines: renderConfirmLines(width, this._confirm) }],
+        palette: DEFAULT_PANEL_PALETTE,
+      });
+    }
 
     const flat = this._getFlat();
 
@@ -168,15 +245,21 @@ export class ToolInspectorPanel extends BasePanel {
     if (flat.length === 0) {
       return buildPanelWorkspace(width, height, {
         title,
-        intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+        intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls — including calls made by delegated subagents.',
         sections: [
           {
             title: 'Calls',
             lines: buildEmptyState(
               width,
-              ' No tool calls yet',
-              'Tool executions appear here as the agent works. Expand a call to inspect its arguments and result payload.',
-              [],
+              this.records.length > 0 && this.filterMode !== 'all'
+                ? ` No "${this.filterMode}" calls`
+                : ' No tool calls yet',
+              this.records.length > 0 && this.filterMode !== 'all'
+                ? 'The active tool filter hides every recorded call.'
+                : 'Tool executions appear here as the agent works, including calls made by delegated subagents. Expand a call to inspect its arguments and result payload.',
+              this.records.length > 0 && this.filterMode !== 'all'
+                ? [{ command: 'f', summary: 'cycle the tool filter back to all calls' }]
+                : [{ command: '/spawn <task>', summary: 'run an agent to populate the tool-call timeline' }],
               DEFAULT_PANEL_PALETTE,
             ),
           },
@@ -209,22 +292,14 @@ export class ToolInspectorPanel extends BasePanel {
         : this.records.filter(r => r.tool === this.filterMode);
       const rec = filtered[selected.recordIndex];
       if (rec) {
-        detailLines.push(buildPanelLine(width, [[' Tool ', DEFAULT_PANEL_PALETTE.label], [rec.tool, DEFAULT_PANEL_PALETTE.info], ['   Started ', DEFAULT_PANEL_PALETTE.label], [shortTime(rec.startMs), DEFAULT_PANEL_PALETTE.value]]));
-        detailLines.push(buildPanelLine(width, [[' Status ', DEFAULT_PANEL_PALETTE.label], [rec.endMs === undefined ? 'running' : rec.error ? 'error' : 'completed', rec.endMs === undefined ? DEFAULT_PANEL_PALETTE.warn : rec.error ? DEFAULT_PANEL_PALETTE.bad : DEFAULT_PANEL_PALETTE.good]]));
+        detailLines.push(buildPanelLine(width, [[' Tool ', DEFAULT_PANEL_PALETTE.label], [rec.tool, DEFAULT_PANEL_PALETTE.info], ['   Started ', DEFAULT_PANEL_PALETTE.label], [shortTime(rec.execStartMs ?? rec.startMs), DEFAULT_PANEL_PALETTE.value]]));
+        detailLines.push(buildPanelLine(width, [[' Status ', DEFAULT_PANEL_PALETTE.label], [statusLabel(rec), statusColor(rec)]]));
         detailLines.push(buildPanelLine(width, [
-          [' Risk ', DEFAULT_PANEL_PALETTE.label],
+          [' Class ', DEFAULT_PANEL_PALETTE.label],
           [rec.outputClass ?? detectOutputClass(rec.tool, rec.args), DEFAULT_PANEL_PALETTE.warn],
           ['   Approved ', DEFAULT_PANEL_PALETTE.label],
           [rec.approved === undefined ? 'unknown' : rec.approved ? 'yes' : 'no', rec.approved === false ? DEFAULT_PANEL_PALETTE.bad : DEFAULT_PANEL_PALETTE.value],
         ]));
-        if (rec.policyAction || rec.spillBackend) {
-          detailLines.push(buildPanelLine(width, [
-            [' Output ', DEFAULT_PANEL_PALETTE.label],
-            [rec.policyAction ?? 'none', rec.policyAction && rec.policyAction !== 'none' ? DEFAULT_PANEL_PALETTE.warn : DEFAULT_PANEL_PALETTE.value],
-            ['   Spill ', DEFAULT_PANEL_PALETTE.label],
-            [rec.spillBackend ?? 'none', rec.spillBackend ? DEFAULT_PANEL_PALETTE.info : DEFAULT_PANEL_PALETTE.dim],
-          ]));
-        }
         if (rec.resultSummary) {
           detailLines.push(buildPanelLine(width, [[' Summary ', DEFAULT_PANEL_PALETTE.label], [rec.resultSummary, DEFAULT_PANEL_PALETTE.value]]));
         }
@@ -234,7 +309,7 @@ export class ToolInspectorPanel extends BasePanel {
 
     const selectedSection: PanelWorkspaceSection = { title: 'Selected', lines: detailLines };
     const callsSection = resolveScrollablePanelSection(width, height, {
-      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls — including calls made by delegated subagents.',
       footerLines,
       palette: DEFAULT_PANEL_PALETTE,
       beforeSections: [summary],
@@ -251,7 +326,7 @@ export class ToolInspectorPanel extends BasePanel {
 
     return buildPanelWorkspace(width, height, {
       title,
-      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls — including calls made by delegated subagents.',
       sections: [
         summary,
         callsSection.section,
@@ -285,25 +360,24 @@ export class ToolInspectorPanel extends BasePanel {
 
     for (let i = 0; i < filtered.length; i++) {
       const rec = filtered[i]!;
-      const dur = rec.endMs !== undefined ? ` (${formatMs(rec.endMs - rec.startMs)})` : ' (running)';
+      // Duration is measured from real execution start (TOOL_EXECUTING.startedAt) when
+      // known, not from queue/receive time, so it reflects actual run time rather than
+      // time spent waiting on permission/hook checks. Falls back to startMs for calls
+      // that never reached TOOL_EXECUTING (e.g. denied before execution).
+      const durBaseMs = rec.execStartMs ?? rec.startMs;
+      const dur = rec.cancelled
+        ? ` (cancelled${rec.endMs !== undefined ? ` ${formatMs(rec.endMs - durBaseMs)}` : ''})`
+        : rec.endMs !== undefined ? ` (${formatMs(rec.endMs - durBaseMs)})` : ' (running)';
       const expand = rec.expanded ? ' ▾' : ' ▸';
       const ts = shortTime(rec.startMs);
-      const risk = rec.outputClass ?? detectOutputClass(rec.tool, rec.args);
-      const action = rec.policyAction && rec.policyAction !== 'none' ? ` ${rec.policyAction}` : '';
-      const callText = `${ts} ${rec.tool} [${risk}]${action}${dur}${expand}`;
+      const cls = rec.outputClass ?? detectOutputClass(rec.tool, rec.args);
+      const callText = `${ts} ${rec.tool} [${cls}]${dur}${expand}`;
       flat.push({ kind: 'call', recordIndex: i, text: callText });
 
       if (rec.expanded) {
         const argsStr = truncateJson(rec.args, 200);
         flat.push({ kind: 'detail', text: `Args: ${argsStr}`, isError: false });
-        flat.push({ kind: 'detail', text: `Risk: ${risk}${rec.approved === undefined ? '' : `  Approved: ${rec.approved ? 'yes' : 'no'}`}`, isError: false });
-        if (rec.policyAction || rec.spillBackend) {
-          flat.push({
-            kind: 'detail',
-            text: `Output policy: ${rec.policyAction ?? 'none'}${rec.spillBackend ? `  Spill: ${rec.spillBackend}` : ''}`,
-            isError: false,
-          });
-        }
+        flat.push({ kind: 'detail', text: `Class: ${cls}${rec.approved === undefined ? '' : `  Approved: ${rec.approved ? 'yes' : 'no'}`}`, isError: false });
         if (rec.resultSummary) {
           flat.push({ kind: 'detail', text: `Summary: ${rec.resultSummary}`, isError: false });
         }
@@ -332,6 +406,17 @@ export class ToolInspectorPanel extends BasePanel {
     }
   }
 
+  /** The tool-call record backing the currently-selected flat row, if any. */
+  private _selectedRecord(): ToolCallRecord | undefined {
+    const flat = this._getFlat();
+    const row = flat[this.cursorIndex];
+    if (!row || row.kind !== 'call') return undefined;
+    const filtered = this.filterMode === 'all'
+      ? this.records
+      : this.records.filter(r => r.tool === this.filterMode);
+    return filtered[row.recordIndex];
+  }
+
   private _cycleFilter(): void {
     const tools = [...new Set(this.records.map(r => r.tool))];
     if (tools.length === 0) return;
@@ -344,6 +429,18 @@ export class ToolInspectorPanel extends BasePanel {
     this.markDirty();
   }
 
+  /**
+   * Public counterpart to the 'f' cycle — sets the filter directly to a named
+   * tool. Used by cross-panel jumps (WO-136: DocsPanel Enter on a tool row)
+   * so the inspector opens already scoped to the tool the operator picked.
+   */
+  public filterByTool(tool: string): void {
+    this.filterMode = tool;
+    this.cursorIndex = 0;
+    this.autoScroll = false;
+    this.markDirty();
+  }
+
   private _move(delta: number): void {
     const flat = this._getFlat();
     if (flat.length === 0) return;
@@ -376,11 +473,17 @@ export class ToolInspectorPanel extends BasePanel {
       this.markDirty();
     }));
 
+    // Real execution start — recorded separately from TOOL_RECEIVED's queue time so
+    // displayed durations reflect actual run time, not time spent waiting on
+    // permission/hook checks ahead of execution.
+    this.unsubs.push(this.toolEvents.on('TOOL_EXECUTING', (data) => {
+      const rec = this.records.findLast(r => r.callId === data.callId);
+      if (rec) rec.execStartMs = data.startedAt;
+      this.markDirty();
+    }));
+
     // NOTE: After SDK OBS-05 (0.21.31), TOOL_SUCCEEDED/TOOL_FAILED.result is a ToolResultSummary
-    // ({ kind, byteSize, preview? }) rather than the raw ToolResult object. The previous
-    // `_policyAudit` extraction is no longer reachable via this event — policy audit metadata
-    // must be sourced from a different channel (approval broker / tool result store) if the
-    // Tool Inspector is to display it in future.
+    // ({ kind, byteSize, preview? }) rather than the raw ToolResult object.
     this.unsubs.push(this.toolEvents.on('TOOL_SUCCEEDED', (data) => {
       const rec = this.records.findLast(r => r.callId === data.callId);
       if (rec) {
@@ -402,6 +505,19 @@ export class ToolInspectorPanel extends BasePanel {
       this.markDirty();
     }));
 
+    // Terminal state for a cancelled call — without this subscription, a call
+    // cancelled mid-flight (e.g. via Ctrl+C) never gets an endMs and shows as
+    // "running" forever.
+    this.unsubs.push(this.toolEvents.on('TOOL_CANCELLED', (data) => {
+      const rec = this.records.findLast(r => r.callId === data.callId);
+      if (rec) {
+        rec.endMs = Date.now();
+        rec.cancelled = true;
+        rec.resultSummary = data.reason ?? 'cancelled';
+      }
+      this.markDirty();
+    }));
+
     this.unsubs.push(this.turnEvents.on('TURN_ERROR', (data) => {
       // Mark any running calls as errored
       for (const rec of this.records) {

package/src/panels/types.ts

@@ -1,5 +1,20 @@
 import type { Line } from '../types/grid.ts';
+import type { StatusState } from '../renderer/status-glyphs.ts';
 import type { ComponentResourceContract, ComponentHealthState } from '../runtime/perf/panel-contracts.ts';
+// Routed through the `@/` alias (not `./panel-manager.ts`) so this foundational
+// types module stays a leaf in the relative-import graph the architecture
+// cycle-checker walks. Type-only, erased at runtime — no real dependency edge.
+import type { PanelManager } from '@/panels/panel-manager.ts';
+
+/**
+ * Context passed to a panel's `handlePanelIntegrationAction` hook so it can
+ * drive cross-panel behavior (e.g. file-explorer opening the preview panel)
+ * without the input layer needing `instanceof` knowledge of each panel type.
+ */
+export interface PanelIntegrationContext {
+  readonly panelManager: PanelManager;
+  readonly executeCommand?: (name: string, args: string[]) => Promise<unknown>;
+}
 
 /**
  * Named logical key identifiers emitted by the input tokenizer.
@@ -28,7 +43,28 @@ export type NamedKey =
  */
 export type KeyName = NamedKey | (string & {});
 
-export type PanelCategory = 'development' | 'agent' | 'monitoring' | 'session' | 'ai';
+/**
+ * WO-152: the former single 'monitoring' bucket held 33 panels pre-merge —
+ * too coarse for the picker to be useful and too large for any one operator
+ * mental model. Split into named operator domains so each category holds a
+ * bounded, coherent set (no category may exceed 10 registrations):
+ *   - providers:              provider/model connectivity, cost, and token usage
+ *   - security-policy:        auth, policy governance, and isolation posture
+ *   - automation-control:     hooks, plugins, marketplace, automation jobs, worktrees
+ *   - incidents-diagnostics:  failure review, eval gates, API call debugging
+ *   - runtime-ops:            live operator consoles (cockpit, tasks, orchestration, comms)
+ * 'development' | 'agent' | 'session' | 'ai' are unchanged from before the split.
+ */
+export type PanelCategory =
+  | 'development'
+  | 'agent'
+  | 'session'
+  | 'ai'
+  | 'providers'
+  | 'security-policy'
+  | 'automation-control'
+  | 'incidents-diagnostics'
+  | 'runtime-ops';
 
 export interface Panel {
   id: string;
@@ -67,15 +103,40 @@ export interface Panel {
   // Scroll input (optional)
   // Positive delta scrolls down; negative delta scrolls up.
   handleScroll?(deltaRows: number): boolean;
+
+  /**
+   * Cross-panel integration hook (optional). Called before the panel's own
+   * `handleInput` when a navigation/confirm key is pressed, so a panel can
+   * drive another panel (e.g. open a file in the preview panel). Return `true`
+   * to consume the key. The legacy `handlePanelIntegrationAction` router in
+   * `src/input/panel-integration-actions.ts` consults this first, then falls
+   * back to its built-in `instanceof` routing.
+   */
+  handlePanelIntegrationAction?(key: string, ctx: PanelIntegrationContext): boolean;
 }
 
 export interface PanelRegistration extends Pick<Panel, 'id' | 'name' | 'icon' | 'category'> {
   factory: () => Panel;
   description: string;
   /**
-   * Instantiate this panel during bootstrap and retain the instance when it is
-   * closed so its background data continues to accumulate before the user
-   * actively opens the workspace.
+   * WO-152 lifecycle flags. `preload` and `retainOnClose` are independent —
+   * a panel can eagerly instantiate without being kept alive on close, or be
+   * kept alive on close without eager bootstrap instantiation. They happened
+   * to be identical for all builtin panels before this split (both driven by
+   * a single `preload: true`); that existing 10-panel retained set is
+   * preserved unchanged by giving each of those 10 registrations both flags.
+   *
+   * - `preload` — instantiate this panel during `PanelManager.prewarmRegistered()`
+   *   (called once at bootstrap) so its factory runs and it starts
+   *   accumulating background data (subscriptions, timers) before the user
+   *   ever opens the workspace. Panels without `preload` are instantiated
+   *   lazily on first `open()`.
+   * - `retainOnClose` — when this panel is closed, keep the live instance in
+   *   `PanelManager`'s retained-panel map (background subscriptions/timers
+   *   keep running) instead of calling `onDestroy()`. Reopening returns the
+   *   same instance with its accumulated state intact. Panels without
+   *   `retainOnClose` are destroyed on close and rebuilt fresh next open.
    */
   preload?: boolean;
+  retainOnClose?: boolean;
 }