aicodeman 0.2.9 → 0.3.0

package/dist/web/server.js

@@ -13,22 +13,19 @@ import Fastify from 'fastify';
 import fastifyCompress from '@fastify/compress';
 import fastifyCookie from '@fastify/cookie';
 import fastifyStatic from '@fastify/static';
-import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
+import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { existsSync, statSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync, chmodSync, realpathSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, chmodSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
-import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { homedir, totalmem, freemem, loadavg, cpus } from 'node:os';
+import { homedir } from 'node:os';
 import { EventEmitter } from 'node:events';
 import { Session, } from '../session.js';
-import { fileStreamManager } from '../file-stream-manager.js';
 import { RespawnController } from '../respawn-controller.js';
 import { createMultiplexer } from '../mux-factory.js';
 import { getStore } from '../state-store.js';
-import { generateClaudeMd } from '../templates/claude-md.js';
-import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.js';
-import { writeHooksConfig, updateCaseEnvVars } from '../hooks-config.js';
+import { extractCompletionPhrase } from '../ralph-config.js';
+import { fileStreamManager } from '../file-stream-manager.js';
 import { subagentWatcher, } from '../subagent-watcher.js';
 import { imageWatcher } from '../image-watcher.js';
 import { TranscriptWatcher } from '../transcript-watcher.js';
@@ -37,7 +34,6 @@ import { TunnelManager } from '../tunnel-manager.js';
 import { v4 as uuidv4 } from 'uuid';
 import { createRequire } from 'node:module';
 import { RunSummaryTracker } from '../run-summary.js';
-import { PlanOrchestrator } from '../plan-orchestrator.js';
 import { getLifecycleLog } from '../session-lifecycle-log.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
@@ -45,181 +41,18 @@ import webpush from 'web-push';
 const require = createRequire(import.meta.url);
 const { version: APP_VERSION } = require('../../package.json');
 import { getErrorMessage, ApiErrorCode, createErrorResponse, DEFAULT_NICE_CONFIG, } from '../types.js';
-import { CreateSessionSchema, RunPromptSchema, SessionInputWithLimitSchema, ResizeSchema, CreateCaseSchema, QuickStartSchema, HookEventSchema, ConfigUpdateSchema, RespawnConfigSchema, SessionNameSchema, SessionColorSchema, RalphConfigSchema, FixPlanImportSchema, RalphPromptWriteSchema, AutoClearSchema, AutoCompactSchema, ImageWatcherSchema, FlickerFilterSchema, QuickRunSchema, ScheduledRunSchema, LinkCaseSchema, GeneratePlanSchema, GeneratePlanDetailedSchema, CancelPlanSchema, PlanTaskUpdateSchema, PlanTaskAddSchema, CpuLimitSchema, SettingsUpdateSchema, ModelConfigUpdateSchema, SubagentWindowStatesSchema, SubagentParentMapSchema, InteractiveRespawnSchema, RespawnEnableSchema, PushSubscribeSchema, PushPreferencesUpdateSchema, RalphLoopStartSchema, isValidWorkingDir, } from './schemas.js';
-import { StaleExpirationMap } from '../utils/index.js';
+import { CleanupManager, KeyedDebouncer, StaleExpirationMap } from '../utils/index.js';
 import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.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));
-// Batch terminal data for performance - collect for 16ms (60fps) before sending
-const TERMINAL_BATCH_INTERVAL = 16;
-// Batch task:updated events for 100ms
-const TASK_UPDATE_BATCH_INTERVAL = 100;
+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';
 // 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)
-// State update debounce interval (batch expensive toDetailedState() calls)
-const STATE_UPDATE_DEBOUNCE_INTERVAL = 500;
-// Cache TTL for getLightSessionsState() — avoids re-serializing all sessions on every SSE init / /api/sessions call
-const SESSIONS_LIST_CACHE_TTL = 1000;
-// Scheduled runs cleanup interval (check every 5 minutes)
-const SCHEDULED_CLEANUP_INTERVAL = 5 * 60 * 1000;
-// Completed scheduled runs max age (1 hour)
-const SCHEDULED_RUN_MAX_AGE = 60 * 60 * 1000;
-// SSE client health check interval (every 30 seconds)
-const SSE_HEALTH_CHECK_INTERVAL = 30 * 1000;
-// Maximum allowed input length for session write (64KB)
-const MAX_INPUT_LENGTH = 64 * 1024;
-// Maximum terminal resize dimensions
-const MAX_TERMINAL_COLS = 500;
-const MAX_TERMINAL_ROWS = 200;
-// Maximum session name length
-const MAX_SESSION_NAME_LENGTH = 128;
-// Maximum hook data size (prevents oversized SSE broadcasts)
-const MAX_HOOK_DATA_SIZE = 8 * 1024;
-// Maximum screenshot upload size (10MB)
-const MAX_SCREENSHOT_SIZE = 10 * 1024 * 1024;
-// Auth session cookie TTL (24h — matches autonomous run length)
-const AUTH_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
-// Auth session cookie name
-const AUTH_COOKIE_NAME = 'codeman_session';
-// Max concurrent auth sessions
-const MAX_AUTH_SESSIONS = 100;
-// Max failed auth attempts per IP before rate-limiting
-const AUTH_FAILURE_MAX = 10;
-// Failed auth attempt tracking window (15 minutes)
-const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
-// Screenshots directory
-const SCREENSHOTS_DIR = join(homedir(), '.codeman', 'screenshots');
-// Stats collection interval (2 seconds)
-const STATS_COLLECTION_INTERVAL_MS = 2000;
-// Session limit wait time before retrying (5 seconds)
-const SESSION_LIMIT_WAIT_MS = 5000;
-// Pause between scheduled run iterations (2 seconds)
-const ITERATION_PAUSE_MS = 2000;
-// Terminal batch flush threshold - flush immediately if batch exceeds this size
-// Set high (32KB) to allow effective batching; avg Ink events are ~14KB
-const BATCH_FLUSH_THRESHOLD = 32 * 1024;
-// Pre-compiled regex for terminal buffer cleaning (avoids per-request compilation)
-// eslint-disable-next-line no-control-regex
-const CLAUDE_BANNER_PATTERN = /\x1b\[1mClaud/;
-// eslint-disable-next-line no-control-regex
-const CTRL_L_PATTERN = /\x0c/g;
-const LEADING_WHITESPACE_PATTERN = /^[\s\r\n]+/;
-/**
- * Formats uptime in seconds to a human-readable string.
- */
-function formatUptime(seconds) {
-    const days = Math.floor(seconds / 86400);
-    const hours = Math.floor((seconds % 86400) / 3600);
-    const minutes = Math.floor((seconds % 3600) / 60);
-    const secs = Math.floor(seconds % 60);
-    const parts = [];
-    if (days > 0)
-        parts.push(`${days}d`);
-    if (hours > 0)
-        parts.push(`${hours}h`);
-    if (minutes > 0)
-        parts.push(`${minutes}m`);
-    if (secs > 0 || parts.length === 0)
-        parts.push(`${secs}s`);
-    return parts.join(' ');
-}
-/**
- * Sanitizes hook event data before broadcasting via SSE.
- * Extracts only relevant fields and limits total size to prevent
- * oversized payloads from being broadcast to all connected clients.
- */
-function sanitizeHookData(data) {
-    if (!data || typeof data !== 'object')
-        return {};
-    // Only forward known safe fields from Claude Code hook stdin
-    const safeFields = {};
-    const allowedKeys = [
-        'hook_event_name',
-        'tool_name',
-        'tool_input',
-        'session_id',
-        'cwd',
-        'permission_mode',
-        'stop_hook_active',
-        'transcript_path',
-    ];
-    for (const key of allowedKeys) {
-        if (key in data && data[key] !== undefined) {
-            safeFields[key] = data[key];
-        }
-    }
-    // For tool_input, extract only summary fields (not full file content)
-    if (safeFields.tool_input && typeof safeFields.tool_input === 'object') {
-        const input = safeFields.tool_input;
-        const summary = {};
-        if (input.command)
-            summary.command = String(input.command).slice(0, 500);
-        if (input.file_path)
-            summary.file_path = String(input.file_path).slice(0, 500);
-        if (input.description)
-            summary.description = String(input.description).slice(0, 200);
-        if (input.query)
-            summary.query = String(input.query).slice(0, 200);
-        if (input.url)
-            summary.url = String(input.url).slice(0, 500);
-        if (input.pattern)
-            summary.pattern = String(input.pattern).slice(0, 200);
-        if (input.prompt)
-            summary.prompt = String(input.prompt).slice(0, 200);
-        safeFields.tool_input = summary;
-    }
-    // Final size check - drop if serialized data exceeds limit
-    const serialized = JSON.stringify(safeFields);
-    if (serialized.length > MAX_HOOK_DATA_SIZE) {
-        return { tool_name: safeFields.tool_name, _truncated: true };
-    }
-    return safeFields;
-}
-/**
- * Auto-configure Ralph tracker for a session.
- *
- * Priority order:
- * 1. .claude/ralph-loop.local.md (official Ralph Wiggum plugin state)
- * 2. CLAUDE.md <promise> tags (fallback)
- *
- * The ralph-loop.local.md file has priority because it contains
- * the exact configuration from an active Ralph loop session.
- */
-function autoConfigureRalph(session, workingDir, broadcast) {
-    // First, try to read the official Ralph Wiggum plugin state file
-    const ralphConfig = parseRalphLoopConfig(workingDir);
-    if (ralphConfig && ralphConfig.completionPromise) {
-        session.ralphTracker.enable();
-        session.ralphTracker.startLoop(ralphConfig.completionPromise, ralphConfig.maxIterations ?? undefined);
-        // Restore iteration count if available
-        if (ralphConfig.iteration > 0) {
-            // The tracker's cycleCount will be updated when we detect iteration patterns
-            // in the terminal output, but we can set maxIterations now
-            console.log(`[auto-detect] Ralph loop at iteration ${ralphConfig.iteration}/${ralphConfig.maxIterations ?? '∞'}`);
-        }
-        console.log(`[auto-detect] Configured Ralph loop for session ${session.id} from ralph-loop.local.md: ${ralphConfig.completionPromise}`);
-        broadcast('session:ralphLoopUpdate', {
-            sessionId: session.id,
-            state: session.ralphTracker.loopState,
-        });
-        return;
-    }
-    // Fallback: try CLAUDE.md
-    const claudeMdPath = join(workingDir, 'CLAUDE.md');
-    const completionPhrase = extractCompletionPhrase(claudeMdPath);
-    if (completionPhrase) {
-        session.ralphTracker.enable();
-        session.ralphTracker.startLoop(completionPhrase);
-        console.log(`[auto-detect] Configured Ralph loop for session ${session.id} from CLAUDE.md: ${completionPhrase}`);
-        broadcast('session:ralphLoopUpdate', {
-            sessionId: session.id,
-            state: session.ralphTracker.loopState,
-        });
-    }
-}
 /**
  * Get or generate a self-signed TLS certificate for HTTPS.
  * Certs are stored in ~/.codeman/certs/ and reused across restarts.
@@ -248,8 +81,6 @@ function getOrCreateSelfSignedCert() {
     };
 }
 export class WebServer extends EventEmitter {
-    /** Cached CPU count — doesn't change at runtime */
-    static CPU_COUNT = cpus().length;
     app;
     sessions = new Map();
     respawnControllers = new Map();
@@ -277,16 +108,14 @@ export class WebServer extends EventEmitter {
         ttlMs: 5 * 60 * 1000, // 5 minutes - auto-expire stale session timing data
         refreshOnGet: false, // Don't refresh on reads, only on explicit sets
     });
-    // Scheduled runs cleanup timer
-    scheduledCleanupTimer = null;
+    // Centralized cleanup for standalone timers (intervals + resettable timeouts)
+    cleanup = new CleanupManager();
     // SSE event batching
     taskUpdateBatches = new Map();
-    taskUpdateBatchTimer = null;
+    taskUpdateBatchTimerId = null;
     // State update batching (reduce expensive toDetailedState() serialization)
     stateUpdatePending = new Set();
-    stateUpdateTimer = null;
-    // SSE client health check timer
-    sseHealthCheckTimer = null;
+    stateUpdateTimerId = null;
     // Flag to prevent new timers during shutdown
     _isStopping = false;
     // Cached light state for SSE init (avoids rebuilding on every reconnect)
