@covibes/zeroshot 1.0.1

package/src/tui/LAYOUT.md

@@ -0,0 +1,261 @@
+# TUI Dashboard Layout Module
+
+Dashboard layout builder for real-time cluster monitoring with blessed-contrib.
+
+## Overview
+
+The layout module creates a responsive terminal UI with a 20x12 grid layout containing:
+
+- **Clusters Table** (top-left): View all active clusters, status, agent count, and uptime
+- **System Stats** (top-right): CPU, memory, and cluster statistics
+- **Agents Table** (middle): List all agents with role, status, iteration, and resource usage
+- **Live Logs** (lower): Real-time event stream with color-coded severity levels
+- **Help Bar** (bottom): Keyboard shortcut reference
+
+## Grid Layout
+
+```
+┌─────────────────────────────────────────────┬─────────────────────┐
+│ Clusters Table (6 rows x 8 cols)            │ System Stats Box    │
+│                                             │ (6 rows x 4 cols)   │
+├─────────────────────────────────────────────┴─────────────────────┤
+│ Agents Table (6 rows x 12 cols)                                    │
+├────────────────────────────────────────────────────────────────────┤
+│ Live Logs (6 rows x 12 cols)                                       │
+├────────────────────────────────────────────────────────────────────┤
+│ Help Bar (2 rows x 12 cols)                                        │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+const blessed = require('blessed');
+const { createLayout } = require('./layout');
+
+// Create screen
+const screen = blessed.screen({ mouse: true, title: 'Cluster Dashboard' });
+
+// Create layout
+const layout = createLayout(screen);
+
+// Render
+screen.render();
+
+// Exit handler
+screen.key(['q', 'C-c'], () => process.exit(0));
+```
+
+### Updating Tables
+
+```javascript
+const { updateClustersTable, updateAgentsTable, updateStatsBox, addLogEntry } = require('./layout');
+
+// Update clusters table
+updateClustersTable(layout.clustersTable, [
+  {
+    id: 'cluster-swift-falcon',
+    status: 'running',
+    agentCount: 5,
+    config: 'default',
+    uptime: '2h 30m',
+  },
+]);
+
+// Update agents table
+updateAgentsTable(layout.agentTable, [
+  {
+    clusterId: 'cluster-swift-falcon',
+    id: 'worker-1',
+    role: 'worker',
+    status: 'running',
+    iteration: 3,
+    cpu: '12.5%',
+    memory: '245 MB',
+  },
+]);
+
+// Update system stats
+updateStatsBox(layout.statsBox, {
+  activeClusters: 2,
+  totalAgents: 5,
+  usedMemory: '512 MB',
+  totalMemory: '8 GB',
+  totalCPU: '26.2%',
+});
+
+// Add log entry
+addLogEntry(layout.logsBox, 'Cluster started successfully', 'info');
+addLogEntry(layout.logsBox, 'Warning: High CPU usage', 'warn');
+addLogEntry(layout.logsBox, 'Error: Agent crashed', 'error');
+```
+
+## API Reference
+
+### createLayout(screen)
+
+Creates the dashboard layout with all widgets.
+
+**Parameters:**
+
+- `screen` (blessed.screen): Blessed screen instance
+
+**Returns:**
+
+```javascript
+{
+  (screen, // Blessed screen
+    grid, // blessed-contrib grid
+    clustersTable, // Clusters table widget
+    agentTable, // Agents table widget
+    statsBox, // System stats box widget
+    logsBox, // Live logs widget
+    helpBar, // Help bar widget
+    widgets, // Array of interactive widgets [clustersTable, agentTable, logsBox]
+    focus(index), // Function to focus widget by index
+    getCurrentFocus()); // Function to get current focus index
+}
+```
+
+### updateClustersTable(clustersTable, clusters)
+
+Updates the clusters table with current data.
+
+**Parameters:**
+
+- `clustersTable`: Clusters table widget
+- `clusters` (array): Array of cluster objects with properties:
+  - `id` (string): Cluster identifier
+  - `status` (string): running | stopped | initializing | stopping | failed | killed
+  - `agentCount` (number): Number of agents
+  - `config` (string): Configuration name
+  - `uptime` (string): Formatted uptime (e.g., "2h 30m")
+
+### updateAgentsTable(agentTable, agents)
+
+Updates the agents table with current data.
+
+**Parameters:**
+
+- `agentTable`: Agents table widget
+- `agents` (array): Array of agent objects with properties:
+  - `clusterId` (string): Parent cluster ID
+  - `id` (string): Agent identifier
+  - `role` (string): worker | validator | orchestrator
+  - `status` (string): running | idle | failed
+  - `iteration` (number): Current iteration count
+  - `cpu` (string): CPU percentage (e.g., "12.5%")
+  - `memory` (string): Memory usage (e.g., "245 MB")
+
+### updateStatsBox(statsBox, stats)
+
+Updates the system stats box.
+
+**Parameters:**
+
+- `statsBox`: Stats box widget
+- `stats` (object):
+  - `activeClusters` (number): Count of active clusters
+  - `totalAgents` (number): Total agent count
+  - `usedMemory` (string): Formatted memory usage
+  - `totalMemory` (string): Formatted total memory
+  - `totalCPU` (string): Total CPU percentage
+
+### addLogEntry(logsBox, message, level)
+
+Adds a timestamped log entry.
+
+**Parameters:**
+
+- `logsBox`: Logs box widget
+- `message` (string): Log message
+- `level` (string): info | warn | error | debug (default: info)
+
+### clearLogs(logsBox)
+
+Clears all log entries.
+
+**Parameters:**
+
+- `logsBox`: Logs box widget
+
+## Keyboard Navigation
+
+| Key       | Action                     |
+| --------- | -------------------------- |
+| Tab       | Next widget                |
+| Shift+Tab | Previous widget            |
+| ↑/↓       | Navigate in focused widget |
+| Enter     | Select/activate            |
+| q         | Quit                       |
+
+## Color Scheme
+
+- **Borders**: Cyan
+- **Headers**: Cyan (bold)
+- **Text**: White
+- **Selection**: Black text on cyan background
+- **Log levels**:
+  - info: White
+  - warn: Yellow
+  - error: Red
+  - debug: Gray
+
+## Demo
+
+Run the included demo:
+
+```bash
+node src/tui/demo.js
+```
+
+Keyboard shortcuts in demo:
+
+- [r] - Refresh data
+- [c] - Simulate cluster start
+- [k] - Simulate cluster kill
+- [s] - Simulate warning
+- [q] - Quit
+
+## Testing
+
+Run tests:
+
+```bash
+npm test -- tests/tui-layout.test.js
+```
+
+Tests verify:
+
+- Layout creation and widget initialization
+- Data update functions
+- Focus navigation
+- Log entry handling
+- Edge cases (empty data, missing properties)
+
+## Styling Customization
+
+Widgets can be customized by modifying the configuration objects in `createLayout()`:
+
+```javascript
+const clustersTable = grid.set(0, 0, 6, 8, contrib.table, {
+  fg: 'white', // Foreground color
+  selectedFg: 'black', // Selected foreground
+  selectedBg: 'cyan', // Selected background
+  border: { type: 'line', fg: 'cyan' },
+  style: {
+    header: { fg: 'cyan', bold: true },
+    cell: { selected: { fg: 'black', bg: 'cyan' } },
+  },
+});
+```
+
+## Related Modules
+
+- `formatters.js` - Value formatting utilities (timestamps, bytes, CPU)
+- `renderer.js` - Additional rendering helpers
+- `keybindings.js` - Keyboard event handlers
+- `data-poller.js` - Real-time data collection
+- `index.js` - Main dashboard integration

