@pellux/goodvibes-agent 0.1.0

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

@@ -0,0 +1,429 @@
+// ---------------------------------------------------------------------------
+// ToolInspectorPanel — chronological list of tool calls with args/results.
+// ---------------------------------------------------------------------------
+
+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 {
+  buildEmptyState,
+  buildPanelLine,
+  buildStyledPanelLine,
+  buildPanelWorkspace,
+  resolveScrollablePanelSection,
+  DEFAULT_PANEL_PALETTE,
+  type PanelWorkspaceSection,
+} from './polish.ts';
+import { truncateDisplay } from '../utils/terminal-width.ts';
+
+const C = {
+  headerBg:    '#1a1a2e',
+  headerFg:    '#ffffff',
+  statusBar:   '#222233',
+  statusFg:    '#aaaaaa',
+  toolFg:      '#00ccff',
+  resultFg:    '#66ddff',
+  errorFg:     '#ff6666',
+  durationFg:  '#aaaa66',
+  argsFg:      '#aaaaaa',
+  dimFg:       '#555566',
+  selected:    '#00ffff',
+  selectedBg:  '#1a2a3a',
+  labelFg:     '#8888bb',
+  filterFg:    '#ffcc44',
+} as const;
+
+const MAX_ENTRIES = 500;
+
+interface ToolCallRecord {
+  callId: string;
+  tool: string;
+  args: Record<string, unknown>;
+  startMs: number;
+  endMs?: number;
+  result?: unknown;
+  error?: string;
+  expanded: boolean;
+  approved?: boolean;
+  outputClass?: string;
+  policyAction?: string;
+  spillBackend?: string;
+  resultSummary?: string;
+}
+
+type FilterMode = 'all' | string;
+
+type FlatRow =
+  | { kind: 'call'; recordIndex: number; text: string }
+  | { kind: 'detail'; text: string; isError: boolean };
+
+function shortTime(ms: number): string {
+  const d = new Date(ms);
+  return `${String(d.getHours()).padStart(2,'0')}:${String(d.getMinutes()).padStart(2,'0')}:${String(d.getSeconds()).padStart(2,'0')}`;
+}
+
+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`;
+}
+
+function truncateJson(val: unknown, maxLen = 120): string {
+  const s = JSON.stringify(val) ?? 'null';
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + '\u2026' : s;
+}
+
+function summarizeResult(result: unknown): string | undefined {
+  // SDK OBS-05 (0.21.31+): TOOL_SUCCEEDED/TOOL_FAILED.result is a ToolResultSummary
+  // { kind: 'text' | 'json' | 'binary' | 'error' | 'empty'; byteSize: number; preview?: string }.
+  if (!result || typeof result !== 'object') return 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;
+  }
+  if (typeof record.kind === 'string' && typeof record.byteSize === 'number') {
+    return `${record.kind} (${record.byteSize}B)`;
+  }
+  return undefined;
+}
+
+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';
+  if (name.includes('write') || name.includes('edit') || name.includes('patch')) return 'write';
+  if (name.includes('exec') || name.includes('shell') || name.includes('bash') || typeof args.command === 'string') return 'execute';
+  if (name.includes('fetch') || name.includes('http') || name.includes('remote')) return 'network';
+  return 'analyze';
+}
+
+export class ToolInspectorPanel extends BasePanel {
+  private records: ToolCallRecord[] = [];
+  private filterMode: FilterMode = 'all';
+  private unsubs: Array<() => void> = [];
+  private cursorIndex = 0;
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private _flatCache: FlatRow[] | null = null;
+
+  constructor(
+    private readonly toolEvents: UiEventFeed<ToolEvent>,
+    private readonly turnEvents: UiEventFeed<TurnEvent>,
+  ) {
+    super('tools', 'Tools', 'X', 'ai');
+    this._attachBus();
+  }
+
+  override onActivate(): void {
+    this.needsRender = true;
+  }
+
+  override onDeactivate(): void {
+    super.onDeactivate();
+  }
+
+  override onDestroy(): void {
+    this._detachBus();
+  }
+
+  override markDirty(): void {
+    this._flatCache = null;
+    super.markDirty();
+  }
+
+  handleInput(key: string): boolean {
+    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 'g':        this.autoScroll = true;   this.markDirty(); return true;
+      case 'f':        this._cycleFilter();      return true;
+      default:         return false;
+    }
+  }
+
+  render(width: number, height: number): Line[] {
+    if (height <= 0 || width <= 0) return [];
+
+    const running = this.records.filter(r => r.endMs === undefined).length;
+    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],
+      ]),
+    ];
+
+    const flat = this._getFlat();
+
+    if (this.autoScroll) {
+      this.cursorIndex = Math.max(0, flat.length - 1);
+    }
+
+    if (flat.length === 0) {
+      return buildPanelWorkspace(width, height, {
+        title,
+        intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+        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.',
+              [],
+              DEFAULT_PANEL_PALETTE,
+            ),
+          },
+        ],
+        footerLines,
+        palette: DEFAULT_PANEL_PALETTE,
+      });
+    }
+
+    this.cursorIndex = Math.max(0, Math.min(this.cursorIndex, Math.max(0, flat.length - 1)));
+    const summary: PanelWorkspaceSection = {
+      title: 'Summary',
+      lines: [
+        buildPanelLine(width, [
+          [' Calls ', DEFAULT_PANEL_PALETTE.label],
+          [String(this.records.length), DEFAULT_PANEL_PALETTE.value],
+          ['   Running ', DEFAULT_PANEL_PALETTE.label],
+          [String(running), running > 0 ? DEFAULT_PANEL_PALETTE.warn : DEFAULT_PANEL_PALETTE.dim],
+          ['   Filter ', DEFAULT_PANEL_PALETTE.label],
+          [this.filterMode === 'all' ? 'all' : this.filterMode, this.filterMode === 'all' ? DEFAULT_PANEL_PALETTE.dim : DEFAULT_PANEL_PALETTE.info],
+        ]),
+      ],
+    };
+
+    const selected = flat[this.cursorIndex];
+    const detailLines: Line[] = [];
+    if (selected?.kind === 'call') {
+      const filtered = this.filterMode === 'all'
+        ? this.records
+        : 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, [
+          [' Risk ', 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]]));
+        }
+        if (rec.error) detailLines.push(buildPanelLine(width, [[' Error ', DEFAULT_PANEL_PALETTE.bad], [rec.error, DEFAULT_PANEL_PALETTE.value]]));
+      }
+    }
+
+    const selectedSection: PanelWorkspaceSection = { title: 'Selected', lines: detailLines };
+    const callsSection = resolveScrollablePanelSection(width, height, {
+      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+      footerLines,
+      palette: DEFAULT_PANEL_PALETTE,
+      beforeSections: [summary],
+      section: {
+        title: 'Calls',
+        scrollableLines: flat.map((row, index) => this._renderRow(width, row, index === this.cursorIndex)),
+        selectedIndex: this.cursorIndex,
+        scrollOffset: this.scrollOffset,
+        minRows: 8,
+      },
+      afterSections: [selectedSection],
+    });
+    this.scrollOffset = callsSection.scrollOffset;
+
+    return buildPanelWorkspace(width, height, {
+      title,
+      intro: 'Inspect chronological tool activity, arguments, results, errors, and running calls.',
+      sections: [
+        summary,
+        callsSection.section,
+        selectedSection,
+      ],
+      footerLines,
+      palette: DEFAULT_PANEL_PALETTE,
+    });
+  }
+
+  private _renderRow(width: number, row: FlatRow, isCursor: boolean): Line {
+    const bg = isCursor ? C.selectedBg : '';
+    if (row.kind === 'call') {
+      return buildStyledPanelLine(width, [
+        { text: isCursor ? '▸' : ' ', fg: C.selected, bg, bold: isCursor },
+        { text: truncateDisplay(row.text, Math.max(0, width - 1)), fg: isCursor ? C.selected : C.toolFg, bg, bold: isCursor },
+      ]);
+    }
+    return buildStyledPanelLine(width, [
+      { text: '  ', fg: C.argsFg, bg },
+      { text: truncateDisplay(row.text, Math.max(0, width - 2)), fg: row.isError ? C.errorFg : C.argsFg, bg },
+    ]);
+  }
+
+  private _getFlat(): FlatRow[] {
+    if (this._flatCache) return this._flatCache;
+    const flat: FlatRow[] = [];
+    const filtered = this.filterMode === 'all'
+      ? this.records
+      : this.records.filter(r => r.tool === this.filterMode);
+
+    for (let i = 0; i < filtered.length; i++) {
+      const rec = filtered[i]!;
+      const dur = rec.endMs !== undefined ? ` (${formatMs(rec.endMs - rec.startMs)})` : ' (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}`;
+      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,
+          });
+        }
+        if (rec.resultSummary) {
+          flat.push({ kind: 'detail', text: `Summary: ${rec.resultSummary}`, isError: false });
+        }
+        if (rec.result !== undefined) {
+          flat.push({ kind: 'detail', text: `Result: ${truncateJson(rec.result, 200)}`, isError: false });
+        }
+        if (rec.error) {
+          flat.push({ kind: 'detail', text: `Error: ${rec.error}`, isError: true });
+        }
+      }
+    }
+    this._flatCache = flat;
+    return flat;
+  }
+
+  private _toggleExpand(): void {
+    const flat = this._getFlat();
+    const row = flat[this.cursorIndex];
+    if (!row || row.kind !== 'call') return;
+    const rec = this.records.filter(r =>
+      this.filterMode === 'all' ? true : r.tool === this.filterMode
+    )[row.recordIndex];
+    if (rec) {
+      rec.expanded = !rec.expanded;
+      this.markDirty();
+    }
+  }
+
+  private _cycleFilter(): void {
+    const tools = [...new Set(this.records.map(r => r.tool))];
+    if (tools.length === 0) return;
+    if (this.filterMode === 'all') {
+      this.filterMode = tools[0]!;
+    } else {
+      const idx = tools.indexOf(this.filterMode);
+      this.filterMode = idx >= tools.length - 1 ? 'all' : tools[idx + 1]!;
+    }
+    this.markDirty();
+  }
+
+  private _move(delta: number): void {
+    const flat = this._getFlat();
+    if (flat.length === 0) return;
+    this.cursorIndex = Math.max(0, Math.min(flat.length - 1, this.cursorIndex + delta));
+    this.markDirty();
+  }
+
+  private _attachBus(): void {
+    if (this.unsubs.length > 0) return;
+
+    this.unsubs.push(this.toolEvents.on('TOOL_RECEIVED', (data) => {
+      if (this.records.length >= MAX_ENTRIES) {
+        this.records.shift();
+      }
+      this.records.push({
+        callId: data.callId,
+        tool: data.tool,
+        args: data.args,
+        startMs: Date.now(),
+        expanded: false,
+        outputClass: detectOutputClass(data.tool, data.args),
+      });
+      this.autoScroll = true;
+      this.markDirty();
+    }));
+
+    this.unsubs.push(this.toolEvents.on('TOOL_PERMISSIONED', (data) => {
+      const rec = this.records.findLast(r => r.callId === data.callId);
+      if (rec) rec.approved = data.approved;
+      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.
+    this.unsubs.push(this.toolEvents.on('TOOL_SUCCEEDED', (data) => {
+      const rec = this.records.findLast(r => r.callId === data.callId);
+      if (rec) {
+        rec.endMs = Date.now();
+        rec.result = data.result;
+        rec.resultSummary = summarizeResult(data.result);
+      }
+      this.markDirty();
+    }));
+
+    this.unsubs.push(this.toolEvents.on('TOOL_FAILED', (data) => {
+      const rec = this.records.findLast(r => r.callId === data.callId);
+      if (rec) {
+        rec.endMs = Date.now();
+        rec.result = data.result;
+        rec.error = data.error;
+        rec.resultSummary = summarizeResult(data.result) ?? data.error;
+      }
+      this.markDirty();
+    }));
+
+    this.unsubs.push(this.turnEvents.on('TURN_ERROR', (data) => {
+      // Mark any running calls as errored
+      for (const rec of this.records) {
+        if (rec.endMs === undefined) {
+          rec.endMs = Date.now();
+          rec.error = data.error ?? 'unknown error';
+        }
+      }
+      this.markDirty();
+    }));
+  }
+
+  private _detachBus(): void {
+    for (const unsub of this.unsubs) unsub();
+    this.unsubs = [];
+  }
+}

package/src/panels/types.ts

@@ -0,0 +1,54 @@
+import type { Line } from '../types/grid.ts';
+import type { ComponentResourceContract, ComponentHealthState } from '../runtime/perf/panel-contracts.ts';
+
+export type PanelCategory = 'development' | 'agent' | 'monitoring' | 'session' | 'ai';
+
+export interface Panel {
+  id: string;
+  name: string;
+  icon: string; // single char for tab bar
+  category: PanelCategory;
+
+  // Lifecycle
+  onActivate(): void;
+  onDeactivate(): void;
+  onDestroy(): void;
+
+  // Rendering
+  render(width: number, height: number): Line[];
+
+  // State
+  isTransient: boolean;
+  isPinned: boolean;
+  needsRender: boolean;
+
+  // Dirty-flag contract (R2: activated panel render skipping)
+  /** Mark this panel as needing a re-render on the next frame. */
+  invalidate(): void;
+  /** Called by the compositor after a successful render to clear the dirty flag. */
+  markRendered(): void;
+
+  // Resource contract (optional — panels may declare resource requirements)
+  resourceContract?: Readonly<ComponentResourceContract>;
+
+  // Health state (optional — set by ComponentHealthMonitor when panel is registered)
+  healthState?: Readonly<ComponentHealthState>;
+
+  // Input (optional)
+  handleInput?(key: string): boolean;
+
+  // Scroll input (optional)
+  // Positive delta scrolls down; negative delta scrolls up.
+  handleScroll?(deltaRows: number): 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.
+   */
+  preload?: boolean;
+}

package/src/panels/watchers-panel.ts

@@ -0,0 +1,193 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine } from '../types/grid.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 {
+  buildEmptyState,
+  buildGuidanceLine,
+  buildKeyValueLine,
+  buildPanelLine,
+  buildPanelWorkspace,
+  DEFAULT_PANEL_PALETTE,
+  type PanelPalette,
+} from './polish.ts';
+
+const C = {
+  ...DEFAULT_PANEL_PALETTE,
+  header: '#94a3b8',
+  headerBg: '#1e293b',
+  ok: '#22c55e',
+  warn: '#eab308',
+  error: '#ef4444',
+  info: '#38bdf8',
+  selectBg: '#0f172a',
+} as const;
+
+function stateColor(state: string): string {
+  if (state === 'running') return C.ok;
+  if (state === 'degraded') return C.warn;
+  if (state === 'failed') return C.error;
+  return C.dim;
+}
+
+function sourceStatusColor(state?: string): string {
+  if (state === 'healthy') return C.ok;
+  if (state === 'lagging' || state === 'stale' || state === 'degraded') return C.warn;
+  if (state === 'failed') return C.error;
+  return C.dim;
+}
+
+function formatLag(value?: number): string {
+  if (!value || value <= 0) return 'n/a';
+  if (value < 1000) return `${value}ms`;
+  if (value < 60_000) return `${Math.round(value / 1000)}s`;
+  return `${Math.round(value / 60_000)}m`;
+}
+
+function formatTime(value?: number): string {
+  if (!value) return 'n/a';
+  return new Date(value).toLocaleString();
+}
+
+type WatcherEntry = UiWatchersSnapshot['watchers'][number];
+
+export class WatchersPanel extends ScrollableListPanel<WatcherEntry> {
+  private readonly readModel?: UiReadModel<UiWatchersSnapshot>;
+  private readonly unsub: (() => void) | null;
+
+  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;
+  }
+
+  public override onDestroy(): void {
+    this.unsub?.();
+  }
+
+  protected override getPalette(): PanelPalette {
+    return C;
+  }
+
+  protected getItems(): readonly WatcherEntry[] {
+    if (!this.readModel) return [];
+    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[] {
+    const intro = 'Managed watchers and source health used to trigger automation, refresh routes, and surface degraded upstream conditions.';
+
+    if (!this.readModel) {
+      const workspace = buildPanelWorkspace(width, height, {
+        title: 'Watchers',
+        intro,
+        sections: [{
+          lines: buildEmptyState(
+            width,
+            ' Runtime store not wired.',
+            'This panel needs the shared runtime store to inspect watcher health and source lag.',
+            [{ command: '/services auth-review', summary: 'inspect supporting services until watcher wiring is available' }],
+            C,
+          ),
+        }],
+        palette: C,
+      });
+      while (workspace.length < height) workspace.push(createEmptyLine(width));
+      return workspace;
+    }
+
+    const snapshot = this.readModel.getSnapshot();
+    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) {
+      return this.renderList(width, height, {
+        title: 'Watchers',
+        header: headerLines,
+        emptyMessage: ' No watchers registered.',
+      });
+    }
+
+    this.clampSelection();
+    const selected = watchers[this.selectedIndex]!;
+
+    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],
+      ]),
+    ];
+    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',
+      header: headerLines,
+      footer: footerLines,
+    });
+  }
+}