feat: server mode with REST API and SSE event streaming

[nextlevelshit]

Context

Fabro supports a server mode (fabro serve) — an HTTP API with SSE event streaming, concurrent run scheduling, web UI, and team access via JWT/mTLS auth. This enables 24/7 pipeline execution, team dashboards, and programmatic integration.

Wave currently operates as a CLI tool only. Adding a server mode enables team workflows, webhook-triggered pipelines, and persistent monitoring.

Design

Server Launch

wave serve                           # default: 127.0.0.1:8080
wave serve --port 9090 --max-concurrent 10

REST API

Endpoint	Method	Purpose
/api/runs	POST	Submit a new pipeline run
/api/runs	GET	List runs (with filters)
/api/runs/:id	GET	Get run details
/api/runs/:id/logs	GET	Get run logs
/api/runs/:id/events	GET (SSE)	Stream real-time events
/api/runs/:id/cancel	POST	Cancel a running pipeline
/api/runs/:id/gate/:step	POST	Answer a human gate
/api/pipelines	GET	List available pipelines
/api/personas	GET	List available personas
/api/health	GET	Health check

SSE Event Streaming

Real-time events for all pipeline activity — same events already emitted by internal/event/:

event: step_started
data: {"run_id": "...", "step": "plan", "persona": "navigator"}

event: step_completed  
data: {"run_id": "...", "step": "plan", "status": "success", "duration_ms": 30000}

event: stream_activity
data: {"run_id": "...", "step": "implement", "content": "Writing tests..."}

Concurrent Scheduling

FIFO queue with configurable concurrency limit (default: 5). Matches Wave's existing "max 6 concurrent pipelines" guideline.

Web UI Integration

The existing internal/webui/ already provides a web dashboard. Server mode upgrades it from read-only to interactive:

• Submit runs from browser
• Monitor live progress via SSE
• Answer human gates in browser
• View retrospectives

Authentication

• JWT tokens for API access
• Optional mTLS for machine-to-machine
• Demo mode for local development (no auth)

Configuration

server:
  bind: "127.0.0.1:8080"
  max_concurrent: 5
  auth:
    mode: jwt              # jwt | mtls | none
    jwt_secret: "${WAVE_JWT_SECRET}"
  tls:
    enabled: false
    cert: ""
    key: ""

What Wave Keeps

• CLI as primary interface (server is additive)
• Same pipeline/persona/contract model
• Existing event infrastructure (SSE wraps existing events)

What Wave Gains

• Team workflows — multiple developers share a Wave instance
• Webhook triggers — GitHub/GitLab webhooks can trigger pipelines
• 24/7 operation — persistent server for continuous development
• Programmatic access — API enables custom integrations
• Interactive web UI — full pipeline management from browser

Implementation Scope

1. wave serve command — HTTP server with goroutine-per-run
2. REST API handlers in internal/webui/ (extend existing)
3. SSE endpoint wrapping existing event emitter
4. Run queue with concurrent scheduling
5. Gate handler for HTTP-based human gates
6. Auth middleware (JWT, optional mTLS)

Research Sources

• Fabro server: fabro serve with Axum, SQLite, JWT/mTLS
• Fabro API: OpenAPI-first, REST + SSE, concurrent scheduling
• Fabro web UI: React 19 + React Router + Vite

[nextlevelshit]

Implemented and merged as part of epic #589. See #609 for session diary.