aegis-bridge 2.2.2

package/dist/server.js

@@ -0,0 +1,1577 @@
+/**
+ * server.ts — HTTP API server for Aegis.
+ *
+ * Exposes RESTful endpoints for creating, managing, and interacting
+ * with Claude Code sessions running in tmux.
+ *
+ * Notification channels (Telegram, webhooks, etc.) are pluggable —
+ * the server doesn't know which channels are active.
+ */
+import Fastify from 'fastify';
+import fs from 'node:fs/promises';
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import fastifyStatic from '@fastify/static';
+import fastifyWebsocket from '@fastify/websocket';
+import fastifyCors from '@fastify/cors';
+import { z } from 'zod';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { TmuxManager } from './tmux.js';
+import { SessionManager } from './session.js';
+import { SessionMonitor, DEFAULT_MONITOR_CONFIG } from './monitor.js';
+import { JsonlWatcher } from './jsonl-watcher.js';
+import { ChannelManager, TelegramChannel, WebhookChannel, } from './channels/index.js';
+import { loadConfig } from './config.js';
+import { captureScreenshot, isPlaywrightAvailable } from './screenshot.js';
+import { validateScreenshotUrl, resolveAndCheckIp } from './ssrf.js';
+import { validateWorkDir } from './validation.js';
+import { SessionEventBus } from './events.js';
+import { SSEWriter } from './sse-writer.js';
+import { SSEConnectionLimiter } from './sse-limiter.js';
+import { PipelineManager } from './pipeline.js';
+import { AuthManager } from './auth.js';
+import { MetricsCollector } from './metrics.js';
+import { registerHookRoutes } from './hooks.js';
+import { registerWsTerminalRoute } from './ws-terminal.js';
+import { SwarmMonitor } from './swarm-monitor.js';
+import { execSync } from 'node:child_process';
+import { authKeySchema, sendMessageSchema, commandSchema, bashSchema, screenshotSchema, permissionHookSchema, stopHookSchema, batchSessionSchema, pipelineSchema, parseIntSafe, } from './validation.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// ── Configuration ────────────────────────────────────────────────────
+// Issue #349: CSP policy for dashboard responses (shared between static and SPA fallback)
+const DASHBOARD_CSP = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ws: wss:";
+// Config loaded at startup; env vars override file values
+let config;
+// These will be initialized after config is loaded
+let tmux;
+let sessions;
+let monitor;
+let jsonlWatcher;
+const channels = new ChannelManager();
+const eventBus = new SessionEventBus();
+let sseLimiter;
+let pipelines;
+let auth;
+let metrics;
+let swarmMonitor;
+// ── Inbound command handler ─────────────────────────────────────────
+async function handleInbound(cmd) {
+    try {
+        switch (cmd.action) {
+            case 'approve':
+                await sessions.approve(cmd.sessionId);
+                break;
+            case 'reject':
+                await sessions.reject(cmd.sessionId);
+                break;
+            case 'escape':
+                await sessions.escape(cmd.sessionId);
+                break;
+            case 'kill':
+                await channels.sessionEnded(makePayload('session.ended', cmd.sessionId, 'killed'));
+                await sessions.killSession(cmd.sessionId);
+                monitor.removeSession(cmd.sessionId);
+                metrics.cleanupSession(cmd.sessionId);
+                break;
+            case 'message':
+            case 'command':
+                if (cmd.text)
+                    await sessions.sendMessage(cmd.sessionId, cmd.text);
+                break;
+        }
+    }
+    catch (e) {
+        console.error(`Inbound command error [${cmd.action}]:`, e);
+    }
+}
+// ── HTTP Server ─────────────────────────────────────────────────────
+const app = Fastify({
+    bodyLimit: 1048576, // 1MB — Issue #349: explicit body size limit
+    logger: {
+        // #230: Redact auth tokens from request logs
+        serializers: {
+            req(req) {
+                const url = req.url?.includes('token=')
+                    ? req.url.replace(/token=[^&]*/g, 'token=[REDACTED]')
+                    : req.url;
+                return {
+                    method: req.method,
+                    url,
+                    // ...rest intentionally omitted — prevents token leakage via headers
+                };
+            },
+        },
+    },
+});
+// #227: Security headers on all API responses (skip SSE)
+app.addHook('onSend', (req, reply, payload, done) => {
+    const contentType = reply.getHeader('content-type');
+    if (typeof contentType === 'string' && contentType.includes('text/event-stream')) {
+        return done();
+    }
+    reply.header('X-Content-Type-Options', 'nosniff');
+    reply.header('X-Frame-Options', 'DENY');
+    reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+    reply.header('Permissions-Policy', 'camera=(), microphone=()');
+    done();
+});
+// Auth middleware setup (Issue #39: multi-key auth with rate limiting)
+// #228: Per-IP rate limiting (applies even with master token, with higher limits)
+const ipRateLimits = new Map();
+const IP_WINDOW_MS = 60_000;
+const IP_LIMIT_NORMAL = 120; // per minute for regular keys
+const IP_LIMIT_MASTER = 300; // per minute for master token
+function checkIpRateLimit(ip, isMaster) {
+    const now = Date.now();
+    const timestamps = ipRateLimits.get(ip) || [];
+    // Prune old entries
+    while (timestamps.length > 0 && timestamps[0] < now - IP_WINDOW_MS) {
+        timestamps.shift();
+    }
+    timestamps.push(now);
+    ipRateLimits.set(ip, timestamps);
+    const limit = isMaster ? IP_LIMIT_MASTER : IP_LIMIT_NORMAL;
+    return timestamps.length > limit;
+}
+/** #357: Prune IPs whose timestamp arrays are entirely outside the rate-limit window. */
+function pruneIpRateLimits() {
+    const cutoff = Date.now() - IP_WINDOW_MS;
+    for (const [ip, timestamps] of ipRateLimits) {
+        // All timestamps are old — remove the entry entirely
+        if (timestamps.length === 0 || timestamps[timestamps.length - 1] < cutoff) {
+            ipRateLimits.delete(ip);
+        }
+    }
+}
+function setupAuth(authManager) {
+    app.addHook('onRequest', async (req, reply) => {
+        // Skip auth for health endpoint and dashboard (Issue #349: exact path matching)
+        // #126: Dashboard is served as public static files; API endpoints are protected
+        const urlPath = req.url?.split('?')[0] ?? '';
+        if (urlPath === '/health' || urlPath === '/v1/health')
+            return;
+        if (urlPath === '/dashboard' || urlPath.startsWith('/dashboard/'))
+            return;
+        // Hook routes — exact match: /v1/hooks/{eventName} (alpha only, no path traversal)
+        // Issue #394: Require valid X-Session-Id for known sessions instead of blanket bypass.
+        // CC hooks run from localhost and always include the session ID they were started with.
+        const hookMatch = /^\/v1\/hooks\/[A-Za-z]+$/.exec(urlPath);
+        if (hookMatch) {
+            const hookSessionId = req.headers['x-session-id']
+                || req.query?.sessionId;
+            if (hookSessionId && sessions.getSession(hookSessionId)) {
+                return; // valid session — allow
+            }
+            // No valid session context — reject even when auth is disabled
+            return reply.status(401).send({ error: 'Unauthorized — hook endpoint requires valid session ID' });
+        }
+        // #303: WS terminal routes have their own preHandler for auth (supports ?token=)
+        // Exact match: /v1/sessions/{id}/terminal
+        if (/^\/v1\/sessions\/[^/]+\/terminal$/.test(urlPath))
+            return;
+        // If no auth configured (no master token, no keys), allow all
+        if (!authManager.authEnabled)
+            return;
+        // #124/#125: Accept token from Authorization header; ?token= query param
+        // only on SSE routes where EventSource cannot set headers.
+        // #297: SSE routes also accept short-lived SSE tokens via ?token=.
+        const isSSERoute = req.url?.includes('/events');
+        let token;
+        const header = req.headers.authorization;
+        if (header?.startsWith('Bearer ')) {
+            token = header.slice(7);
+        }
+        else if (isSSERoute) {
+            token = req.query.token;
+        }
+        if (!token) {
+            return reply.status(401).send({ error: 'Unauthorized — Bearer token required' });
+        }
+        // #297: Check if this is a short-lived SSE token first
+        if (isSSERoute && token.startsWith('sse_')) {
+            if (authManager.validateSSEToken(token)) {
+                return; // authenticated via short-lived SSE token
+            }
+            return reply.status(401).send({ error: 'Unauthorized — SSE token invalid or expired' });
+        }
+        const result = authManager.validate(token);
+        if (!result.valid) {
+            return reply.status(401).send({ error: 'Unauthorized — invalid API key' });
+        }
+        if (result.rateLimited) {
+            return reply.status(429).send({ error: 'Rate limit exceeded — 100 req/min per key' });
+        }
+        // #228: Per-IP rate limiting (applies to all authenticated requests)
+        const clientIp = req.ip ?? req.headers['x-forwarded-for'] ?? 'unknown';
+        const isMaster = result.keyId === 'master';
+        if (checkIpRateLimit(clientIp, isMaster)) {
+            return reply.status(429).send({ error: 'Rate limit exceeded — IP throttled' });
+        }
+    });
+}
+// ── v1 API Routes ───────────────────────────────────────────────────
+// #226: Zod schema for session creation
+const createSessionSchema = z.object({
+    workDir: z.string().min(1),
+    name: z.string().max(200).optional(),
+    prompt: z.string().max(100_000).optional(),
+    resumeSessionId: z.string().uuid().optional(),
+    claudeCommand: z.string().max(10_000).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    stallThresholdMs: z.number().int().positive().max(3_600_000).optional(),
+    permissionMode: z.enum(['default', 'bypassPermissions', 'plan']).optional(),
+    autoApprove: z.boolean().optional(),
+}).strict();
+// Health
+app.get('/v1/health', async () => {
+    const pkg = await import('../package.json', { with: { type: 'json' } });
+    const activeCount = sessions.listSessions().length;
+    const totalCount = metrics.getTotalSessionsCreated();
+    return {
+        status: 'ok',
+        version: pkg.default.version,
+        uptime: process.uptime(),
+        sessions: { active: activeCount, total: totalCount },
+        timestamp: new Date().toISOString(),
+    };
+});
+// Backwards compat: unversioned health
+app.get('/health', async () => {
+    const pkg = await import('../package.json', { with: { type: 'json' } });
+    const activeCount = sessions.listSessions().length;
+    const totalCount = metrics.getTotalSessionsCreated();
+    return {
+        status: 'ok',
+        version: pkg.default.version,
+        uptime: process.uptime(),
+        sessions: { active: activeCount, total: totalCount },
+        timestamp: new Date().toISOString(),
+    };
+});
+// Issue #81: Swarm awareness — list all detected CC swarms and their teammates
+app.get('/v1/swarm', async () => {
+    const result = await swarmMonitor.scan();
+    return result;
+});
+// API key management (Issue #39)
+// Security: reject all auth key operations when auth is not enabled
+app.post('/v1/auth/keys', async (req, reply) => {
+    if (!auth.authEnabled)
+        return reply.status(403).send({ error: 'Auth is not enabled' });
+    const parsed = authKeySchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { name, rateLimit } = parsed.data;
+    const result = await auth.createKey(name, rateLimit);
+    return reply.status(201).send(result);
+});
+app.get('/v1/auth/keys', async (req, reply) => {
+    if (!auth.authEnabled)
+        return reply.status(403).send({ error: 'Auth is not enabled' });
+    return auth.listKeys();
+});
+app.delete('/v1/auth/keys/:id', async (req, reply) => {
+    if (!auth.authEnabled)
+        return reply.status(403).send({ error: 'Auth is not enabled' });
+    const revoked = await auth.revokeKey(req.params.id);
+    if (!revoked)
+        return reply.status(404).send({ error: 'Key not found' });
+    return { ok: true };
+});
+// #297: SSE token endpoint — generates short-lived, single-use token
+// to avoid exposing long-lived bearer tokens in SSE URL query params.
+// Must be registered BEFORE setupAuth skips auth key routes.
+app.post('/v1/auth/sse-token', async (req, reply) => {
+    // This route goes through the onRequest auth hook, so the caller is
+    // already authenticated. We just need to extract their keyId.
+    const header = req.headers.authorization;
+    let keyId = 'anonymous';
+    if (header?.startsWith('Bearer ')) {
+        const token = header.slice(7);
+        const result = auth.validate(token);
+        if (result.keyId)
+            keyId = result.keyId;
+    }
+    try {
+        const sseToken = await auth.generateSSEToken(keyId);
+        return reply.status(201).send(sseToken);
+    }
+    catch (e) {
+        return reply.status(429).send({ error: e instanceof Error ? e.message : 'SSE token limit reached' });
+    }
+});
+// Global metrics (Issue #40)
+app.get('/v1/metrics', async () => metrics.getGlobalMetrics(sessions.listSessions().length));
+// Per-session metrics (Issue #40)
+app.get('/v1/sessions/:id/metrics', async (req, reply) => {
+    const m = metrics.getSessionMetrics(req.params.id);
+    if (!m)
+        return reply.status(404).send({ error: 'No metrics for this session' });
+    return m;
+});
+// Issue #89 L14: Webhook dead letter queue
+app.get('/v1/webhooks/dead-letter', async () => {
+    for (const ch of channels.getChannels()) {
+        if (ch.name === 'webhook' && 'getDeadLetterQueue' in ch) {
+            return ch.getDeadLetterQueue();
+        }
+    }
+    return [];
+});
+// Issue #89 L15: Per-channel health reporting
+app.get('/v1/channels/health', async () => {
+    return channels.getChannels().map(ch => {
+        const health = ch.getHealth?.();
+        if (health)
+            return health;
+        return { channel: ch.name, healthy: true, lastSuccess: null, lastError: null, pendingCount: 0 };
+    });
+});
+// Issue #87: Per-session latency metrics
+app.get('/v1/sessions/:id/latency', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const realtimeLatency = sessions.getLatencyMetrics(req.params.id);
+    const aggregatedLatency = metrics.getSessionLatency(req.params.id);
+    return {
+        sessionId: req.params.id,
+        realtime: realtimeLatency,
+        aggregated: aggregatedLatency,
+    };
+});
+// Global SSE event stream — aggregates events from ALL active sessions
+app.get('/v1/events', async (req, reply) => {
+    const clientIp = req.ip;
+    const acquireResult = sseLimiter.acquire(clientIp);
+    if (!acquireResult.allowed) {
+        const status = acquireResult.reason === 'per_ip_limit' ? 429 : 503;
+        return reply.status(status).send({
+            error: acquireResult.reason === 'per_ip_limit'
+                ? `Per-IP connection limit reached (${acquireResult.current}/${acquireResult.limit})`
+                : `Global connection limit reached (${acquireResult.current}/${acquireResult.limit})`,
+            reason: acquireResult.reason,
+        });
+    }
+    // Issue #505: Subscribe BEFORE writing response headers so that if
+    // subscription fails, we can still return a proper HTTP error.
+    let unsubscribe;
+    const connectionId = acquireResult.connectionId;
+    let writer;
+    // Queue events that arrive between subscription and writer creation
+    const pendingEvents = [];
+    let subscriptionReady = false;
+    const handler = (event) => {
+        if (!subscriptionReady) {
+            pendingEvents.push(event);
+            return;
+        }
+        const id = event.id != null ? `id: ${event.id}\n` : '';
+        writer.write(`${id}data: ${JSON.stringify(event)}\n\n`);
+    };
+    try {
+        unsubscribe = eventBus.subscribeGlobal(handler);
+    }
+    catch (err) {
+        req.log.error({ err }, 'Global SSE subscription failed');
+        sseLimiter.release(connectionId);
+        return reply.status(500).send({ error: 'Failed to create SSE subscription' });
+    }
+    reply.raw.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    });
+    writer = new SSEWriter(reply.raw, req.raw, () => {
+        unsubscribe?.();
+        sseLimiter.release(connectionId);
+    });
+    // Now safe to deliver events — flush any queued during setup
+    subscriptionReady = true;
+    for (const event of pendingEvents) {
+        const id = event.id != null ? `id: ${event.id}\n` : '';
+        writer.write(`${id}data: ${JSON.stringify(event)}\n\n`);
+    }
+    writer.write(`data: ${JSON.stringify({
+        event: 'connected',
+        timestamp: new Date().toISOString(),
+        data: { activeSessions: sessions.listSessions().length },
+    })}\n\n`);
+    // Issue #301: Replay missed global events if client sends Last-Event-ID
+    const lastEventId = req.headers['last-event-id'];
+    if (lastEventId) {
+        const missed = eventBus.getGlobalEventsSince(parseInt(lastEventId, 10) || 0);
+        for (const { id, event: globalEvent } of missed) {
+            writer.write(`id: ${id}\ndata: ${JSON.stringify(globalEvent)}\n\n`);
+        }
+    }
+    writer.startHeartbeat(30_000, 90_000, () => `data: ${JSON.stringify({ event: 'heartbeat', timestamp: new Date().toISOString() })}\n\n`);
+    await reply;
+});
+// List sessions (with pagination and status filter)
+app.get('/v1/sessions', async (req) => {
+    const page = Math.max(1, parseInt(req.query.page || '1', 10) || 1);
+    const limit = Math.min(100, Math.max(1, parseInt(req.query.limit || '20', 10) || 20));
+    const statusFilter = req.query.status;
+    let all = sessions.listSessions();
+    if (statusFilter) {
+        all = all.filter(s => s.status === statusFilter);
+    }
+    // Sort by createdAt descending (newest first)
+    all.sort((a, b) => b.createdAt - a.createdAt);
+    const total = all.length;
+    const start = (page - 1) * limit;
+    const items = all.slice(start, start + limit);
+    return {
+        sessions: items,
+        total,
+        page,
+        limit,
+    };
+});
+// Backwards compat: /sessions (no prefix) returns raw array
+app.get('/sessions', async () => sessions.listSessions());
+/** Validate workDir — delegates to validation.ts (Issue #435). */
+const validateWorkDirWithConfig = (workDir) => validateWorkDir(workDir, config.allowedWorkDirs);
+// Create session
+app.post('/v1/sessions', async (req, reply) => {
+    const parsed = createSessionSchema.safeParse(req.body);
+    if (!parsed.success) {
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    }
+    const { workDir, name, prompt, resumeSessionId, claudeCommand, env, stallThresholdMs, permissionMode, autoApprove } = parsed.data;
+    console.time("POST_CREATE_SESSION");
+    if (!workDir)
+        return reply.status(400).send({ error: 'workDir is required' });
+    const safeWorkDir = await validateWorkDirWithConfig(workDir);
+    if (typeof safeWorkDir === 'object')
+        return reply.status(400).send({ error: safeWorkDir.error, code: safeWorkDir.code });
+    const session = await sessions.createSession({ workDir: safeWorkDir, name, resumeSessionId, claudeCommand, env, stallThresholdMs, permissionMode, autoApprove });
+    console.timeEnd("POST_CREATE_SESSION");
+    console.time("POST_CHANNEL_CREATED");
+    // Issue #46: Create Telegram topic BEFORE sending prompt.
+    // The monitor starts polling immediately after createSession().
+    // If we wait for sendInitialPrompt (up to 15s), the monitor may find
+    // new messages but can't forward them because no topic exists yet.
+    // Those messages are lost forever (monitorOffset advances past them).
+    await channels.sessionCreated({
+        event: 'session.created',
+        timestamp: new Date().toISOString(),
+        session: { id: session.id, name: session.windowName, workDir },
+        detail: `Session created: ${session.windowName}`,
+        meta: prompt ? { prompt: prompt.slice(0, 200), permissionMode: permissionMode ?? (autoApprove ? 'bypassPermissions' : undefined) } : undefined,
+    });
+    console.timeEnd("POST_CHANNEL_CREATED");
+    console.time("POST_SEND_INITIAL_PROMPT");
+    // Now send the prompt (topic exists, monitor can forward messages)
+    let promptDelivery;
+    if (prompt) {
+        promptDelivery = await sessions.sendInitialPrompt(session.id, prompt);
+        console.timeEnd("POST_SEND_INITIAL_PROMPT");
+        metrics.promptSent(promptDelivery.delivered);
+    }
+    else {
+        console.timeEnd("POST_SEND_INITIAL_PROMPT");
+    }
+    return reply.status(201).send({ ...session, promptDelivery });
+});
+// Backwards compat
+app.post('/sessions', async (req, reply) => {
+    const parsed = createSessionSchema.safeParse(req.body);
+    if (!parsed.success) {
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    }
+    const { workDir, name, prompt, resumeSessionId, claudeCommand, env, stallThresholdMs, permissionMode, autoApprove } = parsed.data;
+    if (!workDir)
+        return reply.status(400).send({ error: 'workDir is required' });
+    const safeWorkDir = await validateWorkDirWithConfig(workDir);
+    if (typeof safeWorkDir === 'object')
+        return reply.status(400).send({ error: safeWorkDir.error, code: safeWorkDir.code });
+    const session = await sessions.createSession({ workDir: safeWorkDir, name, resumeSessionId, claudeCommand, env, stallThresholdMs, permissionMode, autoApprove });
+    // Issue #46: Topic first, then prompt (same fix as v1 route)
+    await channels.sessionCreated({
+        event: 'session.created',
+        timestamp: new Date().toISOString(),
+        session: { id: session.id, name: session.windowName, workDir },
+        detail: `Session created: ${session.windowName}`,
+        meta: prompt ? { prompt: prompt.slice(0, 200), permissionMode: permissionMode ?? (autoApprove ? 'bypassPermissions' : undefined) } : undefined,
+    });
+    let promptDelivery;
+    if (prompt) {
+        promptDelivery = await sessions.sendInitialPrompt(session.id, prompt);
+        metrics.promptSent(promptDelivery.delivered);
+    }
+    return reply.status(201).send({ ...session, promptDelivery });
+});
+// Get session (Issue #20: includes actionHints for interactive states)
+app.get('/v1/sessions/:id', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    return addActionHints(session);
+});
+app.get('/sessions/:id', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    return addActionHints(session);
+});
+// #128: Bulk health check — returns health for all sessions in one request
+app.get('/v1/sessions/health', async () => {
+    const allSessions = sessions.listSessions();
+    const results = {};
+    await Promise.all(allSessions.map(async (s) => {
+        try {
+            results[s.id] = await sessions.getHealth(s.id);
+        }
+        catch { /* health check failed — report error state */
+            results[s.id] = {
+                alive: false, windowExists: false, claudeRunning: false,
+                paneCommand: null, status: 'unknown', hasTranscript: false,
+                lastActivity: 0, lastActivityAgo: 0, sessionAge: 0,
+                details: 'Error fetching health',
+            };
+        }
+    }));
+    return results;
+});
+// Session health check (Issue #2)
+app.get('/v1/sessions/:id/health', async (req, reply) => {
+    try {
+        return await sessions.getHealth(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.get('/sessions/:id/health', async (req, reply) => {
+    try {
+        return await sessions.getHealth(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Send message (with delivery verification — Issue #1)
+app.post('/v1/sessions/:id/send', async (req, reply) => {
+    const parsed = sendMessageSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { text } = parsed.data;
+    try {
+        const result = await sessions.sendMessage(req.params.id, text);
+        await channels.message({
+            event: 'message.user',
+            timestamp: new Date().toISOString(),
+            session: { id: req.params.id, name: '', workDir: '' },
+            detail: text,
+        });
+        return { ok: true, delivered: result.delivered, attempts: result.attempts };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/send', async (req, reply) => {
+    const parsed = sendMessageSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { text } = parsed.data;
+    try {
+        const result = await sessions.sendMessage(req.params.id, text);
+        await channels.message({
+            event: 'message.user',
+            timestamp: new Date().toISOString(),
+            session: { id: req.params.id, name: '', workDir: '' },
+            detail: text,
+        });
+        return { ok: true, delivered: result.delivered, attempts: result.attempts };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Read messages
+app.get('/v1/sessions/:id/read', async (req, reply) => {
+    try {
+        return await sessions.readMessages(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.get('/sessions/:id/read', async (req, reply) => {
+    try {
+        return await sessions.readMessages(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Approve
+app.post('/v1/sessions/:id/approve', async (req, reply) => {
+    try {
+        await sessions.approve(req.params.id);
+        // Issue #87: Record permission response latency
+        const lat = sessions.getLatencyMetrics(req.params.id);
+        if (lat !== null && lat.permission_response_ms !== null) {
+            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/approve', async (req, reply) => {
+    try {
+        await sessions.approve(req.params.id);
+        const lat = sessions.getLatencyMetrics(req.params.id);
+        if (lat !== null && lat.permission_response_ms !== null) {
+            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Reject
+app.post('/v1/sessions/:id/reject', async (req, reply) => {
+    try {
+        await sessions.reject(req.params.id);
+        const lat = sessions.getLatencyMetrics(req.params.id);
+        if (lat !== null && lat.permission_response_ms !== null) {
+            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/reject', async (req, reply) => {
+    try {
+        await sessions.reject(req.params.id);
+        const lat = sessions.getLatencyMetrics(req.params.id);
+        if (lat !== null && lat.permission_response_ms !== null) {
+            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Issue #336: Answer pending AskUserQuestion
+app.post('/v1/sessions/:id/answer', async (req, reply) => {
+    const { questionId, answer } = req.body || {};
+    if (!questionId || answer === undefined || answer === null) {
+        return reply.status(400).send({ error: 'questionId and answer are required' });
+    }
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const resolved = sessions.submitAnswer(req.params.id, questionId, answer);
+    if (!resolved) {
+        return reply.status(409).send({ error: 'No pending question matching this questionId' });
+    }
+    return { ok: true };
+});
+// Escape
+app.post('/v1/sessions/:id/escape', async (req, reply) => {
+    try {
+        await sessions.escape(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/escape', async (req, reply) => {
+    try {
+        await sessions.escape(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Interrupt (Ctrl+C)
+app.post('/v1/sessions/:id/interrupt', async (req, reply) => {
+    try {
+        await sessions.interrupt(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/interrupt', async (req, reply) => {
+    try {
+        await sessions.interrupt(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Kill session
+app.delete('/v1/sessions/:id', async (req, reply) => {
+    if (!sessions.getSession(req.params.id)) {
+        return reply.status(404).send({ error: 'Session not found' });
+    }
+    try {
+        eventBus.emitEnded(req.params.id, 'killed');
+        await channels.sessionEnded(makePayload('session.ended', req.params.id, 'killed'));
+        await sessions.killSession(req.params.id);
+        monitor.removeSession(req.params.id);
+        metrics.cleanupSession(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.delete('/sessions/:id', async (req, reply) => {
+    if (!sessions.getSession(req.params.id)) {
+        return reply.status(404).send({ error: 'Session not found' });
+    }
+    try {
+        eventBus.emitEnded(req.params.id, 'killed');
+        await channels.sessionEnded(makePayload('session.ended', req.params.id, 'killed'));
+        await sessions.killSession(req.params.id);
+        monitor.removeSession(req.params.id);
+        metrics.cleanupSession(req.params.id);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Capture raw pane
+app.get('/v1/sessions/:id/pane', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const pane = await tmux.capturePane(session.windowId);
+    return { pane };
+});
+app.get('/sessions/:id/pane', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const pane = await tmux.capturePane(session.windowId);
+    return { pane };
+});
+// Slash command
+app.post('/v1/sessions/:id/command', async (req, reply) => {
+    const parsed = commandSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { command } = parsed.data;
+    try {
+        const cmd = command.startsWith('/') ? command : `/${command}`;
+        await sessions.sendMessage(req.params.id, cmd);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/command', async (req, reply) => {
+    const parsed = commandSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { command } = parsed.data;
+    try {
+        const cmd = command.startsWith('/') ? command : `/${command}`;
+        await sessions.sendMessage(req.params.id, cmd);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Bash mode
+app.post('/v1/sessions/:id/bash', async (req, reply) => {
+    const parsed = bashSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { command } = parsed.data;
+    try {
+        const cmd = command.startsWith('!') ? command : `!${command}`;
+        await sessions.sendMessage(req.params.id, cmd);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.post('/sessions/:id/bash', async (req, reply) => {
+    const parsed = bashSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { command } = parsed.data;
+    try {
+        const cmd = command.startsWith('!') ? command : `!${command}`;
+        await sessions.sendMessage(req.params.id, cmd);
+        return { ok: true };
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Session summary (Issue #35)
+app.get('/v1/sessions/:id/summary', async (req, reply) => {
+    try {
+        return await sessions.getSummary(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.get('/sessions/:id/summary', async (req, reply) => {
+    try {
+        return await sessions.getSummary(req.params.id);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Paginated transcript read
+app.get('/v1/sessions/:id/transcript', async (req, reply) => {
+    try {
+        const page = Math.max(1, parseInt(req.query.page || '1', 10) || 1);
+        const limit = Math.min(200, Math.max(1, parseInt(req.query.limit || '50', 10) || 50));
+        const roleFilter = req.query.role;
+        return await sessions.readTranscript(req.params.id, page, limit, roleFilter);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Screenshot capture (Issue #22)
+app.post('/v1/sessions/:id/screenshot', async (req, reply) => {
+    const parsed = screenshotSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { url, fullPage, width, height } = parsed.data;
+    const urlError = validateScreenshotUrl(url);
+    if (urlError)
+        return reply.status(400).send({ error: urlError });
+    // Post-DNS-resolution check: resolve hostname and reject private IPs
+    const ipError = await resolveAndCheckIp(new URL(url).hostname);
+    if (ipError)
+        return reply.status(400).send({ error: ipError });
+    // Validate session exists
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    if (!isPlaywrightAvailable()) {
+        return reply.status(501).send({
+            error: 'Playwright is not installed',
+            message: 'Install Playwright to enable screenshots: npx playwright install chromium && npm install -D playwright',
+        });
+    }
+    try {
+        const result = await captureScreenshot({ url, fullPage, width, height });
+        return reply.status(200).send(result);
+    }
+    catch (e) {
+        return reply.status(500).send({ error: `Screenshot failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+});
+app.post('/sessions/:id/screenshot', async (req, reply) => {
+    const parsed = screenshotSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { url, fullPage, width, height } = parsed.data;
+    const urlError = validateScreenshotUrl(url);
+    if (urlError)
+        return reply.status(400).send({ error: urlError });
+    // Post-DNS-resolution check: resolve hostname and reject private IPs
+    const dnsError = await resolveAndCheckIp(new URL(url).hostname);
+    if (dnsError)
+        return reply.status(400).send({ error: dnsError });
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    if (!isPlaywrightAvailable()) {
+        return reply.status(501).send({
+            error: 'Playwright is not installed',
+            message: 'Install Playwright to enable screenshots: npx playwright install chromium && npm install -D playwright',
+        });
+    }
+    try {
+        const result = await captureScreenshot({ url, fullPage, width, height });
+        return reply.status(200).send(result);
+    }
+    catch (e) {
+        return reply.status(500).send({ error: `Screenshot failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+});
+// SSE event stream (Issue #32)
+app.get('/v1/sessions/:id/events', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const clientIp = req.ip;
+    const acquireResult = sseLimiter.acquire(clientIp);
+    if (!acquireResult.allowed) {
+        const status = acquireResult.reason === 'per_ip_limit' ? 429 : 503;
+        return reply.status(status).send({
+            error: acquireResult.reason === 'per_ip_limit'
+                ? `Per-IP connection limit reached (${acquireResult.current}/${acquireResult.limit})`
+                : `Global connection limit reached (${acquireResult.current}/${acquireResult.limit})`,
+            reason: acquireResult.reason,
+        });
+    }
+    // Issue #505: Subscribe BEFORE writing response headers so that if
+    // subscription fails, we can still return a proper HTTP error.
+    let unsubscribe;
+    const connectionId = acquireResult.connectionId;
+    let writer;
+    // Queue events that arrive between subscription and writer creation
+    const pendingEvents = [];
+    let subscriptionReady = false;
+    try {
+        const handler = (event) => {
+            if (!subscriptionReady) {
+                pendingEvents.push(event);
+                return;
+            }
+            const id = event.id != null ? `id: ${event.id}\n` : '';
+            writer.write(`${id}data: ${JSON.stringify(event)}\n\n`);
+        };
+        unsubscribe = eventBus.subscribe(req.params.id, handler);
+    }
+    catch (err) {
+        req.log.error({ err, sessionId: req.params.id }, 'SSE subscription failed — unable to create event listener');
+        sseLimiter.release(connectionId);
+        return reply.status(500).send({ error: 'Failed to create SSE subscription' });
+    }
+    reply.raw.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    });
+    writer = new SSEWriter(reply.raw, req.raw, () => {
+        unsubscribe?.();
+        sseLimiter.release(connectionId);
+    });
+    // Now safe to deliver events — flush any queued during setup
+    subscriptionReady = true;
+    for (const event of pendingEvents) {
+        const id = event.id != null ? `id: ${event.id}\n` : '';
+        writer.write(`${id}data: ${JSON.stringify(event)}\n\n`);
+    }
+    // Send initial connected event
+    writer.write(`data: ${JSON.stringify({ event: 'connected', sessionId: session.id, timestamp: new Date().toISOString() })}\n\n`);
+    // Issue #308: Replay missed events if client sends Last-Event-ID
+    const lastEventId = req.headers['last-event-id'];
+    if (lastEventId) {
+        const missed = eventBus.getEventsSince(req.params.id, parseInt(lastEventId, 10) || 0);
+        for (const event of missed) {
+            const id = event.id != null ? `id: ${event.id}\n` : '';
+            writer.write(`${id}data: ${JSON.stringify(event)}\n\n`);
+        }
+    }
+    writer.startHeartbeat(30_000, 90_000, () => `data: ${JSON.stringify({ event: 'heartbeat', sessionId: session.id, timestamp: new Date().toISOString() })}\n\n`);
+    // Don't let Fastify auto-send (we manage the response manually)
+    await reply;
+});
+// ── Claude Code Hook Endpoints (Issue #161) ─────────────────────────
+// POST /v1/sessions/:id/hooks/permission — PermissionRequest hook from CC
+app.post('/v1/sessions/:id/hooks/permission', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const parsed = permissionHookSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { tool_name, tool_input, permission_mode } = parsed.data;
+    // Update session status
+    session.status = 'permission_prompt';
+    session.lastActivity = Date.now();
+    await sessions.save();
+    // Notify channels and SSE
+    const detail = tool_name
+        ? `Permission request: ${tool_name}${permission_mode ? ` (${permission_mode})` : ''}`
+        : 'Permission requested';
+    await channels.statusChange({
+        event: 'status.permission',
+        timestamp: new Date().toISOString(),
+        session: { id: session.id, name: session.windowName, workDir: session.workDir },
+        detail,
+        meta: { tool_name, tool_input, permission_mode },
+    });
+    eventBus.emitApproval(session.id, detail);
+    return reply.status(200).send({});
+});
+// POST /v1/sessions/:id/hooks/stop — Stop hook from CC
+app.post('/v1/sessions/:id/hooks/stop', async (req, reply) => {
+    const session = sessions.getSession(req.params.id);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const parsed = stopHookSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const { stop_reason } = parsed.data;
+    // Update session status
+    session.status = 'idle';
+    session.lastActivity = Date.now();
+    await sessions.save();
+    // Notify channels and SSE
+    const detail = stop_reason
+        ? `Claude Code stopped: ${stop_reason}`
+        : 'Claude Code session ended normally';
+    await channels.statusChange({
+        event: 'status.idle',
+        timestamp: new Date().toISOString(),
+        session: { id: session.id, name: session.windowName, workDir: session.workDir },
+        detail,
+        meta: { stop_reason },
+    });
+    eventBus.emitStatus(session.id, 'idle', detail);
+    return reply.status(200).send({});
+});
+// Batch create (Issue #36)
+app.post('/v1/sessions/batch', async (req, reply) => {
+    const parsed = batchSessionSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const specs = parsed.data.sessions;
+    for (const spec of specs) {
+        const safeWorkDir = await validateWorkDirWithConfig(spec.workDir);
+        if (typeof safeWorkDir === 'object') {
+            return reply.status(400).send({ error: `Invalid workDir "${spec.workDir}": ${safeWorkDir.error}`, code: safeWorkDir.code });
+        }
+        spec.workDir = safeWorkDir;
+    }
+    const result = await pipelines.batchCreate(specs);
+    return reply.status(201).send(result);
+});
+// Pipeline create (Issue #36)
+app.post('/v1/pipelines', async (req, reply) => {
+    const parsed = pipelineSchema.safeParse(req.body);
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+    const pipeConfig = parsed.data;
+    const safeWorkDir = await validateWorkDirWithConfig(pipeConfig.workDir);
+    if (typeof safeWorkDir === 'object') {
+        return reply.status(400).send({ error: `Invalid workDir: ${safeWorkDir.error}`, code: safeWorkDir.code });
+    }
+    pipeConfig.workDir = safeWorkDir;
+    try {
+        const pipeline = await pipelines.createPipeline(pipeConfig);
+        return reply.status(201).send(pipeline);
+    }
+    catch (e) {
+        return reply.status(400).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+// Pipeline status
+app.get('/v1/pipelines/:id', async (req, reply) => {
+    const pipeline = pipelines.getPipeline(req.params.id);
+    if (!pipeline)
+        return reply.status(404).send({ error: 'Pipeline not found' });
+    return pipeline;
+});
+// List pipelines
+app.get('/v1/pipelines', async () => pipelines.listPipelines());
+// ── Session Reaper ──────────────────────────────────────────────────
+async function reapStaleSessions(maxAgeMs) {
+    const now = Date.now();
+    // Snapshot list before iterating — killSession() modifies the sessions map
+    const snapshot = [...sessions.listSessions()];
+    for (const session of snapshot) {
+        // Guard: session may have been deleted by DELETE handler between snapshot and here
+        if (!sessions.getSession(session.id))
+            continue;
+        const age = now - session.createdAt;
+        if (age > maxAgeMs) {
+            const ageMin = Math.round(age / 60000);
+            console.log(`Reaper: killing session ${session.windowName} (${session.id.slice(0, 8)}) — age ${ageMin}min`);
+            try {
+                await channels.sessionEnded({
+                    event: 'session.ended',
+                    timestamp: new Date().toISOString(),
+                    session: { id: session.id, name: session.windowName, workDir: session.workDir },
+                    detail: `Auto-killed: exceeded ${maxAgeMs / 3600000}h time limit`,
+                });
+                await sessions.killSession(session.id);
+                monitor.removeSession(session.id);
+                metrics.cleanupSession(session.id);
+            }
+            catch (e) {
+                console.error(`Reaper: failed to kill session ${session.id}:`, e);
+            }
+        }
+    }
+}
+// ── Zombie Reaper (Issue #283) ──────────────────────────────────────
+const ZOMBIE_REAP_DELAY_MS = parseIntSafe(process.env.ZOMBIE_REAP_DELAY_MS, 60000);
+const ZOMBIE_REAP_INTERVAL_MS = parseIntSafe(process.env.ZOMBIE_REAP_INTERVAL_MS, 60000);
+async function reapZombieSessions() {
+    const now = Date.now();
+    // Snapshot list before iterating — killSession() modifies the sessions map
+    const snapshot = [...sessions.listSessions()];
+    for (const session of snapshot) {
+        // Guard: session may have been deleted between snapshot and here
+        if (!sessions.getSession(session.id))
+            continue;
+        if (!session.lastDeadAt)
+            continue;
+        const deadDuration = now - session.lastDeadAt;
+        if (deadDuration < ZOMBIE_REAP_DELAY_MS)
+            continue;
+        console.log(`Reaper: removing zombie session ${session.windowName} (${session.id.slice(0, 8)})`);
+        try {
+            monitor.removeSession(session.id);
+            await sessions.killSession(session.id);
+            metrics.cleanupSession(session.id);
+            await channels.sessionEnded({
+                event: 'session.ended',
+                timestamp: new Date().toISOString(),
+                session: { id: session.id, name: session.windowName, workDir: session.workDir },
+                detail: `Zombie reaped: dead for ${Math.round(deadDuration / 1000)}s`,
+            });
+        }
+        catch (e) {
+            console.error(`Reaper: failed to reap zombie session ${session.id}:`, e);
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+/** Issue #20: Add actionHints to session response for interactive states. */
+function addActionHints(session) {
+    // #357: Convert Set to array for JSON serialization
+    const result = {
+        ...session,
+        activeSubagents: session.activeSubagents ? [...session.activeSubagents] : undefined,
+    };
+    if (session.status === 'permission_prompt' || session.status === 'bash_approval') {
+        result.actionHints = {
+            approve: { method: 'POST', url: `/v1/sessions/${session.id}/approve`, description: 'Approve the pending permission' },
+            reject: { method: 'POST', url: `/v1/sessions/${session.id}/reject`, description: 'Reject the pending permission' },
+        };
+    }
+    return result;
+}
+function makePayload(event, sessionId, detail, meta) {
+    const session = sessions.getSession(sessionId);
+    return {
+        event,
+        timestamp: new Date().toISOString(),
+        session: {
+            id: sessionId,
+            name: session?.windowName || 'unknown',
+            workDir: session?.workDir || '',
+        },
+        detail,
+        ...(meta && { meta }),
+    };
+}
+// ── Start ────────────────────────────────────────────────────────────
+/** Register notification channels from config */
+function registerChannels(cfg) {
+    // Telegram (optional)
+    if (cfg.tgBotToken && cfg.tgGroupId) {
+        channels.register(new TelegramChannel({
+            botToken: cfg.tgBotToken,
+            groupChatId: cfg.tgGroupId,
+            allowedUserIds: cfg.tgAllowedUsers,
+        }));
+    }
+    // Webhooks (optional)
+    if (cfg.webhooks.length > 0) {
+        const webhookChannel = new WebhookChannel({
+            endpoints: cfg.webhooks.map(url => ({ url })),
+        });
+        channels.register(webhookChannel);
+    }
+}
+// ── PID file (peer Aegis detection) ───────────────────────────────────
+let pidFilePath = '';
+function writePidFile() {
+    try {
+        pidFilePath = path.join(config.stateDir, 'aegis.pid');
+        writeFileSync(pidFilePath, String(process.pid));
+    }
+    catch { /* non-critical */ }
+}
+function readPidFile() {
+    try {
+        const p = path.join(config.stateDir, 'aegis.pid');
+        const content = readFileSync(p, 'utf-8').trim();
+        const pid = parseInt(content, 10);
+        return isNaN(pid) ? null : pid;
+    }
+    catch { /* pid file missing or unreadable */
+        return null;
+    }
+}
+// ── Port conflict recovery (Issue #99, #162) ──────────────────────────
+/**
+ * Check if a PID exists using `process.kill(pid, 0)`.
+ */
+function pidExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch { /* ESRCH — process does not exist */
+        return false;
+    }
+}
+/**
+ * Check if a PID is an ancestor of the current process.
+ */
+function isAncestorPid(pid) {
+    try {
+        let current = process.ppid;
+        for (let depth = 0; depth < 10 && current > 1; depth++) {
+            if (current === pid)
+                return true;
+            try {
+                current = parseInt(readFileSync(`/proc/${current}/stat`, 'utf-8').split(' ')[1], 10);
+            }
+            catch { /* /proc unavailable or process gone — stop walking */
+                break;
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return false;
+}
+/**
+ * Wait for a port to be released with exponential backoff.
+ */
+async function waitForPortRelease(port, maxWaitMs = 5_000) {
+    const net = await import('node:net');
+    const start = Date.now();
+    let delay = 200;
+    while (Date.now() - start < maxWaitMs) {
+        try {
+            await new Promise((resolve, reject) => {
+                const sock = net.createServer();
+                sock.once('error', reject);
+                sock.listen(port, '127.0.0.1', () => {
+                    sock.close();
+                    reject(new Error('port free')); // signal success
+                });
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.message === 'port free')
+                return;
+        }
+        await new Promise(resolve => setTimeout(resolve, delay));
+        delay = Math.min(delay * 1.5, 1_000);
+    }
+}
+/**
+ * Kill stale process holding a port. Returns true if a process was killed.
+ * Uses `lsof` to find the PID, verifies it exists, skips ancestors,
+ * and tries SIGTERM before SIGKILL.
+ */
+async function killStalePortHolder(port) {
+    // Small random delay to reduce race window with systemd restarts
+    await new Promise(resolve => setTimeout(resolve, 100 + Math.random() * 400));
+    try {
+        const output = execSync(`lsof -ti tcp:${port}`, { encoding: 'utf-8', timeout: 5_000 }).trim();
+        if (!output)
+            return false;
+        const pids = output.split('\n').map(s => parseInt(s.trim(), 10)).filter(n => !isNaN(n));
+        if (pids.length === 0)
+            return false;
+        let killed = false;
+        for (const pid of pids) {
+            // Skip own PID
+            if (pid === process.pid)
+                continue;
+            // Skip ancestors to avoid killing parent process (e.g. systemd supervisor)
+            if (isAncestorPid(pid)) {
+                console.warn(`EADDRINUSE recovery: skipping ancestor PID ${pid} on port ${port}`);
+                continue;
+            }
+            // Skip peer Aegis instance (another Aegis process that wrote the PID file)
+            const pidFilePid = readPidFile();
+            if (pidFilePid !== null && pid === pidFilePid && pid !== process.pid) {
+                console.warn(`EADDRINUSE recovery: skipping peer Aegis PID ${pid} (PID file match) on port ${port}`);
+                continue;
+            }
+            // Verify PID exists before attempting to kill
+            if (!pidExists(pid))
+                continue;
+            console.warn(`EADDRINUSE recovery: killing stale process PID ${pid} on port ${port}`);
+            // Try SIGTERM first for graceful shutdown
+            try {
+                process.kill(pid, 'SIGTERM');
+                await new Promise(resolve => setTimeout(resolve, 2_000));
+                // Check if process exited after SIGTERM
+                if (!pidExists(pid)) {
+                    killed = true;
+                    continue;
+                }
+            }
+            catch { /* process may have already exited */ }
+            // Fallback to SIGKILL if SIGTERM didn't work
+            try {
+                process.kill(pid, 'SIGKILL');
+                killed = true;
+            }
+            catch { /* already dead */ }
+        }
+        if (killed) {
+            await waitForPortRelease(port);
+        }
+        return killed;
+    }
+    catch {
+        // lsof not found or no process on port — that's fine
+        return false;
+    }
+}
+/**
+ * Listen with EADDRINUSE recovery: if port is taken, kill the stale holder and retry once.
+ */
+async function listenWithRetry(app, port, host, maxRetries = 1) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            await app.listen({ port, host });
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof Error && 'code' in err && err.code === 'EADDRINUSE') || attempt >= maxRetries) {
+                throw err;
+            }
+            console.error(`EADDRINUSE on port ${port} — attempting recovery (attempt ${attempt + 1}/${maxRetries})`);
+            const killed = await killStalePortHolder(port);
+            if (!killed) {
+                console.error(`EADDRINUSE recovery failed: no stale process found on port ${port}`);
+                throw err;
+            }
+        }
+    }
+}
+async function main() {
+    // Load configuration
+    config = await loadConfig();
+    // Initialize core components with config
+    tmux = new TmuxManager(config.tmuxSession);
+    sessions = new SessionManager(tmux, config);
+    sseLimiter = new SSEConnectionLimiter({ maxConnections: config.sseMaxConnections, maxPerIp: config.sseMaxPerIp });
+    monitor = new SessionMonitor(sessions, channels, { ...DEFAULT_MONITOR_CONFIG, pollIntervalMs: 5000 });
+    // Register channels
+    registerChannels(config);
+    // Setup auth (Issue #39: multi-key + backward compat)
+    const { join } = await import('node:path');
+    auth = new AuthManager(join(config.stateDir, 'keys.json'), config.authToken);
+    await auth.load();
+    setupAuth(auth);
+    // Register WebSocket plugin for live terminal streaming (Issue #108)
+    await app.register(fastifyWebsocket);
+    registerWsTerminalRoute(app, sessions, tmux, auth);
+    // #217: CORS configuration — restrictive by default
+    const corsOrigin = process.env.CORS_ORIGIN;
+    await app.register(fastifyCors, {
+        origin: corsOrigin ? corsOrigin.split(',').map(s => s.trim()) : false,
+    });
+    // Load persisted sessions
+    await sessions.load();
+    await tmux.ensureSession();
+    // Initialize channels
+    await channels.init(handleInbound);
+    // Wire SSE event bus (Issue #32)
+    monitor.setEventBus(eventBus);
+    // Issue #84: Wire JSONL watcher for fs.watch-based message detection
+    jsonlWatcher = new JsonlWatcher();
+    monitor.setJsonlWatcher(jsonlWatcher);
+    // Start watching JSONL files for already-discovered sessions
+    for (const session of sessions.listSessions()) {
+        if (session.jsonlPath) {
+            jsonlWatcher.watch(session.id, session.jsonlPath, session.monitorOffset);
+        }
+    }
+    // Register HTTP hook receiver (Issue #169, Issue #87: pass metrics for latency tracking)
+    registerHookRoutes(app, { sessions, eventBus, metrics });
+    // Initialize pipeline manager (Issue #36)
+    pipelines = new PipelineManager(sessions, eventBus);
+    // Initialize metrics (Issue #40)
+    metrics = new MetricsCollector(join(config.stateDir, 'metrics.json'));
+    await metrics.load();
+    // Issue #361: Store interval refs so graceful shutdown can clear them
+    const reaperInterval = setInterval(() => reapStaleSessions(config.maxSessionAgeMs), config.reaperIntervalMs);
+    const zombieReaperInterval = setInterval(() => reapZombieSessions(), ZOMBIE_REAP_INTERVAL_MS);
+    const metricsSaveInterval = setInterval(() => { void metrics.save(); }, 5 * 60 * 1000);
+    // #357: Prune stale IP rate-limit entries every minute
+    const ipPruneInterval = setInterval(pruneIpRateLimits, 60_000);
+    // Issue #361: Graceful shutdown handler
+    // Issue #415: Reentrance guard at handler level prevents double execution on rapid SIGINT
+    let shuttingDown = false;
+    async function gracefulShutdown(signal) {
+        console.log(`${signal} received, shutting down gracefully...`);
+        // 1. Stop accepting new requests
+        try {
+            await app.close();
+        }
+        catch (e) {
+            console.error('Error closing server:', e);
+        }
+        // 2. Stop background monitors and intervals
+        monitor.stop();
+        swarmMonitor.stop();
+        clearInterval(reaperInterval);
+        clearInterval(zombieReaperInterval);
+        clearInterval(metricsSaveInterval);
+        clearInterval(ipPruneInterval);
+        // 3. Destroy channels (awaits Telegram poll loop)
+        try {
+            await channels.destroy();
+        }
+        catch (e) {
+            console.error('Error destroying channels:', e);
+        }
+        // 4. Save session state
+        try {
+            await sessions.save();
+        }
+        catch (e) {
+            console.error('Error saving sessions:', e);
+        }
+        // 5. Save metrics
+        try {
+            await metrics.save();
+        }
+        catch (e) {
+            console.error('Error saving metrics:', e);
+        }
+        // 6. Cleanup PID file
+        try {
+            if (pidFilePath) {
+                unlinkSync(pidFilePath);
+            }
+        }
+        catch { /* non-critical */ }
+        console.log('Graceful shutdown complete');
+        process.exit(0);
+    }
+    process.on('SIGTERM', () => { if (!shuttingDown) {
+        shuttingDown = true;
+        void gracefulShutdown('SIGTERM');
+    } });
+    process.on('SIGINT', () => { if (!shuttingDown) {
+        shuttingDown = true;
+        void gracefulShutdown('SIGINT');
+    } });
+    process.on('unhandledRejection', (reason) => {
+        console.error('unhandledRejection:', reason);
+    });
+    // Start monitor
+    monitor.start();
+    // Issue #81: Start swarm monitor for agent swarm awareness
+    swarmMonitor = new SwarmMonitor(sessions);
+    swarmMonitor.onEvent((event) => {
+        if (!event.swarm.parentSession)
+            return;
+        const parentId = event.swarm.parentSession.id;
+        const teammate = event.teammate;
+        if (event.type === 'teammate_spawned') {
+            const detail = `🔧 Teammate ${teammate.windowName} spawned`;
+            eventBus.emit(parentId, {
+                event: 'subagent_start',
+                sessionId: parentId,
+                timestamp: new Date().toISOString(),
+                data: { teammate: teammate.windowName, windowId: teammate.windowId },
+            });
+            channels.swarmEvent(makePayload('swarm.teammate_spawned', parentId, detail, {
+                teammateName: teammate.windowName,
+                teammateWindowId: teammate.windowId,
+                teammateCwd: teammate.cwd,
+            }));
+        }
+        else if (event.type === 'teammate_finished') {
+            const detail = `✅ Teammate ${teammate.windowName} finished`;
+            eventBus.emit(parentId, {
+                event: 'subagent_stop',
+                sessionId: parentId,
+                timestamp: new Date().toISOString(),
+                data: { teammate: teammate.windowName },
+            });
+            channels.swarmEvent(makePayload('swarm.teammate_finished', parentId, detail, {
+                teammateName: teammate.windowName,
+            }));
+        }
+    });
+    swarmMonitor.start();
+    // Issue #71: Wire swarm monitor into Telegram channel for /swarm command
+    for (const ch of channels.getChannels()) {
+        if ('setSwarmMonitor' in ch && typeof ch.setSwarmMonitor === 'function') {
+            ch.setSwarmMonitor(swarmMonitor);
+        }
+    }
+    // Start reaper (intervals already created above with stored refs for graceful shutdown)
+    console.log(`Session reaper active: max age ${config.maxSessionAgeMs / 3600000}h, check every ${config.reaperIntervalMs / 60000}min`);
+    // Start zombie reaper (Issue #283)
+    console.log(`Zombie reaper active: grace period ${ZOMBIE_REAP_DELAY_MS / 1000}s, check every ${ZOMBIE_REAP_INTERVAL_MS / 1000}s`);
+    // #127: Serve dashboard static files (Issue #105) — graceful if missing
+    // Issue #539: Dashboard is copied into dist/dashboard/ during build
+    const dashboardRoot = path.join(__dirname, "dashboard");
+    let dashboardAvailable = false;
+    try {
+        await fs.access(dashboardRoot);
+        dashboardAvailable = true;
+    }
+    catch {
+        console.warn("Dashboard directory not found — skipping dashboard serving. Run 'npm run build:dashboard' to enable.");
+    }
+    if (dashboardAvailable) {
+        await app.register(fastifyStatic, {
+            root: dashboardRoot,
+            prefix: "/dashboard/",
+            // #146: Cache hashed assets aggressively, no-cache for index.html
+            setHeaders: (reply, pathname) => {
+                // Security headers (#145)
+                reply.setHeader('X-Frame-Options', 'DENY');
+                reply.setHeader('X-Content-Type-Options', 'nosniff');
+                reply.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+                // Issue #349: Content-Security-Policy for dashboard
+                reply.setHeader('Content-Security-Policy', DASHBOARD_CSP);
+                // Cache control (#146)
+                if (pathname === '/index.html' || pathname === '/') {
+                    reply.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+                }
+                else {
+                    reply.setHeader('Cache-Control', 'public, max-age=604800, immutable');
+                }
+            },
+        });
+    }
+    // SPA fallback for dashboard routes (Issue #105)
+    app.setNotFoundHandler(async (req, reply) => {
+        if (dashboardAvailable && (req.url === "/dashboard" || req.url?.startsWith("/dashboard/") || req.url?.startsWith("/dashboard?"))) {
+            // Issue #349: CSP header for SPA dashboard responses
+            reply.header('Content-Security-Policy', DASHBOARD_CSP);
+            return reply.sendFile("index.html", dashboardRoot);
+        }
+        return reply.status(404).send({ error: "Not found" });
+    });
+    await listenWithRetry(app, config.port, config.host);
+    writePidFile();
+    console.log(`Aegis running on http://${config.host}:${config.port}`);
+    console.log(`Channels: ${channels.count} registered`);
+    console.log(`State dir: ${config.stateDir}`);
+    console.log(`Claude projects dir: ${config.claudeProjectsDir}`);
+    if (config.authToken)
+        console.log('Auth: Bearer token required');
+}
+main().catch(err => {
+    console.error('Failed to start Aegis:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map