aicodeman 0.3.0 → 0.3.1

package/dist/web/server.js

@@ -1,11 +1,28 @@
 /**
- * @fileoverview Codeman web server and REST API
+ * @fileoverview Codeman web server — central hub coordinating all subsystems.
  *
- * Provides a Fastify-based web server with:
- * - REST API for session management, respawn control, and monitoring
- * - Server-Sent Events (SSE) for real-time updates at /api/events
- * - Static file serving for the web UI
- * - 60fps terminal streaming with batched updates
+ * Fastify-based web server providing:
+ * - ~111 REST API routes (delegated to `src/web/routes/` domain modules)
+ * - SSE streaming at `/api/events` with backpressure handling
+ * - Static file serving for the web UI (1-year cache in production)
+ * - 60fps terminal streaming via batched PTY output (16-50ms adaptive)
+ *
+ * Coordinates: SessionManager, RespawnController, SubagentWatcher, TeamWatcher,
+ * TranscriptWatcher, ImageWatcher, TunnelManager, PushSubscriptionStore,
+ * PlanOrchestrator, RunSummaryTracker, FileStreamManager.
+ *
+ * Key exports:
+ * - `WebServer` class — implements all port interfaces, extends EventEmitter
+ * - `startWebServer(options)` — factory function to create and start the server
+ *
+ * Implements port interfaces: `SessionPort`, `EventPort`, `ConfigPort`,
+ * `RespawnPort`, `MuxPort`, `FilePort`, `ScheduledPort`, `PushPort`, `TeamPort`
+ * (see `src/web/ports/` for definitions)
+ *
+ * @dependencies All major subsystems (session, respawn-controller, subagent-watcher,
+ *   team-watcher, tunnel-manager, state-store, etc.)
+ * @consumedby src/index.ts (entry point), src/cli.ts
+ * @emits SSE events via broadcast() — see sse-events.ts for full registry
  *
  * @module web/server
  */
@@ -43,16 +60,22 @@ const { version: APP_VERSION } = require('../../package.json');
 import { getErrorMessage, ApiErrorCode, createErrorResponse, DEFAULT_NICE_CONFIG, } from '../types.js';
 import { CleanupManager, KeyedDebouncer, StaleExpirationMap } from '../utils/index.js';
 import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.js';
+import { SseEvent } from './sse-events.js';
 import { registerAuthMiddleware, registerSecurityHeaders } from './middleware/auth.js';
 import { registerPushRoutes, registerTeamRoutes, registerMuxRoutes, registerFileRoutes, registerScheduledRoutes, registerHookEventRoutes, registerSystemRoutes, registerCaseRoutes, registerSessionRoutes, registerRespawnRoutes, registerRalphRoutes, registerPlanRoutes, } from './routes/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-import { TERMINAL_BATCH_INTERVAL, TASK_UPDATE_BATCH_INTERVAL, STATE_UPDATE_DEBOUNCE_INTERVAL, SESSIONS_LIST_CACHE_TTL, SCHEDULED_CLEANUP_INTERVAL, SCHEDULED_RUN_MAX_AGE, SSE_HEALTH_CHECK_INTERVAL, SESSION_LIMIT_WAIT_MS, ITERATION_PAUSE_MS, BATCH_FLUSH_THRESHOLD, STATS_COLLECTION_INTERVAL_MS, } from '../config/server-timing.js';
+import { TERMINAL_BATCH_INTERVAL, TASK_UPDATE_BATCH_INTERVAL, STATE_UPDATE_DEBOUNCE_INTERVAL, SESSIONS_LIST_CACHE_TTL, SCHEDULED_CLEANUP_INTERVAL, SCHEDULED_RUN_MAX_AGE, SSE_HEARTBEAT_INTERVAL, SSE_PADDING_SIZE, SESSION_LIMIT_WAIT_MS, ITERATION_PAUSE_MS, BATCH_FLUSH_THRESHOLD, STATS_COLLECTION_INTERVAL_MS, } from '../config/server-timing.js';
 // DEC mode 2026 - Synchronized Output
 // When terminal supports this, it buffers all output between start/end markers
 // and renders atomically, eliminating partial-frame flicker from Ink redraws.
 // Supported by: WezTerm, Kitty, Ghostty, iTerm2 3.5+, Windows Terminal, VSCode terminal
 const DEC_SYNC_START = '\x1b[?2026h'; // Begin synchronized update
 const DEC_SYNC_END = '\x1b[?2026l'; // End synchronized update (flush to screen)
+// SSE padding for Cloudflare tunnel buffer flushing.
+// Cloudflare quick tunnels buffer small SSE responses, causing lag for real-time events.
+// Appending SSE comment padding (ignored by EventSource) forces the proxy to flush.
+// Pre-computed once at startup to avoid repeated string allocation.
+const SSE_PADDING = ':' + 'p'.repeat(SSE_PADDING_SIZE) + '\n';
 /**
  * Get or generate a self-signed TLS certificate for HTTPS.
  * Certs are stored in ~/.codeman/certs/ and reused across restarts.
@@ -138,6 +161,8 @@ export class WebServer extends EventEmitter {
     subagentWatcherHandlers = null;
     imageWatcherHandlers = null;
     tunnelManager = new TunnelManager();
+    /** Cached tunnel active state — updated on TunnelStarted/TunnelStopped to avoid getUrl() on every broadcast */
+    _isTunnelActive = false;
     authSessions = null;
     authFailures = null;
     qrAuthFailures = null;
