# Track Specification: MMA Multi-Worker Visualization (mma_multiworker_viz_20260306)

## Overview
Split-view GUI for parallel worker streams per tier. Visualize multiple concurrent workers with individual status, output tabs, and resource usage. Enable kill/restart per worker.

## Current State Audit

### Already Implemented (DO NOT re-implement)

#### Worker Streams (gui_2.py)
- **`mma_streams` dict**: `{stream_key: output_text}` - stores worker output
- **`_render_tier_stream_panel()`**: Renders single stream panel
- **Stream keys**: `"Tier 1"`, `"Tier 2"`, `"Tier 3"`, `"Tier 4"`

#### MMA Dashboard (gui_2.py)
- **`_render_mma_dashboard()`**: Displays tier usage table, ticket DAG
- **`active_tickets`**: List of currently active tickets
- **No multi-worker display**

#### DAG Execution (dag_engine.py, multi_agent_conductor.py)
- **Sequential execution**: Workers run one at a time
- **No parallel execution**: `run_in_executor` used but sequentially
- **See**: `true_parallel_worker_execution_20260306` for parallel implementation

### Gaps to Fill (This Track's Scope)
- No visualization for concurrent workers
- No per-worker status display
- No independent output scrolling per worker
- No per-worker kill buttons

## Architectural Constraints

### Stream Performance
- Multiple concurrent streams MUST NOT degrade UI
- Each stream renders only when visible
- Old output MUST be pruned (memory bound)

### Memory Efficiency
- Stream output buffer limited per worker (e.g., 10KB max)
- Prune oldest lines when buffer exceeded

### State Synchronization
- Stream updates via `_pending_gui_tasks` pattern
- Thread-safe append to stream dict

## Architecture Reference

### Key Integration Points

| File | Lines | Purpose |
|------|-------|---------|
| `src/gui_2.py` | 2500-2600 | `mma_streams` dict, stream rendering |
| `src/gui_2.py` | 2650-2750 | `_render_mma_dashboard()` |
| `src/multi_agent_conductor.py` | 100-150 | Worker stream output |
| `src/dag_engine.py` | 80-100 | Execution state |

### Proposed Multi-Worker Stream Structure

```python
# Enhanced mma_streams structure:
mma_streams: dict[str, dict[str, Any]] = {
 "worker-001": {
  "tier": "Tier 3",
  "ticket_id": "T-001",
  "status": "running",  # running | completed | failed | killed
  "output": "...",
  "started_at": time.time(),
  "thread_id": 12345,
 },
 "worker-002": {
  "tier": "Tier 3",
  "ticket_id": "T-002",
  "status": "running",
  ...
 }
}
```

## Functional Requirements

### FR1: Multi-Pane Layout
- Split view showing all active workers
- Use `imgui.columns()` or child windows
- Show worker ID, tier, ticket ID, status

### FR2: Per-Worker Status
- Display: running, completed, failed, killed
- Color-coded status indicators
- Show elapsed time for running workers

### FR3: Output Tabs
- Each worker has scrollable output area
- Independent scroll position per tab
- Auto-scroll option for active workers

### FR4: Per-Worker Kill
- Kill button on each worker panel
- Confirmation before kill
- Status updates to "killed" after termination

## Non-Functional Requirements

| Requirement | Constraint |
|-------------|------------|
| Concurrent Workers | Support 4+ workers displayed |
| Memory per Stream | Max 10KB output buffer |
| Frame Rate | 60fps with 4 workers |

## Testing Requirements

### Unit Tests
- Test stream dict structure
- Test output pruning at buffer limit
- Test status updates

### Integration Tests (via `live_gui` fixture)
- Start multiple workers, verify all displayed
- Kill one worker, verify others continue
- Verify scroll independence

## Dependencies
- **Depends on**: `true_parallel_worker_execution_20260306` (for actual parallel execution)
- This track provides visualization only

## Out of Scope
- Actual parallel execution (separate track)
- Worker restart (separate track)
- Historical worker data

## Acceptance Criteria
- [ ] 4+ concurrent workers displayed simultaneously
- [ ] Each worker shows individual status
- [ ] Output streams scroll independently
- [ ] Kill button terminates specific worker
- [ ] Status updates in real-time
- [ ] Memory bounded per stream
- [ ] 1-space indentation maintained