@@ -296,14 +125,13 @@ export class WebServer extends EventEmitter {
     cachedSessionsList = null;
     // Token recording for daily stats (track what's been recorded to avoid double-counting)
     lastRecordedTokens = new Map();
-    tokenRecordingTimer = null;
     // Server startup time for respawn grace period calculation
     serverStartTime = Date.now();
     // Pending respawn start timers (for cleanup on shutdown)
     pendingRespawnStarts = new Map();
     // Active plan orchestrators (for cancellation via API)
     activePlanOrchestrators = new Map();
-    persistDebounceTimers = new Map();
+    persistDeb = new KeyedDebouncer(100);
     // Grace period before starting restored respawn controllers (2 minutes)
     static RESPAWN_RESTORE_GRACE_PERIOD_MS = 2 * 60 * 1000;
     // Stored listener handlers for cleanup
@@ -312,6 +140,7 @@ export class WebServer extends EventEmitter {
     tunnelManager = new TunnelManager();
     authSessions = null;
     authFailures = null;
+    qrAuthFailures = null;
     pushStore = new PushSubscriptionStore();
     teamWatcher = new TeamWatcher();
     teamWatcherHandlers = null;
@@ -324,3562 +153,320 @@ export class WebServer extends EventEmitter {
         if (https) {
             const { key, cert } = getOrCreateSelfSignedCert();
             this.app = Fastify({ logger: false, https: { key, cert } });
-        }
-        else {
-            this.app = Fastify({ logger: false });
-        }
-        this.mux = createMultiplexer();
-        // Set up mux event listeners
-        this.mux.on('sessionCreated', (session) => {
-            this.broadcast('mux:created', session);
-        });
-        this.mux.on('sessionKilled', (data) => {
-            this.broadcast('mux:killed', data);
-        });
-        this.mux.on('sessionDied', (data) => {
-            getLifecycleLog().log({
-                event: 'mux_died',
-                sessionId: data.sessionId || 'unknown',
-                extra: data,
-            });
-            this.broadcast('mux:died', data);
-        });
-        this.mux.on('statsUpdated', (sessions) => {
-            this.broadcast('mux:statsUpdated', sessions);
-        });
-        // Set up subagent watcher listeners
-        this.setupSubagentWatcherListeners();
-        // Set up image watcher listeners
-        this.setupImageWatcherListeners();
-        // Set up team watcher listeners
-        this.setupTeamWatcherListeners();
-        // Set up tunnel manager listeners
-        this.tunnelManager.on('started', (data) => {
-            this.broadcast('tunnel:started', data);
-        });
-        this.tunnelManager.on('stopped', () => {
-            this.broadcast('tunnel:stopped', {});
-        });
-        this.tunnelManager.on('error', (message) => {
-            this.broadcast('tunnel:error', { message });
-        });
-        this.tunnelManager.on('progress', (data) => {
-            this.broadcast('tunnel:progress', data);
-        });
-    }
-    /**
-     * Set up event listeners for subagent watcher.
-     * Broadcasts real-time subagent activity to SSE clients.
-     *
-     * The SubagentWatcher now extracts descriptions directly from the parent session's
-     * transcript, which contains the exact Task tool call with the description parameter.
-     * This is more reliable than the previous timing-based correlation approach.
-     */
-    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),
-            error: (error, agentId) => {
-                console.error(`[SubagentWatcher] Error${agentId ? ` for ${agentId}` : ''}:`, error.message);
-            },
-        };
-        subagentWatcher.on('subagent:discovered', this.subagentWatcherHandlers.discovered);
-        subagentWatcher.on('subagent:updated', this.subagentWatcherHandlers.updated);
-        subagentWatcher.on('subagent:tool_call', this.subagentWatcherHandlers.toolCall);
-        subagentWatcher.on('subagent:tool_result', this.subagentWatcherHandlers.toolResult);
-        subagentWatcher.on('subagent:progress', this.subagentWatcherHandlers.progress);
-        subagentWatcher.on('subagent:message', this.subagentWatcherHandlers.message);
-        subagentWatcher.on('subagent:completed', this.subagentWatcherHandlers.completed);
-        subagentWatcher.on('subagent:error', this.subagentWatcherHandlers.error);
-    }
-    /**
-     * Clean up subagent watcher listeners to prevent memory leaks.
-     */
-    cleanupSubagentWatcherListeners() {
-        if (this.subagentWatcherHandlers) {
-            subagentWatcher.off('subagent:discovered', this.subagentWatcherHandlers.discovered);
-            subagentWatcher.off('subagent:updated', this.subagentWatcherHandlers.updated);
-            subagentWatcher.off('subagent:tool_call', this.subagentWatcherHandlers.toolCall);
-            subagentWatcher.off('subagent:tool_result', this.subagentWatcherHandlers.toolResult);
-            subagentWatcher.off('subagent:progress', this.subagentWatcherHandlers.progress);
-            subagentWatcher.off('subagent:message', this.subagentWatcherHandlers.message);
-            subagentWatcher.off('subagent:completed', this.subagentWatcherHandlers.completed);
-            subagentWatcher.off('subagent:error', this.subagentWatcherHandlers.error);
-            this.subagentWatcherHandlers = null;
-        }
-    }
-    /**
-     * Set up event listeners for image watcher.
-     * Broadcasts image detection events to SSE clients for auto-popup.
-     */
-    setupImageWatcherListeners() {
-        // Store handlers for cleanup on shutdown
-        this.imageWatcherHandlers = {
-            detected: (event) => this.broadcast('image:detected', event),
-            error: (error, sessionId) => {
-                console.error(`[ImageWatcher] Error${sessionId ? ` for ${sessionId}` : ''}:`, error.message);
-            },
-        };
-        imageWatcher.on('image:detected', this.imageWatcherHandlers.detected);
-        imageWatcher.on('image:error', this.imageWatcherHandlers.error);
-    }
-    /**
-     * Clean up image watcher listeners to prevent memory leaks.
-     */
-    cleanupImageWatcherListeners() {
-        if (this.imageWatcherHandlers) {
-            imageWatcher.off('image:detected', this.imageWatcherHandlers.detected);
-            imageWatcher.off('image:error', this.imageWatcherHandlers.error);
-            this.imageWatcherHandlers = null;
-        }
-    }
-    /**
-     * Set up event listeners for team watcher.
-     * Broadcasts team activity events to SSE clients.
-     */
-    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),
-        };
-        this.teamWatcher.on('teamCreated', this.teamWatcherHandlers.teamCreated);
-        this.teamWatcher.on('teamUpdated', this.teamWatcherHandlers.teamUpdated);
-        this.teamWatcher.on('teamRemoved', this.teamWatcherHandlers.teamRemoved);
-        this.teamWatcher.on('taskUpdated', this.teamWatcherHandlers.taskUpdated);
-    }
-    /**
-     * Clean up team watcher listeners to prevent memory leaks.
-     */
-    cleanupTeamWatcherListeners() {
-        if (this.teamWatcherHandlers) {
-            this.teamWatcher.off('teamCreated', this.teamWatcherHandlers.teamCreated);
-            this.teamWatcher.off('teamUpdated', this.teamWatcherHandlers.teamUpdated);
-            this.teamWatcher.off('teamRemoved', this.teamWatcherHandlers.teamRemoved);
-            this.teamWatcher.off('taskUpdated', this.teamWatcherHandlers.taskUpdated);
-            this.teamWatcherHandlers = null;
-        }
-    }
-    async setupRoutes() {
-        // Allow multipart/form-data for screenshot uploads — skip Fastify's body parser
-        // so the route handler can read the raw stream directly.
-        this.app.addContentTypeParser('multipart/form-data', (_req, _payload, done) => {
-            done(null);
-        });
-        // Enable gzip/brotli compression for all responses.
-        // Massive win: 793KB uncompressed → ~120KB compressed for static assets.
-        // Threshold 1024 = don't compress tiny responses (headers > savings).
-        await this.app.register(fastifyCompress, {
-            threshold: 1024,
-        });
-        // Cookie plugin (needed for auth session tokens)
-        await this.app.register(fastifyCookie);
-        // Optional HTTP Basic Auth with session cookies and rate limiting
-        const authPassword = process.env.CODEMAN_PASSWORD;
-        if (authPassword) {
-            const authUsername = process.env.CODEMAN_USERNAME || 'admin';
-            const expectedHeader = 'Basic ' + Buffer.from(`${authUsername}:${authPassword}`).toString('base64');
-            // Session token store — active sessions extend TTL on access
-            this.authSessions = new StaleExpirationMap({
-                ttlMs: AUTH_SESSION_TTL_MS,
-                refreshOnGet: true,
-            });
-            // Failure counter per IP — decay naturally after 15 minutes
-            this.authFailures = new StaleExpirationMap({
-                ttlMs: AUTH_FAILURE_WINDOW_MS,
-                refreshOnGet: false,
-            });
-            this.app.addHook('onRequest', (req, reply, done) => {
-                // Hook events come from local Claude Code hooks (curl from localhost) — no auth headers available.
-                // Safe: validated by HookEventSchema, only triggers broadcasts.
-                // Security: restrict bypass to localhost only — prevents forged hook events via tunnel/LAN.
-                if (req.url === '/api/hook-event' && req.method === 'POST') {
-                    const ip = req.ip;
-                    if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') {
-                        done();
-                        return;
-                    }
-                    // Non-localhost hook requests fall through to normal auth
-                }
-                const clientIp = req.ip;
-                // Rate limit: reject if too many failed attempts from this IP
-                const failures = this.authFailures.get(clientIp) ?? 0;
-                if (failures >= AUTH_FAILURE_MAX) {
-                    reply.code(429).send('Too Many Requests — try again later');
-                    return;
-                }
-                // Check session cookie first (avoids re-sending credentials on every request)
-                // Use get() instead of has() so refreshOnGet extends the TTL on active sessions
-                const sessionToken = req.cookies[AUTH_COOKIE_NAME];
-                if (sessionToken && this.authSessions.get(sessionToken) !== undefined) {
-                    done();
-                    return;
-                }
-                // Check Basic Auth header (timing-safe comparison to prevent side-channel attacks)
-                const auth = req.headers.authorization;
-                const authBuf = Buffer.from(auth ?? '');
-                const expectedBuf = Buffer.from(expectedHeader);
-                if (authBuf.length === expectedBuf.length && timingSafeEqual(authBuf, expectedBuf)) {
-                    // Issue session token cookie so browser doesn't need to re-send credentials
-                    const token = randomBytes(32).toString('hex');
-                    // Evict oldest if at capacity (prevent unbounded growth)
-                    if (this.authSessions.size >= MAX_AUTH_SESSIONS) {
-                        const oldestKey = this.authSessions.keys().next().value;
-                        if (oldestKey !== undefined)
-                            this.authSessions.delete(oldestKey);
-                    }
-                    this.authSessions.set(token, clientIp);
-                    // Reset failure count on successful auth
-                    this.authFailures.delete(clientIp);
-                    reply.setCookie(AUTH_COOKIE_NAME, token, {
-                        httpOnly: true,
-                        secure: this.https,
-                        sameSite: 'lax',
-                        maxAge: AUTH_SESSION_TTL_MS / 1000, // seconds
-                        path: '/',
-                    });
-                    done();
-                    return;
-                }
-                // Auth failed — track failure count
-                this.authFailures.set(clientIp, failures + 1);
-                reply.header('WWW-Authenticate', 'Basic realm="Codeman"');
-                reply.code(401).send('Unauthorized');
-            });
-        }
-        // Security headers + CORS on every response
-        this.app.addHook('onRequest', (req, reply, done) => {
-            reply.header('X-Content-Type-Options', 'nosniff');
-            reply.header('X-Frame-Options', 'SAMEORIGIN');
-            reply.header('Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: blob:; connect-src 'self' wss://api.deepgram.com; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'");
-            if (this.https) {
-                reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
-            }
-            // CORS: restrict to same-origin (localhost) only
-            const origin = req.headers.origin;
-            if (origin) {
-                try {
-                    const url = new URL(origin);
-                    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '::1') {
-                        reply.header('Access-Control-Allow-Origin', origin);
-                        reply.header('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-                        reply.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-                        reply.header('Access-Control-Max-Age', '86400');
-                    }
-                }
-                catch {
-                    // Invalid origin header — do not set CORS headers
-                }
-            }
-            // Handle CORS preflight
-            if (req.method === 'OPTIONS') {
-                reply.code(204).send();
-                done();
-                return;
-            }
-            done();
-        });
-        // Service worker must never be cached — browsers check for SW updates on navigation
-        this.app.get('/sw.js', async (_req, reply) => {
-            return reply
-                .header('Cache-Control', 'no-cache, no-store')
-                .header('Service-Worker-Allowed', '/')
-                .type('application/javascript')
-                .sendFile('sw.js', join(__dirname, 'public'));
-        });
-        // Serve static files — versioned assets (?v=X) are immutable, cache aggressively
-        // preCompressed: serve pre-built .br/.gz files (from build step) to avoid per-request CPU compression
-        await this.app.register(fastifyStatic, {
-            root: join(__dirname, 'public'),
-            prefix: '/',
-            maxAge: '1y',
-            immutable: true,
-            preCompressed: true,
-        });
-        // SSE endpoint for real-time updates
-        this.app.get('/api/events', (req, reply) => {
-            // Enforce SSE client limit to prevent memory exhaustion from too many connections
-            if (this.sseClients.size >= MAX_SSE_CLIENTS) {
-                reply.code(503).send('Too many SSE connections');
-                return;
-            }
-            reply.raw.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive',
-                'X-Accel-Buffering': 'no', // Disable nginx buffering
-            });
-            this.sseClients.add(reply);
-            // 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());
-            req.raw.on('close', () => {
-                this.sseClients.delete(reply);
-                this.backpressuredClients.delete(reply);
-            });
-        });
-        // API Routes
-        // Logout: invalidate session cookie
-        this.app.post('/api/logout', async (req, reply) => {
-            const sessionToken = req.cookies[AUTH_COOKIE_NAME];
-            if (sessionToken && this.authSessions) {
-                this.authSessions.delete(sessionToken);
-            }
-            reply.clearCookie(AUTH_COOKIE_NAME, { path: '/' });
-            return { success: true };
-        });
-        this.app.get('/api/status', async () => this.getLightState());
-        this.app.get('/api/tunnel/status', async () => this.tunnelManager.getStatus());
-        this.app.get('/api/tunnel/qr', async (_req, reply) => {
-            const url = this.tunnelManager.getUrl();
-            if (!url) {
-                return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Tunnel not running'));
-            }
-            try {
-                const QRCode = require('qrcode');
-                const svg = await QRCode.toString(url, { type: 'svg', margin: 2, width: 256 });
-                // Return as data URI to avoid Fastify compress issues with SVG content-type
-                return { svg };
-            }
-            catch (err) {
-                return reply.code(500).send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err)));
-            }
-        });
-        // OpenCode CLI availability check
-        this.app.get('/api/opencode/status', async () => {
-            const { isOpenCodeAvailable, resolveOpenCodeDir } = await import('../utils/opencode-cli-resolver.js');
-            return {
-                available: isOpenCodeAvailable(),
-                path: resolveOpenCodeDir(),
-            };
-        });
-        // Cleanup stale sessions from state file
-        this.app.post('/api/cleanup-state', async () => {
-            const cleaned = this.cleanupStaleSessions();
-            return { success: true, cleanedSessions: cleaned };
-        });
-        // Session lifecycle audit log
-        this.app.get('/api/session-lifecycle', async (req) => {
-            const query = req.query;
-            const lifecycleLog = getLifecycleLog();
-            const entries = await lifecycleLog.query({
-                sessionId: query.sessionId,
-                event: query.event,
-                since: query.since ? Number(query.since) : undefined,
-                limit: query.limit ? Math.min(Number(query.limit), 1000) : 200,
-            });
-            return { success: true, entries };
-        });
-        // Global stats endpoint
-        this.app.get('/api/stats', async () => {
-            const activeSessionTokens = {};
-            for (const [sessionId, session] of this.sessions) {
-                activeSessionTokens[sessionId] = {
-                    inputTokens: session.inputTokens,
-                    outputTokens: session.outputTokens,
-                    totalCost: session.totalCost,
-                };
-            }
-            return {
-                success: true,
-                stats: this.store.getAggregateStats(activeSessionTokens),
-                raw: this.store.getGlobalStats(),
-            };
-        });
-        // Token stats with daily history
-        this.app.get('/api/token-stats', async () => {
-            // Get aggregate totals (global + active sessions)
-            const activeSessionTokens = {};
-            for (const [sessionId, session] of this.sessions) {
-                activeSessionTokens[sessionId] = {
-                    inputTokens: session.inputTokens,
-                    outputTokens: session.outputTokens,
-                    totalCost: session.totalCost,
-                };
-            }
-            return {
-                success: true,
-                daily: this.store.getDailyStats(30),
-                totals: this.store.getAggregateStats(activeSessionTokens),
-            };
-        });
-        this.app.get('/api/config', async () => {
-            return { success: true, config: this.store.getConfig() };
-        });
-        this.app.put('/api/config', async (req) => {
-            // Validate request body against schema to prevent arbitrary config injection
-            const parseResult = ConfigUpdateSchema.safeParse(req.body);
-            if (!parseResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Invalid config: ${parseResult.error.message}`);
-            }
-            this.store.setConfig(parseResult.data);
-            return { success: true, config: this.store.getConfig() };
-        });
-        // Debug/monitoring endpoint - lightweight, only runs when called
-        // Returns comprehensive memory metrics for debugging memory leaks
-        this.app.get('/api/debug/memory', async () => {
-            const mem = process.memoryUsage();
-            const subagentStats = subagentWatcher.getStats();
-            // Calculate total Map entries for memory estimation
-            const serverMapSizes = {
-                sessions: this.sessions.size,
-                sseClients: this.sseClients.size,
-                respawnControllers: this.respawnControllers.size,
-                runSummaryTrackers: this.runSummaryTrackers.size,
-                transcriptWatchers: this.transcriptWatchers.size,
-                scheduledRuns: this.scheduledRuns.size,
-                terminalBatches: this.terminalBatches.size,
-                taskUpdateBatches: this.taskUpdateBatches.size,
-                stateUpdatePending: this.stateUpdatePending.size,
-                lastRecordedTokens: this.lastRecordedTokens.size,
-                pendingRespawnStarts: this.pendingRespawnStarts.size,
-                respawnTimers: this.respawnTimers.size,
-                activePlanOrchestrators: this.activePlanOrchestrators.size,
-                cleaningUp: this.cleaningUp.size,
-            };
-            const totalServerMapEntries = Object.values(serverMapSizes).reduce((a, b) => a + b, 0);
-            const totalSubagentMapEntries = Object.values(subagentStats).reduce((a, b) => a + b, 0);
-            return {
-                memory: {
-                    rss: mem.rss,
-                    rssMB: Math.round((mem.rss / 1024 / 1024) * 10) / 10,
-                    heapUsed: mem.heapUsed,
-                    heapUsedMB: Math.round((mem.heapUsed / 1024 / 1024) * 10) / 10,
-                    heapTotal: mem.heapTotal,
-                    heapTotalMB: Math.round((mem.heapTotal / 1024 / 1024) * 10) / 10,
-                    external: mem.external,
-                    externalMB: Math.round((mem.external / 1024 / 1024) * 10) / 10,
-                    arrayBuffers: mem.arrayBuffers,
-                    arrayBuffersMB: Math.round((mem.arrayBuffers / 1024 / 1024) * 10) / 10,
-                },
-                mapSizes: {
-                    server: serverMapSizes,
-                    subagentWatcher: subagentStats,
-                    totals: {
-                        serverEntries: totalServerMapEntries,
-                        subagentEntries: totalSubagentMapEntries,
-                        allEntries: totalServerMapEntries + totalSubagentMapEntries,
-                    },
-                },
-                watchers: {
-                    fileDebouncers: subagentStats.fileDebouncerCount,
-                    dirWatchers: subagentStats.dirWatcherCount,
-                    transcriptWatchers: this.transcriptWatchers.size,
-                    total: subagentStats.fileDebouncerCount + subagentStats.dirWatcherCount + this.transcriptWatchers.size,
-                },
-                timers: {
-                    respawnTimers: this.respawnTimers.size,
-                    pendingRespawnStarts: this.pendingRespawnStarts.size,
-                    subagentIdleTimers: subagentStats.idleTimerCount,
-                    total: this.respawnTimers.size + this.pendingRespawnStarts.size + subagentStats.idleTimerCount,
-                },
-                uptime: {
-                    seconds: Math.round(process.uptime()),
-                    formatted: formatUptime(process.uptime()),
-                },
-                timestamp: Date.now(),
-            };
-        });
-        // Session management
-        this.app.get('/api/sessions', async () => this.getLightSessionsState());
-        this.app.post('/api/sessions', async (req) => {
-            // Prevent unbounded session creation
-            if (this.sessions.size >= MAX_CONCURRENT_SESSIONS) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached. Delete some sessions first.`);
-            }
-            const result = CreateSessionSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const body = result.data;
-            const workingDir = body.workingDir || process.cwd();
-            // Validate workingDir exists and is a directory
-            if (body.workingDir) {
-                try {
-                    const stat = statSync(workingDir);
-                    if (!stat.isDirectory()) {
-                        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory');
-                    }
-                }
-                catch {
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist');
-                }
-            }
-            // Write env overrides to .claude/settings.local.json if provided
-            if (body.envOverrides && Object.keys(body.envOverrides).length > 0) {
-                await updateCaseEnvVars(workingDir, body.envOverrides);
-            }
-            // Check OpenCode availability if requested
-            if (body.mode === 'opencode') {
-                const { isOpenCodeAvailable } = await import('../utils/opencode-cli-resolver.js');
-                if (!isOpenCodeAvailable()) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
-                }
-            }
-            const globalNice = await this.getGlobalNiceConfig();
-            const modelConfig = await this.getModelConfig();
-            const mode = body.mode || 'claude';
-            const model = mode === 'opencode' ? body.openCodeConfig?.model : mode !== 'shell' ? modelConfig?.defaultModel : undefined;
-            const claudeModeConfig = await this.getClaudeModeConfig();
-            const session = new Session({
-                workingDir,
-                mode,
-                name: body.name || '',
-                mux: this.mux,
-                useMux: true,
-                niceConfig: globalNice,
-                model,
-                claudeMode: claudeModeConfig.claudeMode,
-                allowedTools: claudeModeConfig.allowedTools,
-                openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
-            });
-            this.sessions.set(session.id, session);
-            this.store.incrementSessionsCreated();
-            this.persistSessionState(session);
-            await this.setupSessionListeners(session);
-            getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name });
-            // Use light state for broadcast + response — buffers are fetched on-demand via /terminal.
-            // Avoids serializing 2-3MB of terminal+text buffers per session creation.
-            const lightState = this.getSessionStateWithRespawn(session);
-            this.broadcast('session:created', lightState);
-            return { success: true, session: lightState };
-        });
-        // Rename a session
-        this.app.put('/api/sessions/:id/name', async (req) => {
-            const { id } = req.params;
-            const result = SessionNameSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = result.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const name = String(body.name || '').slice(0, MAX_SESSION_NAME_LENGTH);
-            session.name = name;
-            // Also update the mux session name if applicable
-            this.mux.updateSessionName(id, session.name);
-            this.persistSessionState(session);
-            this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
-            return { success: true, name: session.name };
-        });
-        // Set session color
-        this.app.put('/api/sessions/:id/color', async (req) => {
-            const { id } = req.params;
-            const result = SessionColorSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = result.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const validColors = ['default', 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink'];
-            if (!validColors.includes(body.color)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid color');
-            }
-            session.setColor(body.color);
-            this.persistSessionState(session);
-            this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
-            return { success: true, color: session.color };
-        });
-        this.app.delete('/api/sessions/:id', async (req) => {
-            const { id } = req.params;
-            const query = req.query;
-            const killMux = query.killMux !== 'false'; // Default to true
-            if (!this.sessions.has(id)) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            await this.cleanupSession(id, killMux, 'user_delete');
-            return { success: true };
-        });
-        // Kill all sessions at once
-        this.app.delete('/api/sessions', async () => {
-            const sessionIds = Array.from(this.sessions.keys());
-            let killed = 0;
-            for (const id of sessionIds) {
-                if (this.sessions.has(id)) {
-                    await this.cleanupSession(id, true, 'user_bulk_delete');
-                    killed++;
-                }
-            }
-            return { success: true, data: { killed } };
-        });
-        this.app.get('/api/sessions/:id', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Use light state (no full buffers) — terminal buffer available via /terminal endpoint.
-            // Full buffers were 2-3MB and caused slowness when polled frequently (e.g. Ralph wizard).
-            return this.getSessionStateWithRespawn(session);
-        });
-        this.app.get('/api/sessions/:id/output', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            return {
-                success: true,
-                data: {
-                    textOutput: session.textOutput,
-                    messages: session.messages,
-                    errorBuffer: session.errorBuffer,
-                },
-            };
-        });
-        // Get Ralph state (Ralph loop + todos) for a session
-        this.app.get('/api/sessions/:id/ralph-state', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            return {
-                success: true,
-                data: {
-                    loop: session.ralphLoopState,
-                    todos: session.ralphTodos,
-                    todoStats: session.ralphTodoStats,
-                },
-            };
-        });
-        // Get run summary for a session (what happened while you were away)
-        this.app.get('/api/sessions/:id/run-summary', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = this.runSummaryTrackers.get(id);
-            if (!tracker) {
-                // Create a fresh tracker if one doesn't exist (shouldn't happen normally)
-                const newTracker = new RunSummaryTracker(id, session.name);
-                this.runSummaryTrackers.set(id, newTracker);
-                return { success: true, summary: newTracker.getSummary() };
-            }
-            // Update session name in case it changed
-            tracker.setSessionName(session.name);
-            return { success: true, summary: tracker.getSummary() };
-        });
-        // Get active Bash tools for a session (file-viewing commands)
-        this.app.get('/api/sessions/:id/active-tools', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            return {
-                success: true,
-                data: {
-                    tools: session.activeTools,
-                },
-            };
-        });
-        // Get file tree for session's working directory (File Browser)
-        this.app.get('/api/sessions/:id/files', async (req) => {
-            const { id } = req.params;
-            const { depth, showHidden } = req.query;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const maxDepth = Math.min(parseInt(depth || '5', 10), 10);
-            const includeHidden = showHidden === 'true';
-            const workingDir = session.workingDir;
-            // Default excludes - large/generated directories
-            const excludeDirs = new Set([
-                '.git',
-                'node_modules',
-                'dist',
-                'build',
-                '__pycache__',
-                '.cache',
-                '.next',
-                '.nuxt',
-                'coverage',
-                '.venv',
-                'venv',
-                '.tox',
-                'target',
-                'vendor',
-            ]);
-            let totalFiles = 0;
-            let totalDirectories = 0;
-            let truncated = false;
-            const maxFiles = 5000;
-            const scanDirectory = async (dirPath, currentDepth) => {
-                if (currentDepth > maxDepth || totalFiles + totalDirectories > maxFiles) {
-                    truncated = true;
-                    return [];
-                }
-                try {
-                    const entries = await fs.readdir(dirPath, { withFileTypes: true });
-                    const nodes = [];
-                    // Sort: directories first, then alphabetically
-                    entries.sort((a, b) => {
-                        if (a.isDirectory() && !b.isDirectory())
-                            return -1;
-                        if (!a.isDirectory() && b.isDirectory())
-                            return 1;
-                        return a.name.localeCompare(b.name);
-                    });
-                    for (const entry of entries) {
-                        if (totalFiles + totalDirectories > maxFiles) {
-                            truncated = true;
-                            break;
-                        }
-                        // Skip hidden files unless requested
-                        if (!includeHidden && entry.name.startsWith('.'))
-                            continue;
-                        // Skip excluded directories
-                        if (entry.isDirectory() && excludeDirs.has(entry.name))
-                            continue;
-                        const fullPath = join(dirPath, entry.name);
-                        const relativePath = fullPath.slice(workingDir.length + 1);
-                        if (entry.isDirectory()) {
-                            totalDirectories++;
-                            const children = await scanDirectory(fullPath, currentDepth + 1);
-                            nodes.push({
-                                name: entry.name,
-                                path: relativePath,
-                                type: 'directory',
-                                children,
-                            });
-                        }
-                        else {
-                            totalFiles++;
-                            const ext = entry.name.includes('.') ? entry.name.split('.').pop()?.toLowerCase() : undefined;
-                            let size;
-                            try {
-                                const stat = await fs.stat(fullPath);
-                                size = stat.size;
-                            }
-                            catch {
-                                // Skip if can't stat
-                            }
-                            nodes.push({
-                                name: entry.name,
-                                path: relativePath,
-                                type: 'file',
-                                size,
-                                extension: ext,
-                            });
-                        }
-                    }
-                    return nodes;
-                }
-                catch (err) {
-                    // Can't read directory (permission denied, etc.)
-                    return [];
-                }
-            };
-            const tree = await scanDirectory(workingDir, 1);
-            return {
-                success: true,
-                data: {
-                    root: workingDir,
-                    tree,
-                    totalFiles,
-                    totalDirectories,
-                    truncated,
-                },
-            };
-        });
-        // Get file content for preview (File Browser)
-        this.app.get('/api/sessions/:id/file-content', async (req) => {
-            const { id } = req.params;
-            const { path: filePath, lines, raw } = req.query;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (!filePath) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing path parameter');
-            }
-            // Validate path is within working directory (security: resolve symlinks to prevent traversal)
-            const fullPath = resolve(session.workingDir, filePath);
-            let resolvedPath;
-            try {
-                resolvedPath = realpathSync(fullPath);
-            }
-            catch {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found');
-            }
-            const relativePath = relative(session.workingDir, resolvedPath);
-            if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory');
-            }
-            try {
-                const stat = await fs.stat(resolvedPath);
-                // Check if it's a binary/media file
-                const ext = filePath.split('.').pop()?.toLowerCase() || '';
-                const binaryExts = new Set([
-                    'png',
-                    'jpg',
-                    'jpeg',
-                    'gif',
-                    'webp',
-                    'ico',
-                    'svg',
-                    'bmp',
-                    'mp4',
-                    'webm',
-                    'mov',
-                    'avi',
-                    'mp3',
-                    'wav',
-                    'ogg',
-                    'pdf',
-                    'zip',
-                    'tar',
-                    'gz',
-                    'exe',
-                    'dll',
-                    'so',
-                    'woff',
-                    'woff2',
-                    'ttf',
-                    'eot',
-                ]);
-                const imageExts = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico']);
-                const videoExts = new Set(['mp4', 'webm', 'mov', 'avi']);
-                if (raw === 'true' || binaryExts.has(ext)) {
-                    // Return metadata for binary files
-                    return {
-                        success: true,
-                        data: {
-                            path: filePath,
-                            size: stat.size,
-                            type: imageExts.has(ext) ? 'image' : videoExts.has(ext) ? 'video' : 'binary',
-                            extension: ext,
-                            url: `/api/sessions/${id}/file-raw?path=${encodeURIComponent(filePath)}`,
-                        },
-                    };
-                }
-                // Validate file size before reading (DoS protection - prevent memory exhaustion)
-                const MAX_TEXT_FILE_SIZE = 10 * 1024 * 1024; // 10MB
-                if (stat.size > MAX_TEXT_FILE_SIZE) {
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, `File too large (${Math.round(stat.size / 1024 / 1024)}MB > ${MAX_TEXT_FILE_SIZE / 1024 / 1024}MB limit)`);
-                }
-                // Read text file with line limit (bounded to prevent DoS)
-                const MAX_LINES_LIMIT = 10000;
-                const maxLines = Math.min(parseInt(lines || '500', 10) || 500, MAX_LINES_LIMIT);
-                const content = await fs.readFile(resolvedPath, 'utf-8');
-                const allLines = content.split('\n');
-                const truncatedContent = allLines.length > maxLines;
-                const displayContent = truncatedContent ? allLines.slice(0, maxLines).join('\n') : content;
-                return {
-                    success: true,
-                    data: {
-                        path: filePath,
-                        content: displayContent,
-                        size: stat.size,
-                        totalLines: allLines.length,
-                        truncated: truncatedContent,
-                        extension: ext,
-                    },
-                };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${getErrorMessage(err)}`);
-            }
-        });
-        // Serve raw file content (for images/binary files)
-        this.app.get('/api/sessions/:id/file-raw', async (req, reply) => {
-            const { id } = req.params;
-            const { path: filePath } = req.query;
-            const session = this.sessions.get(id);
-            if (!session) {
-                reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found'));
-                return;
-            }
-            if (!filePath) {
-                reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing path parameter'));
-                return;
-            }
-            // Validate path is within working directory (security: resolve symlinks to prevent traversal)
-            const fullPath = resolve(session.workingDir, filePath);
-            let resolvedPath;
-            try {
-                resolvedPath = realpathSync(fullPath);
-            }
-            catch {
-                reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
-                return;
-            }
-            const relativePath = relative(session.workingDir, resolvedPath);
-            if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
-                reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory'));
-                return;
-            }
-            try {
-                // Validate file size before reading (DoS protection - prevent memory exhaustion)
-                const MAX_RAW_FILE_SIZE = 50 * 1024 * 1024; // 50MB for raw files
-                const stat = await fs.stat(resolvedPath);
-                if (stat.size > MAX_RAW_FILE_SIZE) {
-                    reply
-                        .code(400)
-                        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, `File too large (${Math.round(stat.size / 1024 / 1024)}MB > ${MAX_RAW_FILE_SIZE / 1024 / 1024}MB limit)`));
-                    return;
-                }
-                const ext = filePath.split('.').pop()?.toLowerCase() || '';
-                const mimeTypes = {
-                    png: 'image/png',
-                    jpg: 'image/jpeg',
-                    jpeg: 'image/jpeg',
-                    gif: 'image/gif',
-                    webp: 'image/webp',
-                    svg: 'image/svg+xml',
-                    ico: 'image/x-icon',
-                    bmp: 'image/bmp',
-                    mp4: 'video/mp4',
-                    webm: 'video/webm',
-                    mov: 'video/quicktime',
-                    mp3: 'audio/mpeg',
-                    wav: 'audio/wav',
-                    ogg: 'audio/ogg',
-                    pdf: 'application/pdf',
-                    json: 'application/json',
-                };
-                const content = await fs.readFile(resolvedPath);
-                reply.header('Content-Type', mimeTypes[ext] || 'application/octet-stream');
-                reply.send(content);
-            }
-            catch (err) {
-                reply
-                    .code(500)
-                    .send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${getErrorMessage(err)}`));
-            }
-        });
-        // Stream file content via tail -f (SSE endpoint)
-        this.app.get('/api/sessions/:id/tail-file', async (req, reply) => {
-            const { id } = req.params;
-            const { path: filePath, lines } = req.query;
-            const session = this.sessions.get(id);
-            if (!session) {
-                reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found'));
-                return;
-            }
-            if (!filePath) {
-                reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing path parameter'));
-                return;
-            }
-            // Set up SSE headers
-            reply.raw.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive',
-                'X-Accel-Buffering': 'no',
-            });
-            // Track stream for cleanup
-            const streamRef = {};
-            // Create the file stream
-            const result = await fileStreamManager.createStream({
-                sessionId: id,
-                filePath,
-                workingDir: session.workingDir,
-                lines: lines ? parseInt(lines, 10) : undefined,
-                onData: (data) => {
-                    // Send data as SSE event
-                    reply.raw.write(`data: ${JSON.stringify({ type: 'data', content: data })}\n\n`);
-                },
-                onEnd: () => {
-                    reply.raw.write(`data: ${JSON.stringify({ type: 'end' })}\n\n`);
-                    reply.raw.end();
-                },
-                onError: (error) => {
-                    reply.raw.write(`data: ${JSON.stringify({ type: 'error', error })}\n\n`);
-                },
-            });
-            if (!result.success) {
-                reply.raw.write(`data: ${JSON.stringify({ type: 'error', error: result.error })}\n\n`);
-                reply.raw.end();
-                return;
-            }
-            streamRef.id = result.streamId;
-            // Notify client of successful connection
-            reply.raw.write(`data: ${JSON.stringify({ type: 'connected', streamId: result.streamId, filePath })}\n\n`);
-            // Handle client disconnect
-            req.raw.on('close', () => {
-                if (streamRef.id) {
-                    fileStreamManager.closeStream(streamRef.id);
-                }
-            });
-        });
-        // Close a file stream
-        this.app.delete('/api/sessions/:id/tail-file/:streamId', async (req) => {
-            const { id, streamId } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const closed = fileStreamManager.closeStream(streamId);
-            return { success: closed };
-        });
-        // Configure Ralph (Ralph Wiggum) settings
-        this.app.post('/api/sessions/:id/ralph-config', async (req) => {
-            const { id } = req.params;
-            const ralphResult = RalphConfigSchema.safeParse(req.body);
-            if (!ralphResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { enabled, completionPhrase, maxIterations, reset, disableAutoEnable } = ralphResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Ralph tracker is not supported for opencode sessions
-            if (session.mode === 'opencode') {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Ralph tracker is not supported for opencode sessions');
-            }
-            // Handle reset first (before other config)
-            if (reset) {
-                if (reset === 'full') {
-                    session.ralphTracker.fullReset();
-                }
-                else {
-                    session.ralphTracker.reset();
-                }
-            }
-            // Configure auto-enable behavior
-            if (disableAutoEnable !== undefined) {
-                if (disableAutoEnable) {
-                    session.ralphTracker.disableAutoEnable();
-                }
-                else {
-                    session.ralphTracker.enableAutoEnable();
-                }
-            }
-            // Enable/disable the tracker
-            if (enabled !== undefined) {
-                if (enabled) {
-                    session.ralphTracker.enable();
-                    // Allow re-enabling on restart if user explicitly enabled
-                    session.ralphTracker.enableAutoEnable();
-                }
-                else {
-                    session.ralphTracker.disable();
-                    // Prevent re-enabling on restart when user explicitly disabled
-                    session.ralphTracker.disableAutoEnable();
-                }
-                // Persist Ralph enabled state
-                this.mux.updateRalphEnabled(id, enabled);
-            }
-            // Configure the Ralph tracker
-            if (completionPhrase !== undefined) {
-                // Start loop with completion phrase to set it up for watching
-                if (completionPhrase) {
-                    session.ralphTracker.startLoop(completionPhrase, maxIterations || undefined);
-                }
-            }
-            if (maxIterations !== undefined) {
-                session.ralphTracker.setMaxIterations(maxIterations || null);
-            }
-            // Persist and broadcast the update
-            this.persistSessionState(session);
-            this.broadcast('session:ralphLoopUpdate', {
-                sessionId: id,
-                state: session.ralphLoopState,
-            });
-            return { success: true };
-        });
-        // Reset circuit breaker for Ralph tracker
-        this.app.post('/api/sessions/:id/ralph-circuit-breaker/reset', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            session.ralphTracker.resetCircuitBreaker();
-            return { success: true };
-        });
-        // Get Ralph status block and circuit breaker state
-        this.app.get('/api/sessions/:id/ralph-status', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            return {
-                success: true,
-                data: {
-                    lastStatusBlock: session.ralphTracker.lastStatusBlock,
-                    circuitBreaker: session.ralphTracker.circuitBreakerStatus,
-                    cumulativeStats: session.ralphTracker.cumulativeStats,
-                    exitGateMet: session.ralphTracker.exitGateMet,
-                },
-            };
-        });
-        // Generate @fix_plan.md content from todos
-        this.app.get('/api/sessions/:id/fix-plan', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const content = session.ralphTracker.generateFixPlanMarkdown();
-            return {
-                success: true,
-                data: {
-                    content,
-                    todoCount: session.ralphTracker.todos.length,
-                },
-            };
-        });
-        // Import todos from @fix_plan.md content
-        this.app.post('/api/sessions/:id/fix-plan/import', async (req) => {
-            const { id } = req.params;
-            const importResult = FixPlanImportSchema.safeParse(req.body);
-            if (!importResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { content } = importResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const importedCount = session.ralphTracker.importFixPlanMarkdown(content);
-            this.persistSessionState(session);
-            return {
-                success: true,
-                data: {
-                    importedCount,
-                    todos: session.ralphTracker.todos,
-                },
-            };
-        });
-        // Write @fix_plan.md to session's working directory
-        this.app.post('/api/sessions/:id/fix-plan/write', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const workingDir = session.workingDir;
-            if (!workingDir) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Session has no working directory');
-            }
-            const content = session.ralphTracker.generateFixPlanMarkdown();
-            const filePath = join(workingDir, '@fix_plan.md');
-            try {
-                await fs.writeFile(filePath, content, 'utf-8');
-                return {
-                    success: true,
-                    data: {
-                        filePath,
-                        todoCount: session.ralphTracker.todos.length,
-                    },
-                };
-            }
-            catch (error) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to write file: ${error}`);
-            }
-        });
-        // Read @fix_plan.md from session's working directory and import
-        this.app.post('/api/sessions/:id/fix-plan/read', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const workingDir = session.workingDir;
-            if (!workingDir) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Session has no working directory');
-            }
-            const filePath = join(workingDir, '@fix_plan.md');
-            try {
-                const content = await fs.readFile(filePath, 'utf-8');
-                const importedCount = session.ralphTracker.importFixPlanMarkdown(content);
-                this.persistSessionState(session);
-                return {
-                    success: true,
-                    data: {
-                        filePath,
-                        importedCount,
-                        todos: session.ralphTracker.todos,
-                    },
-                };
-            }
-            catch (error) {
-                if (error.code === 'ENOENT') {
-                    return createErrorResponse(ApiErrorCode.NOT_FOUND, '@fix_plan.md not found in working directory');
-                }
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${error}`);
-            }
-        });
-        // Write Ralph prompt to file in session's working directory
-        // This avoids mux input escaping issues with long multi-line prompts
-        this.app.post('/api/sessions/:id/ralph-prompt/write', async (req) => {
-            const { id } = req.params;
-            const promptResult = RalphPromptWriteSchema.safeParse(req.body);
-            if (!promptResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { content } = promptResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const workingDir = session.workingDir;
-            if (!workingDir) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Session has no working directory');
-            }
-            const filePath = join(workingDir, '@ralph_prompt.md');
-            try {
-                await fs.writeFile(filePath, content, 'utf-8');
-                return {
-                    success: true,
-                    data: {
-                        filePath,
-                        contentLength: content.length,
-                    },
-                };
-            }
-            catch (error) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to write file: ${error}`);
-            }
-        });
-        // Run prompt in session
-        this.app.post('/api/sessions/:id/run', async (req) => {
-            const { id } = req.params;
-            const result = RunPromptSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { prompt } = result.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (session.isBusy()) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
-            }
-            // Run async, don't wait
-            session.runPrompt(prompt).catch((err) => {
-                this.broadcast('session:error', { id, error: err.message });
-            });
-            this.broadcast('session:running', { id, prompt });
-            return { success: true };
-        });
-        // Start interactive Claude session (persists even if browser disconnects)
-        this.app.post('/api/sessions/:id/interactive', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (session.isBusy()) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
-            }
-            try {
-                // Auto-detect completion phrase from CLAUDE.md BEFORE starting (only if globally enabled and not explicitly disabled by user)
-                // Ralph tracker is not supported for opencode sessions
-                if (session.mode !== 'opencode' &&
-                    this.store.getConfig().ralphEnabled &&
-                    !session.ralphTracker.autoEnableDisabled) {
-                    autoConfigureRalph(session, session.workingDir, () => { });
-                    if (!session.ralphTracker.enabled) {
-                        session.ralphTracker.enable();
-                    }
-                }
-                await session.startInteractive();
-                getLifecycleLog().log({
-                    event: 'started',
-                    sessionId: id,
-                    name: session.name,
-                    mode: session.mode,
-                });
-                this.broadcast('session:interactive', { id });
-                this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // Start a plain shell session (no Claude)
-        this.app.post('/api/sessions/:id/shell', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (session.isBusy()) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
-            }
-            try {
-                await session.startShell();
-                getLifecycleLog().log({
-                    event: 'started',
-                    sessionId: id,
-                    name: session.name,
-                    mode: 'shell',
-                });
-                this.broadcast('session:interactive', { id, mode: 'shell' });
-                this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // Send input to interactive session
-        // useMux: true uses writeViaMux which is more reliable for programmatic input
-        this.app.post('/api/sessions/:id/input', async (req) => {
-            const { id } = req.params;
-            const result = SessionInputWithLimitSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { input, useMux } = result.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const inputStr = String(input);
-            if (inputStr.length > MAX_INPUT_LENGTH) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Input exceeds maximum length (${MAX_INPUT_LENGTH} bytes)`);
-            }
-            // Write input to PTY. Direct write is synchronous; writeViaMux
-            // (tmux send-keys) is fire-and-forget to avoid blocking the HTTP response.
-            if (useMux) {
-                // Fire-and-forget: don't block HTTP response on tmux child process.
-                // Fallback to direct write on failure.
-                session
-                    .writeViaMux(inputStr)
-                    .then((ok) => {
-                    if (!ok) {
-                        console.warn(`[Server] writeViaMux failed for session ${id}, falling back to direct write`);
-                        session.write(inputStr);
-                    }
-                })
-                    .catch(() => {
-                    session.write(inputStr);
-                });
-            }
-            else {
-                session.write(inputStr);
-            }
-            return { success: true };
-        });
-        // Resize session terminal
-        this.app.post('/api/sessions/:id/resize', async (req) => {
-            const { id } = req.params;
-            const result = ResizeSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { cols, rows } = result.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Note: Zod already validates that cols and rows are positive integers within bounds
-            if (cols > MAX_TERMINAL_COLS || rows > MAX_TERMINAL_ROWS) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Terminal dimensions exceed maximum (${MAX_TERMINAL_COLS}x${MAX_TERMINAL_ROWS})`);
-            }
-            session.resize(cols, rows);
-            return { success: true };
-        });
-        // Get session terminal buffer (for reconnecting)
-        // Query params:
-        //   tail=<bytes> - Only return last N bytes (faster initial load)
-        this.app.get('/api/sessions/:id/terminal', async (req) => {
-            const { id } = req.params;
-            const query = req.query;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
-            const fullSize = session.terminalBufferLength;
-            let truncated = false;
-            let cleanBuffer;
-            if (tailBytes > 0 && fullSize > tailBytes) {
-                // Fast path: tail from the end, skip expensive banner search on full 2MB buffer.
-                // Banner is near the top and gets discarded by tail anyway.
-                cleanBuffer = session.terminalBuffer.slice(-tailBytes);
-                truncated = true;
-                // Avoid starting mid-ANSI-escape: find first newline within the first 4KB
-                // and start from there. This prevents xterm.js from parsing a partial escape
-                // sequence which corrupts cursor position for all subsequent Ink redraws.
-                const firstNewline = cleanBuffer.indexOf('\n');
-                if (firstNewline > 0 && firstNewline < 4096) {
-                    cleanBuffer = cleanBuffer.slice(firstNewline + 1);
-                }
-            }
-            else {
-                // Full buffer: clean junk before actual Claude content
-                cleanBuffer = session.terminalBuffer;
-                // Find where Claude banner starts (has color codes before "Claude")
-                const claudeMatch = cleanBuffer.match(CLAUDE_BANNER_PATTERN);
-                if (claudeMatch && claudeMatch.index !== undefined && claudeMatch.index > 0) {
-                    let lineStart = claudeMatch.index;
-                    while (lineStart > 0 && cleanBuffer[lineStart - 1] !== '\n') {
-                        lineStart--;
-                    }
-                    cleanBuffer = cleanBuffer.slice(lineStart);
-                }
-            }
-            // Remove Ctrl+L and leading whitespace (cheap on tailed subset)
-            cleanBuffer = cleanBuffer.replace(CTRL_L_PATTERN, '').replace(LEADING_WHITESPACE_PATTERN, '');
-            return {
-                terminalBuffer: cleanBuffer,
-                status: session.status,
-                fullSize,
-                truncated,
-            };
-        });
-        // ============ Respawn Controller Endpoints ============
-        // Get respawn status for a session
-        this.app.get('/api/sessions/:id/respawn', async (req) => {
-            const { id } = req.params;
-            const controller = this.respawnControllers.get(id);
-            if (!controller) {
-                return { enabled: false, status: null };
-            }
-            return {
-                enabled: true,
-                ...controller.getStatus(),
-            };
-        });
-        // Get respawn config (from running controller or pre-saved)
-        this.app.get('/api/sessions/:id/respawn/config', async (req) => {
-            const { id } = req.params;
-            const controller = this.respawnControllers.get(id);
-            if (controller) {
-                return { success: true, config: controller.getConfig(), active: true };
-            }
-            // Return pre-saved config from mux-sessions.json
-            const preConfig = this.mux.getSession(id)?.respawnConfig;
-            if (preConfig) {
-                return { success: true, config: preConfig, active: false };
-            }
-            return { success: true, config: null, active: false };
-        });
-        // Start respawn controller for a session
-        this.app.post('/api/sessions/:id/respawn/start', async (req) => {
-            const { id } = req.params;
-            let body;
-            if (req.body) {
-                const result = RespawnConfigSchema.safeParse(req.body);
-                if (!result.success) {
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid respawn config');
-                }
-                body = result.data;
-            }
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Respawn is not supported for opencode sessions
-            if (session.mode === 'opencode') {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
-            }
-            // Create or get existing controller
-            let controller = this.respawnControllers.get(id);
-            if (!controller) {
-                // Merge request body with pre-saved config from mux-sessions.json
-                const preConfig = this.mux.getSession(id)?.respawnConfig;
-                const config = body || preConfig ? { ...preConfig, ...body } : undefined;
-                controller = new RespawnController(session, config);
-                this.respawnControllers.set(id, controller);
-                this.setupRespawnListeners(id, controller);
-            }
-            else if (body) {
-                controller.updateConfig(body);
-            }
-            controller.start();
-            // Persist respawn config to mux session and state.json
-            this.saveRespawnConfig(id, controller.getConfig());
-            this.persistSessionState(session);
-            this.broadcast('respawn:started', { sessionId: id, status: controller.getStatus() });
-            return { success: true, status: controller.getStatus() };
-        });
-        // Stop respawn controller for a session
-        this.app.post('/api/sessions/:id/respawn/stop', async (req) => {
-            const { id } = req.params;
-            const controller = this.respawnControllers.get(id);
-            if (!controller) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Respawn controller not found');
-            }
-            controller.stop();
-            // Remove controller from map so persistSessionState doesn't save respawnEnabled: true
-            this.respawnControllers.delete(id);
-            // Clear any timed respawn
-            const timerInfo = this.respawnTimers.get(id);
-            if (timerInfo) {
-                clearTimeout(timerInfo.timer);
-                this.respawnTimers.delete(id);
-            }
-            // Clear persisted respawn config
-            this.mux.clearRespawnConfig(id);
-            // Update state.json (respawnConfig removed)
-            const session = this.sessions.get(id);
-            if (session) {
-                this.persistSessionState(session);
-            }
-            this.broadcast('respawn:stopped', { sessionId: id });
-            return { success: true };
-        });
-        // Update respawn configuration (works with or without running controller)
-        this.app.put('/api/sessions/:id/respawn/config', async (req) => {
-            const { id } = req.params;
-            // Validate respawn config to prevent arbitrary field injection
-            const parseResult = RespawnConfigSchema.safeParse(req.body);
-            if (!parseResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Invalid respawn config: ${parseResult.error.message}`);
-            }
-            const config = parseResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const controller = this.respawnControllers.get(id);
-            if (controller) {
-                // Update running controller
-                controller.updateConfig(config);
-                this.saveRespawnConfig(id, controller.getConfig());
-                this.persistSessionState(session);
-                this.broadcast('respawn:configUpdated', { sessionId: id, config: controller.getConfig() });
-                return { success: true, config: controller.getConfig() };
-            }
-            // No controller running - save as pre-config for when respawn starts
-            const existing = this.mux.getSession(id);
-            const currentConfig = existing?.respawnConfig;
-            const merged = {
-                enabled: config.enabled ?? currentConfig?.enabled ?? false,
-                idleTimeoutMs: config.idleTimeoutMs ?? currentConfig?.idleTimeoutMs ?? 10000,
-                updatePrompt: config.updatePrompt ?? currentConfig?.updatePrompt ?? 'update all the docs and CLAUDE.md',
-                interStepDelayMs: config.interStepDelayMs ?? currentConfig?.interStepDelayMs ?? 1000,
-                sendClear: config.sendClear ?? currentConfig?.sendClear ?? true,
-                sendInit: config.sendInit ?? currentConfig?.sendInit ?? true,
-                kickstartPrompt: config.kickstartPrompt ?? currentConfig?.kickstartPrompt,
-                autoAcceptPrompts: config.autoAcceptPrompts ?? currentConfig?.autoAcceptPrompts ?? true,
-                autoAcceptDelayMs: config.autoAcceptDelayMs ?? currentConfig?.autoAcceptDelayMs ?? 8000,
-                aiIdleCheckEnabled: config.aiIdleCheckEnabled ?? currentConfig?.aiIdleCheckEnabled ?? true,
-                aiIdleCheckModel: config.aiIdleCheckModel ?? currentConfig?.aiIdleCheckModel ?? 'claude-opus-4-5-20251101',
-                aiIdleCheckMaxContext: config.aiIdleCheckMaxContext ?? currentConfig?.aiIdleCheckMaxContext ?? 16000,
-                aiIdleCheckTimeoutMs: config.aiIdleCheckTimeoutMs ?? currentConfig?.aiIdleCheckTimeoutMs ?? 90000,
-                aiIdleCheckCooldownMs: config.aiIdleCheckCooldownMs ?? currentConfig?.aiIdleCheckCooldownMs ?? 180000,
-                aiPlanCheckEnabled: config.aiPlanCheckEnabled ?? currentConfig?.aiPlanCheckEnabled ?? true,
-                aiPlanCheckModel: config.aiPlanCheckModel ?? currentConfig?.aiPlanCheckModel ?? 'claude-opus-4-5-20251101',
-                aiPlanCheckMaxContext: config.aiPlanCheckMaxContext ?? currentConfig?.aiPlanCheckMaxContext ?? 8000,
-                aiPlanCheckTimeoutMs: config.aiPlanCheckTimeoutMs ?? currentConfig?.aiPlanCheckTimeoutMs ?? 60000,
-                aiPlanCheckCooldownMs: config.aiPlanCheckCooldownMs ?? currentConfig?.aiPlanCheckCooldownMs ?? 30000,
-                durationMinutes: currentConfig?.durationMinutes,
-            };
-            this.mux.updateRespawnConfig(id, merged);
-            this.persistSessionState(session);
-            this.broadcast('respawn:configUpdated', { sessionId: id, config: merged });
-            return { success: true, config: merged };
-        });
-        // Start interactive session WITH respawn enabled
-        this.app.post('/api/sessions/:id/interactive-respawn', async (req) => {
-            const { id } = req.params;
-            const irResult = req.body ? InteractiveRespawnSchema.safeParse(req.body) : { success: true, data: {} };
-            if (!irResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = irResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (session.isBusy()) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
-            }
-            // Respawn is not supported for opencode sessions
-            if (session.mode === 'opencode') {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
-            }
-            try {
-                // Auto-detect completion phrase from CLAUDE.md BEFORE starting (only if globally enabled and not explicitly disabled by user)
-                if (this.store.getConfig().ralphEnabled && !session.ralphTracker.autoEnableDisabled) {
-                    autoConfigureRalph(session, session.workingDir, () => { });
-                    if (!session.ralphTracker.enabled) {
-                        session.ralphTracker.enable();
-                    }
-                }
-                // Start interactive session
-                await session.startInteractive();
-                getLifecycleLog().log({
-                    event: 'started',
-                    sessionId: id,
-                    name: session.name,
-                    mode: session.mode,
-                    reason: 'interactive_respawn',
-                });
-                this.broadcast('session:interactive', { id });
-                this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-                // Create and start respawn controller
-                const controller = new RespawnController(session, body?.respawnConfig);
-                this.respawnControllers.set(id, controller);
-                this.setupRespawnListeners(id, controller);
-                controller.start();
-                // Set up timed stop if duration specified
-                if (body?.durationMinutes && body.durationMinutes > 0) {
-                    this.setupTimedRespawn(id, body.durationMinutes);
-                }
-                // Persist full session state with respawn config
-                this.persistSessionState(session);
-                this.broadcast('respawn:started', { sessionId: id, status: controller.getStatus() });
-                return {
-                    success: true,
-                    data: {
-                        message: 'Interactive session with respawn started',
-                        respawnStatus: controller.getStatus(),
-                    },
-                };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // Enable respawn on an EXISTING interactive session
-        this.app.post('/api/sessions/:id/respawn/enable', async (req) => {
-            const { id } = req.params;
-            const reResult = req.body ? RespawnEnableSchema.safeParse(req.body) : { success: true, data: {} };
-            if (!reResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = reResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Respawn is not supported for opencode sessions
-            if (session.mode === 'opencode') {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
-            }
-            // Check if session is running (has a PID)
-            if (!session.pid) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Session is not running. Start it first.');
-            }
-            // Stop existing controller if any
-            const existingController = this.respawnControllers.get(id);
-            if (existingController) {
-                existingController.stop();
-            }
-            // Create and start new respawn controller (merge with pre-saved config)
-            const preConfig = this.mux.getSession(id)?.respawnConfig;
-            const config = body?.config || preConfig ? { ...preConfig, ...body?.config } : undefined;
-            const controller = new RespawnController(session, config);
-            this.respawnControllers.set(id, controller);
-            this.setupRespawnListeners(id, controller);
-            controller.start();
-            // Set up timed stop if duration specified
-            if (body?.durationMinutes && body.durationMinutes > 0) {
-                this.setupTimedRespawn(id, body.durationMinutes);
-            }
-            // Persist respawn config to mux session and state.json
-            this.saveRespawnConfig(id, controller.getConfig(), body?.durationMinutes);
-            this.persistSessionState(session);
-            this.broadcast('respawn:started', { sessionId: id, status: controller.getStatus() });
-            return {
-                success: true,
-                message: 'Respawn enabled on existing session',
-                respawnStatus: controller.getStatus(),
-            };
-        });
-        // Set auto-clear on a session
-        this.app.post('/api/sessions/:id/auto-clear', async (req) => {
-            const { id } = req.params;
-            const acResult = AutoClearSchema.safeParse(req.body);
-            if (!acResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = acResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            session.setAutoClear(body.enabled, body.threshold);
-            this.persistSessionState(session);
-            this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
-            return {
-                success: true,
-                data: {
-                    autoClear: {
-                        enabled: session.autoClearEnabled,
-                        threshold: session.autoClearThreshold,
-                    },
-                },
-            };
-        });
-        // Set auto-compact on a session
-        this.app.post('/api/sessions/:id/auto-compact', async (req) => {
-            const { id } = req.params;
-            const compactResult = AutoCompactSchema.safeParse(req.body);
-            if (!compactResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = compactResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            session.setAutoCompact(body.enabled, body.threshold, body.prompt);
-            this.persistSessionState(session);
-            this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
-            return {
-                success: true,
-                data: {
-                    autoCompact: {
-                        enabled: session.autoCompactEnabled,
-                        threshold: session.autoCompactThreshold,
-                        prompt: session.autoCompactPrompt,
-                    },
-                },
-            };
-        });
-        // Toggle image watcher for a session
-        this.app.post('/api/sessions/:id/image-watcher', async (req) => {
-            const { id } = req.params;
-            const iwResult = ImageWatcherSchema.safeParse(req.body);
-            if (!iwResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = iwResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            if (body.enabled) {
-                imageWatcher.watchSession(session.id, session.workingDir);
-            }
-            else {
-                imageWatcher.unwatchSession(session.id);
-            }
-            // Store state on session for persistence
-            session.imageWatcherEnabled = body.enabled;
-            this.persistSessionState(session);
-            return {
-                success: true,
-                data: {
-                    imageWatcherEnabled: body.enabled,
-                },
-            };
-        });
-        // Toggle flicker filter for a session
-        this.app.post('/api/sessions/:id/flicker-filter', async (req) => {
-            const { id } = req.params;
-            const ffResult = FlickerFilterSchema.safeParse(req.body);
-            if (!ffResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = ffResult.data;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            session.flickerFilterEnabled = body.enabled;
-            this.persistSessionState(session);
-            this.broadcast('session:updated', this.getSessionStateWithRespawn(session));
-            return {
-                success: true,
-                data: {
-                    flickerFilterEnabled: body.enabled,
-                },
-            };
-        });
-        // Quick run (create session, run prompt, return result, then cleanup)
-        this.app.post('/api/run', async (req) => {
-            // Prevent unbounded session creation
-            if (this.sessions.size >= MAX_CONCURRENT_SESSIONS) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached`);
-            }
-            const qrResult = QuickRunSchema.safeParse(req.body);
-            if (!qrResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { prompt, workingDir } = qrResult.data;
-            if (!prompt.trim()) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'prompt is required');
-            }
-            const dir = workingDir || process.cwd();
-            // Validate workingDir exists and is a directory
-            if (workingDir) {
-                try {
-                    const stat = statSync(dir);
-                    if (!stat.isDirectory()) {
-                        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory');
-                    }
-                }
-                catch {
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist');
-                }
-            }
-            const session = new Session({ workingDir: dir });
-            this.sessions.set(session.id, session);
-            this.store.incrementSessionsCreated();
-            this.persistSessionState(session);
-            await this.setupSessionListeners(session);
-            getLifecycleLog().log({
-                event: 'created',
-                sessionId: session.id,
-                name: session.name,
-                reason: 'run_prompt',
-            });
-            this.broadcast('session:created', this.getSessionStateWithRespawn(session));
-            try {
-                const result = await session.runPrompt(prompt);
-                // Clean up session after completion to prevent memory leak
-                await this.cleanupSession(session.id, true, 'run_prompt_complete');
-                return { success: true, sessionId: session.id, ...result };
-            }
-            catch (err) {
-                // Clean up session on error too
-                await this.cleanupSession(session.id, true, 'run_prompt_error');
-                return { success: false, sessionId: session.id, error: getErrorMessage(err) };
-            }
-        });
-        // Scheduled runs
-        this.app.get('/api/scheduled', async () => {
-            return Array.from(this.scheduledRuns.values());
-        });
-        this.app.post('/api/scheduled', async (req) => {
-            const srResult = ScheduledRunSchema.safeParse(req.body);
-            if (!srResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { prompt, workingDir, durationMinutes } = srResult.data;
-            // Validate workingDir exists and is a directory
-            if (workingDir) {
-                try {
-                    const stat = statSync(workingDir);
-                    if (!stat.isDirectory()) {
-                        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory');
-                    }
-                }
-                catch {
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist');
-                }
-            }
-            const run = await this.startScheduledRun(prompt, workingDir || process.cwd(), durationMinutes ?? 60);
-            return { success: true, run };
-        });
-        this.app.delete('/api/scheduled/:id', async (req) => {
-            const { id } = req.params;
-            const run = this.scheduledRuns.get(id);
-            if (!run) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Scheduled run not found');
-            }
-            await this.stopScheduledRun(id);
-            return { success: true };
-        });
-        this.app.get('/api/scheduled/:id', async (req) => {
-            const { id } = req.params;
-            const run = this.scheduledRuns.get(id);
-            if (!run) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Scheduled run not found');
-            }
-            return run;
-        });
-        // Case management
-        const casesDir = join(homedir(), 'codeman-cases');
-        this.app.get('/api/cases', async () => {
-            const cases = [];
-            // Get cases from casesDir
-            try {
-                const entries = await fs.readdir(casesDir, { withFileTypes: true });
-                for (const e of entries) {
-                    if (e.isDirectory()) {
-                        cases.push({
-                            name: e.name,
-                            path: join(casesDir, e.name),
-                            hasClaudeMd: existsSync(join(casesDir, e.name, 'CLAUDE.md')),
-                        });
-                    }
-                }
-            }
-            catch {
-                // casesDir may not exist yet
-            }
-            // Get linked cases
-            const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-            try {
-                const linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-                for (const [name, path] of Object.entries(linkedCases)) {
-                    // Only add if not already in cases (avoid duplicates) and path exists
-                    if (!cases.some((c) => c.name === name) && existsSync(path)) {
-                        cases.push({
-                            name,
-                            path,
-                            hasClaudeMd: existsSync(join(path, 'CLAUDE.md')),
-                        });
-                    }
-                }
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.warn('[Server] Failed to read linked cases:', err);
-                }
-            }
-            return cases;
-        });
-        this.app.post('/api/cases', async (req) => {
-            const result = CreateCaseSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { name, description } = result.data;
-            const casePath = join(casesDir, name);
-            // Security: Path traversal protection - use relative path check
-            const resolvedPath = resolve(casePath);
-            const resolvedBase = resolve(casesDir);
-            const relPath = relative(resolvedBase, resolvedPath);
-            if (relPath.startsWith('..') || isAbsolute(relPath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case path');
-            }
-            if (existsSync(casePath)) {
-                return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Case already exists');
-            }
-            try {
-                mkdirSync(casePath, { recursive: true });
-                mkdirSync(join(casePath, 'src'), { recursive: true });
-                // Read settings to get custom template path
-                const templatePath = await this.getDefaultClaudeMdPath();
-                const claudeMd = generateClaudeMd(name, description || '', templatePath);
-                writeFileSync(join(casePath, 'CLAUDE.md'), claudeMd);
-                // Write .claude/settings.local.json with hooks for desktop notifications
-                await writeHooksConfig(casePath);
-                this.broadcast('case:created', { name, path: casePath });
-                return { success: true, data: { case: { name, path: casePath } } };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // Link an existing folder as a case
-        this.app.post('/api/cases/link', async (req) => {
-            const lcResult = LinkCaseSchema.safeParse(req.body);
-            if (!lcResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { name, path: folderPath } = lcResult.data;
-            // Expand ~ to home directory
-            const expandedPath = folderPath.startsWith('~') ? join(homedir(), folderPath.slice(1)) : folderPath;
-            // Validate the folder exists
-            if (!existsSync(expandedPath)) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, `Folder not found: ${expandedPath}`);
-            }
-            // Check if case name already exists in casesDir
-            const casePath = join(casesDir, name);
-            if (existsSync(casePath)) {
-                return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'A case with this name already exists in codeman-cases.');
-            }
-            // Load existing linked cases
-            const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-            let linkedCases = {};
-            try {
-                linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.warn('[Server] Failed to read linked cases:', err);
-                }
-            }
-            // Check if name is already linked
-            if (linkedCases[name]) {
-                return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, `Case "${name}" is already linked to ${linkedCases[name]}`);
-            }
-            // Save the linked case
-            linkedCases[name] = expandedPath;
-            try {
-                const codemanDir = join(homedir(), '.codeman');
-                if (!existsSync(codemanDir)) {
-                    mkdirSync(codemanDir, { recursive: true });
-                }
-                await fs.writeFile(linkedCasesFile, JSON.stringify(linkedCases, null, 2));
-                this.broadcast('case:linked', { name, path: expandedPath });
-                return { success: true, data: { case: { name, path: expandedPath } } };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        this.app.get('/api/cases/:name', async (req) => {
-            const { name } = req.params;
-            // First check linked cases
-            const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-            try {
-                const linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-                if (linkedCases[name]) {
-                    const linkedPath = linkedCases[name];
-                    return {
-                        name,
-                        path: linkedPath,
-                        hasClaudeMd: existsSync(join(linkedPath, 'CLAUDE.md')),
-                        linked: true,
-                    };
-                }
-            }
-            catch {
-                // ENOENT or parse errors - fall through to casesDir check
-            }
-            // Then check casesDir
-            const casePath = join(casesDir, name);
-            if (!existsSync(casePath)) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Case not found');
-            }
-            return {
-                name,
-                path: casePath,
-                hasClaudeMd: existsSync(join(casePath, 'CLAUDE.md')),
-            };
-        });
-        // Read @fix_plan.md from a case directory (for wizard to detect existing plans)
-        this.app.get('/api/cases/:name/fix-plan', async (req) => {
-            const { name } = req.params;
-            // Get case path (check linked cases first, then casesDir)
-            let casePath = null;
-            const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-            try {
-                const linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-                if (linkedCases[name]) {
-                    casePath = linkedCases[name];
-                }
-            }
-            catch {
-                // ENOENT or parse errors - fall through to casesDir
-            }
-            if (!casePath) {
-                casePath = join(casesDir, name);
-            }
-            const fixPlanPath = join(casePath, '@fix_plan.md');
-            if (!existsSync(fixPlanPath)) {
-                return { success: true, exists: false, content: null, todos: [] };
-            }
-            try {
-                const content = await fs.readFile(fixPlanPath, 'utf-8');
-                // Parse todos from the content (similar to ralph-tracker's importFixPlanMarkdown)
-                const todos = [];
-                const todoPattern = /^-\s*\[([ xX-])\]\s*(.+)$/;
-                const p0HeaderPattern = /^##\s*(High Priority|Critical|P0|Critical Path)/i;
-                const p1HeaderPattern = /^##\s*(Standard|P1|Medium Priority)/i;
-                const p2HeaderPattern = /^##\s*(Nice to Have|P2|Low Priority)/i;
-                const completedHeaderPattern = /^##\s*Completed/i;
-                let currentPriority = null;
-                let inCompletedSection = false;
-                for (const line of content.split('\n')) {
-                    const trimmed = line.trim();
-                    if (p0HeaderPattern.test(trimmed)) {
-                        currentPriority = 'P0';
-                        inCompletedSection = false;
-                        continue;
-                    }
-                    if (p1HeaderPattern.test(trimmed)) {
-                        currentPriority = 'P1';
-                        inCompletedSection = false;
-                        continue;
-                    }
-                    if (p2HeaderPattern.test(trimmed)) {
-                        currentPriority = 'P2';
-                        inCompletedSection = false;
-                        continue;
-                    }
-                    if (completedHeaderPattern.test(trimmed)) {
-                        inCompletedSection = true;
-                        continue;
-                    }
-                    const match = trimmed.match(todoPattern);
-                    if (match) {
-                        const [, checkboxState, taskContent] = match;
-                        let status;
-                        if (inCompletedSection || checkboxState === 'x' || checkboxState === 'X') {
-                            status = 'completed';
-                        }
-                        else if (checkboxState === '-') {
-                            status = 'in_progress';
-                        }
-                        else {
-                            status = 'pending';
-                        }
-                        todos.push({
-                            content: taskContent.trim(),
-                            status,
-                            priority: inCompletedSection ? null : currentPriority,
-                        });
-                    }
-                }
-                // Calculate stats in a single pass for better performance
-                let pending = 0, inProgress = 0, completed = 0;
-                for (const t of todos) {
-                    if (t.status === 'pending')
-                        pending++;
-                    else if (t.status === 'in_progress')
-                        inProgress++;
-                    else if (t.status === 'completed')
-                        completed++;
-                }
-                const stats = { total: todos.length, pending, inProgress, completed };
-                return {
-                    success: true,
-                    exists: true,
-                    content,
-                    todos,
-                    stats,
-                };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read @fix_plan.md: ${err}`);
-            }
-        });
-        // Quick Start: Create case (if needed) and start interactive session in one click
-        this.app.post('/api/quick-start', async (req) => {
-            // Prevent unbounded session creation
-            if (this.sessions.size >= MAX_CONCURRENT_SESSIONS) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached.`);
-            }
-            const result = QuickStartSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { caseName = 'testcase', mode = 'claude', openCodeConfig } = result.data;
-            // Check OpenCode availability if requested
-            if (mode === 'opencode') {
-                const { isOpenCodeAvailable } = await import('../utils/opencode-cli-resolver.js');
-                if (!isOpenCodeAvailable()) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
-                }
-            }
-            const casePath = join(casesDir, caseName);
-            // Security: Path traversal protection - use relative path check
-            const resolvedPath = resolve(casePath);
-            const resolvedBase = resolve(casesDir);
-            const relPath = relative(resolvedBase, resolvedPath);
-            if (relPath.startsWith('..') || isAbsolute(relPath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case path');
-            }
-            // Create case folder and CLAUDE.md if it doesn't exist
-            if (!existsSync(casePath)) {
-                try {
-                    mkdirSync(casePath, { recursive: true });
-                    mkdirSync(join(casePath, 'src'), { recursive: true });
-                    // Read settings to get custom template path
-                    const templatePath = await this.getDefaultClaudeMdPath();
-                    const claudeMd = generateClaudeMd(caseName, '', templatePath);
-                    writeFileSync(join(casePath, 'CLAUDE.md'), claudeMd);
-                    // Write .claude/settings.local.json with hooks for desktop notifications
-                    // (Claude-specific — OpenCode uses its own plugin system)
-                    if (mode !== 'opencode') {
-                        await writeHooksConfig(casePath);
-                    }
-                    this.broadcast('case:created', { name: caseName, path: casePath });
-                }
-                catch (err) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
-                }
-            }
-            // Create a new session with the case as working directory
-            // Apply global Nice priority config and model config from settings
-            const niceConfig = await this.getGlobalNiceConfig();
-            const qsModelConfig = await this.getModelConfig();
-            const qsModel = mode === 'opencode' ? openCodeConfig?.model : mode !== 'shell' ? qsModelConfig?.defaultModel : undefined;
-            const qsClaudeModeConfig = await this.getClaudeModeConfig();
-            const session = new Session({
-                workingDir: casePath,
-                mux: this.mux,
-                useMux: true,
-                mode: mode,
-                niceConfig: niceConfig,
-                model: qsModel,
-                claudeMode: qsClaudeModeConfig.claudeMode,
-                allowedTools: qsClaudeModeConfig.allowedTools,
-                openCodeConfig: mode === 'opencode' ? openCodeConfig : undefined,
-            });
-            // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
-            // so the initial state already has the phrase configured (only if globally enabled)
-            if (mode === 'claude' && this.store.getConfig().ralphEnabled) {
-                autoConfigureRalph(session, casePath, () => { }); // no broadcast yet
-                if (!session.ralphTracker.enabled) {
-                    session.ralphTracker.enable();
-                    session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart
-                }
-            }
-            this.sessions.set(session.id, session);
-            this.store.incrementSessionsCreated();
-            this.persistSessionState(session);
-            await this.setupSessionListeners(session);
-            getLifecycleLog().log({
-                event: 'created',
-                sessionId: session.id,
-                name: session.name,
-                reason: 'quick_start',
-            });
-            this.broadcast('session:created', this.getSessionStateWithRespawn(session));
-            // Start in the appropriate mode
-            try {
-                if (mode === 'shell') {
-                    await session.startShell();
-                    getLifecycleLog().log({
-                        event: 'started',
-                        sessionId: session.id,
-                        name: session.name,
-                        mode: 'shell',
-                    });
-                    this.broadcast('session:interactive', { id: session.id, mode: 'shell' });
-                }
-                else {
-                    // Both 'claude' and 'opencode' modes use startInteractive()
-                    await session.startInteractive();
-                    getLifecycleLog().log({
-                        event: 'started',
-                        sessionId: session.id,
-                        name: session.name,
-                        mode,
-                    });
-                    this.broadcast('session:interactive', { id: session.id, mode });
-                }
-                this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-                // Save lastUsedCase to settings for TUI/web sync
-                try {
-                    const settingsFilePath = join(homedir(), '.codeman', 'settings.json');
-                    let settings = {};
-                    try {
-                        settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
-                    }
-                    catch (err) {
-                        if (err.code !== 'ENOENT')
-                            throw err;
-                    }
-                    settings.lastUsedCase = caseName;
-                    const dir = dirname(settingsFilePath);
-                    if (!existsSync(dir)) {
-                        mkdirSync(dir, { recursive: true });
-                    }
-                    // Use async write to avoid blocking event loop
-                    fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
-                        // Non-critical but log for debugging
-                        console.warn('[Server] Failed to save settings (lastUsedCase):', err);
-                    });
-                }
-                catch (err) {
-                    // Non-critical but log for debugging
-                    console.warn('[Server] Failed to prepare settings update:', err);
-                }
-                return {
-                    success: true,
-                    sessionId: session.id,
-                    casePath,
-                    caseName,
-                };
-            }
-            catch (err) {
-                // Clean up session on error to prevent orphaned resources
-                await this.cleanupSession(session.id, true, 'quick_start_error');
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // ========== Ralph Loop Start (replaces 6-8 serial API calls from frontend) ==========
-        this.app.post('/api/ralph-loop/start', async (req) => {
-            // Prevent unbounded session creation
-            if (this.sessions.size >= MAX_CONCURRENT_SESSIONS) {
-                return createErrorResponse(ApiErrorCode.SESSION_BUSY, `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached.`);
-            }
-            const rlResult = RalphLoopStartSchema.safeParse(req.body);
-            if (!rlResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, rlResult.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { caseName, taskDescription, completionPhrase, maxIterations, enableRespawn, planItems } = rlResult.data;
-            const casePath = join(casesDir, caseName);
-            // Security: Path traversal protection
-            const rlResolvedPath = resolve(casePath);
-            const rlResolvedBase = resolve(casesDir);
-            const rlRelPath = relative(rlResolvedBase, rlResolvedPath);
-            if (rlRelPath.startsWith('..') || isAbsolute(rlRelPath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case path');
-            }
-            // Create case folder if it doesn't exist (reuse quick-start logic)
-            if (!existsSync(casePath)) {
-                try {
-                    mkdirSync(casePath, { recursive: true });
-                    mkdirSync(join(casePath, 'src'), { recursive: true });
-                    const templatePath = await this.getDefaultClaudeMdPath();
-                    const claudeMd = generateClaudeMd(caseName, '', templatePath);
-                    writeFileSync(join(casePath, 'CLAUDE.md'), claudeMd);
-                    await writeHooksConfig(casePath);
-                    this.broadcast('case:created', { name: caseName, path: casePath });
-                }
-                catch (err) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
-                }
-            }
-            // Create session
-            const niceConfig = await this.getGlobalNiceConfig();
-            const rlModelConfig = await this.getModelConfig();
-            const rlClaudeModeConfig = await this.getClaudeModeConfig();
-            const session = new Session({
-                workingDir: casePath,
-                mux: this.mux,
-                useMux: true,
-                mode: 'claude',
-                niceConfig,
-                model: rlModelConfig?.defaultModel,
-                claudeMode: rlClaudeModeConfig.claudeMode,
-                allowedTools: rlClaudeModeConfig.allowedTools,
-            });
-            // Configure Ralph tracker
-            autoConfigureRalph(session, casePath, () => { });
-            if (!session.ralphTracker.enabled) {
-                session.ralphTracker.enable();
-                session.ralphTracker.enableAutoEnable();
-            }
-            session.ralphTracker.startLoop(completionPhrase, maxIterations ?? undefined);
-            // Build fix_plan markdown from plan items if provided
-            const enabledItems = planItems?.filter((i) => i.enabled) ?? [];
-            let planContent = '';
-            if (enabledItems.length > 0) {
-                const p0 = enabledItems.filter((i) => i.priority === 'P0');
-                const p1 = enabledItems.filter((i) => i.priority === 'P1');
-                const p2 = enabledItems.filter((i) => i.priority === 'P2');
-                const noPri = enabledItems.filter((i) => !i.priority);
-                planContent = '# Implementation Plan\n\n';
-                planContent += `Generated: ${new Date().toISOString().slice(0, 10)}\n\n`;
-                if (p0.length > 0) {
-                    planContent += '## Critical Path (P0)\n\n';
-                    p0.forEach((i) => {
-                        planContent += `- [ ] ${i.content}\n`;
-                    });
-                    planContent += '\n';
-                }
-                if (p1.length > 0) {
-                    planContent += '## Standard (P1)\n\n';
-                    p1.forEach((i) => {
-                        planContent += `- [ ] ${i.content}\n`;
-                    });
-                    planContent += '\n';
-                }
-                if (p2.length > 0) {
-                    planContent += '## Nice-to-Have (P2)\n\n';
-                    p2.forEach((i) => {
-                        planContent += `- [ ] ${i.content}\n`;
-                    });
-                    planContent += '\n';
-                }
-                if (noPri.length > 0) {
-                    planContent += '## Tasks\n\n';
-                    noPri.forEach((i) => {
-                        planContent += `- [ ] ${i.content}\n`;
-                    });
-                    planContent += '\n';
-                }
-                // Import into tracker and write to disk
-                session.ralphTracker.importFixPlanMarkdown(planContent);
-                const fixPlanPath = join(casePath, '@fix_plan.md');
-                writeFileSync(fixPlanPath, planContent, 'utf-8');
-            }
-            // Build full prompt
-            const hasPlan = enabledItems.length > 0;
-            let fullPrompt = taskDescription + '\n\n---\n\n';
-            if (hasPlan) {
-                fullPrompt += '## Task Plan\n\n';
-                fullPrompt += 'A task plan has been written to `@fix_plan.md`. Use this to track progress:\n';
-                fullPrompt += '- Reference the plan at the start of each iteration\n';
-                fullPrompt += '- Update task checkboxes as you complete items\n';
-                fullPrompt += '- Work through items in priority order (P0 > P1 > P2)\n\n';
-            }
-            fullPrompt += '## Iteration Protocol\n\n';
-            fullPrompt += 'This is an autonomous loop. Files from previous iterations persist. On each iteration:\n';
-            fullPrompt += '1. Check what work has already been done\n';
-            fullPrompt += '2. Make incremental progress toward completion\n';
-            fullPrompt += '3. Commit meaningful changes with descriptive messages\n\n';
-            fullPrompt += '## Verification\n\n';
-            fullPrompt += 'After each significant change:\n';
-            fullPrompt += '- Run tests to verify (npm test, pytest, etc.)\n';
-            fullPrompt += '- Check for type/lint errors if applicable\n';
-            fullPrompt += '- If tests fail, read the error, fix it, and retry\n\n';
-            fullPrompt += '## Completion Criteria\n\n';
-            fullPrompt += `Output \`<promise>${completionPhrase}</promise>\` when ALL of the following are true:\n`;
-            fullPrompt += '- All requirements from the task description are implemented\n';
-            fullPrompt += '- All tests pass\n';
-            fullPrompt += '- Changes are committed\n\n';
-            fullPrompt += '## If Stuck\n\n';
-            fullPrompt += 'If you encounter the same error for 3+ iterations:\n';
-            fullPrompt += "1. Document what you've tried\n";
-            fullPrompt += '2. Identify the specific blocker\n';
-            fullPrompt += '3. Try an alternative approach\n';
-            fullPrompt += '4. If truly blocked, output `<promise>BLOCKED</promise>` with an explanation\n';
-            // Write prompt to file
-            const promptPath = join(casePath, '@ralph_prompt.md');
-            writeFileSync(promptPath, fullPrompt, 'utf-8');
-            // Register session
-            this.sessions.set(session.id, session);
-            this.store.incrementSessionsCreated();
-            this.persistSessionState(session);
-            await this.setupSessionListeners(session);
-            getLifecycleLog().log({
-                event: 'created',
-                sessionId: session.id,
-                name: session.name,
-                reason: 'ralph_loop_start',
-            });
-            this.broadcast('session:created', this.getSessionStateWithRespawn(session));
-            // Start interactive mode
-            try {
-                await session.startInteractive();
-                getLifecycleLog().log({
-                    event: 'started',
-                    sessionId: session.id,
-                    name: session.name,
-                    mode: 'claude',
-                });
-                this.broadcast('session:interactive', { id: session.id, mode: 'claude' });
-                this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-            }
-            catch (err) {
-                await this.cleanupSession(session.id, true, 'ralph_loop_start_error');
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-            // Enable respawn if requested
-            if (enableRespawn) {
-                const ralphUpdatePrompt = 'Before /clear: Update CLAUDE.md with discoveries and notes, mark completed tasks in @fix_plan.md, write a brief progress summary to a file so the next iteration can continue seamlessly.';
-                const ralphKickstartPrompt = `You are in a Ralph Wiggum loop. Read @fix_plan.md for task status, continue on the next uncompleted task, output <promise>${completionPhrase}</promise> when ALL tasks are complete.`;
-                const controller = new RespawnController(session, {
-                    updatePrompt: ralphUpdatePrompt,
-                    sendClear: true,
-                    sendInit: true,
-                    kickstartPrompt: ralphKickstartPrompt,
-                });
-                this.respawnControllers.set(session.id, controller);
-                this.setupRespawnListeners(session.id, controller);
-                controller.start();
-                this.saveRespawnConfig(session.id, controller.getConfig());
-                this.persistSessionState(session);
-                this.broadcast('respawn:started', {
-                    sessionId: session.id,
-                    status: controller.getStatus(),
-                });
-            }
-            // Save lastUsedCase
-            try {
-                const settingsFilePath = join(homedir(), '.codeman', 'settings.json');
-                let settings = {};
-                try {
-                    settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
-                }
-                catch {
-                    /* ignore */
-                }
-                settings.lastUsedCase = caseName;
-                const dir = dirname(settingsFilePath);
-                if (!existsSync(dir))
-                    mkdirSync(dir, { recursive: true });
-                fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch(() => { });
-            }
-            catch {
-                /* non-critical */
-            }
-            const sessionId = session.id;
-            // Async: poll for CLI readiness, then send prompt
-            setImmediate(() => {
-                const pollReady = async () => {
-                    for (let attempt = 0; attempt < 60; attempt++) {
-                        await new Promise((r) => setTimeout(r, 500));
-                        const s = this.sessions.get(sessionId);
-                        if (!s)
-                            return; // session was deleted
-                        // Check terminal output for prompt indicator
-                        const termBuf = s.getTerminalBuffer().slice(-2048);
-                        if (termBuf.includes('❯') || termBuf.includes('tokens')) {
-                            break;
-                        }
-                    }
-                    // Small extra delay for CLI to settle
-                    await new Promise((r) => setTimeout(r, 2000));
-                    const s = this.sessions.get(sessionId);
-                    if (!s)
-                        return;
-                    try {
-                        await s.writeViaMux('Read @ralph_prompt.md and follow the instructions. Start working immediately.\r');
-                    }
-                    catch (err) {
-                        console.warn(`[RalphLoop] Failed to send prompt to session ${sessionId}:`, getErrorMessage(err));
-                    }
-                };
-                pollReady().catch((err) => console.error('[RalphLoop] pollReady error:', err));
-            });
-            return {
-                success: true,
-                data: { sessionId, caseName },
-            };
-        });
-        this.app.post('/api/generate-plan', async (req) => {
-            const gpResult = GeneratePlanSchema.safeParse(req.body);
-            if (!gpResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { taskDescription, detailLevel = 'standard' } = gpResult.data;
-            // Build sophisticated prompt based on Ralph Wiggum methodology
-            const detailConfig = {
-                brief: { style: 'high-level milestones', testDepth: 'basic' },
-                standard: { style: 'balanced implementation steps', testDepth: 'thorough' },
-                detailed: {
-                    style: 'granular sub-tasks with full TDD coverage',
-                    testDepth: 'comprehensive',
-                },
-            };
-            const levelConfig = detailConfig[detailLevel] || detailConfig.standard;
-            const prompt = `You are an expert software architect breaking down a task into a thorough implementation plan.
-
-## TASK TO IMPLEMENT
-${taskDescription}
-
-## YOUR MISSION
-Create a detailed, actionable implementation plan following Test-Driven Development (TDD) methodology.
-Think deeply about:
-- What are ALL the components, modules, and features needed?
-- What could go wrong? Add defensive steps for error handling.
-- How will we verify each part works? Tests before implementation.
-- What edge cases need handling?
-- What's the logical order of dependencies?
-
-## DETAIL LEVEL: ${detailLevel.toUpperCase()}
-Style: ${levelConfig.style}
-Generate as many steps as needed to properly cover the task - don't artificially limit yourself.
-For complex projects, this could be 30, 50, or even 100+ steps. Quality over brevity.
-
-## PLAN STRUCTURE
-
-Your plan MUST include these phases in order:
-
-### Phase 1: Foundation & Setup
-- Project structure, dependencies, configuration
-- Database schemas, type definitions, interfaces
-
-### Phase 2: Core Implementation (TDD Cycle)
-For EACH feature:
-1. Write failing tests first (unit tests)
-2. Implement the feature
-3. Run tests, debug until passing
-4. Refactor if needed
-
-### Phase 3: Integration & Edge Cases
-- Integration tests for feature interactions
-- Edge case handling (errors, boundaries, invalid input)
-- Error messages and user feedback
-
-### Phase 4: Verification & Hardening
-- Run full test suite
-- Fix any failing tests
-- Add missing test coverage
-- Final verification that ALL requirements are met
-
-## OUTPUT FORMAT
-Return ONLY a JSON array. Each item MUST have:
-- id: unique identifier (e.g., "P0-001", "P1-002")
-- content: specific action (verb phrase, 15-120 chars, be descriptive!)
-- priority: "P0" (critical/blocking), "P1" (required), "P2" (enhancement)
-- verificationCriteria: HOW to verify this step is complete (required!)
-- tddPhase: "setup" | "test" | "impl" | "verify"
-- dependencies: array of task IDs this depends on (empty if none)
-
-## EXAMPLE OUTPUT
-[
-  {"id": "P0-001", "content": "Create project structure with src/, tests/, and config directories", "priority": "P0", "verificationCriteria": "Directories exist, package.json initialized", "tddPhase": "setup", "dependencies": []},
-  {"id": "P0-002", "content": "Define TypeScript interfaces for User, Session, and AuthToken types", "priority": "P0", "verificationCriteria": "Types compile without errors, exported from types.ts", "tddPhase": "setup", "dependencies": ["P0-001"]},
-  {"id": "P0-003", "content": "Write failing unit tests for password hashing (valid password, empty, too short)", "priority": "P0", "verificationCriteria": "Tests exist, fail with 'not implemented'", "tddPhase": "test", "dependencies": ["P0-002"]},
-  {"id": "P0-004", "content": "Implement password hashing with bcrypt, configurable salt rounds", "priority": "P0", "verificationCriteria": "npm test -- --grep='password' passes", "tddPhase": "impl", "dependencies": ["P0-003"]},
-  {"id": "P0-005", "content": "Write failing tests for JWT token generation and validation", "priority": "P0", "verificationCriteria": "Tests exist, fail with 'not implemented'", "tddPhase": "test", "dependencies": ["P0-004"]},
-  {"id": "P0-006", "content": "Implement JWT service with access/refresh token support", "priority": "P0", "verificationCriteria": "npm test -- --grep='JWT' passes", "tddPhase": "impl", "dependencies": ["P0-005"]},
-  {"id": "P1-001", "content": "Write integration tests for login flow (valid creds, invalid, locked account)", "priority": "P1", "verificationCriteria": "Integration tests exist, fail until endpoint implemented", "tddPhase": "test", "dependencies": ["P0-006"]},
-  {"id": "P1-002", "content": "Implement login endpoint with rate limiting and audit logging", "priority": "P1", "verificationCriteria": "All login tests pass, endpoint returns 200/401 correctly", "tddPhase": "impl", "dependencies": ["P1-001"]},
-  {"id": "P1-003", "content": "Run full test suite and verify all tests pass", "priority": "P1", "verificationCriteria": "npm test exits with code 0, coverage > 80%", "tddPhase": "verify", "dependencies": ["P1-002"]}
-]
-
-## CRITICAL RULES
-1. EVERY task MUST have verificationCriteria - this is non-negotiable!
-2. EVERY implementation step should have a corresponding test step BEFORE it
-3. Use tddPhase: "test" for writing tests, "impl" for implementation
-4. Dependencies must form a valid DAG - no cycles
-5. Be SPECIFIC - not "Add tests" but "Write tests for X covering Y and Z"
-6. End with verification that ALL original requirements are met
-7. Use P0 for foundation and core features, P1 for required work, P2 for nice-to-have
-
-NOW: Generate the implementation plan for the task above. Think step by step.`;
-            // Create temporary session for the AI call using Opus 4.5 for deep reasoning
-            const session = new Session({
-                workingDir: process.cwd(),
-                mux: this.mux,
-                useMux: false, // No mux needed for one-shot
-                mode: 'claude',
-            });
-            // Use configured model for plan generation, falling back to opus
-            const planModelConfig = await this.getModelConfig();
-            const modelToUse = planModelConfig?.agentTypeOverrides?.implement || planModelConfig?.defaultModel || 'opus';
-            try {
-                const { result, cost } = await session.runPrompt(prompt, { model: modelToUse });
-                // Parse JSON from result
-                const jsonMatch = result.match(/\[[\s\S]*\]/);
-                if (!jsonMatch) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Failed to parse plan - no JSON array found');
-                }
-                let items;
-                try {
-                    const parsed = JSON.parse(jsonMatch[0]);
-                    if (!Array.isArray(parsed)) {
-                        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Invalid response - expected array');
-                    }
-                    // Validate and normalize items with enhanced fields
-                    items = parsed.map((item, idx) => {
-                        if (typeof item !== 'object' || item === null) {
-                            return {
-                                id: `task-${idx}`,
-                                content: `Step ${idx + 1}`,
-                                priority: null,
-                                verificationCriteria: 'Task completed successfully',
-                                status: 'pending',
-                                attempts: 0,
-                                version: 1,
-                            };
-                        }
-                        const obj = item;
-                        const content = typeof obj.content === 'string' ? obj.content.slice(0, 200) : `Step ${idx + 1}`;
-                        let priority = null;
-                        if (obj.priority === 'P0' || obj.priority === 'P1' || obj.priority === 'P2') {
-                            priority = obj.priority;
-                        }
-                        // Parse tddPhase
-                        let tddPhase;
-                        if (obj.tddPhase === 'setup' ||
-                            obj.tddPhase === 'test' ||
-                            obj.tddPhase === 'impl' ||
-                            obj.tddPhase === 'verify') {
-                            tddPhase = obj.tddPhase;
-                        }
-                        return {
-                            id: obj.id ? String(obj.id) : `task-${idx}`,
-                            content,
-                            priority,
-                            verificationCriteria: typeof obj.verificationCriteria === 'string' ? obj.verificationCriteria : 'Task completed successfully',
-                            tddPhase,
-                            dependencies: Array.isArray(obj.dependencies) ? obj.dependencies.map(String) : [],
-                            status: 'pending',
-                            attempts: 0,
-                            version: 1,
-                        };
-                    });
-                    // No artificial limit - let Claude generate what's needed
-                }
-                catch (parseErr) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Failed to parse plan JSON: ' + getErrorMessage(parseErr));
-                }
-                return {
-                    success: true,
-                    data: { items, costUsd: cost },
-                };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Plan generation failed: ' + getErrorMessage(err));
-            }
-            finally {
-                // Clean up the temporary session
-                try {
-                    await session.stop();
-                }
-                catch {
-                    // Ignore cleanup errors
-                }
-            }
-        });
-        // Generate detailed implementation plan using subagent orchestration
-        // This spawns multiple specialist subagents in parallel for thorough analysis
-        this.app.post('/api/generate-plan-detailed', async (req) => {
-            const gpdResult = GeneratePlanDetailedSchema.safeParse(req.body);
-            if (!gpdResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { taskDescription, caseName } = gpdResult.data;
-            // Determine output directory for saving wizard results
-            let outputDir;
-            if (caseName) {
-                const casesDir = join(homedir(), 'codeman-cases');
-                const casePath = join(casesDir, caseName);
-                // Security: Path traversal protection - use relative path check
-                const resolvedCase = resolve(casePath);
-                const resolvedBase = resolve(casesDir);
-                const relPath = relative(resolvedBase, resolvedCase);
-                if (!relPath.startsWith('..') && !isAbsolute(relPath) && existsSync(casePath)) {
-                    outputDir = join(casePath, 'ralph-wizard');
-                    // Clear old ralph-wizard directory to ensure fresh prompts for each generation
-                    // This prevents stale prompts from previous runs being shown when clicking on agents
-                    if (existsSync(outputDir)) {
-                        try {
-                            rmSync(outputDir, { recursive: true, force: true });
-                            console.log(`[API] Cleared old ralph-wizard directory: ${outputDir}`);
-                        }
-                        catch (err) {
-                            console.warn(`[API] Failed to clear ralph-wizard directory:`, err);
-                        }
-                    }
-                }
-            }
-            const detailedModelConfig = await this.getModelConfig();
-            const orchestrator = new PlanOrchestrator(this.mux, process.cwd(), outputDir, detailedModelConfig ?? undefined);
-            // Store orchestrator for potential cancellation via API (not on disconnect)
-            // Plan generation continues even if browser disconnects - only explicit cancel stops it
-            const orchestratorId = `plan-${Date.now()}`;
-            this.activePlanOrchestrators.set(orchestratorId, orchestrator);
-            // Broadcast the orchestrator ID so frontend can cancel if needed
-            this.broadcast('plan:started', { orchestratorId });
-            // Track progress for SSE updates
-            const progressUpdates = [];
-            const onProgress = (phase, detail) => {
-                const update = { phase, detail, timestamp: Date.now() };
-                progressUpdates.push(update);
-                // Broadcast progress to connected clients
-                this.broadcast('plan:progress', update);
-            };
-            // Broadcast plan subagent events for UI visibility
-            const onSubagent = (event) => {
-                this.broadcast('plan:subagent', event);
-            };
-            try {
-                const result = await orchestrator.generateDetailedPlan(taskDescription, onProgress, onSubagent);
-                // Clean up orchestrator from active map
-                this.activePlanOrchestrators.delete(orchestratorId);
-                this.broadcast('plan:completed', { orchestratorId, success: result.success });
-                if (!result.success) {
-                    return createErrorResponse(ApiErrorCode.OPERATION_FAILED, result.error || 'Plan generation failed');
-                }
-                return {
-                    success: true,
-                    data: {
-                        items: result.items,
-                        costUsd: result.costUsd,
-                        metadata: result.metadata,
-                        progressLog: progressUpdates,
-                        orchestratorId,
-                    },
-                };
-            }
-            catch (err) {
-                // Clean up on error too
-                this.activePlanOrchestrators.delete(orchestratorId);
-                this.broadcast('plan:completed', {
-                    orchestratorId,
-                    success: false,
-                    error: getErrorMessage(err),
-                });
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Detailed plan generation failed: ' + getErrorMessage(err));
-            }
-        });
-        // Cancel active plan generation
-        this.app.post('/api/cancel-plan-generation', async (req) => {
-            const cpResult = CancelPlanSchema.safeParse(req.body);
-            if (!cpResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const { orchestratorId } = cpResult.data;
-            // If specific orchestrator ID provided, cancel just that one
-            if (orchestratorId) {
-                const orchestrator = this.activePlanOrchestrators.get(orchestratorId);
-                if (!orchestrator) {
-                    return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Plan generation not found or already completed');
-                }
-                console.log(`[API] Cancelling plan generation ${orchestratorId}`);
-                await orchestrator.cancel();
-                this.activePlanOrchestrators.delete(orchestratorId);
-                this.broadcast('plan:cancelled', { orchestratorId });
-                return { success: true, data: { cancelled: orchestratorId } };
-            }
-            // Otherwise cancel all active plan generations
-            const cancelled = [];
-            for (const [id, orchestrator] of this.activePlanOrchestrators) {
-                console.log(`[API] Cancelling plan generation ${id}`);
-                await orchestrator.cancel();
-                cancelled.push(id);
-                this.broadcast('plan:cancelled', { orchestratorId: id });
-            }
-            this.activePlanOrchestrators.clear();
-            return { success: true, data: { cancelled } };
-        });
-        // Get ralph-wizard files for a case (prompts and results)
-        this.app.get('/api/cases/:caseName/ralph-wizard/files', async (req) => {
-            const { caseName } = req.params;
-            const casesDir = join(homedir(), 'codeman-cases');
-            let casePath = join(casesDir, caseName);
-            // Security: Path traversal protection - use relative path check
-            const resolvedCase = resolve(casePath);
-            const resolvedBase = resolve(casesDir);
-            const relPath = relative(resolvedBase, resolvedCase);
-            if (relPath.startsWith('..') || isAbsolute(relPath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
-            }
-            // Check linked cases if path doesn't exist
-            if (!existsSync(casePath)) {
-                const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-                try {
-                    const linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-                    if (linkedCases[caseName]) {
-                        casePath = linkedCases[caseName];
-                    }
-                }
-                catch {
-                    // No linked cases file
-                }
-            }
-            const wizardDir = join(casePath, 'ralph-wizard');
-            if (!existsSync(wizardDir)) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Ralph wizard directory not found');
-            }
-            // List all subdirectories and their files
-            const files = [];
-            const entries = readdirSync(wizardDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (entry.isDirectory()) {
-                    const agentDir = join(wizardDir, entry.name);
-                    const agentFiles = {
-                        agentType: entry.name,
-                    };
-                    if (existsSync(join(agentDir, 'prompt.md'))) {
-                        agentFiles.promptFile = `${entry.name}/prompt.md`;
-                    }
-                    if (existsSync(join(agentDir, 'result.json'))) {
-                        agentFiles.resultFile = `${entry.name}/result.json`;
-                    }
-                    if (agentFiles.promptFile || agentFiles.resultFile) {
-                        files.push(agentFiles);
-                    }
-                }
-            }
-            return { success: true, data: { files, caseName } };
-        });
-        // Read a specific ralph-wizard file
-        // Cache disabled to ensure fresh prompts when starting new plan generations
-        this.app.get('/api/cases/:caseName/ralph-wizard/file/:filePath', async (req, reply) => {
-            const { caseName, filePath } = req.params;
-            const casesDir = join(homedir(), 'codeman-cases');
-            let casePath = join(casesDir, caseName);
-            // Prevent browser caching - prompts change between plan generations
-            reply.header('Cache-Control', 'no-store, no-cache, must-revalidate');
-            reply.header('Pragma', 'no-cache');
-            reply.header('Expires', '0');
-            // Security: Path traversal protection for case name - use relative path check
-            const resolvedCase = resolve(casePath);
-            const resolvedBase = resolve(casesDir);
-            const relPath = relative(resolvedBase, resolvedCase);
-            if (relPath.startsWith('..') || isAbsolute(relPath)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
-            }
-            // Check linked cases if path doesn't exist
-            if (!existsSync(casePath)) {
-                const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-                try {
-                    const linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-                    if (linkedCases[caseName]) {
-                        casePath = linkedCases[caseName];
-                    }
-                }
-                catch {
-                    // No linked cases file
-                }
-            }
-            const wizardDir = join(casePath, 'ralph-wizard');
-            // Decode the file path (it may be URL encoded)
-            const decodedPath = decodeURIComponent(filePath);
-            const fullPath = join(wizardDir, decodedPath);
-            // Security: ensure path is within wizard directory
-            const resolvedPath = resolve(fullPath);
-            const resolvedWizard = resolve(wizardDir);
-            if (!resolvedPath.startsWith(resolvedWizard)) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid file path');
-            }
-            let content;
-            try {
-                content = await fs.readFile(fullPath, 'utf-8');
-            }
-            catch (err) {
-                if (err.code === 'ENOENT') {
-                    return createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found');
-                }
-                throw err;
-            }
-            const isJson = filePath.endsWith('.json');
-            // Parse JSON content safely (may contain invalid JSON or unescaped control characters)
-            let parsed = null;
-            if (isJson) {
-                try {
-                    parsed = JSON.parse(content);
-                }
-                catch {
-                    // Try repairing common JSON issues (unescaped control characters, trailing commas)
-                    try {
-                        let repaired = content;
-                        // Fix trailing commas before closing brackets
-                        repaired = repaired.replace(/,(\s*[\]}])/g, '$1');
-                        // Fix unescaped control characters within JSON strings
-                        repaired = repaired.replace(/"([^"\\]|\\.)*"/g, (match) => {
-                            return match
-                                .replace(/\n/g, '\\n')
-                                .replace(/\r/g, '\\r')
-                                .replace(/\t/g, '\\t')
-                                .replace(
-                            // eslint-disable-next-line no-control-regex
-                            /[\x00-\x1f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
-                        });
-                        parsed = JSON.parse(repaired);
-                    }
-                    catch {
-                        // Still invalid - return null for parsed, content available as raw string
-                    }
-                }
-            }
-            return {
-                success: true,
-                data: {
-                    content,
-                    filePath: decodedPath,
-                    isJson,
-                    parsed,
-                },
-            };
-        });
-        // ============ Plan Management Endpoints ============
-        // These endpoints support runtime plan adaptation with checkpoints, failure tracking, and versioning
-        // Update a specific plan task (status, attempts, errors)
-        this.app.patch('/api/sessions/:id/plan/task/:taskId', async (req) => {
-            const { id, taskId } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = session.ralphTracker;
-            if (!tracker) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
-            }
-            const ptuResult = PlanTaskUpdateSchema.safeParse(req.body);
-            if (!ptuResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const update = ptuResult.data;
-            const result = tracker.updatePlanTask(taskId, update);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, result.error || 'Task not found');
-            }
-            this.broadcast('session:planTaskUpdate', { sessionId: id, taskId, update: result.task });
-            return { success: true, data: result.task };
-        });
-        // Trigger a checkpoint review (at iterations 5, 10, 20, etc.)
-        this.app.post('/api/sessions/:id/plan/checkpoint', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = session.ralphTracker;
-            if (!tracker) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
-            }
-            const checkpoint = tracker.generateCheckpointReview();
-            this.broadcast('session:planCheckpoint', { sessionId: id, checkpoint });
-            return { success: true, data: checkpoint };
-        });
-        // Get plan version history
-        this.app.get('/api/sessions/:id/plan/history', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = session.ralphTracker;
-            if (!tracker) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
-            }
-            return { success: true, data: tracker.getPlanHistory() };
-        });
-        // Rollback to a previous plan version
-        this.app.post('/api/sessions/:id/plan/rollback/:version', async (req) => {
-            const { id, version } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = session.ralphTracker;
-            if (!tracker) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
-            }
-            const result = tracker.rollbackToVersion(parseInt(version, 10));
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, result.error || 'Version not found');
-            }
-            this.broadcast('session:planRollback', { sessionId: id, version: parseInt(version, 10) });
-            return { success: true, data: result.plan };
-        });
-        // Add a new task to the plan (for runtime adaptation)
-        this.app.post('/api/sessions/:id/plan/task', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const tracker = session.ralphTracker;
-            if (!tracker) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
-            }
-            const ptaResult = PlanTaskAddSchema.safeParse(req.body);
-            if (!ptaResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const task = ptaResult.data;
-            const result = tracker.addPlanTask(task);
-            this.broadcast('session:planTaskAdded', { sessionId: id, task: result.task });
-            return { success: true, data: result.task };
-        });
-        // ============ App Settings Endpoints ============
-        const settingsPath = join(homedir(), '.codeman', 'settings.json');
-        this.app.get('/api/settings', async () => {
-            try {
-                const content = await fs.readFile(settingsPath, 'utf-8');
-                return JSON.parse(content);
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.error('Failed to read settings:', err);
-                }
-            }
-            return {};
-        });
-        this.app.put('/api/settings', async (req) => {
-            const settingsResult = SettingsUpdateSchema.safeParse(req.body);
-            if (!settingsResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid settings');
-            }
-            const settings = settingsResult.data;
-            try {
-                const dir = dirname(settingsPath);
-                if (!existsSync(dir)) {
-                    mkdirSync(dir, { recursive: true });
-                }
-                let existing = {};
-                try {
-                    existing = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
-                }
-                catch {
-                    /* ignore */
-                }
-                const merged = { ...existing, ...settings };
-                await fs.writeFile(settingsPath, JSON.stringify(merged, null, 2));
-                // Handle subagent tracking toggle dynamically
-                const subagentEnabled = settings.subagentTrackingEnabled ?? true;
-                if (subagentEnabled && !subagentWatcher.isRunning()) {
-                    subagentWatcher.start();
-                    console.log('Subagent watcher started via settings change');
-                }
-                else if (!subagentEnabled && subagentWatcher.isRunning()) {
-                    subagentWatcher.stop();
-                    console.log('Subagent watcher stopped via settings change');
-                }
-                // Handle image watcher toggle dynamically
-                const imageWatcherEnabled = settings.imageWatcherEnabled ?? false;
-                if (imageWatcherEnabled && !imageWatcher.isRunning()) {
-                    imageWatcher.start();
-                    // Re-watch all active sessions that have image watcher enabled
-                    for (const session of this.sessions.values()) {
-                        if (session.imageWatcherEnabled) {
-                            imageWatcher.watchSession(session.id, session.workingDir);
-                        }
-                    }
-                    console.log('Image watcher started via settings change');
-                }
-                else if (!imageWatcherEnabled && imageWatcher.isRunning()) {
-                    imageWatcher.stop();
-                    console.log('Image watcher stopped via settings change');
-                }
-                // Handle tunnel toggle dynamically
-                if ('tunnelEnabled' in settings) {
-                    const tunnelEnabled = settings.tunnelEnabled;
-                    if (tunnelEnabled && !this.tunnelManager.isRunning()) {
-                        this.tunnelManager.start(this.port, this.https);
-                        console.log('Tunnel started via settings change');
-                    }
-                    else if (tunnelEnabled && this.tunnelManager.isRunning() && this.tunnelManager.getUrl()) {
-                        // Tunnel already running — re-emit so the client gets the URL
-                        this.broadcast('tunnel:started', { url: this.tunnelManager.getUrl() });
-                        console.log('Tunnel already running, re-broadcast URL to client');
-                    }
-                    else if (!tunnelEnabled && this.tunnelManager.isRunning()) {
-                        this.tunnelManager.stop();
-                        console.log('Tunnel stopped via settings change');
-                    }
-                }
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // ============ Model Configuration Endpoints ============
-        this.app.get('/api/execution/model-config', async () => {
-            try {
-                const content = await fs.readFile(settingsPath, 'utf-8');
-                const settings = JSON.parse(content);
-                return { success: true, data: settings.modelConfig || {} };
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.error('Failed to read model config:', err);
-                }
-                return { success: true, data: {} };
-            }
-        });
-        this.app.put('/api/execution/model-config', async (req) => {
-            const mcResult = ModelConfigUpdateSchema.safeParse(req.body);
-            if (!mcResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid model config');
-            }
-            const modelConfig = mcResult.data;
-            try {
-                let settings = {};
-                try {
-                    const content = await fs.readFile(settingsPath, 'utf-8');
-                    settings = JSON.parse(content);
-                }
-                catch {
-                    // File doesn't exist yet, start fresh
-                }
-                settings.modelConfig = modelConfig;
-                const dir = dirname(settingsPath);
-                if (!existsSync(dir)) {
-                    mkdirSync(dir, { recursive: true });
-                }
-                await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // ============ CPU Priority Endpoints ============
-        // Get Nice priority config for a session
-        this.app.get('/api/sessions/:id/cpu-limit', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            return {
-                success: true,
-                nice: session.niceConfig,
-            };
-        });
-        // Update Nice priority config for a session
-        // Note: Changes only apply to NEW sessions, not running ones
-        this.app.post('/api/sessions/:id/cpu-limit', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            const clResult = CpuLimitSchema.safeParse(req.body);
-            if (!clResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-            }
-            const body = clResult.data;
-            session.setNice(body);
-            this.persistSessionState(session);
-            this.broadcast('session:updated', { session: this.getSessionStateWithRespawn(session) });
-            return {
-                success: true,
-                nice: session.niceConfig,
-                note: 'Nice priority only affects newly created mux sessions, not currently running ones.',
-            };
-        });
-        // ============ Subagent Window State Endpoints ============
-        // Persists minimized/open window states for cross-browser sync
-        const windowStatesPath = join(homedir(), '.codeman', 'subagent-window-states.json');
-        this.app.get('/api/subagent-window-states', async () => {
-            try {
-                const content = await fs.readFile(windowStatesPath, 'utf-8');
-                return JSON.parse(content);
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.error('Failed to read subagent window states:', err);
-                }
-            }
-            return { minimized: {}, open: [] };
-        });
-        this.app.put('/api/subagent-window-states', async (req) => {
-            const swResult = SubagentWindowStatesSchema.safeParse(req.body);
-            if (!swResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid window states');
-            }
-            const states = swResult.data;
-            try {
-                const dir = dirname(windowStatesPath);
-                if (!existsSync(dir)) {
-                    mkdirSync(dir, { recursive: true });
-                }
-                await fs.writeFile(windowStatesPath, JSON.stringify(states, null, 2));
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // ============ Subagent Parent Associations ============
-        // Persists which TAB each agent window connects to.
-        // This is the PERMANENT record of agent -> tab associations.
-        const parentMapPath = join(homedir(), '.codeman', 'subagent-parents.json');
-        this.app.get('/api/subagent-parents', async () => {
-            try {
-                const content = await fs.readFile(parentMapPath, 'utf-8');
-                return JSON.parse(content);
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    console.error('Failed to read subagent parent map:', err);
-                }
-            }
-            return {};
-        });
-        this.app.put('/api/subagent-parents', async (req) => {
-            const spResult = SubagentParentMapSchema.safeParse(req.body);
-            if (!spResult.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid parent map');
-            }
-            const parentMap = spResult.data;
-            try {
-                const dir = dirname(parentMapPath);
-                if (!existsSync(dir)) {
-                    mkdirSync(dir, { recursive: true });
-                }
-                await fs.writeFile(parentMapPath, JSON.stringify(parentMap, null, 2));
-                return { success: true };
-            }
-            catch (err) {
-                return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
-            }
-        });
-        // ============ Mux Session Management Endpoints ============
-        // Get all tracked mux sessions with stats
-        this.app.get('/api/mux-sessions', async () => {
-            const sessions = await this.mux.getSessionsWithStats();
-            return {
-                sessions,
-                muxAvailable: this.mux.isAvailable(),
-            };
-        });
-        // Kill a mux session
-        this.app.delete('/api/mux-sessions/:sessionId', async (req) => {
-            const { sessionId } = req.params;
-            const success = await this.mux.killSession(sessionId);
-            return { success };
-        });
-        // Reconcile mux sessions (find dead ones)
-        this.app.post('/api/mux-sessions/reconcile', async () => {
-            const result = await this.mux.reconcileSessions();
-            return result;
-        });
-        // Start stats collection
-        this.app.post('/api/mux-sessions/stats/start', async () => {
-            this.mux.startStatsCollection(STATS_COLLECTION_INTERVAL_MS);
-            return { success: true };
-        });
-        // Stop stats collection
-        this.app.post('/api/mux-sessions/stats/stop', async () => {
-            this.mux.stopStatsCollection();
-            return { success: true };
-        });
-        // System stats endpoint for frontend header display
-        this.app.get('/api/system/stats', async () => {
-            return this.getSystemStats();
-        });
-        // ========== Subagent Monitoring (Claude Code Background Agents) ==========
-        // List all known subagents
-        this.app.get('/api/subagents', async (req) => {
-            const { minutes } = req.query;
-            const subagents = minutes
-                ? subagentWatcher.getRecentSubagents(parseInt(minutes, 10))
-                : subagentWatcher.getSubagents();
-            return { success: true, data: subagents };
-        });
-        // Get subagents for a specific session (by working directory)
-        this.app.get('/api/sessions/:id/subagents', async (req) => {
-            const { id } = req.params;
-            const session = this.sessions.get(id);
-            if (!session) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, `Session ${id} not found`);
-            }
-            const subagents = subagentWatcher.getSubagentsForSession(session.workingDir);
-            return { success: true, data: subagents };
+        }
+        else {
+            this.app = Fastify({ logger: false });
+        }
+        this.mux = createMultiplexer();
+        // Set up mux event listeners
+        this.mux.on('sessionCreated', (session) => {
+            this.broadcast('mux:created', session);
         });
-        // Get a specific subagent's info
-        this.app.get('/api/subagents/:agentId', async (req) => {
-            const { agentId } = req.params;
-            const info = subagentWatcher.getSubagent(agentId);
-            if (!info) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, `Subagent ${agentId} not found`);
-            }
-            return { success: true, data: info };
+        this.mux.on('sessionKilled', (data) => {
+            this.broadcast('mux:killed', data);
         });
-        // Get a subagent's transcript
-        this.app.get('/api/subagents/:agentId/transcript', async (req) => {
-            const { agentId } = req.params;
-            const { limit, format } = req.query;
-            const limitNum = limit ? parseInt(limit, 10) : undefined;
-            const transcript = await subagentWatcher.getTranscript(agentId, limitNum);
-            if (format === 'formatted') {
-                const formatted = subagentWatcher.formatTranscript(transcript);
-                return { success: true, data: { formatted, entryCount: transcript.length } };
-            }
-            return { success: true, data: transcript };
+        this.mux.on('sessionDied', (data) => {
+            getLifecycleLog().log({
+                event: 'mux_died',
+                sessionId: data.sessionId || 'unknown',
+                extra: data,
+            });
+            this.broadcast('mux:died', data);
         });
-        // Kill a subagent
-        this.app.delete('/api/subagents/:agentId', async (req) => {
-            const { agentId } = req.params;
-            const info = subagentWatcher.getSubagent(agentId);
-            if (!info) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subagent not found');
-            }
-            const killed = await subagentWatcher.killSubagent(agentId);
-            if (killed) {
-                return { success: true, data: { agentId, status: 'killed' } };
-            }
-            return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Subagent not found or already completed');
+        this.mux.on('statsUpdated', (sessions) => {
+            this.broadcast('mux:statsUpdated', sessions);
         });
-        // Trigger cleanup of stale subagents
-        this.app.post('/api/subagents/cleanup', async () => {
-            const removed = subagentWatcher.cleanupNow();
-            return { success: true, data: { removed, remaining: subagentWatcher.getSubagents().length } };
+        // Set up subagent watcher listeners
+        this.setupSubagentWatcherListeners();
+        // Set up image watcher listeners
+        this.setupImageWatcherListeners();
+        // Set up team watcher listeners
+        this.setupTeamWatcherListeners();
+        // Set up tunnel manager listeners
+        this.tunnelManager.on('started', (data) => {
+            this.broadcast('tunnel:started', data);
         });
-        // Clear all tracked subagents (memory only - does not delete files)
-        this.app.delete('/api/subagents', async () => {
-            const cleared = subagentWatcher.clearAll();
-            return { success: true, data: { cleared } };
+        this.tunnelManager.on('stopped', () => {
+            this.broadcast('tunnel:stopped', {});
         });
-        // ========== Agent Teams ==========
-        // List all discovered teams
-        this.app.get('/api/teams', async () => {
-            return { success: true, data: this.teamWatcher.getTeams() };
+        this.tunnelManager.on('error', (message) => {
+            this.broadcast('tunnel:error', { message });
         });
-        // Get tasks for a specific team
-        this.app.get('/api/teams/:name/tasks', async (req) => {
-            const { name } = req.params;
-            return { success: true, data: this.teamWatcher.getTeamTasks(name) };
+        this.tunnelManager.on('progress', (data) => {
+            this.broadcast('tunnel:progress', data);
         });
-        // ========== Hook Events ==========
-        this.app.post('/api/hook-event', async (req) => {
-            const result = HookEventSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { event, sessionId, data } = result.data;
-            if (!this.sessions.has(sessionId)) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-            }
-            // Signal the respawn controller based on hook event type
-            const controller = this.respawnControllers.get(sessionId);
-            if (controller) {
-                if (event === 'elicitation_dialog') {
-                    // Block auto-accept for question prompts
-                    controller.signalElicitation();
-                }
-                else if (event === 'stop') {
-                    // DEFINITIVE idle signal - Claude finished responding
-                    controller.signalStopHook();
+        // QR token rotation — broadcast inline SVG for instant desktop refresh
+        this.tunnelManager.on('qrTokenRotated', async () => {
+            const url = this.tunnelManager.getUrl();
+            if (url && process.env.CODEMAN_PASSWORD) {
+                try {
+                    const svg = await this.tunnelManager.getQrSvg(url);
+                    this.broadcast('tunnel:qrRotated', { svg });
                 }
-                else if (event === 'idle_prompt') {
-                    // DEFINITIVE idle signal - Claude has been idle for 60+ seconds
-                    controller.signalIdlePrompt();
+                catch {
+                    // QR generation failed — skip this rotation
                 }
             }
-            // Start transcript watching if transcript_path is provided and safe
-            if (data && 'transcript_path' in data) {
-                const transcriptPath = String(data.transcript_path);
-                if (transcriptPath && isValidWorkingDir(transcriptPath)) {
-                    this.startTranscriptWatcher(sessionId, transcriptPath);
+        });
+        this.tunnelManager.on('qrTokenRegenerated', async () => {
+            const url = this.tunnelManager.getUrl();
+            if (url && process.env.CODEMAN_PASSWORD) {
+                try {
+                    const svg = await this.tunnelManager.getQrSvg(url);
+                    this.broadcast('tunnel:qrRegenerated', { svg });
+                }
+                catch {
+                    // QR generation failed — skip
                 }
             }
-            // Sanitize forwarded data: only include known safe fields, limit size
-            const safeData = sanitizeHookData(data);
-            this.broadcast(`hook:${event}`, { sessionId, timestamp: Date.now(), ...safeData });
-            // Send push notifications for hook events
-            const session = this.sessions.get(sessionId);
-            const sessionName = session?.name ?? sessionId.slice(0, 8);
-            this.sendPushNotifications(`hook:${event}`, { sessionId, sessionName, ...safeData });
-            // Track in run summary
-            const summaryTracker = this.runSummaryTrackers.get(sessionId);
-            if (summaryTracker) {
-                summaryTracker.recordHookEvent(event, safeData);
-            }
-            return { success: true };
-        });
-        // ========== Web Push ==========
-        this.app.get('/api/push/vapid-key', async () => {
-            return { success: true, data: { publicKey: this.pushStore.getPublicKey() } };
         });
-        this.app.post('/api/push/subscribe', async (req) => {
-            const result = PushSubscribeSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const { endpoint, keys, userAgent, pushPreferences } = result.data;
-            const record = this.pushStore.addSubscription({
-                id: uuidv4(),
-                endpoint,
-                keys,
-                userAgent: userAgent ?? req.headers['user-agent'] ?? '',
-                createdAt: Date.now(),
-                pushPreferences: pushPreferences ?? {},
-            });
-            return { success: true, data: { id: record.id } };
+    }
+    /**
+     * Set up event listeners for subagent watcher.
+     * Broadcasts real-time subagent activity to SSE clients.
+     *
+     * The SubagentWatcher now extracts descriptions directly from the parent session's
+     * transcript, which contains the exact Task tool call with the description parameter.
+     * This is more reliable than the previous timing-based correlation approach.
+     */
+    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),
+            error: (error, agentId) => {
+                console.error(`[SubagentWatcher] Error${agentId ? ` for ${agentId}` : ''}:`, error.message);
+            },
+        };
+        subagentWatcher.on('subagent:discovered', this.subagentWatcherHandlers.discovered);
+        subagentWatcher.on('subagent:updated', this.subagentWatcherHandlers.updated);
+        subagentWatcher.on('subagent:tool_call', this.subagentWatcherHandlers.toolCall);
+        subagentWatcher.on('subagent:tool_result', this.subagentWatcherHandlers.toolResult);
+        subagentWatcher.on('subagent:progress', this.subagentWatcherHandlers.progress);
+        subagentWatcher.on('subagent:message', this.subagentWatcherHandlers.message);
+        subagentWatcher.on('subagent:completed', this.subagentWatcherHandlers.completed);
+        subagentWatcher.on('subagent:error', this.subagentWatcherHandlers.error);
+    }
+    /**
+     * Clean up subagent watcher listeners to prevent memory leaks.
+     */
+    cleanupSubagentWatcherListeners() {
+        if (this.subagentWatcherHandlers) {
+            subagentWatcher.off('subagent:discovered', this.subagentWatcherHandlers.discovered);
+            subagentWatcher.off('subagent:updated', this.subagentWatcherHandlers.updated);
+            subagentWatcher.off('subagent:tool_call', this.subagentWatcherHandlers.toolCall);
+            subagentWatcher.off('subagent:tool_result', this.subagentWatcherHandlers.toolResult);
+            subagentWatcher.off('subagent:progress', this.subagentWatcherHandlers.progress);
+            subagentWatcher.off('subagent:message', this.subagentWatcherHandlers.message);
+            subagentWatcher.off('subagent:completed', this.subagentWatcherHandlers.completed);
+            subagentWatcher.off('subagent:error', this.subagentWatcherHandlers.error);
+            this.subagentWatcherHandlers = null;
+        }
+    }
+    /**
+     * Set up event listeners for image watcher.
+     * Broadcasts image detection events to SSE clients for auto-popup.
+     */
+    setupImageWatcherListeners() {
+        // Store handlers for cleanup on shutdown
+        this.imageWatcherHandlers = {
+            detected: (event) => this.broadcast('image:detected', event),
+            error: (error, sessionId) => {
+                console.error(`[ImageWatcher] Error${sessionId ? ` for ${sessionId}` : ''}:`, error.message);
+            },
+        };
+        imageWatcher.on('image:detected', this.imageWatcherHandlers.detected);
+        imageWatcher.on('image:error', this.imageWatcherHandlers.error);
+    }
+    /**
+     * Clean up image watcher listeners to prevent memory leaks.
+     */
+    cleanupImageWatcherListeners() {
+        if (this.imageWatcherHandlers) {
+            imageWatcher.off('image:detected', this.imageWatcherHandlers.detected);
+            imageWatcher.off('image:error', this.imageWatcherHandlers.error);
+            this.imageWatcherHandlers = null;
+        }
+    }
+    /**
+     * Set up event listeners for team watcher.
+     * Broadcasts team activity events to SSE clients.
+     */
+    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),
+        };
+        this.teamWatcher.on('teamCreated', this.teamWatcherHandlers.teamCreated);
+        this.teamWatcher.on('teamUpdated', this.teamWatcherHandlers.teamUpdated);
+        this.teamWatcher.on('teamRemoved', this.teamWatcherHandlers.teamRemoved);
+        this.teamWatcher.on('taskUpdated', this.teamWatcherHandlers.taskUpdated);
+    }
+    /**
+     * Clean up team watcher listeners to prevent memory leaks.
+     */
+    cleanupTeamWatcherListeners() {
+        if (this.teamWatcherHandlers) {
+            this.teamWatcher.off('teamCreated', this.teamWatcherHandlers.teamCreated);
+            this.teamWatcher.off('teamUpdated', this.teamWatcherHandlers.teamUpdated);
+            this.teamWatcher.off('teamRemoved', this.teamWatcherHandlers.teamRemoved);
+            this.teamWatcher.off('taskUpdated', this.teamWatcherHandlers.taskUpdated);
+            this.teamWatcherHandlers = null;
+        }
+    }
+    /**
+     * Build a route context object satisfying all 5 port interfaces.
+     * Single object with zero runtime cost — ISP enforced at the type level.
+     */
+    createRouteContext() {
+        return {
+            // SessionPort
+            sessions: this.sessions,
+            addSession: (session) => {
+                this.sessions.set(session.id, session);
+            },
+            cleanupSession: this.cleanupSession.bind(this),
+            setupSessionListeners: this.setupSessionListeners.bind(this),
+            persistSessionState: this.persistSessionState.bind(this),
+            persistSessionStateNow: this._persistSessionStateNow.bind(this),
+            getSessionStateWithRespawn: this.getSessionStateWithRespawn.bind(this),
+            // EventPort
+            broadcast: this.broadcast.bind(this),
+            sendPushNotifications: this.sendPushNotifications.bind(this),
+            batchTerminalData: this.batchTerminalData.bind(this),
+            broadcastSessionStateDebounced: this.broadcastSessionStateDebounced.bind(this),
+            batchTaskUpdate: this.batchTaskUpdate.bind(this),
+            // RespawnPort
+            respawnControllers: this.respawnControllers,
+            respawnTimers: this.respawnTimers,
+            setupRespawnListeners: this.setupRespawnListeners.bind(this),
+            setupTimedRespawn: this.setupTimedRespawn.bind(this),
+            restoreRespawnController: this.restoreRespawnController.bind(this),
+            saveRespawnConfig: this.saveRespawnConfig.bind(this),
+            // ConfigPort
+            store: this.store,
+            port: this.port,
+            https: this.https,
+            testMode: this.testMode,
+            serverStartTime: this.serverStartTime,
+            getGlobalNiceConfig: this.getGlobalNiceConfig.bind(this),
+            getModelConfig: this.getModelConfig.bind(this),
+            getClaudeModeConfig: this.getClaudeModeConfig.bind(this),
+            getDefaultClaudeMdPath: this.getDefaultClaudeMdPath.bind(this),
+            getLightState: this.getLightState.bind(this),
+            getLightSessionsState: this.getLightSessionsState.bind(this),
+            startTranscriptWatcher: this.startTranscriptWatcher.bind(this),
+            stopTranscriptWatcher: this.stopTranscriptWatcher.bind(this),
+            // InfraPort
+            mux: this.mux,
+            runSummaryTrackers: this.runSummaryTrackers,
+            activePlanOrchestrators: this.activePlanOrchestrators,
+            scheduledRuns: this.scheduledRuns,
+            teamWatcher: this.teamWatcher,
+            tunnelManager: this.tunnelManager,
+            pushStore: this.pushStore,
+            startScheduledRun: this.startScheduledRun.bind(this),
+            stopScheduledRun: this.stopScheduledRun.bind(this),
+            // AuthPort
+            authSessions: this.authSessions,
+            qrAuthFailures: this.qrAuthFailures,
+        };
+    }
+    async setupRoutes() {
+        // Allow multipart/form-data for screenshot uploads — skip Fastify's body parser
+        // so the route handler can read the raw stream directly.
+        this.app.addContentTypeParser('multipart/form-data', (_req, _payload, done) => {
+            done(null);
         });
-        this.app.put('/api/push/subscribe/:id', async (req) => {
-            const { id } = req.params;
-            const result = PushPreferencesUpdateSchema.safeParse(req.body);
-            if (!result.success) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-            }
-            const updated = this.pushStore.updatePreferences(id, result.data.pushPreferences);
-            if (!updated) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subscription not found');
-            }
-            return { success: true };
+        // Enable gzip/brotli compression for all responses.
+        // Massive win: 793KB uncompressed → ~120KB compressed for static assets.
+        // Threshold 1024 = don't compress tiny responses (headers > savings).
+        await this.app.register(fastifyCompress, {
+            threshold: 1024,
         });
-        this.app.delete('/api/push/subscribe/:id', async (req) => {
-            const { id } = req.params;
-            const removed = this.pushStore.removeSubscription(id);
-            if (!removed) {
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subscription not found');
-            }
-            return { success: true };
+        // Cookie plugin (needed for auth session tokens)
+        await this.app.register(fastifyCookie);
+        // Auth middleware (Basic Auth + session cookies + rate limiting)
+        const authState = registerAuthMiddleware(this.app, this.https);
+        if (authState) {
+            this.authSessions = authState.authSessions;
+            this.authFailures = authState.authFailures;
+            this.qrAuthFailures = authState.qrAuthFailures;
+        }
+        // Security headers + CORS
+        registerSecurityHeaders(this.app, this.https);
+        // Service worker must never be cached — browsers check for SW updates on navigation
+        this.app.get('/sw.js', async (_req, reply) => {
+            return reply
+                .header('Cache-Control', 'no-cache, no-store')
+                .header('Service-Worker-Allowed', '/')
+                .type('application/javascript')
+                .sendFile('sw.js', join(__dirname, 'public'));
         });
-        // Screenshot upload endpoint (accepts multipart/form-data)
-        // Upload form served as static file: /upload.html (src/web/public/upload.html)
-        this.app.post('/api/screenshots', async (req, reply) => {
-            const contentType = req.headers['content-type'] ?? '';
-            if (!contentType.includes('multipart/form-data')) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Expected multipart/form-data');
-            }
-            // Parse multipart boundary
-            const boundaryMatch = contentType.match(/boundary=(.+?)(?:;|$)/);
-            if (!boundaryMatch) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing boundary');
-            }
-            // Collect raw body
-            const chunks = [];
-            let totalSize = 0;
-            for await (const chunk of req.raw) {
-                totalSize += chunk.length;
-                if (totalSize > MAX_SCREENSHOT_SIZE) {
-                    reply.status(413);
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'File too large (max 10MB)');
-                }
-                chunks.push(chunk);
-            }
-            const body = Buffer.concat(chunks);
-            // Extract file from multipart body
-            const boundary = '--' + boundaryMatch[1];
-            const boundaryBuf = Buffer.from(boundary);
-            const parts = [];
-            let pos = 0;
-            // Find each part between boundaries
-            while (pos < body.length) {
-                const start = body.indexOf(boundaryBuf, pos);
-                if (start === -1)
-                    break;
-                const afterBoundary = start + boundaryBuf.length;
-                // Check for closing boundary (--)
-                if (body[afterBoundary] === 0x2d && body[afterBoundary + 1] === 0x2d)
-                    break;
-                // Skip \r\n after boundary
-                const headerStart = afterBoundary + 2;
-                const headerEnd = body.indexOf(Buffer.from('\r\n\r\n'), headerStart);
-                if (headerEnd === -1)
-                    break;
-                const headers = body.subarray(headerStart, headerEnd).toString();
-                const dataStart = headerEnd + 4;
-                const nextBoundary = body.indexOf(boundaryBuf, dataStart);
-                // Data ends 2 bytes before next boundary (\r\n)
-                const dataEnd = nextBoundary === -1 ? body.length : nextBoundary - 2;
-                parts.push({ headers, data: body.subarray(dataStart, dataEnd) });
-                pos = nextBoundary === -1 ? body.length : nextBoundary;
-            }
-            const filePart = parts.find((p) => p.headers.includes('name="file"'));
-            if (!filePart || filePart.data.length === 0) {
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'No file uploaded');
-            }
-            // Determine extension from Content-Type or filename
-            let ext = '.png';
-            const filenameMatch = filePart.headers.match(/filename="(.+?)"/);
-            if (filenameMatch) {
-                const origExt = filenameMatch[1].match(/\.(png|jpg|jpeg|webp|gif)$/i);
-                if (origExt)
-                    ext = origExt[0].toLowerCase();
-            }
-            const ctMatch = filePart.headers.match(/Content-Type:\s*image\/(png|jpeg|webp|gif)/i);
-            if (ctMatch) {
-                const map = {
-                    png: '.png',
-                    jpeg: '.jpg',
-                    webp: '.webp',
-                    gif: '.gif',
-                };
-                ext = map[ctMatch[1].toLowerCase()] ?? ext;
-            }
-            // Save to ~/.codeman/screenshots/
-            if (!existsSync(SCREENSHOTS_DIR)) {
-                mkdirSync(SCREENSHOTS_DIR, { recursive: true });
-            }
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
-            const filename = `screenshot_${timestamp}${ext}`;
-            const filepath = join(SCREENSHOTS_DIR, filename);
-            await fs.writeFile(filepath, filePart.data);
-            return { success: true, path: filepath, filename };
+        // Serve static files — versioned assets (?v=X) are immutable, cache aggressively
+        // preCompressed: serve pre-built .br/.gz files (from build step) to avoid per-request CPU compression
+        await this.app.register(fastifyStatic, {
+            root: join(__dirname, 'public'),
+            prefix: '/',
+            maxAge: '1y',
+            immutable: true,
+            preCompressed: true,
         });
-        // List screenshots
-        this.app.get('/api/screenshots', async () => {
-            if (!existsSync(SCREENSHOTS_DIR)) {
-                return { files: [] };
+        // SSE endpoint for real-time updates
+        this.app.get('/api/events', (req, reply) => {
+            // Enforce SSE client limit to prevent memory exhaustion from too many connections
+            if (this.sseClients.size >= MAX_SSE_CLIENTS) {
+                reply.code(503).send('Too many SSE connections');
+                return;
             }
-            const files = readdirSync(SCREENSHOTS_DIR)
-                .filter((f) => /\.(png|jpg|jpeg|webp|gif)$/i.test(f))
-                .sort()
-                .reverse()
-                .slice(0, 50)
-                .map((name) => ({ name, path: join(SCREENSHOTS_DIR, name) }));
-            return { files };
+            reply.raw.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no', // Disable nginx buffering
+            });
+            this.sseClients.add(reply);
+            // 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());
+            req.raw.on('close', () => {
+                this.sseClients.delete(reply);
+                this.backpressuredClients.delete(reply);
+            });
         });
-        // Serve individual screenshot
-        this.app.get('/api/screenshots/:name', async (req, reply) => {
-            const { name } = req.params;
-            // Prevent path traversal
-            if (name.includes('/') || name.includes('\\') || name.includes('..')) {
-                reply.status(400);
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid filename');
+        // Global error handler for structured errors thrown by findSessionOrFail
+        this.app.setErrorHandler((error, _req, reply) => {
+            const statusCode = error.statusCode ?? 500;
+            const body = error.body;
+            if (body) {
+                reply.code(statusCode).send(body);
             }
-            const filepath = join(SCREENSHOTS_DIR, name);
-            if (!existsSync(filepath)) {
-                reply.status(404);
-                return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Screenshot not found');
-            }
-            const ext = name.match(/\.(png|jpg|jpeg|webp|gif)$/i)?.[1]?.toLowerCase() ?? 'png';
-            const mimeMap = {
-                png: 'image/png',
-                jpg: 'image/jpeg',
-                jpeg: 'image/jpeg',
-                webp: 'image/webp',
-                gif: 'image/gif',
-            };
-            reply.type(mimeMap[ext] ?? 'image/png');
-            return fs.readFile(filepath);
-        });
+            else {
+                reply.code(statusCode).send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(error)));
+            }
+        });
+        // Register all route modules
+        const ctx = this.createRouteContext();
+        registerPushRoutes(this.app, ctx);
+        registerTeamRoutes(this.app, ctx);
+        registerMuxRoutes(this.app, ctx);
+        registerFileRoutes(this.app, ctx);
+        registerScheduledRoutes(this.app, ctx);
+        registerHookEventRoutes(this.app, ctx);
+        registerSystemRoutes(this.app, ctx);
+        registerCaseRoutes(this.app, ctx);
+        registerSessionRoutes(this.app, ctx);
+        registerRespawnRoutes(this.app, ctx);
+        registerRalphRoutes(this.app, ctx);
+        registerPlanRoutes(this.app, ctx);
     }
     /**
      * Start a transcript watcher for a session.
@@ -3936,16 +523,12 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
     }
     /** Debounced wrapper — coalesces rapid persistSessionState calls per session */
     persistSessionState(session) {
-        const existing = this.persistDebounceTimers.get(session.id);
-        if (existing)
-            clearTimeout(existing);
-        this.persistDebounceTimers.set(session.id, setTimeout(() => {
-            this.persistDebounceTimers.delete(session.id);
+        this.persistDeb.schedule(session.id, () => {
             // Session may have been removed during debounce
             if (this.sessions.has(session.id)) {
                 this._persistSessionStateNow(session);
             }
-        }, 100));
+        });
     }
     /** Persists full session state including respawn config to state.json */
     _persistSessionStateNow(session) {
@@ -4002,49 +585,6 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         };
         this.mux.updateRespawnConfig(sessionId, persistedConfig);
     }
-    // Get system CPU and memory usage
-    getSystemStats() {
-        try {
-            const totalMem = totalmem();
-            // macOS: os.freemem() only returns truly free pages, not cached/purgeable memory.
-            // Use vm_stat to get accurate used memory (wired + active + compressed).
-            let usedMem;
-            if (process.platform === 'darwin') {
-                try {
-                    const vmstat = execSync('vm_stat', { encoding: 'utf-8', timeout: 2000 });
-                    const pageSize = parseInt(vmstat.match(/page size of (\d+)/)?.[1] || '4096', 10);
-                    const wired = parseInt(vmstat.match(/Pages wired down:\s+(\d+)/)?.[1] || '0', 10);
-                    const active = parseInt(vmstat.match(/Pages active:\s+(\d+)/)?.[1] || '0', 10);
-                    const compressed = parseInt(vmstat.match(/Pages occupied by compressor:\s+(\d+)/)?.[1] || '0', 10);
-                    usedMem = (wired + active + compressed) * pageSize;
-                }
-                catch {
-                    usedMem = totalMem - freemem();
-                }
-            }
-            else {
-                usedMem = totalMem - freemem();
-            }
-            // CPU load average (1 min) as percentage (rough approximation)
-            const load = loadavg()[0];
-            const cpuCount = WebServer.CPU_COUNT;
-            const cpuPercent = Math.min(100, Math.round((load / cpuCount) * 100));
-            return {
-                cpu: cpuPercent,
-                memory: {
-                    usedMB: Math.round(usedMem / (1024 * 1024)),
-                    totalMB: Math.round(totalMem / (1024 * 1024)),
-                    percent: Math.round((usedMem / totalMem) * 100),
-                },
-            };
-        }
-        catch {
-            return {
-                cpu: 0,
-                memory: { usedMB: 0, totalMB: 0, percent: 0 },
-            };
-        }
-    }
     // Clean up all resources associated with a session
     // Track sessions currently being cleaned up to prevent concurrent cleanup races
     cleaningUp = new Set();
@@ -4119,11 +659,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
             this.runSummaryTrackers.delete(sessionId);
         }
         // Clear pending persist-debounce timer (prevents stale closure holding session ref)
-        const pendingPersist = this.persistDebounceTimers.get(sessionId);
-        if (pendingPersist) {
-            clearTimeout(pendingPersist);
-            this.persistDebounceTimers.delete(sessionId);
-        }
+        this.persistDeb.cancelKey(sessionId);
         // Clear batches, per-session timers, and pending state updates
         this.terminalBatches.delete(sessionId);
         this.terminalBatchSizes.delete(sessionId);
@@ -4332,11 +868,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
                     this.stateUpdatePending.delete(session.id);
                     this.lastTerminalEventTime.delete(session.id);
                     // Clear pending persist-debounce timer
-                    const pendingPersist = this.persistDebounceTimers.get(session.id);
-                    if (pendingPersist) {
-                        clearTimeout(pendingPersist);
-                        this.persistDebounceTimers.delete(session.id);
-                    }
+                    this.persistDeb.cancelKey(session.id);
                     // Close any active file streams
                     fileStreamManager.closeSessionStreams(session.id);
                     // Remove stored listener refs to break closure references (prevents memory leak).
@@ -5034,9 +1566,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         //   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') {
+        if (event === 'session:created' || event === 'session:deleted' || event === 'session:updated') {
             this.cachedLightState = null;
             this.cachedSessionsList = null;
         }
@@ -5143,11 +1673,11 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         // Use composite key to avoid losing updates when multiple tasks update in same batch window
         const key = `${sessionId}:${task.id}`;
         this.taskUpdateBatches.set(key, { sessionId, task });
-        if (!this.taskUpdateBatchTimer) {
-            this.taskUpdateBatchTimer = setTimeout(() => {
+        if (!this.taskUpdateBatchTimerId) {
+            this.taskUpdateBatchTimerId = this.cleanup.setTimeout(() => {
+                this.taskUpdateBatchTimerId = null;
                 this.flushTaskUpdateBatches();
-                this.taskUpdateBatchTimer = null;
-            }, TASK_UPDATE_BATCH_INTERVAL);
+            }, TASK_UPDATE_BATCH_INTERVAL, { description: 'task update batch flush' });
         }
     }
     flushTaskUpdateBatches() {
@@ -5171,11 +1701,11 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         if (this._isStopping)
             return;
         this.stateUpdatePending.add(sessionId);
-        if (!this.stateUpdateTimer) {
-            this.stateUpdateTimer = setTimeout(() => {
+        if (!this.stateUpdateTimerId) {
+            this.stateUpdateTimerId = this.cleanup.setTimeout(() => {
+                this.stateUpdateTimerId = null;
                 this.flushStateUpdates();
-                this.stateUpdateTimer = null;
-            }, STATE_UPDATE_DEBOUNCE_INTERVAL);
+            }, STATE_UPDATE_DEBOUNCE_INTERVAL, { description: 'state update debounce flush' });
         }
     }
     flushStateUpdates() {
@@ -5345,17 +1875,17 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         // Set API URL for child processes (MCP server, spawned sessions)
         process.env.CODEMAN_API_URL = `${protocol}://localhost:${this.port}`;
         // Start scheduled runs cleanup timer
-        this.scheduledCleanupTimer = setInterval(() => {
+        this.cleanup.setInterval(() => {
             this.cleanupScheduledRuns();
-        }, SCHEDULED_CLEANUP_INTERVAL);
+        }, SCHEDULED_CLEANUP_INTERVAL, { description: 'scheduled runs cleanup' });
         // Start SSE client health check timer (prevents memory leaks from dead connections)
-        this.sseHealthCheckTimer = setInterval(() => {
+        this.cleanup.setInterval(() => {
             this.cleanupDeadSSEClients();
-        }, SSE_HEALTH_CHECK_INTERVAL);
+        }, SSE_HEALTH_CHECK_INTERVAL, { description: 'SSE client health check' });
         // Start token recording timer (every 5 minutes for long-running sessions)
-        this.tokenRecordingTimer = setInterval(() => {
+        this.cleanup.setInterval(() => {
             this.recordPeriodicTokenUsage();
-        }, 5 * 60 * 1000);
+        }, 5 * 60 * 1000, { description: 'periodic token recording' });
         // Start subagent watcher for Claude Code background agent visibility (if enabled)
         if (await this.isSubagentTrackingEnabled()) {
             subagentWatcher.start();
@@ -5608,11 +2138,8 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         getLifecycleLog().log({ event: 'server_stopped', sessionId: '*' });
         // Set stopping flag to prevent new timer creation during shutdown
         this._isStopping = true;
-        // Clear SSE health check timer
-        if (this.sseHealthCheckTimer) {
-            clearInterval(this.sseHealthCheckTimer);
-            this.sseHealthCheckTimer = null;
-        }
+        // Dispose all managed timers (intervals + resettable timeouts)
+        this.cleanup.dispose();
         // Gracefully close all SSE connections before clearing
         for (const client of this.sseClients) {
             try {
@@ -5633,38 +2160,18 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         this.terminalBatchTimers.clear();
         this.terminalBatches.clear();
         this.terminalBatchSizes.clear();
-        if (this.taskUpdateBatchTimer) {
-            clearTimeout(this.taskUpdateBatchTimer);
-            this.taskUpdateBatchTimer = null;
-        }
         this.taskUpdateBatches.clear();
-        if (this.stateUpdateTimer) {
-            clearTimeout(this.stateUpdateTimer);
-            this.stateUpdateTimer = null;
-        }
         this.stateUpdatePending.clear();
-        // Clear token recording timer
-        if (this.tokenRecordingTimer) {
-            clearInterval(this.tokenRecordingTimer);
-            this.tokenRecordingTimer = null;
-        }
         this.lastRecordedTokens.clear();
-        // Clear scheduled cleanup timer
-        if (this.scheduledCleanupTimer) {
-            clearInterval(this.scheduledCleanupTimer);
-            this.scheduledCleanupTimer = null;
-        }
         // Stop multiplexer and flush pending saves
         this.mux.destroy();
         // Flush any pending persist-debounce timers and persist dirty sessions
-        for (const [sessionId, timer] of this.persistDebounceTimers) {
-            clearTimeout(timer);
+        this.persistDeb.flushAll((sessionId) => {
             const session = this.sessions.get(sessionId);
             if (session) {
                 this._persistSessionStateNow(session);
             }
-        }
-        this.persistDebounceTimers.clear();
+        });
         // Clear cached state
         this.cachedLightState = null;
         this.cachedSessionsList = null;
@@ -5771,6 +2278,10 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
             this.authFailures.dispose();
             this.authFailures = null;
         }
+        if (this.qrAuthFailures) {
+            this.qrAuthFailures.dispose();
+            this.qrAuthFailures = null;
+        }
         this.activePlanOrchestrators.clear();
         this.cleaningUp.clear();
         // Dispose push store (flush pending saves)