@@ -160,10 +185,10 @@ export class WebServer extends EventEmitter {
         this.mux = createMultiplexer();
         // Set up mux event listeners
         this.mux.on('sessionCreated', (session) => {
-            this.broadcast('mux:created', session);
+            this.broadcast(SseEvent.MuxCreated, session);
         });
         this.mux.on('sessionKilled', (data) => {
-            this.broadcast('mux:killed', data);
+            this.broadcast(SseEvent.MuxKilled, data);
         });
         this.mux.on('sessionDied', (data) => {
             getLifecycleLog().log({
@@ -171,10 +196,10 @@ export class WebServer extends EventEmitter {
                 sessionId: data.sessionId || 'unknown',
                 extra: data,
             });
-            this.broadcast('mux:died', data);
+            this.broadcast(SseEvent.MuxDied, data);
         });
         this.mux.on('statsUpdated', (sessions) => {
-            this.broadcast('mux:statsUpdated', sessions);
+            this.broadcast(SseEvent.MuxStatsUpdated, sessions);
         });
         // Set up subagent watcher listeners
         this.setupSubagentWatcherListeners();
@@ -184,16 +209,18 @@ export class WebServer extends EventEmitter {
         this.setupTeamWatcherListeners();
         // Set up tunnel manager listeners
         this.tunnelManager.on('started', (data) => {
-            this.broadcast('tunnel:started', data);
+            this._isTunnelActive = true;
+            this.broadcast(SseEvent.TunnelStarted, data);
         });
         this.tunnelManager.on('stopped', () => {
-            this.broadcast('tunnel:stopped', {});
+            this._isTunnelActive = false;
+            this.broadcast(SseEvent.TunnelStopped, {});
         });
         this.tunnelManager.on('error', (message) => {
-            this.broadcast('tunnel:error', { message });
+            this.broadcast(SseEvent.TunnelError, { message });
         });
         this.tunnelManager.on('progress', (data) => {
-            this.broadcast('tunnel:progress', data);
+            this.broadcast(SseEvent.TunnelProgress, data);
         });
         // QR token rotation — broadcast inline SVG for instant desktop refresh
         this.tunnelManager.on('qrTokenRotated', async () => {
@@ -201,7 +228,7 @@ export class WebServer extends EventEmitter {
             if (url && process.env.CODEMAN_PASSWORD) {
                 try {
                     const svg = await this.tunnelManager.getQrSvg(url);
-                    this.broadcast('tunnel:qrRotated', { svg });
+                    this.broadcast(SseEvent.TunnelQrRotated, { svg });
                 }
                 catch {
                     // QR generation failed — skip this rotation
@@ -213,7 +240,7 @@ export class WebServer extends EventEmitter {
             if (url && process.env.CODEMAN_PASSWORD) {
                 try {
                     const svg = await this.tunnelManager.getQrSvg(url);
-                    this.broadcast('tunnel:qrRegenerated', { svg });
+                    this.broadcast(SseEvent.TunnelQrRegenerated, { svg });
                 }
                 catch {
                     // QR generation failed — skip
@@ -232,13 +259,13 @@ export class WebServer extends EventEmitter {
     setupSubagentWatcherListeners() {
         // Store handlers for cleanup on shutdown
         this.subagentWatcherHandlers = {
-            discovered: (info) => this.broadcast('subagent:discovered', info),
-            updated: (info) => this.broadcast('subagent:updated', info),
-            toolCall: (data) => this.broadcast('subagent:tool_call', data),
-            toolResult: (data) => this.broadcast('subagent:tool_result', data),
-            progress: (data) => this.broadcast('subagent:progress', data),
-            message: (data) => this.broadcast('subagent:message', data),
-            completed: (info) => this.broadcast('subagent:completed', info),
+            discovered: (info) => this.broadcast(SseEvent.SubagentDiscovered, info),
+            updated: (info) => this.broadcast(SseEvent.SubagentUpdated, info),
+            toolCall: (data) => this.broadcast(SseEvent.SubagentToolCall, data),
+            toolResult: (data) => this.broadcast(SseEvent.SubagentToolResult, data),
+            progress: (data) => this.broadcast(SseEvent.SubagentProgress, data),
+            message: (data) => this.broadcast(SseEvent.SubagentMessage, data),
+            completed: (info) => this.broadcast(SseEvent.SubagentCompleted, info),
             error: (error, agentId) => {
                 console.error(`[SubagentWatcher] Error${agentId ? ` for ${agentId}` : ''}:`, error.message);
             },
@@ -275,7 +302,7 @@ export class WebServer extends EventEmitter {
     setupImageWatcherListeners() {
         // Store handlers for cleanup on shutdown
         this.imageWatcherHandlers = {
-            detected: (event) => this.broadcast('image:detected', event),
+            detected: (event) => this.broadcast(SseEvent.ImageDetected, event),
             error: (error, sessionId) => {
                 console.error(`[ImageWatcher] Error${sessionId ? ` for ${sessionId}` : ''}:`, error.message);
             },
@@ -299,10 +326,10 @@ export class WebServer extends EventEmitter {
      */
     setupTeamWatcherListeners() {
         this.teamWatcherHandlers = {
-            teamCreated: (config) => this.broadcast('team:created', config),
-            teamUpdated: (config) => this.broadcast('team:updated', config),
-            teamRemoved: (config) => this.broadcast('team:removed', config),
-            taskUpdated: (data) => this.broadcast('team:taskUpdated', data),
+            teamCreated: (config) => this.broadcast(SseEvent.TeamCreated, config),
+            teamUpdated: (config) => this.broadcast(SseEvent.TeamUpdated, config),
+            teamRemoved: (config) => this.broadcast(SseEvent.TeamRemoved, config),
+            taskUpdated: (data) => this.broadcast(SseEvent.TeamTaskUpdated, data),
         };
         this.teamWatcher.on('teamCreated', this.teamWatcherHandlers.teamCreated);
         this.teamWatcher.on('teamUpdated', this.teamWatcherHandlers.teamUpdated);
@@ -436,7 +463,17 @@ export class WebServer extends EventEmitter {
             // Send initial state
             // Use light state for SSE init to avoid sending 2MB+ terminal buffers
             // Buffers are fetched on-demand when switching tabs
-            this.sendSSE(reply, 'init', this.getLightState());
+            this.sendSSE(reply, SseEvent.Init, this.getLightState());
+            // Flush Cloudflare tunnel buffer with padding — ensures the init event
+            // (and any immediately following events) are delivered without proxy delay.
+            if (this._isTunnelActive) {
+                try {
+                    reply.raw.write(SSE_PADDING);
+                }
+                catch {
+                    /* client gone */
+                }
+            }
             req.raw.on('close', () => {
                 this.sseClients.delete(reply);
                 this.backpressuredClients.delete(reply);
@@ -482,20 +519,20 @@ export class WebServer extends EventEmitter {
                 if (controller) {
                     controller.signalTranscriptComplete();
                 }
-                this.broadcast('transcript:complete', { sessionId, timestamp: Date.now() });
+                this.broadcast(SseEvent.TranscriptComplete, { sessionId, timestamp: Date.now() });
             });
             watcher.on('transcript:plan_mode', () => {
                 const controller = this.respawnControllers.get(sessionId);
                 if (controller) {
                     controller.signalTranscriptPlanMode();
                 }
-                this.broadcast('transcript:plan_mode', { sessionId, timestamp: Date.now() });
+                this.broadcast(SseEvent.TranscriptPlanMode, { sessionId, timestamp: Date.now() });
             });
             watcher.on('transcript:tool_start', (toolName) => {
-                this.broadcast('transcript:tool_start', { sessionId, toolName, timestamp: Date.now() });
+                this.broadcast(SseEvent.TranscriptToolStart, { sessionId, toolName, timestamp: Date.now() });
             });
             watcher.on('transcript:tool_end', (toolName, isError) => {
-                this.broadcast('transcript:tool_end', {
+                this.broadcast(SseEvent.TranscriptToolEnd, {
                     sessionId,
                     toolName,
                     isError,
@@ -635,7 +672,7 @@ export class WebServer extends EventEmitter {
             controller.removeAllListeners();
             this.respawnControllers.delete(sessionId);
             // Notify UI that respawn is stopped for this session
-            this.broadcast('respawn:stopped', { sessionId, reason: 'session_cleanup' });
+            this.broadcast(SseEvent.RespawnStopped, { sessionId, reason: 'session_cleanup' });
         }
         // Clear respawn timer
         const timerInfo = this.respawnTimers.get(sessionId);
@@ -678,7 +715,7 @@ export class WebServer extends EventEmitter {
         // Clear Ralph state from store
         this.store.removeRalphState(sessionId);
         // Broadcast Ralph cleared to update UI
-        this.broadcast('session:ralphLoopUpdate', {
+        this.broadcast(SseEvent.SessionRalphLoopUpdate, {
             sessionId,
             state: {
                 enabled: false,
@@ -691,7 +728,7 @@ export class WebServer extends EventEmitter {
                 elapsedHours: null,
             },
         });
-        this.broadcast('session:ralphTodoUpdate', {
+        this.broadcast(SseEvent.SessionRalphTodoUpdate, {
             sessionId,
             todos: [],
             stats: { total: 0, pending: 0, inProgress: 0, completed: 0 },
@@ -755,7 +792,7 @@ export class WebServer extends EventEmitter {
                 this.store.removeSession(sessionId);
             }
         }
-        this.broadcast('session:deleted', { id: sessionId });
+        this.broadcast(SseEvent.SessionDeleted, { id: sessionId });
     }
     async setupSessionListeners(session) {
         // Create run summary tracker for this session
@@ -770,45 +807,51 @@ export class WebServer extends EventEmitter {
         if ((await this.isImageWatcherEnabled()) && session.imageWatcherEnabled) {
             imageWatcher.watchSession(session.id, session.workingDir);
         }
-        // Store all listener references for explicit cleanup on session delete
-        // This prevents memory leaks from closure references keeping objects alive
+        // Store all listener references for explicit cleanup on session delete.
+        // This prevents memory leaks from closure references keeping objects alive.
         const listeners = {
+            // ─── Terminal Output ─────────────────────────────────────
+            // These listeners handle raw PTY output streaming to SSE clients.
+            /** Batches PTY output → broadcasts `session:terminal` at 16-50ms intervals */
             terminal: (data) => {
-                // Use batching for better performance at high throughput
                 this.batchTerminalData(session.id, data);
             },
+            /** Broadcasts `session:clearTerminal` — tells clients to wipe their xterm buffer (after mux attach) */
             clearTerminal: () => {
-                // Tell clients to clear their terminal (after mux attach)
-                this.broadcast('session:clearTerminal', { id: session.id });
+                this.broadcast(SseEvent.SessionClearTerminal, { id: session.id });
             },
+            /** Broadcasts `session:needsRefresh` — tells clients to reload buffer (e.g., after OpenCode TUI stabilizes) */
             needsRefresh: () => {
-                // Tell clients to reload the terminal buffer (e.g., after OpenCode TUI stabilizes)
-                this.broadcast('session:needsRefresh', { id: session.id });
+                this.broadcast(SseEvent.SessionNeedsRefresh, { id: session.id });
             },
+            // ─── Session Messages & Errors ──────────────────────────
+            /** Broadcasts `session:message` — structured Claude JSON messages (assistant, tool_use, etc.) */
             message: (msg) => {
-                this.broadcast('session:message', { id: session.id, message: msg });
+                this.broadcast(SseEvent.SessionMessage, { id: session.id, message: msg });
             },
+            /** Broadcasts `session:error` + sends push notification */
             error: (error) => {
-                this.broadcast('session:error', { id: session.id, error });
-                this.sendPushNotifications('session:error', {
+                this.broadcast(SseEvent.SessionError, { id: session.id, error });
+                this.sendPushNotifications(SseEvent.SessionError, {
                     sessionId: session.id,
                     sessionName: session.name,
                     error: String(error),
                 });
-                // Track in run summary
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker)
                     tracker.recordError('Session error', String(error));
             },
+            /** Broadcasts `session:completion` + `session:updated` — prompt finished, persists state */
             completion: (result, cost) => {
-                this.broadcast('session:completion', { id: session.id, result, cost });
-                this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
+                this.broadcast(SseEvent.SessionCompletion, { id: session.id, result, cost });
+                this.broadcast(SseEvent.SessionUpdated, this.getSessionStateWithRespawn(session));
                 this.persistSessionState(session);
-                // Track tokens in run summary (completion event has updated token values)
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker)
                     tracker.recordTokens(session.inputTokens, session.outputTokens);
             },
+            // ─── Session Lifecycle ──────────────────────────────────
+            /** Broadcasts `session:exit` + `session:updated` — PTY process exited; cleans up respawn, timers, listeners */
             exit: (code) => {
                 getLifecycleLog().log({
                     event: 'exit',
@@ -818,8 +861,8 @@ export class WebServer extends EventEmitter {
                 });
                 // Wrap in try/catch to ensure cleanup always happens
                 try {
-                    this.broadcast('session:exit', { id: session.id, code });
-                    this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
+                    this.broadcast(SseEvent.SessionExit, { id: session.id, code });
+                    this.broadcast(SseEvent.SessionUpdated, this.getSessionStateWithRespawn(session));
                     this.persistSessionState(session);
                 }
                 catch (err) {
@@ -908,121 +951,130 @@ export class WebServer extends EventEmitter {
                     console.error(`[Server] Error cleaning up session resources on exit for ${session.id}:`, err);
                 }
             },
+            // ─── Activity State ─────────────────────────────────────
+            /** Broadcasts `session:working` — Claude started processing */
             working: () => {
-                this.broadcast('session:working', { id: session.id });
-                // Track in run summary
+                this.broadcast(SseEvent.SessionWorking, { id: session.id });
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker) {
                     tracker.recordWorking();
                     tracker.recordTokens(session.inputTokens, session.outputTokens);
                 }
             },
+            /** Broadcasts `session:idle` — Claude finished processing, waiting for input */
             idle: () => {
-                this.broadcast('session:idle', { id: session.id });
-                // Use debounced state update (idle can fire frequently)
+                this.broadcast(SseEvent.SessionIdle, { id: session.id });
                 this.broadcastSessionStateDebounced(session.id);
-                // Track in run summary
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker) {
                     tracker.recordIdle();
                     tracker.recordTokens(session.inputTokens, session.outputTokens);
                 }
             },
-            // Background task events - use debounced state updates to reduce serialization overhead
+            // ─── Background Task Events ──────────────────────────────
+            // Debounced state updates to reduce serialization overhead.
+            /** Broadcasts `task:created` — new background task discovered */
             taskCreated: (task) => {
-                this.broadcast('task:created', { sessionId: session.id, task });
+                this.broadcast(SseEvent.TaskCreated, { sessionId: session.id, task });
                 this.broadcastSessionStateDebounced(session.id);
             },
+            /** Batched broadcast of `task:updated` — high-frequency progress updates */
             taskUpdated: (task) => {
-                // Use batching for better performance at high update rates
                 this.batchTaskUpdate(session.id, task);
             },
+            /** Broadcasts `task:completed` — background task finished successfully */
             taskCompleted: (task) => {
-                this.broadcast('task:completed', { sessionId: session.id, task });
+                this.broadcast(SseEvent.TaskCompleted, { sessionId: session.id, task });
                 this.broadcastSessionStateDebounced(session.id);
             },
+            /** Broadcasts `task:failed` — background task errored */
             taskFailed: (task, error) => {
-                this.broadcast('task:failed', { sessionId: session.id, task, error });
+                this.broadcast(SseEvent.TaskFailed, { sessionId: session.id, task, error });
                 this.broadcastSessionStateDebounced(session.id);
             },
+            // ─── Auto-Operations ────────────────────────────────────
+            /** Broadcasts `session:autoClear` — context window auto-cleared at token threshold */
             autoClear: (data) => {
-                this.broadcast('session:autoClear', { sessionId: session.id, ...data });
+                this.broadcast(SseEvent.SessionAutoClear, { sessionId: session.id, ...data });
                 this.broadcastSessionStateDebounced(session.id);
-                // Track in run summary
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker)
                     tracker.recordAutoClear(data.tokens, data.threshold);
             },
+            /** Broadcasts `session:autoCompact` — context window auto-compacted at token threshold */
             autoCompact: (data) => {
-                this.broadcast('session:autoCompact', { sessionId: session.id, ...data });
+                this.broadcast(SseEvent.SessionAutoCompact, { sessionId: session.id, ...data });
                 this.broadcastSessionStateDebounced(session.id);
-                // Track in run summary
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker)
                     tracker.recordAutoCompact(data.tokens, data.threshold);
             },
-            // Claude Code CLI info parsed from terminal (version, model, account)
+            // ─── CLI Info ────────────────────────────────────────────
+            /** Broadcasts `session:cliInfo` — Claude Code version, model, account type parsed from terminal */
             cliInfoUpdated: (data) => {
-                this.broadcast('session:cliInfo', { sessionId: session.id, ...data });
+                this.broadcast(SseEvent.SessionCliInfo, { sessionId: session.id, ...data });
                 this.broadcastSessionStateDebounced(session.id);
             },
-            // Ralph tracking events
+            // ─── Ralph Tracking Events ──────────────────────────────
+            /** Broadcasts `session:ralphLoopUpdate` — Ralph tracker loop state changed (iteration, phase) */
             ralphLoopUpdate: (state) => {
-                this.broadcast('session:ralphLoopUpdate', { sessionId: session.id, state });
-                // Persist Ralph state
+                this.broadcast(SseEvent.SessionRalphLoopUpdate, { sessionId: session.id, state });
                 this.store.updateRalphState(session.id, { loop: state });
             },
+            /** Broadcasts `session:ralphTodoUpdate` — todo items added, completed, or modified */
             ralphTodoUpdate: (todos) => {
-                this.broadcast('session:ralphTodoUpdate', { sessionId: session.id, todos });
-                // Persist Ralph state
+                this.broadcast(SseEvent.SessionRalphTodoUpdate, { sessionId: session.id, todos });
                 this.store.updateRalphState(session.id, { todos });
             },
+            /** Broadcasts `session:ralphCompletionDetected` + push notification — completion phrase matched */
             ralphCompletionDetected: (phrase) => {
-                this.broadcast('session:ralphCompletionDetected', { sessionId: session.id, phrase });
-                this.sendPushNotifications('session:ralphCompletionDetected', {
+                this.broadcast(SseEvent.SessionRalphCompletionDetected, { sessionId: session.id, phrase });
+                this.sendPushNotifications(SseEvent.SessionRalphCompletionDetected, {
                     sessionId: session.id,
                     sessionName: session.name,
                     phrase,
                 });
-                // Track in run summary
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker)
                     tracker.recordRalphCompletion(phrase);
             },
-            // RALPH_STATUS block events
+            /** Broadcasts `session:ralphStatusUpdate` — RALPH_STATUS block parsed from output */
             ralphStatusBlockDetected: (block) => {
-                this.broadcast('session:ralphStatusUpdate', { sessionId: session.id, block });
-                // Track in run summary
+                this.broadcast(SseEvent.SessionRalphStatusUpdate, { sessionId: session.id, block });
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker) {
                     tracker.addEvent(block.status === 'BLOCKED' ? 'warning' : 'idle_detected', block.status === 'BLOCKED' ? 'warning' : 'info', `Ralph Status: ${block.status}`, `Tasks: ${block.tasksCompletedThisLoop}, Files: ${block.filesModified}, Tests: ${block.testsStatus}`);
                 }
             },
+            /** Broadcasts `session:circuitBreakerUpdate` — circuit breaker state changed (CLOSED/HALF_OPEN/OPEN) */
             ralphCircuitBreakerUpdate: (status) => {
-                this.broadcast('session:circuitBreakerUpdate', { sessionId: session.id, status });
-                // Track state changes in run summary
+                this.broadcast(SseEvent.SessionCircuitBreakerUpdate, { sessionId: session.id, status });
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker && status.state === 'OPEN') {
                     tracker.addEvent('warning', 'warning', 'Circuit Breaker Opened', status.reason);
                 }
             },
+            /** Broadcasts `session:exitGateMet` — all completion indicators met, ready to exit */
             ralphExitGateMet: (data) => {
-                this.broadcast('session:exitGateMet', { sessionId: session.id, ...data });
-                // Track in run summary
+                this.broadcast(SseEvent.SessionExitGateMet, { sessionId: session.id, ...data });
                 const tracker = this.runSummaryTrackers.get(session.id);
                 if (tracker) {
                     tracker.addEvent('ralph_completion', 'success', 'Exit Gate Met', `Indicators: ${data.completionIndicators}, EXIT_SIGNAL: ${data.exitSignal}`);
                 }
             },
-            // Bash tool tracking events (for clickable file paths)
+            // ─── Bash Tool Tracking ────────────────────────────────
+            // Used for clickable file paths in the UI.
+            /** Broadcasts `session:bashToolStart` — bash tool invocation started */
             bashToolStart: (tool) => {
-                this.broadcast('session:bashToolStart', { sessionId: session.id, tool });
+                this.broadcast(SseEvent.SessionBashToolStart, { sessionId: session.id, tool });
             },
+            /** Broadcasts `session:bashToolEnd` — bash tool invocation completed */
             bashToolEnd: (tool) => {
-                this.broadcast('session:bashToolEnd', { sessionId: session.id, tool });
+                this.broadcast(SseEvent.SessionBashToolEnd, { sessionId: session.id, tool });
             },
+            /** Broadcasts `session:bashToolsUpdate` — full active bash tools list refreshed */
             bashToolsUpdate: (tools) => {
-                this.broadcast('session:bashToolsUpdate', { sessionId: session.id, tools });
+                this.broadcast(SseEvent.SessionBashToolsUpdate, { sessionId: session.id, tools });
             },
         };
         // Store listener refs for cleanup
@@ -1059,102 +1111,124 @@ export class WebServer extends EventEmitter {
         controller.setTeamWatcher(this.teamWatcher);
         // Helper to get tracker lazily (may not exist at setup time for restored sessions)
         const getTracker = () => this.runSummaryTrackers.get(sessionId);
+        // ─── Respawn State Machine ──────────────────────────────
+        /** Broadcasts `respawn:stateChanged` — state machine transition (e.g., IDLE → DETECTING → RESPAWNING) */
         controller.on('stateChanged', (state, prevState) => {
-            this.broadcast('respawn:stateChanged', { sessionId, state, prevState });
-            // Track in run summary (lazy lookup since tracker may be created after controller)
+            this.broadcast(SseEvent.RespawnStateChanged, { sessionId, state, prevState });
             const tracker = getTracker();
             if (tracker)
                 tracker.recordStateChange(state, `${prevState} → ${state}`);
         });
+        // ─── Respawn Cycle Lifecycle ────────────────────────────
+        /** Broadcasts `respawn:cycleStarted` — new respawn cycle begins */
         controller.on('respawnCycleStarted', (cycleNumber) => {
-            this.broadcast('respawn:cycleStarted', { sessionId, cycleNumber });
+            this.broadcast(SseEvent.RespawnCycleStarted, { sessionId, cycleNumber });
         });
+        /** Broadcasts `respawn:cycleCompleted` — respawn cycle finished */
         controller.on('respawnCycleCompleted', (cycleNumber) => {
-            this.broadcast('respawn:cycleCompleted', { sessionId, cycleNumber });
+            this.broadcast(SseEvent.RespawnCycleCompleted, { sessionId, cycleNumber });
         });
+        /** Broadcasts `respawn:blocked` + push notification — respawn blocked by error/circuit breaker */
         controller.on('respawnBlocked', (data) => {
-            this.broadcast('respawn:blocked', { sessionId, reason: data.reason, details: data.details });
+            this.broadcast(SseEvent.RespawnBlocked, { sessionId, reason: data.reason, details: data.details });
             const sessionForPush = this.sessions.get(sessionId);
-            this.sendPushNotifications('respawn:blocked', {
+            this.sendPushNotifications(SseEvent.RespawnBlocked, {
                 sessionId,
                 sessionName: sessionForPush?.name ?? sessionId.slice(0, 8),
                 reason: data.reason,
             });
-            // Track in run summary (lazy lookup)
             const tracker = getTracker();
             if (tracker)
                 tracker.recordWarning(`Respawn blocked: ${data.reason}`, data.details);
         });
+        // ─── Respawn Step Progress ──────────────────────────────
+        /** Broadcasts `respawn:stepSent` — respawn step input sent (e.g., /clear, kickstart prompt) */
         controller.on('stepSent', (step, input) => {
-            this.broadcast('respawn:stepSent', { sessionId, step, input });
+            this.broadcast(SseEvent.RespawnStepSent, { sessionId, step, input });
         });
+        /** Broadcasts `respawn:stepCompleted` — respawn step finished */
         controller.on('stepCompleted', (step) => {
-            this.broadcast('respawn:stepCompleted', { sessionId, step });
+            this.broadcast(SseEvent.RespawnStepCompleted, { sessionId, step });
         });
+        /** Broadcasts `respawn:detectionUpdate` — idle/completion detection state changed */
         controller.on('detectionUpdate', (detection) => {
-            this.broadcast('respawn:detectionUpdate', { sessionId, detection });
+            this.broadcast(SseEvent.RespawnDetectionUpdate, { sessionId, detection });
         });
+        /** Broadcasts `respawn:autoAcceptSent` — auto-accepted a permission prompt */
         controller.on('autoAcceptSent', () => {
-            this.broadcast('respawn:autoAcceptSent', { sessionId });
+            this.broadcast(SseEvent.RespawnAutoAcceptSent, { sessionId });
         });
+        // ─── AI Checker Events ──────────────────────────────────
+        /** Broadcasts `respawn:aiCheckStarted` — AI idle checker invoked */
         controller.on('aiCheckStarted', () => {
-            this.broadcast('respawn:aiCheckStarted', { sessionId });
+            this.broadcast(SseEvent.RespawnAiCheckStarted, { sessionId });
         });
+        /** Broadcasts `respawn:aiCheckCompleted` — AI idle check returned verdict (idle/working/stuck) */
         controller.on('aiCheckCompleted', (result) => {
-            this.broadcast('respawn:aiCheckCompleted', {
+            this.broadcast(SseEvent.RespawnAiCheckCompleted, {
                 sessionId,
                 verdict: result.verdict,
                 reasoning: result.reasoning,
                 durationMs: result.durationMs,
             });
-            // Track in run summary (lazy lookup)
             const tracker = getTracker();
             if (tracker)
                 tracker.recordAiCheckResult(result.verdict);
         });
+        /** Broadcasts `respawn:aiCheckFailed` — AI idle check errored */
         controller.on('aiCheckFailed', (error) => {
-            this.broadcast('respawn:aiCheckFailed', { sessionId, error });
-            // Track in run summary (lazy lookup)
+            this.broadcast(SseEvent.RespawnAiCheckFailed, { sessionId, error });
             const tracker = getTracker();
             if (tracker)
                 tracker.recordError('AI check failed', error);
         });
+        /** Broadcasts `respawn:aiCheckCooldown` — AI check on cooldown after failure */
         controller.on('aiCheckCooldown', (active, endsAt) => {
-            this.broadcast('respawn:aiCheckCooldown', { sessionId, active, endsAt });
+            this.broadcast(SseEvent.RespawnAiCheckCooldown, { sessionId, active, endsAt });
         });
+        // ─── Plan Checker Events ────────────────────────────────
+        /** Broadcasts `respawn:planCheckStarted` — AI plan completion checker invoked */
         controller.on('planCheckStarted', () => {
-            this.broadcast('respawn:planCheckStarted', { sessionId });
+            this.broadcast(SseEvent.RespawnPlanCheckStarted, { sessionId });
         });
+        /** Broadcasts `respawn:planCheckCompleted` — plan check returned verdict */
         controller.on('planCheckCompleted', (result) => {
-            this.broadcast('respawn:planCheckCompleted', {
+            this.broadcast(SseEvent.RespawnPlanCheckCompleted, {
                 sessionId,
                 verdict: result.verdict,
                 reasoning: result.reasoning,
                 durationMs: result.durationMs,
             });
         });
+        /** Broadcasts `respawn:planCheckFailed` — plan check errored */
         controller.on('planCheckFailed', (error) => {
-            this.broadcast('respawn:planCheckFailed', { sessionId, error });
+            this.broadcast(SseEvent.RespawnPlanCheckFailed, { sessionId, error });
         });
-        // Timer tracking events for UI countdown display
+        // ─── Timer Events (UI countdown display) ────────────────
+        /** Broadcasts `respawn:timerStarted` — countdown timer started (idle, cooldown, etc.) */
         controller.on('timerStarted', (timer) => {
-            this.broadcast('respawn:timerStarted', { sessionId, timer });
+            this.broadcast(SseEvent.RespawnTimerStarted, { sessionId, timer });
         });
+        /** Broadcasts `respawn:timerCancelled` — timer cancelled before expiry */
         controller.on('timerCancelled', (timerName, reason) => {
-            this.broadcast('respawn:timerCancelled', { sessionId, timerName, reason });
+            this.broadcast(SseEvent.RespawnTimerCancelled, { sessionId, timerName, reason });
         });
+        /** Broadcasts `respawn:timerCompleted` — timer expired */
         controller.on('timerCompleted', (timerName) => {
-            this.broadcast('respawn:timerCompleted', { sessionId, timerName });
+            this.broadcast(SseEvent.RespawnTimerCompleted, { sessionId, timerName });
         });
+        // ─── Logging & Errors ───────────────────────────────────
+        /** Broadcasts `respawn:actionLog` — respawn action logged for audit/debugging */
         controller.on('actionLog', (action) => {
-            this.broadcast('respawn:actionLog', { sessionId, action });
+            this.broadcast(SseEvent.RespawnActionLog, { sessionId, action });
         });
+        /** Broadcasts `respawn:log` — general respawn log message */
         controller.on('log', (message) => {
-            this.broadcast('respawn:log', { sessionId, message });
+            this.broadcast(SseEvent.RespawnLog, { sessionId, message });
         });
+        /** Broadcasts `respawn:error` — respawn controller error */
         controller.on('error', (error) => {
-            this.broadcast('respawn:error', { sessionId, error: error.message });
-            // Track in run summary (lazy lookup)
+            this.broadcast(SseEvent.RespawnError, { sessionId, error: error.message });
             const tracker = getTracker();
             if (tracker)
                 tracker.recordError('Respawn error', error.message);
@@ -1175,7 +1249,7 @@ export class WebServer extends EventEmitter {
                 controller.stop();
                 controller.removeAllListeners();
                 this.respawnControllers.delete(sessionId);
-                this.broadcast('respawn:stopped', { sessionId, reason: 'duration_expired' });
+                this.broadcast(SseEvent.RespawnStopped, { sessionId, reason: 'duration_expired' });
             }
             this.respawnTimers.delete(sessionId);
             // Update persisted state (respawn no longer active)
@@ -1185,7 +1259,7 @@ export class WebServer extends EventEmitter {
             }
         }, durationMinutes * 60 * 1000);
         this.respawnTimers.set(sessionId, { timer, endAt, startedAt: now });
-        this.broadcast('respawn:timerStarted', { sessionId, durationMinutes, endAt, startedAt: now });
+        this.broadcast(SseEvent.RespawnTimerStarted, { sessionId, durationMinutes, endAt, startedAt: now });
     }
     /**
      * Restore a RespawnController from persisted configuration.
@@ -1238,7 +1312,7 @@ export class WebServer extends EventEmitter {
                 const ctrl = this.respawnControllers.get(session.id);
                 if (ctrl && ctrl.state === 'stopped') {
                     ctrl.start();
-                    this.broadcast('respawn:started', { sessionId: session.id });
+                    this.broadcast(SseEvent.RespawnStarted, { sessionId: session.id });
                     console.log(`[Server] Restored respawn controller started for session ${session.id}`);
                 }
             }, delayMs);
@@ -1334,7 +1408,7 @@ export class WebServer extends EventEmitter {
             logs: [`[${new Date().toISOString()}] Scheduled run started`],
         };
         this.scheduledRuns.set(id, run);
-        this.broadcast('scheduled:created', run);
+        this.broadcast(SseEvent.ScheduledCreated, run);
         // Start the run loop (fire-and-forget with error handling)
         this.runScheduledLoop(id).catch((err) => {
             console.error(`[WebServer] Scheduled run ${id} failed:`, err);
@@ -1342,7 +1416,7 @@ export class WebServer extends EventEmitter {
             if (failedRun && failedRun.status === 'running') {
                 failedRun.status = 'stopped';
                 failedRun.logs.push(`[${new Date().toISOString()}] Error: ${err instanceof Error ? err.message : String(err)}`);
-                this.broadcast('scheduled:stopped', { id, reason: 'error' });
+                this.broadcast(SseEvent.ScheduledStopped, { id, reason: 'error' });
             }
         });
         return run;
@@ -1353,7 +1427,7 @@ export class WebServer extends EventEmitter {
             return;
         const addLog = (msg) => {
             run.logs.push(`[${new Date().toISOString()}] ${msg}`);
-            this.broadcast('scheduled:log', { id: runId, log: run.logs[run.logs.length - 1] });
+            this.broadcast(SseEvent.ScheduledLog, { id: runId, log: run.logs[run.logs.length - 1] });
         };
         while (Date.now() < run.endAt && run.status === 'running') {
             // Check session limit before creating new session
@@ -1372,7 +1446,7 @@ export class WebServer extends EventEmitter {
                 await this.setupSessionListeners(session);
                 run.sessionId = session.id;
                 addLog(`Starting task iteration with session ${session.id.slice(0, 8)}`);
-                this.broadcast('scheduled:updated', run);
+                this.broadcast(SseEvent.ScheduledUpdated, run);
                 // Run the prompt
                 const timeRemaining = Math.round((run.endAt - Date.now()) / 60000);
                 const enhancedPrompt = `${run.prompt}\n\nNote: You have approximately ${timeRemaining} minutes remaining in this scheduled run. Work efficiently.`;
@@ -1380,7 +1454,7 @@ export class WebServer extends EventEmitter {
                 run.completedTasks++;
                 run.totalCost += result.cost;
                 addLog(`Task completed. Cost: $${result.cost.toFixed(4)}. Total tasks: ${run.completedTasks}`);
-                this.broadcast('scheduled:updated', run);
+                this.broadcast(SseEvent.ScheduledUpdated, run);
                 // Clean up the session after iteration to prevent memory leaks
                 await this.cleanupSession(session.id, true, 'scheduled_run');
                 run.sessionId = null;
@@ -1389,7 +1463,7 @@ export class WebServer extends EventEmitter {
             }
             catch (err) {
                 addLog(`Error: ${getErrorMessage(err)}`);
-                this.broadcast('scheduled:updated', run);
+                this.broadcast(SseEvent.ScheduledUpdated, run);
                 // Clean up the session on error too
                 if (session) {
                     try {
@@ -1408,7 +1482,7 @@ export class WebServer extends EventEmitter {
             run.status = 'completed';
             addLog(`Scheduled run completed. Total tasks: ${run.completedTasks}, Total cost: $${run.totalCost.toFixed(4)}`);
         }
-        this.broadcast('scheduled:completed', run);
+        this.broadcast(SseEvent.ScheduledCompleted, run);
     }
     async stopScheduledRun(id) {
         const run = this.scheduledRuns.get(id);
@@ -1421,7 +1495,7 @@ export class WebServer extends EventEmitter {
             await this.cleanupSession(run.sessionId, true, 'scheduled_run_stopped');
             run.sessionId = null;
         }
-        this.broadcast('scheduled:stopped', run);
+        this.broadcast(SseEvent.ScheduledStopped, run);
     }
     /**
      * Get session state with respawn controller info included.
@@ -1467,7 +1541,7 @@ export class WebServer extends EventEmitter {
         }
         for (const id of toDelete) {
             this.scheduledRuns.delete(id);
-            this.broadcast('scheduled:deleted', { id });
+            this.broadcast(SseEvent.ScheduledDeleted, { id });
         }
         if (toDelete.length > 0) {
             console.log(`[Server] Cleaned up ${toDelete.length} old scheduled run(s)`);
@@ -1545,7 +1619,7 @@ export class WebServer extends EventEmitter {
                     // Client may have missed terminal data during backpressure.
                     // Tell it to reload the active session's buffer to recover.
                     try {
-                        reply.raw.write(`event: session:needsRefresh\ndata: {}\n\n`);
+                        reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n`);
                     }
                     catch {
                         /* client gone */
@@ -1559,21 +1633,25 @@ export class WebServer extends EventEmitter {
         }
     }
     broadcast(event, data) {
-        // Invalidate caches only on structurally significant events — ones that
-        // change session list content (creation, deletion, or full state refresh).
-        // High-frequency non-structural events (working/idle transitions, completion,
-        // error, respawn state changes) are NOT worth invalidating for because:
-        //   1. The debounced session:updated follows within 500ms with the new state
-        //   2. These caches serve /api/sessions and SSE init — neither is polled rapidly
-        //   3. Invalidating on every working/idle transition makes the 1s TTL useless
-        if (event === 'session:created' || event === 'session:deleted' || event === 'session:updated') {
+        // Skip serialization entirely when no clients are listening
+        if (this.sseClients.size === 0)
+            return;
+        // Invalidate caches only on structural changes (creation/deletion).
+        // SessionUpdated fires too frequently (working/idle transitions, completion)
+        // and makes the 1s TTL cache useless — the debounced session:updated follows
+        // within 500ms anyway, and these caches serve /api/sessions and SSE init
+        // which aren't polled rapidly.
+        if (event === SseEvent.SessionCreated || event === SseEvent.SessionDeleted) {
             this.cachedLightState = null;
             this.cachedSessionsList = null;
         }
-        // Performance optimization: serialize JSON once for all clients
+        // Performance optimization: serialize JSON once for all clients.
+        // Only append Cloudflare tunnel padding when tunnel is actually active —
+        // direct/Tailscale clients don't need 8KB padding on every event.
+        const padding = this._isTunnelActive ? SSE_PADDING : '';
         let message;
         try {
-            message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+            message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n` + padding;
         }
         catch (err) {
             // Handle circular references or non-serializable values
@@ -1687,7 +1765,7 @@ export class WebServer extends EventEmitter {
             return;
         }
         for (const [, { sessionId, task }] of this.taskUpdateBatches) {
-            this.broadcast('task:updated', { sessionId, task });
+            this.broadcast(SseEvent.TaskUpdated, { sessionId, task });
         }
         this.taskUpdateBatches.clear();
     }
@@ -1718,7 +1796,7 @@ export class WebServer extends EventEmitter {
             const session = this.sessions.get(sessionId);
             if (session) {
                 // Single expensive serialization per batch interval
-                this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
+                this.broadcast(SseEvent.SessionUpdated, this.getSessionStateWithRespawn(session));
             }
         }
         this.stateUpdatePending.clear();
@@ -1726,7 +1804,7 @@ export class WebServer extends EventEmitter {
     // ========== Web Push ==========
     /** Map SSE event names to push notification payloads */
     static PUSH_EVENT_MAP = {
-        'hook:permission_prompt': {
+        [SseEvent.HookPermissionPrompt]: {
             title: 'Permission Required',
             urgency: 'critical',
             actions: [
@@ -1734,12 +1812,12 @@ export class WebServer extends EventEmitter {
                 { action: 'deny', title: 'Deny' },
             ],
         },
-        'hook:elicitation_dialog': { title: 'Question Asked', urgency: 'critical' },
-        'hook:idle_prompt': { title: 'Waiting for Input', urgency: 'warning' },
-        'hook:stop': { title: 'Response Complete', urgency: 'info' },
-        'session:error': { title: 'Session Error', urgency: 'critical' },
-        'respawn:blocked': { title: 'Respawn Blocked', urgency: 'critical' },
-        'session:ralphCompletionDetected': { title: 'Task Complete', urgency: 'warning' },
+        [SseEvent.HookElicitationDialog]: { title: 'Question Asked', urgency: 'critical' },
+        [SseEvent.HookIdlePrompt]: { title: 'Waiting for Input', urgency: 'warning' },
+        [SseEvent.HookStop]: { title: 'Response Complete', urgency: 'info' },
+        [SseEvent.SessionError]: { title: 'Session Error', urgency: 'critical' },
+        [SseEvent.RespawnBlocked]: { title: 'Respawn Blocked', urgency: 'critical' },
+        [SseEvent.SessionRalphCompletionDetected]: { title: 'Task Complete', urgency: 'warning' },
     };
     /**
      * Send push notifications for a given event to all subscribed devices.
@@ -1759,19 +1837,19 @@ export class WebServer extends EventEmitter {
         const sessionId = data.sessionId || '';
         // Build body text from event data
         let body = sessionName ? `[${sessionName}]` : '';
-        if (event === 'session:error' && data.error) {
+        if (event === SseEvent.SessionError && data.error) {
             body += body ? ' ' : '';
             body += String(data.error).slice(0, 200);
         }
-        else if (event === 'respawn:blocked' && data.reason) {
+        else if (event === SseEvent.RespawnBlocked && data.reason) {
             body += body ? ' ' : '';
             body += String(data.reason);
         }
-        else if (event === 'session:ralphCompletionDetected' && data.phrase) {
+        else if (event === SseEvent.SessionRalphCompletionDetected && data.phrase) {
             body += body ? ' ' : '';
             body += String(data.phrase);
         }
-        else if (event === 'hook:permission_prompt' && data.tool_name) {
+        else if (event === SseEvent.HookPermissionPrompt && data.tool_name) {
             body += body ? ' ' : '';
             body += `Tool: ${String(data.tool_name)}`;
         }
@@ -1814,8 +1892,11 @@ export class WebServer extends EventEmitter {
                     deadClients.push(client);
                 }
                 else {
-                    // Send SSE comment as keep-alive (comments start with ':')
-                    client.raw.write(':keepalive\n\n');
+                    // Send SSE comment as keep-alive. Only add padding when tunnel is
+                    // active — it flushes Cloudflare proxy buffers but wastes bandwidth
+                    // for direct/Tailscale connections.
+                    const ka = this._isTunnelActive ? ':keepalive\n' + SSE_PADDING : ':keepalive\n\n';
+                    client.raw.write(ka);
                 }
             }
             catch {
@@ -1881,7 +1962,7 @@ export class WebServer extends EventEmitter {
         // Start SSE client health check timer (prevents memory leaks from dead connections)
         this.cleanup.setInterval(() => {
             this.cleanupDeadSSEClients();
-        }, SSE_HEALTH_CHECK_INTERVAL, { description: 'SSE client health check' });
+        }, SSE_HEARTBEAT_INTERVAL, { description: 'SSE heartbeat + dead client cleanup' });
         // Start token recording timer (every 5 minutes for long-running sessions)
         this.cleanup.setInterval(() => {
             this.recordPeriodicTokenUsage();