package/src/tui/README.txt

@@ -0,0 +1,192 @@
+VIBE WATCH - Interactive TUI Dashboard
+=======================================
+
+Launch with: vibe watch
+
+OVERVIEW
+--------
+The vibe watch command provides a real-time, htop/k9s-style dashboard for monitoring all active vibe clusters.
+
+FEATURES
+--------
+✓ Real-time cluster state monitoring (1s refresh)
+✓ CPU and memory tracking per agent (via pidusage)
+✓ Live message streaming from cluster ledgers
+✓ Interactive keyboard controls (kill, stop, export)
+✓ Automatic detection of new clusters
+✓ System-wide statistics (active clusters, agents, avg resources)
+
+LAYOUT
+------
+┌─────────────────────────────────────────────────────────┐
+│ VIBE CLUSTER WATCH                        [q] Quit      │
+├─────────────────────────────────────────────────────────┤
+│ ┌─ Clusters ─────────┐ ┌─ System Stats ──────────────┐ │
+│ │ ID     State  Time  │ │ Active: 2   CPU: 12%       │ │
+│ │ ● a-38 RUN    5m    │ │ Agents: 7   Mem: 245 MB    │ │
+│ │ ● s-62 RUN    2m    │ └────────────────────────────┘ │
+│ └────────────────────┘                                  │
+│ ┌─ Agents ───────────────────────────────────────────┐ │
+│ │ Agent    Role     State    Iter  CPU%  Mem(MB)    │ │
+│ │ worker   impl     exec     3     8.5   67         │ │
+│ │ validator val     idle     1     0.1   42         │ │
+│ └────────────────────────────────────────────────────┘ │
+│ ┌─ Live Logs ────────────────────────────────────────┐ │
+│ │ [09:45:23] worker: TASK_STARTED (iteration 3)     │ │
+│ │ [09:45:24] worker: Implementing feature X...      │ │
+│ └────────────────────────────────────────────────────┘ │
+│ ┌─ Help ─────────────────────────────────────────────┐ │
+│ │ [↑/↓] Nav  [K] Kill  [s] Stop  [e] Export  [q] Quit│ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+
+KEYBOARD SHORTCUTS
+------------------
+Navigation:
+  ↑ / k          Move selection up
+  ↓ / j          Move selection down
+
+Actions (on selected cluster):
+  K              Kill cluster (force, with confirmation)
+  s              Stop cluster (graceful, with confirmation)
+  e              Export cluster conversation (markdown)
+  l              Open full logs in new terminal window
+
+View Controls:
+  r              Force refresh all data
+  f              Toggle filter (running/stopped/all)
+  ? / h          Show help dialog
+
+Exit:
+  q / Ctrl-C     Quit (with confirmation if clusters active)
+
+USAGE
+-----
+# Launch with defaults
+vibe watch
+
+# Filter to only running clusters
+vibe watch --filter running
+
+# Faster refresh (500ms instead of 1s)
+vibe watch --refresh-rate 500
+
+# Show only stopped clusters
+vibe watch --filter stopped
+
+ARCHITECTURE
+------------
+The TUI is composed of 6 modular components:
+
+1. index.js       - Main coordinator, initializes screen/layout/poller
+2. layout.js      - Creates blessed-contrib grid with 5 widgets
+3. renderer.js    - Transforms data into widget updates
+4. data-poller.js - Polls orchestrator at 4 different intervals
+5. keybindings.js - Keyboard event handlers and confirmations
+6. formatters.js  - Utility functions (time, bytes, CPU, icons)
+
+Data Flow:
+  Orchestrator → DataPoller → TUI.onUpdate → Renderer → Widgets → Screen
+
+Polling Strategy:
+  - Cluster states: 1s (main refresh rate)
+  - Resource stats: 2s (expensive pidusage calls)
+  - New clusters:   2s (rare event)
+  - Log messages:   500ms per cluster (real-time feel)
+
+DEPENDENCIES
+------------
+- blessed@0.1.81          Terminal UI framework
+- blessed-contrib@4.11.0  Dashboard widgets (grid, table, log)
+- pidusage@4.0.1          Cross-platform CPU/memory monitoring
+
+TESTING
+-------
+# Run integration test
+node tests/tui-integration.test.js
+
+# Run layout demo (interactive)
+node src/tui/demo.js
+
+# Run unit tests
+npm test
+
+TROUBLESHOOTING
+---------------
+Q: TUI shows "No clusters found"
+A: Start a cluster first: vibe run "test task" or vibe task run "test"
+
+Q: CPU/Memory shows 0%
+A: Process may have died. Check cluster state.
+
+Q: Logs not streaming
+A: Ledger database may be locked. Wait a few seconds.
+
+Q: Terminal garbled on exit
+A: Try running: reset
+
+Q: Keyboard shortcuts not working
+A: Make sure terminal supports key events (most modern terminals do)
+
+DEMO MODE
+---------
+To see the TUI with mock data:
+  node src/tui/demo.js
+
+This starts a live dashboard with simulated clusters that auto-updates.
+Press [r] to refresh, [c] to add cluster, [k] to kill, [q] to quit.
+
+FILES
+-----
+src/tui/
+├── index.js          Main TUI class (6.0K)
+├── layout.js         Widget creation (8.1K)
+├── renderer.js       Data → widgets (5.6K)
+├── data-poller.js    Data collection (8.1K)
+├── keybindings.js    User input (8.9K)
+├── formatters.js     Utilities (3.4K)
+├── demo.js           Interactive demo (5.0K)
+└── LAYOUT.md         API documentation (7.4K)
+
+tests/
+└── tui-integration.test.js  Integration test
+
+MODIFICATIONS TO EXISTING FILES
+-------------------------------
+src/agent-wrapper.js
+  - Added: this.processPid tracking (line 42)
+  - Added: PID capture on spawn (line 605-607)
+  - Added: PROCESS_SPAWNED lifecycle event
+  - Added: TASK_ID_ASSIGNED lifecycle event
+  - Added: pid field in getState() (line 1350)
+
+cli/index.js
+  - Added: vibe watch command with options
+
+lib/completion.js
+  - Added: Shell completion for watch command
+
+package.json
+  - Added: blessed, blessed-contrib, pidusage dependencies
+
+FUTURE ENHANCEMENTS
+-------------------
+Potential improvements:
+- [ ] Sorting clusters by various fields
+- [ ] Filtering by cluster config name
+- [ ] Graph view for CPU/memory over time
+- [ ] Search/filter logs by keyword
+- [ ] Export selected logs to file
+- [ ] Cluster health indicators
+- [ ] Alert notifications for failures
+- [ ] Docker container stats (for isolation mode)
+- [ ] Network I/O stats
+- [ ] Agent communication graph visualization
+
+CREDITS
+-------
+Implementation: 6 parallel agents (Dec 2024)
+Architecture: blessed-contrib grid system
+Inspiration: htop, k9s, lazydocker
+
+For issues or feature requests, see vibe/cluster GitHub repo.

