@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/ui/config.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Aesop UI Configuration — Path and environment resolution.
+
+This module centralizes all path configuration, environment variable resolution,
+and config file loading for the UI dashboard. It provides a reload() function to
+recompute all paths when environment changes (e.g., between test fixtures).
+
+Config precedence: env vars > aesop.config.json > built-in defaults.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+
+# ==============================================================================
+# Path Resolution Functions
+# ==============================================================================
+
+def reload():
+    """Recompute all configuration from current environment.
+
+    Called at module load and whenever environment changes (test fixtures).
+    Mutates module-level globals in place so that importers see the current state.
+    """
+    global PORT, AESOP_ROOT, CONFIG_FILE, STATE_DIR, TRANSCRIPTS_ROOT
+    global WATCHDOG_HEARTBEAT, MONITOR_HEARTBEAT, REPOS_JSON, BACKUP_LOG
+    global ALERTS_LOG, INBOX_FILE, AUDIT_BACKLOG_FILE
+    global UI_SESSION_TOKEN_FILE, TRACKER_FILE, ORCH_STATUS_FILE
+    global COLLECTOR_INTERVAL, SSE_KEEPALIVE_SECONDS, SSE_MAX_CLIENTS, SSE_QUEUE_MAXSIZE, SSE_WRITE_TIMEOUT
+
+    # PORT: env PORT > default 8770
+    PORT = int(os.getenv("PORT", "8770"))
+
+    # Determine AESOP_ROOT: env AESOP_ROOT > default $HOME/aesop
+    AESOP_ROOT = Path(os.getenv("AESOP_ROOT", Path.home() / "aesop"))
+
+    # Try to load config file for additional settings
+    CONFIG_FILE = AESOP_ROOT / "aesop.config.json"
+    config_data = {}
+    if CONFIG_FILE.exists():
+        try:
+            with open(CONFIG_FILE) as f:
+                config_data = json.load(f)
+        except Exception as e:
+            print(f"[config] Failed to load {CONFIG_FILE}: {e}", file=sys.stderr)
+
+    # Derive paths with precedence: env var > config file > built-in default
+    # STATE_DIR: env AESOP_STATE_ROOT > config state_root > AESOP_ROOT/state
+    STATE_DIR = Path(
+        os.getenv(
+            "AESOP_STATE_ROOT",
+            config_data.get("state_root", str(AESOP_ROOT / "state"))
+        )
+    )
+
+    # TRANSCRIPTS_ROOT: env AESOP_TRANSCRIPTS_ROOT > config transcripts_root > ~/.claude/projects
+    TRANSCRIPTS_ROOT = Path(
+        os.getenv(
+            "AESOP_TRANSCRIPTS_ROOT",
+            config_data.get("transcripts_root", "~/.claude/projects")
+        )
+    ).expanduser()
+
+    # Data file paths (all derived from STATE_DIR and AESOP_ROOT)
+    WATCHDOG_HEARTBEAT = STATE_DIR / ".watchdog-heartbeat"
+    MONITOR_HEARTBEAT = STATE_DIR / ".monitor-heartbeat"
+    REPOS_JSON = STATE_DIR / ".watchdog-repos.json"
+    BACKUP_LOG = STATE_DIR / "FLEET-BACKUP.log"
+    ALERTS_LOG = STATE_DIR / "SECURITY-ALERTS.log"
+    INBOX_FILE = STATE_DIR / "ui-inbox.md"
+    AUDIT_BACKLOG_FILE = AESOP_ROOT / "AUDIT-BACKLOG.md"
+    UI_SESSION_TOKEN_FILE = STATE_DIR / ".ui-session-token"
+    TRACKER_FILE = STATE_DIR / "tracker.json"
+    ORCH_STATUS_FILE = STATE_DIR / "orchestrator-status.json"
+
+    # Collector and SSE configuration
+    COLLECTOR_INTERVAL = float(os.getenv("AESOP_UI_COLLECT_INTERVAL", "1.0"))
+    SSE_KEEPALIVE_SECONDS = 15
+    SSE_MAX_CLIENTS = 100  # Resource cap: reject new connections past this
+    SSE_QUEUE_MAXSIZE = 50  # Per-client bounded queue (drops oldest on overflow)
+    SSE_WRITE_TIMEOUT = 5.0  # Write timeout in seconds to prevent stalled clients
+
+
+# ==============================================================================
+# Module-level initialization
+# ==============================================================================
+
+# Initialize configuration at module load time
+# These globals are recomputed by reload() and accessed by other modules
+PORT = 8770
+AESOP_ROOT = Path.home() / "aesop"
+CONFIG_FILE = AESOP_ROOT / "aesop.config.json"
+STATE_DIR = AESOP_ROOT / "state"
+TRANSCRIPTS_ROOT = Path("~/.claude/projects").expanduser()
+WATCHDOG_HEARTBEAT = STATE_DIR / ".watchdog-heartbeat"
+MONITOR_HEARTBEAT = STATE_DIR / ".monitor-heartbeat"
+REPOS_JSON = STATE_DIR / ".watchdog-repos.json"
+BACKUP_LOG = STATE_DIR / "FLEET-BACKUP.log"
+ALERTS_LOG = STATE_DIR / "SECURITY-ALERTS.log"
+INBOX_FILE = STATE_DIR / "ui-inbox.md"
+AUDIT_BACKLOG_FILE = AESOP_ROOT / "AUDIT-BACKLOG.md"
+UI_SESSION_TOKEN_FILE = STATE_DIR / ".ui-session-token"
+TRACKER_FILE = STATE_DIR / "tracker.json"
+ORCH_STATUS_FILE = STATE_DIR / "orchestrator-status.json"
+COLLECTOR_INTERVAL = 1.0
+SSE_KEEPALIVE_SECONDS = 15
+SSE_MAX_CLIENTS = 100
+SSE_QUEUE_MAXSIZE = 50
+SSE_WRITE_TIMEOUT = 5.0
+
+# Perform initial load from environment
+reload()

