# Mission Control Dashboard

> Last Verified: 2026-02-17 | Owner: John

# Runbook: Mission Control Dashboard

**Service Type:** Task Management Web UI
**Runtime:** Node.js (Express)
**Port:** 3030 (internal + LAN accessible)
**Internal URL:** http://localhost:3030
**LAN URL:** http://192.168.68.61:3030 (mobile-friendly)
**Database:** SQLite (~/system/databases/mission-control.db)
**LaunchAgent:** com.john.mc-dashboard
**Source:** ~/system/tools/mc-dashboard.js

---

## Service Info

Mission Control Dashboard is the web UI for task management. Provides CRUD operations, priority management, status tracking, and team coordination.

**Features:**
- Task list with filters (open/closed, owner, priority)
- Create/edit/delete tasks
- Start/pause/resume tasks
- Priority management (H/M/L)
- Owner assignment (john/edita/—)
- Real-time status updates
- Mobile-responsive design
- Auto-refresh every 30 seconds

**CLI Alternative:**
```bash
node ~/system/tools/mc.js list|add|start|done|pause|resume|block
```

---

## Status Check

### LaunchAgent Status
```bash
launchctl list | grep mc-dashboard
```

Expected output: PID shown (e.g., `12345  0  com.john.mc-dashboard`)

If not running: `- 0 com.john.mc-dashboard` (no PID)

### HTTP Check
```bash
curl -I http://localhost:3030
```

Expected: `200 OK`

### LAN Access Check (from another device)
```bash
curl -I http://192.168.68.61:3030
```

Expected: `200 OK`

### Database Check
```bash
sqlite3 ~/system/databases/mission-control.db "SELECT count(*) FROM tasks WHERE status = 'open';"
```

---

## Restart Procedure

### Stop Service
```bash
launchctl unload ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

### Start Service
```bash
launchctl load ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

### Restart (Stop + Start)
```bash
launchctl unload ~/Library/LaunchAgents/com.john.mc-dashboard.plist
launchctl load ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

**Note:** LaunchAgent auto-restarts on crash (KeepAlive=true).

---

## View Logs

### stdout (General logs)
```bash
tail -f ~/system/logs/mc-dashboard.log
```

### stderr (Error logs)
```bash
tail -f ~/system/logs/mc-dashboard.err
```

### Recent errors
```bash
tail -50 ~/system/logs/mc-dashboard.err
```

---

## Troubleshooting

### Problem: Dashboard won't start
**Check LaunchAgent:**
```bash
launchctl list | grep mc-dashboard
```

**Check error log:**
```bash
tail -50 ~/system/logs/mc-dashboard.err
```

**Common causes:**
1. Port 3030 already bound - check `lsof -i :3030`
2. Database locked - check for stale processes using SQLite
3. Node.js not found - check `which node`
4. Permission issues - check file ownership

**Fix:**
```bash
# Kill any process on port 3030
lsof -ti :3030 | xargs kill -9

# Restart
launchctl unload ~/Library/LaunchAgents/com.john.mc-dashboard.plist
launchctl load ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

### Problem: Can't connect from mobile (LAN)
**Check service is listening on all interfaces:**
```bash
lsof -i :3030
```

Expected: `*:3030` (listening on all IPs, not just 127.0.0.1)

**Check firewall:**
```bash
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
```

If firewall is on, allow Node.js:
```bash
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /opt/homebrew/bin/node
```

**Check Mac IP:**
```bash
ipconfig getifaddr en0  # WiFi
ipconfig getifaddr en1  # Ethernet
```

Expected: 192.168.68.61 (or similar)

### Problem: Tasks not updating (stale data)
**Check database integrity:**
```bash
sqlite3 ~/system/databases/mission-control.db "PRAGMA integrity_check;"
```

Expected: `ok`

**Check last write:**
```bash
ls -lh ~/system/databases/mission-control.db
```