package/src/tui/TWO-LEVEL-NAVIGATION.md

@@ -0,0 +1,186 @@
+# Two-Level Navigation - Implementation Summary
+
+## Overview
+
+Completely redesigned TUI layout with separate views for overview and detail modes:
+
+1. **Overview mode** (default): ONLY clusters + stats - clean, focused view
+2. Press Enter → **Detail mode**: ONLY agents + logs for selected cluster
+3. Press Escape → Return to overview
+
+## User Experience
+
+### Overview Mode (Default)
+
+- **ONLY visible:** Large clusters table (16 rows) + system stats sidebar
+- **Hidden:** Agent table and logs (completely invisible)
+- Clean, spacious layout focusing on cluster selection
+- Help text: `[Enter] View  [↑/↓] Navigate  [k] Kill  [s] Stop  [l] Logs  [r] Refresh  [q] Quit`
+
+### Detail Mode (After pressing Enter)
+
+- **ONLY visible:** Full-width agents table (9 rows) + full-width logs (9 rows)
+- **Hidden:** Clusters table and stats box (completely invisible)
+- Dedicated space for monitoring single cluster in depth
+- Help text: `[Esc] Back  [k] Kill  [s] Stop  [e] Export  [l] Logs  [r] Refresh  [q] Quit`
+
+### Navigation Flow
+
+```
+Overview (ONLY clusters + stats)
+    ↓ Enter
+Detail (ONLY agents + logs)
+    ↓ Escape
+Overview (ONLY clusters + stats)
+```
+
+## Implementation Details
+
+### Layout Design
+
+**Overview mode layout** (`src/tui/layout.js`):
+
+- Clusters table: rows 0-16 (16 rows), cols 0-8
+- Stats box: rows 0-16 (16 rows), cols 8-12
+- Help bar: rows 18-20
+- Agents/logs: **hidden** (`.hide()` called on initialization)
+
+**Detail mode layout** (`src/tui/layout.js`):
+
+- Agents table: rows 0-9 (9 rows), cols 0-12 (full width)
+- Logs box: rows 9-18 (9 rows), cols 0-12 (full width)
+- Help bar: rows 18-20
+- Clusters/stats: **hidden** (`.hide()` called on mode switch)
+
+### State Management
+
+**New state in TUI class (`src/tui/index.js`):**
+
+```javascript
+this.viewMode = 'overview'; // or 'detail'
+this.detailClusterId = null; // cluster ID when in detail mode
+```
+
+### Keybindings
+
+**Enter key** (`src/tui/keybindings.js` lines 14-37):
+
+- Checks if in overview mode with clusters available
+- Sets `viewMode = 'detail'` and `detailClusterId`
+- **Hides** clusters table and stats box (`.hide()`)
+- **Shows** agents table and logs box (`.show()`)
+- Updates help text
+- Clears old messages
+
+**Escape key** (`src/tui/keybindings.js` lines 39-59):
+
+- Checks if in detail mode
+- Sets `viewMode = 'overview'` and `detailClusterId = null`
+- **Shows** clusters table and stats box (`.show()`)
+- **Hides** agents table and logs box (`.hide()`)
+- Updates help text
+- Clears messages
+
+### Conditional Rendering
+
+**Cluster state updates** (`src/tui/index.js` lines 107-119):
+
+```javascript
+if (this.viewMode === 'detail' && this.detailClusterId) {
+  // Show agents for detail cluster
+  const status = this.orchestrator.getStatus(this.detailClusterId);
+  this.renderer.renderAgentTable(status.agents, this.resourceStats);
+} else if (this.viewMode === 'overview') {
+  // Don't show agents in overview
+  this.renderer.renderAgentTable([], this.resourceStats);
+}
+```
+
+**Resource stats updates** (`src/tui/index.js` lines 130-137):
+
+- Same conditional logic as above
+- Only renders agents in detail mode
+
+## Testing
+
+### Automated Tests
+
+**Test 1: `tests/tui-integration.test.js`**
+
+- Basic TUI startup
+- Data loading
+- Module integration
+- ✅ PASSING
+
+**Test 2: `tests/tui-navigation-test.js`**
+
+- Initial state verification
+- Enter detail view
+- Verify agents shown
+- Return to overview
+- Conditional rendering logic
+- ✅ PASSING
+
+### Manual Testing
+
+**Run the manual test:**
+
+```bash
+chmod +x tests/tui-keybindings-manual-test.js
+node tests/tui-keybindings-manual-test.js
+```
+
+**Instructions:**
+
+1. Press ↑/↓ or j/k to navigate clusters
+2. Press Enter to drill into detail view → clusters/stats hide, agents/logs appear
+3. Press Escape to return to overview → clusters/stats reappear, agents/logs hide
+4. Verify help text updates correctly
+
+## Files Modified
+
+| File                     | Changes                                                 |
+| ------------------------ | ------------------------------------------------------- |
+| `src/tui/index.js`       | Added viewMode state, conditional rendering             |
+| `src/tui/keybindings.js` | Added Enter/Escape handlers, widget visibility toggling |
+| `src/tui/layout.js`      | Updated help text to show Enter key                     |
+| `src/tui/CHANGES.txt`    | Documented feature and technical changes                |
+
+## Files Created
+
+| File                                   | Purpose                                 |
+| -------------------------------------- | --------------------------------------- |
+| `tests/tui-navigation-test.js`         | Automated test for two-level navigation |
+| `tests/tui-keybindings-manual-test.js` | Interactive manual test                 |
+| `src/tui/TWO-LEVEL-NAVIGATION.md`      | This document                           |
+
+## Performance Impact
+
+- **Startup:** No impact (viewMode check is O(1))
+- **Rendering:** Slight improvement in overview mode (no agent data fetching)
+- **Memory:** Minimal increase (2 new state variables)
+
+## Known Limitations
+
+None. Feature is complete and tested.
+
+## Usage
+
+```bash
+# Start TUI (shows overview by default)
+zeroshot watch
+
+# In overview:
+#   - Use ↑/↓ or j/k to select cluster
+#   - Press Enter to drill into detail view
+
+# In detail:
+#   - View agents and logs for selected cluster
+#   - Press Escape to return to overview
+```
+
+## Future Enhancements (Optional)
+
+- Add breadcrumb showing current cluster in detail mode
+- Add keybinding to jump directly to a cluster by ID
+- Add "pinning" to keep detail view on specific cluster even when new clusters spawn