package/ui/csrf.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Aesop UI CSRF Protection — Token generation and validation.
+
+Session token is generated once at startup and persisted to state/.ui-session-token (0600).
+Token is used to validate mutations via /submit POST endpoint.
+
+CRITICAL: This module reads config paths LIVE at call time via 'import config',
+never 'from config import <path>'. This ensures paths are recomputed when
+config.reload() is called (e.g., between test fixtures).
+"""
+import os
+import secrets
+import sys
+from pathlib import Path
+
+# Must import config module, never "from config import <paths>"
+import config
+
+
+# Module-level session token (set by init())
+SESSION_TOKEN = None
+
+
+def init():
+    """Initialize CSRF protection: generate or load the per-session token.
+
+    This should be called once at startup (after config.reload()).
+    Token is persisted to state/.ui-session-token (mode 0600) and reused
+    across server restarts.
+
+    SECURITY: File is created atomically with restricted permissions using
+    os.open(O_CREAT|O_EXCL) to avoid TOCTOU window where file exists with
+    world-readable permissions.
+    """
+    global SESSION_TOKEN
+    SESSION_TOKEN = _generate_session_token()
+
+
+def _generate_session_token():
+    """Generate or load the per-session CSRF token.
+
+    Token is generated once at startup and persisted to state/.ui-session-token (mode 0600).
+    Subsequent calls return the same token (in-memory).
+
+    SECURITY: File is created atomically with restricted permissions using os.open(O_CREAT|O_EXCL)
+    to avoid TOCTOU window where file exists with world-readable permissions.
+
+    Returns:
+        str: 43-character base64-like random token (256 bits / 3 bytes per char = ~43 chars)
+    """
+    # LIVE CONFIG READ: access config.UI_SESSION_TOKEN_FILE at call time
+    token_file = config.UI_SESSION_TOKEN_FILE
+
+    # Check if token file exists and is readable
+    if token_file.exists():
+        try:
+            token = token_file.read_text().strip()
+            if token and len(token) >= 32:
+                return token
+        except Exception as e:
+            print(f"[csrf] Failed to read token file: {e}", file=sys.stderr)
+
+    # Generate new token: 32 random bytes → 43-char base64-like string
+    token = secrets.token_urlsafe(32)
+
+    # Persist to file with restricted permissions (0600) using atomic creation
+    try:
+        # LIVE CONFIG READ: access config.STATE_DIR at call time
+        config.STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Atomically create file with 0600 permissions using os.open with O_CREAT|O_EXCL.
+        # This ensures the file is never world-readable (no TOCTOU window).
+        # On Windows, mode bits are largely ignored, which is fine.
+        try:
+            fd = os.open(
+                str(token_file),
+                os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+                0o600
+            )
+            # Write token via the file descriptor (no separate chmod needed)
+            with os.fdopen(fd, 'w') as f:
+                f.write(token)
+        except FileExistsError:
+            # File already exists (race condition or previous run).
+            # Try to read it and use that token instead.
+            try:
+                token = token_file.read_text().strip()
+                if token and len(token) >= 32:
+                    return token
+            except Exception as e:
+                print(f"[csrf] Failed to read existing token file: {e}", file=sys.stderr)
+            # If we can't read the existing file, fall back to in-memory token
+    except Exception:
+        pass  # Fail-open: token exists in memory even if file write fails
+
+    return token
+
+
+def validate_csrf_request(headers):
+    """Validate CSRF protections on /submit POST request.
+
+    Performs two checks:
+    1. Origin/Referer validation: if Origin or Referer header is present, must be local
+       (http://127.0.0.1:<port>, http://localhost:<port>)
+    2. X-Aesop-Token validation: must match SESSION_TOKEN
+
+    Args:
+        headers: dict-like object with HTTP headers (case-insensitive)
+
+    Returns:
+        tuple: (is_valid: bool, reason: str or None)
+        - (True, None) if CSRF checks pass
+        - (False, reason) if either check fails
+    """
+    # Check 1: Origin/Referer header validation
+    origin = headers.get("Origin", "").strip()
+    referer = headers.get("Referer", "").strip()
+
+    # If Origin or Referer is present, validate it's local
+    if origin or referer:
+        check_value = origin or referer
+        # Check if it's a local origin: http://127.0.0.1:<PORT> or http://localhost:<PORT>
+        is_local = (
+            check_value.startswith("http://127.0.0.1:") or
+            check_value.startswith("http://localhost:") or
+            check_value.startswith("http://[::1]:")  # IPv6 localhost
+        )
+        if not is_local:
+            return (False, "Foreign Origin/Referer rejected")
+
+    # Check 2: X-Aesop-Token validation
+    token = headers.get("X-Aesop-Token", "").strip()
+    if not token:
+        return (False, "Missing X-Aesop-Token header")
+
+    if token != SESSION_TOKEN:
+        return (False, "Invalid X-Aesop-Token")
+
+    return (True, None)

package/ui/handler.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""Aesop UI — HTTP request handler (DashboardHandler) + server entry (wave-9 split)."""
+import http.server
+import json
+import queue
+import sys
+import threading
+import urllib.parse
+from pathlib import Path
+
+import config
+import csrf
+import sse
+import api
+import api.tracker
+import api.submit
+from render import render_dashboard
+from csrf import validate_csrf_request
+from collectors import (_snapshot_data, _snapshot_tracker,
+                       _snapshot_orchestrator_status, drain_tracker_inbox,
+                       get_alerts, get_heartbeat_status,
+                       get_main_thread_messages, get_monitor_heartbeat_status,
+                       get_recent_events, get_repos_status,
+                       parse_audit_backlog)
+from agents import (_AGENT_ID_FORBIDDEN, _transcripts_fingerprint,
+                   extract_agent_dispatch_prompt, get_fleet_agents)
+from sse import (_latest_lock, _latest_snapshots, _maybe_emit,
+                register_sse_client, unregister_sse_client)
+
+
+class DashboardHandler(http.server.BaseHTTPRequestHandler):
+    """HTTP request handler for dashboard."""
+
+    def log_message(self, format, *args):
+        """Suppress default logging."""
+        pass
+
+    def do_GET(self):
+        """Handle GET requests."""
+        if self.path == "/":
+            self.serve_html()
+        elif self.path == "/data":
+            self.serve_data()
+        elif self.path == "/api/backlog":
+            self.serve_backlog()
+        elif self.path == "/api/agents":
+            self.serve_agents()
+        elif self.path.startswith("/api/tracker"):
+            self.serve_tracker()
+        elif self.path.startswith("/agent?"):
+            self.serve_agent()
+        elif self.path == "/events":
+            self.serve_events()
+        else:
+            self.send_error(404)
+
+    def do_POST(self):
+        """Handle POST requests."""
+        if self.path == "/submit":
+            self.handle_submit()
+        elif self.path == "/api/tracker":
+            self.handle_tracker_create()
+        elif self.path.startswith("/api/tracker/"):
+            self.handle_tracker_mutate()
+        else:
+            self.send_error(404)
+
+    def serve_html(self):
+        """Serve the dashboard HTML."""
+        html = render_dashboard(csrf.SESSION_TOKEN)
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+        self.end_headers()
+        self.wfile.write(html.encode('utf-8'))
+
+    def serve_data(self):
+        """Serve dashboard data as JSON."""
+        data = {
+            "watchdog": get_heartbeat_status(),
+            "monitor": get_monitor_heartbeat_status(),
+            "agents": get_fleet_agents(),
+            "repos": get_repos_status(),
+            "events": get_recent_events(),
+            "alerts": get_alerts(),
+            "messages": get_main_thread_messages(),
+        }
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+        self.end_headers()
+        self.wfile.write(json.dumps(data, default=str).encode('utf-8'))
+
+    def serve_tracker(self):
+        """Serve tracker items as JSON via GET /api/tracker."""
+        try:
+            # Parse query string for filters
+            query = urllib.parse.urlparse(self.path).query
+            params = urllib.parse.parse_qs(query)
+            status = params.get('status', [None])[0]
+            priority = params.get('priority', [None])[0]
+
+            status_code, body = api.tracker.list_items(status=status, priority=priority)
+            self.send_response(status_code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.end_headers()
+            self.wfile.write(json.dumps(body, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+    def handle_tracker_create(self):
+        """Handle POST /api/tracker (create item)."""
+        try:
+            is_valid, reason = validate_csrf_request(self.headers)
+            if not is_valid:
+                self.send_response(403)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "CSRF protection: " + reason}).encode('utf-8'))
+                return
+
+            content_length = int(self.headers.get('Content-Length', 0))
+            # Read bounded amount; api.validate_mutation() validates Content-Length
+            body_bytes = self.rfile.read(min(max(content_length, 0), api.MAX_BODY_BYTES))
+            status_code, result = api.tracker.create(self.headers, body_bytes)
+            self.send_response(status_code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps(result, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+    def handle_tracker_mutate(self):
+        """Handle POST /api/tracker/<id> (update or delete)."""
+        try:
+            is_valid, reason = validate_csrf_request(self.headers)
+            if not is_valid:
+                self.send_response(403)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "CSRF protection: " + reason}).encode('utf-8'))
+                return
+
+            # Extract item_id from path
+            path_parts = self.path.strip("/").split("/")
+            if len(path_parts) < 3:
+                self.send_response(404)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "Not found"}).encode('utf-8'))
+                return
+
+            item_id = path_parts[2]
+
+            # Parse query for action (update or delete)
+            query = urllib.parse.urlparse(self.path).query
+            params = urllib.parse.parse_qs(query)
+            action = params.get('action', ['update'])[0]
+
+            if action == "delete":
+                status_code, result = api.tracker.delete(item_id)
+                self.send_response(status_code)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps(result, default=str).encode('utf-8'))
+            else:
+                content_length = int(self.headers.get('Content-Length', 0))
+                # Read bounded amount; api.validate_mutation() validates Content-Length
+                body_bytes = self.rfile.read(min(max(content_length, 0), api.MAX_BODY_BYTES))
+                status_code, result = api.tracker.update(item_id, body_bytes)
+                self.send_response(status_code)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps(result, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+
+    def serve_backlog(self):
+        """Serve audit backlog data as JSON via GET /api/backlog."""
+        try:
+            data = parse_audit_backlog()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.end_headers()
+            self.wfile.write(json.dumps(data, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+    def serve_agents(self):
+        """Serve rich agent list with metadata via GET /api/agents."""
+        try:
+            agents = get_fleet_agents()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.end_headers()
+            self.wfile.write(json.dumps(agents, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+    def serve_agent(self):
+        """Serve agent dispatch prompt and metadata via GET /agent?id=<agent_id>"""
+        try:
+            # Parse query string
+            query = urllib.parse.urlparse(self.path).query
+            params = urllib.parse.parse_qs(query)
+            agent_id = params.get('id', [None])[0]
+
+            if not agent_id:
+                self.send_response(400)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "missing id parameter"}).encode('utf-8'))
+                return
+
+            # Extract dispatch prompt and metadata
+            data = extract_agent_dispatch_prompt(agent_id)
+
+            if "error" in data:
+                # Rejected input (path traversal, glob metacharacters, or a match
+                # that resolved outside config.TRANSCRIPTS_ROOT) -> 400. A well-formed id
+                # with no matching transcript -> 404. Never 200 on error.
+                status = 400 if data.get("invalid") else 404
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": data["error"]}).encode('utf-8'))
+                return
+
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.end_headers()
+            self.wfile.write(json.dumps(data, default=str).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            print(f"[serve_agent] Uncaught exception: {e}", file=sys.stderr)
+            self.wfile.write(json.dumps({"error": "Internal server error"}).encode('utf-8'))
+
+    def _write_sse_event(self, event_name, payload):
+        """Write one SSE frame with timeout. Caller handles disconnect exceptions."""
+        msg = f"event: {event_name}\ndata: {payload}\n\n"
+        # Set socket timeout to prevent stalled writes from blocking the server
+        old_timeout = None
+        try:
+            old_timeout = self.connection.gettimeout()
+            self.connection.settimeout(config.SSE_WRITE_TIMEOUT)
+        except (AttributeError, OSError):
+            pass
+        try:
+            self.wfile.write(msg.encode("utf-8"))
+            self.wfile.flush()
+        finally:
+            # Restore original timeout
+            try:
+                if old_timeout is not None:
+                    self.connection.settimeout(old_timeout)
+            except (AttributeError, OSError):
+                pass
+
+    def serve_events(self):
+        """GET /events — Server-Sent Events stream.
+
+        No CSRF token required: this is a read-only stream, not a mutation (POST
+        /submit keeps its token requirement unchanged). Holds the connection open
+        for the life of the client; requires ThreadingHTTPServer (see run_server)
+        so one SSE client can't block every other request.
+
+        Returns HTTP 503 if concurrent connection cap (config.SSE_MAX_CLIENTS) is exceeded.
+        """
+        sse.start_collector_thread()
+
+        q = register_sse_client()
+        if q is None:
+            # Connection cap exceeded; return 503 Service Unavailable
+            try:
+                self.send_response(503)
+                self.send_header("Content-Type", "text/plain")
+                self.send_header("Retry-After", "30")
+                self.end_headers()
+                self.wfile.write(b"Service overloaded: too many concurrent clients\n")
+            except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
+                pass
+            return
+
+        try:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.send_header("Connection", "keep-alive")
+            self.send_header("X-Accel-Buffering", "no")
+            self.end_headers()
+        except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
+            unregister_sse_client(q)
+            return
+        try:
+            # Send an immediate full snapshot so first paint isn't empty. If the
+            # collector hasn't produced anything yet (first-ever request), compute
+            # it inline once.
+            with _latest_lock:
+                initial = dict(_latest_snapshots)
+            if all(v is None for v in initial.values()):
+                initial["data"] = json.dumps(_snapshot_data(), default=str, sort_keys=True)
+                initial["backlog"] = json.dumps(parse_audit_backlog(), default=str, sort_keys=True)
+                initial["agents"] = json.dumps(get_fleet_agents(), default=str, sort_keys=True)
+                initial["tracker"] = json.dumps(_snapshot_tracker(), default=str, sort_keys=True)
+                initial["status"] = json.dumps(_snapshot_orchestrator_status(), default=str, sort_keys=True)
+                with _latest_lock:
+                    _latest_snapshots.update(initial)
+
+            for name in ("data", "backlog", "agents", "tracker", "status"):
+                payload = initial.get(name)
+                if payload is not None:
+                    self._write_sse_event(name, payload)
+
+            while True:
+                try:
+                    event_name, payload = q.get(timeout=config.SSE_KEEPALIVE_SECONDS)
+                    self._write_sse_event(event_name, payload)
+                except queue.Empty:
+                    self.wfile.write(b": keepalive\n\n")
+                    self.wfile.flush()
+        except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
+            # Client disconnected (tab closed, network drop) — normal, not an error.
+            pass
+        except Exception:
+            pass
+        finally:
+            unregister_sse_client(q)
+
+    def handle_submit(self):
+        """Handle /submit POST with CSRF protection."""
+        try:
+            # CSRF validation: Check Origin/Referer + X-Aesop-Token
+            is_valid, reason = validate_csrf_request(self.headers)
+            if not is_valid:
+                self.send_response(403)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({
+                    "error": "CSRF protection: " + reason
+                }).encode('utf-8'))
+                return
+
+            content_length = int(self.headers.get('Content-Length', 0))
+            if content_length <= 0 or content_length > 10000:  # 10KB limit, must be positive
+                self.send_response(400)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({
+                    "error": "Invalid Content-Length (must be 1-10000 bytes)"
+                }).encode('utf-8'))
+                return
+
+            body_bytes = self.rfile.read(content_length)
+            data = json.loads(body_bytes.decode('utf-8', errors='ignore'))
+            text = data.get("text", "").strip()
+
+            if not text:
+                self.send_response(400)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": "No text provided"}).encode('utf-8'))
+                return
+
+            ok, result = api.submit.append_to_inbox(text)
+            if not ok:
+                status_code, error = result
+                self.send_response(status_code)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(json.dumps(error).encode('utf-8'))
+                return
+
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"ok": True}).encode('utf-8'))
+        except Exception as e:
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
+
+def run_server():
+    """Start the HTTP server.
+
+    Must be ThreadingHTTPServer, not HTTPServer: GET /events (SSE) holds its
+    connection open for the life of the client, so a single-threaded server would
+    wedge every other request (including the initial page load and /submit)
+    behind that one held connection.
+    """
+    addr = ("127.0.0.1", config.PORT)
+    httpd = http.server.ThreadingHTTPServer(addr, DashboardHandler)
+    httpd.daemon_threads = True
+    sse.start_collector_thread()
+    print(f"Dashboard: http://localhost:{config.PORT}")
+    print(f"config.AESOP_ROOT: {config.AESOP_ROOT}")
+    print(f"Transcripts: {config.TRANSCRIPTS_ROOT}")
+    print(f"Press Ctrl-C to stop")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        sse._collector_stop_event.set()
+        print("\nShutdown complete.")
+        sys.exit(0)