# Track Specification: Kill/Abort Running Workers (kill_abort_workers_20260306)

## Overview
Add ability to kill/abort a running Tier 3 worker mid-execution. Currently workers run to completion; add cancel button with forced termination option.

## Current State Audit

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

#### Worker Execution (multi_agent_conductor.py)
- **`run_worker_lifecycle()`**: Executes ticket via `threading.Thread(daemon=True)`
- **`ConductorEngine.run()`**: Spawns parallel workers:
- **No thread references stored** - threads launched and joined() but no tracking
- **No abort mechanism** - no way to stop a running worker

#### Threading (multi_agent_conductor.py)
- **`threading.Thread`**: Used for workers
- **`threading.Event`**: Available for signaling
- **No abort event per worker**

### Gaps to Fill (This Track's scope)
- No worker thread tracking
- No abort signal mechanism
- No kill button UI
- No cleanup on termination

## Architectural Constraints

### Clean Termination
- Resources (file handles, network connections) MUST be released
- Partial results SHOULD be preserved
- No zombie processes

### Abort Timing
- **AI API calls cannot mid-call interruption** (API limitation)
- Abort only between API calls or during tool execution
- Check abort flag between operations

## Architecture Reference

### Key Integration Points

| File | Lines | Purpose |
|------|-------|---------|
| `src/multi_agent_conductor.py` | ~80-150 | `ConductorEngine.run()` - thread spawning |
| `src/multi_agent_conductor.py` | ~250-320 | `run_worker_lifecycle()` - add abort check |
| `src/gui_2.py` | ~2650-2750 | `_render_mma_dashboard()` - add kill buttons |

### Current Thread Pattern
```python
# In ConductorEngine.run():
threads = []
for ticket in to_run:
    t = threading.Thread(
        target=run_worker_lifecycle,
        args=(ticket, context, context_files, self.event_queue, self, md_content),
        daemon=True
    )
    threads.append(t)
    t.start()

for t in threads:
    t.join()
```

## Functional Requirements

### FR1: Worker Thread Tracking
- Store thread reference in `_active_workers: dict[ticket_id, Thread]`
- Track thread state: running, completed, killed
- Clean up on completion

### FR2: Abort Event Mechan
- Add `threading.Event()` per ticket: `_abort_events[ticket_id]`
- Worker checks event between operations:
- API call cannot be interrupted (limitation documented)

### FR3: Kill Button UI
- Button per running worker in MMA dashboard
- Confirmation dialog before kill
- Disabled if no workers running

### FR4: Clean Termination
- On kill: set `abort_event.set()`
- Wait for thread to finish (with timeout)
- Remove from `_active_workers`
- Preserve partial output in stream

## Non-Functional Requirements
| Requirement | Constraint |
|-------------|------------|
| Response Time | Kill takes effect within 1s of button press |
| No Deadlocks | Kill cannot cause system hang |
| Memory Safety | Worker resources freed after kill |

## Testing Requirements
### Unit Tests
- Test abort event stops worker at check point
- Test worker tracking dict updates correctly
- Test kill button enables/disables based on workers

### Integration Tests (via `live_gui` fixture)
- Start worker, click kill, verify termination
- Verify partial output preserved
- Verify no zombie threads

## Out of Scope
- Force-killing AI API calls (API limitation)
- Kill and restart (separate track)
- Kill during PowerShell execution (separate concern)

## Acceptance Criteria
- [ ] Kill button visible per running worker
- [ ] Confirmation dialog appears
- [ ] Worker terminates within 1s of kill
- [ ] Partial output preserved in stream
- [ ] Resources cleaned up
- [ ] Status reflects "killed"
- [ ] No zombie threads after kill
- [ ] 1-space indentation maintained
| No Deadlocks | Kill cannot cause system hang |
| Memory Safety | Worker resources freed after kill |

## Testing Requirements

### Unit Tests
- Test abort event stops worker at check point
- Test worker tracking dict updates correctly
- Test kill button enables/disables based on workers

### Integration Tests (via `live_gui` fixture)
- Start worker, click kill, verify termination
- Verify partial output preserved
- Verify no zombie threads

### Structural Testing Contract
- Use real threading - no mocking
- Test artifacts go to `tests/artifacts/`

## Out of Scope
- Force-killing AI API calls (API limitation)
- Kill and restart (separate track)
- Kill during PowerShell execution (separate concern)

## Acceptance Criteria
- [ ] Kill button visible per running worker
- [ ] Confirmation dialog appears
- [ ] Worker terminates within 1s of kill
- [ ] Partial output preserved in stream
- [ ] Resources cleaned up
- [ ] Status reflects "killed"
- [ ] No zombie threads after kill
- [ ] 1-space indentation maintained