**Restart dashboard:**
```bash
launchctl unload ~/Library/LaunchAgents/com.john.mc-dashboard.plist
launchctl load ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

### Problem: 500 errors in UI
**Check server logs:**
```bash
tail -f ~/system/logs/mc-dashboard.log ~/system/logs/mc-dashboard.err
```

**Check database:**
```bash
sqlite3 ~/system/databases/mission-control.db "SELECT * FROM tasks LIMIT 1;"
```

**Common causes:**
1. Database schema mismatch - migrate database
2. Corrupted task data - fix in SQLite
3. Node.js error - check stack trace in error log

---

## CLI Integration

Mission Control has two interfaces:
1. **Dashboard (UI)** - http://localhost:3030
2. **CLI** - node ~/system/tools/mc.js

Both read/write the same SQLite database: ~/system/databases/mission-control.db

### CLI Commands
```bash
# List tasks
node ~/system/tools/mc.js list
node ~/system/tools/mc.js list --owner john

# Start task (creates /tmp/mc-active-task)
node ~/system/tools/mc.js start <id>

# Complete task
node ~/system/tools/mc.js done <id> "outcome summary"

# Pause task (removes /tmp/mc-active-task)
node ~/system/tools/mc.js pause <id>

# Block task
node ~/system/tools/mc.js block <id> "blocker reason"

# Show full details
node ~/system/tools/mc.js show <id>

# Who's working on what
node ~/system/tools/mc.js active
```

---

## Dependencies

- **Node.js** - Runtime (/opt/homebrew/bin/node)
- **SQLite3** - Database (built-in with Node.js)
- **LaunchAgent** - Auto-start on login
- **No external services** - Fully local

---

## Backup

### Database Backup
```bash
cp ~/system/databases/mission-control.db ~/backups/mission-control-$(date +%Y%m%d-%H%M%S).db
```

### Automated Backup (daily)
Add to crontab or LaunchAgent:
```bash
0 2 * * * cp ~/system/databases/mission-control.db ~/backups/mission-control-$(date +\%Y\%m\%d).db
```

### Restore from Backup
```bash
# Stop dashboard
launchctl unload ~/Library/LaunchAgents/com.john.mc-dashboard.plist

# Restore database
cp ~/backups/mission-control-YYYYMMDD-HHMMSS.db ~/system/databases/mission-control.db

# Start dashboard
launchctl load ~/Library/LaunchAgents/com.john.mc-dashboard.plist
```

---

## Configuration

### LaunchAgent Plist
**Path:** ~/Library/LaunchAgents/com.john.mc-dashboard.plist

**Key settings:**
- `KeepAlive: true` - Auto-restart on crash
- `RunAtLoad: true` - Start on login
- `StandardOutPath` - Log stdout
- `StandardErrorPath` - Log stderr
- `EnvironmentVariables: HOME` - User home directory

### Application Config
**Port:** 3030 (hardcoded in mc-dashboard.js)
**Database:** ~/system/databases/mission-control.db (hardcoded)
**Auto-refresh:** 30 seconds (client-side)

**To change port:**
1. Edit ~/system/tools/mc-dashboard.js
2. Change `const PORT = 3030;` to desired port
3. Restart LaunchAgent

---

## Related Services

### Mission Control Session Worker
**LaunchAgent:** com.john.mc-session-worker
**Purpose:** Background daemon for session-level task monitoring

**Status check:**
```bash
launchctl list | grep mc-session-worker
```

---

## Notes

- **Access:** LAN-accessible (no auth) - consider adding auth for remote access
- **Mobile-friendly:** Responsive design, touch-optimized
- **No auth:** Anyone on LAN can create/modify tasks - secure network required
- **Auto-refresh:** Dashboard auto-refreshes every 30s
- **Active task enforcement:** ~/system/.claude/hooks/gotcha-enforcer.py checks /tmp/mc-active-task before Write/Edit
- **CLI vs UI:** Both interfaces are equal - use whichever is convenient

---

**Last updated:** 2026-02-10
**Maintained by:** John (AI Director)