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

package/ui/cost.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Cost/scorecard collector — parse ledger and aggregate costs.
+
+This module provides get_cost_summary() which parses the outcomes ledger
+markdown table and returns per-model, per-day, and overall cost/token aggregations
+with optional pricing estimates.
+
+Ledger format (markdown table):
+  | ISO timestamp | agent_type | model | duration | tokens_in | tokens_out | verdict |
+  | 2026-07-11T22:08:17 | Agent | claude-haiku-4-5-20251001 | 0 | 8 | 186 | OK |
+
+CostSummary JSON shape (returned by get_cost_summary()):
+  {
+    "models": {
+      "model-id": {
+        "runs": int,
+        "tokens_in": int,
+        "tokens_out": int,
+        "verdicts": {"OK": int, "FAILED": int, "EMPTY": int, "HUNG": int}
+      },
+      ...
+    },
+    "daily_totals": {
+      "YYYY-MM-DD": {"tokens_in": int, "tokens_out": int},
+      ...
+    },
+    "overall_scorecard": {
+      "total_runs": int,
+      "ok_count": int,
+      "failed_count": int,
+      "empty_count": int,
+      "hung_count": int,
+      "ok_rate": float (0.0-1.0),
+      "failed_rate": float,
+      "empty_rate": float,
+      "hung_rate": float
+    },
+    "skipped_lines": int,
+    "has_pricing": bool,
+    "estimates_by_model": {
+      "model-id": {
+        "input_cost": float (dollars),
+        "output_cost": float (dollars),
+        "total_cost": float (dollars)
+      },
+      ...
+    }
+  }
+
+Key behavior:
+  - Missing ledger file: returns empty summary with documented shape.
+  - Malformed lines: skipped and counted in skipped_lines field.
+  - Config read at CALL time (not import time) for test isolation.
+  - UTF-8 explicit encoding for all file operations.
+  - No external dependencies (pure stdlib).
+  - Pricing estimates ONLY if aesop.config.json has a "pricing" map.
+"""
+import json
+from pathlib import Path
+
+# Note: import config at module level, but read config.X at CALL time
+# (not at import time) to ensure test-fixture isolation works.
+import config
+
+
+def get_cost_summary():
+    """Parse the outcomes ledger and return cost/token/verdict aggregations.
+
+    Reads from the ledger path exposed by config (config.STATE_DIR/ledger/OUTCOMES-LEDGER.md).
+    Returns an empty summary with documented shape if ledger is missing or empty.
+    Malformed lines are skipped and counted in skipped_lines.
+
+    All config paths are read at call time (not import time) to ensure
+    test-fixture isolation via config.reload().
+
+    Returns:
+        dict: CostSummary with models, daily_totals, overall_scorecard,
+              skipped_lines, has_pricing, estimates_by_model.
+    """
+    # Read ledger path at call time
+    ledger_file = config.STATE_DIR / "ledger" / "OUTCOMES-LEDGER.md"
+
+    # Initialize result structure
+    result = {
+        "models": {},
+        "daily_totals": {},
+        "overall_scorecard": {
+            "total_runs": 0,
+            "ok_count": 0,
+            "failed_count": 0,
+            "empty_count": 0,
+            "hung_count": 0,
+            "ok_rate": 0.0,
+            "failed_rate": 0.0,
+            "empty_rate": 0.0,
+            "hung_rate": 0.0,
+        },
+        "skipped_lines": 0,
+        "has_pricing": False,
+        "estimates_by_model": {},
+    }
+
+    # If ledger file doesn't exist, return empty summary
+    if not ledger_file.exists():
+        return result
+
+    # Read and parse ledger with explicit UTF-8 encoding
+    try:
+        content = ledger_file.read_text(encoding='utf-8')
+    except Exception:
+        # Graceful: if read fails, return empty summary
+        return result
+
+    lines = content.strip().split('\n')
+
+    # Parse each line
+    for line in lines:
+        line = line.strip()
+
+        # Skip empty lines
+        if not line:
+            continue
+
+        # Skip header separator lines (all dashes and pipes) — silently, don't count as skipped
+        if all(c in '|-' for c in line):
+            continue
+
+        # Parse pipe-delimited row
+        if not line.startswith('|') or not line.endswith('|'):
+            result["skipped_lines"] += 1
+            continue
+
+        # Split by pipe and strip whitespace
+        parts = [p.strip() for p in line.split('|')]
+
+        # Markdown tables have empty strings at start and end after split
+        # Format: | col1 | col2 | col3 | col4 | col5 | col6 | col7 |
+        # After split: ['', 'col1', 'col2', 'col3', 'col4', 'col5', 'col6', 'col7', '']
+        if len(parts) < 9:  # Need at least 9 parts (empty + 7 columns + empty)
+            result["skipped_lines"] += 1
+            continue
+
+        # Extract columns (skip leading/trailing empty)
+        try:
+            timestamp = parts[1]  # ISO timestamp
+            agent_type = parts[2]  # "Agent"
+            model = parts[3]
+            duration_str = parts[4]
+            tokens_in_str = parts[5]
+            tokens_out_str = parts[6]
+            verdict = parts[7]
+        except IndexError:
+            result["skipped_lines"] += 1
+            continue
+
+        # Parse numeric fields
+        try:
+            tokens_in = int(tokens_in_str)
+            tokens_out = int(tokens_out_str)
+        except ValueError:
+            result["skipped_lines"] += 1
+            continue
+
+        # Validate verdict
+        if verdict not in ("OK", "FAILED", "EMPTY", "HUNG"):
+            result["skipped_lines"] += 1
+            continue
+
+        # Extract date from ISO timestamp (YYYY-MM-DD)
+        try:
+            date_str = timestamp.split('T')[0]
+        except IndexError:
+            result["skipped_lines"] += 1
+            continue
+
+        # Aggregate by model
+        if model not in result["models"]:
+            result["models"][model] = {
+                "runs": 0,
+                "tokens_in": 0,
+                "tokens_out": 0,
+                "verdicts": {"OK": 0, "FAILED": 0, "EMPTY": 0, "HUNG": 0},
+            }
+
+        result["models"][model]["runs"] += 1
+        result["models"][model]["tokens_in"] += tokens_in
+        result["models"][model]["tokens_out"] += tokens_out
+        result["models"][model]["verdicts"][verdict] += 1
+
+        # Aggregate by date
+        if date_str not in result["daily_totals"]:
+            result["daily_totals"][date_str] = {"tokens_in": 0, "tokens_out": 0}
+
+        result["daily_totals"][date_str]["tokens_in"] += tokens_in
+        result["daily_totals"][date_str]["tokens_out"] += tokens_out
+
+        # Count for overall scorecard
+        result["overall_scorecard"]["total_runs"] += 1
+        if verdict == "OK":
+            result["overall_scorecard"]["ok_count"] += 1
+        elif verdict == "FAILED":
+            result["overall_scorecard"]["failed_count"] += 1
+        elif verdict == "EMPTY":
+            result["overall_scorecard"]["empty_count"] += 1
+        elif verdict == "HUNG":
+            result["overall_scorecard"]["hung_count"] += 1
+
+    # Calculate rates
+    total = result["overall_scorecard"]["total_runs"]
+    if total > 0:
+        result["overall_scorecard"]["ok_rate"] = result["overall_scorecard"]["ok_count"] / total
+        result["overall_scorecard"]["failed_rate"] = result["overall_scorecard"]["failed_count"] / total
+        result["overall_scorecard"]["empty_rate"] = result["overall_scorecard"]["empty_count"] / total
+        result["overall_scorecard"]["hung_rate"] = result["overall_scorecard"]["hung_count"] / total
+
+    # Load pricing config at call time and compute estimates
+    pricing_map = _load_pricing_config()
+    if pricing_map:
+        result["has_pricing"] = True
+        for model, stats in result["models"].items():
+            if model in pricing_map:
+                pricing = pricing_map[model]
+                input_price = pricing.get("input_per_mtok", 0.0)
+                output_price = pricing.get("output_per_mtok", 0.0)
+
+                # Calculate costs: (tokens / 1_000_000) * price_per_mtok
+                input_cost = (stats["tokens_in"] * input_price) / 1_000_000
+                output_cost = (stats["tokens_out"] * output_price) / 1_000_000
+                total_cost = input_cost + output_cost
+
+                result["estimates_by_model"][model] = {
+                    "input_cost": input_cost,
+                    "output_cost": output_cost,
+                    "total_cost": total_cost,
+                }
+
+    return result
+
+
+def _load_pricing_config():
+    """Load pricing map from aesop.config.json at call time.
+
+    Returns:
+        dict or None: pricing map {model: {input_per_mtok: float, output_per_mtok: float}}
+                      or None if no pricing config found.
+    """
+    # Read config file at call time (not import time)
+    config_file = config.CONFIG_FILE
+
+    if not config_file.exists():
+        return None
+
+    try:
+        with open(config_file, encoding='utf-8') as f:
+            config_data = json.load(f)
+    except Exception:
+        # Graceful: if config read fails, no pricing
+        return None
+
+    return config_data.get("pricing", None)

package/ui/csrf.py

@@ -102,7 +102,7 @@ def validate_csrf_request(headers):
 
     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>)
+       (http[s]://127.0.0.1:<port>, http[s]://localhost:<port>, http[s]://[::1]:<port>)
     2. X-Aesop-Token validation: must match SESSION_TOKEN
 
     Args:
@@ -120,11 +120,15 @@ def validate_csrf_request(headers):
     # 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>
+        # Check if it's a local origin: http[s]://127.0.0.1:<PORT>, http[s]://localhost:<PORT>,
+        # or http[s]://[::1]:<PORT> (both http:// and https:// schemes accepted for same hosts)
         is_local = (
             check_value.startswith("http://127.0.0.1:") or
+            check_value.startswith("https://127.0.0.1:") or
             check_value.startswith("http://localhost:") or
-            check_value.startswith("http://[::1]:")  # IPv6 localhost
+            check_value.startswith("https://localhost:") or
+            check_value.startswith("http://[::1]:") or  # IPv6 localhost
+            check_value.startswith("https://[::1]:")  # IPv6 localhost HTTPS
         )
         if not is_local:
             return (False, "Foreign Origin/Referer rejected")

package/ui/handler.py

@@ -3,12 +3,14 @@
 import http.server
 import json
 import queue
+import socketserver
 import sys
 import threading
 import urllib.parse
 from pathlib import Path
 
 import config
+import cost
 import csrf
 import sse
 import api
@@ -28,6 +30,42 @@ from sse import (_latest_lock, _latest_snapshots, _maybe_emit,
                 register_sse_client, unregister_sse_client)
 
 
+# SSE section names, in emit order. /api/state returns the same sections so the
+# frontend's first paint is one round trip (plan D3.1).
+_STATE_SECTIONS = ("data", "backlog", "agents", "tracker", "status", "cost")
+
+# MIME types for the built dist's content-hashed assets (wave-14, plan D3.4).
+_ASSET_MIME = {
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".map": "application/json; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+}
+
+
+def _is_local_origin(origin):
+    """True if an Origin header value is on the local allowlist.
+
+    Keep in sync with csrf.validate_csrf_request(): same six local forms
+    (http[s]://127.0.0.1:<port>, http[s]://localhost:<port>, http[s]://[::1]:<port>).
+    Both http:// and https:// schemes are accepted for the same loopback hosts.
+    """
+    return bool(origin) and (
+        origin.startswith("http://127.0.0.1:") or
+        origin.startswith("https://127.0.0.1:") or
+        origin.startswith("http://localhost:") or
+        origin.startswith("https://localhost:") or
+        origin.startswith("http://[::1]:") or
+        origin.startswith("https://[::1]:")
+    )
+
+
 class DashboardHandler(http.server.BaseHTTPRequestHandler):
     """HTTP request handler for dashboard."""
 
@@ -41,16 +79,29 @@ class DashboardHandler(http.server.BaseHTTPRequestHandler):
             self.serve_html()
         elif self.path == "/data":
             self.serve_data()
+        elif self.path == "/api/state":
+            self.serve_api_state()
+        elif self.path == "/api/session":
+            self.serve_api_session()
+        elif self.path == "/api/cost":
+            self.serve_api_cost()
         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("/assets/"):
+            self.serve_asset()
         elif self.path.startswith("/agent?"):
             self.serve_agent()
         elif self.path == "/events":
             self.serve_events()
+        elif self.path == "/favicon.ico":
+            # Browsers auto-request this; answer 204 so it never 404s (keeps the
+            # console clean — the dashboard ships no favicon asset).
+            self.send_response(204)
+            self.end_headers()
         else:
             self.send_error(404)
 
@@ -66,14 +117,177 @@ class DashboardHandler(http.server.BaseHTTPRequestHandler):
             self.send_error(404)
 
     def serve_html(self):
-        """Serve the dashboard HTML."""
-        html = render_dashboard(csrf.SESSION_TOKEN)
+        """Serve the dashboard HTML.
+
+        Wave-14 (plan D3.4/D7 U9 cutover): the built frontend at
+        config.WEB_DIST/index.html is always required and must be present;
+        if missing, return a hard 500 with a clear error (never fall back to
+        a legacy template). config.WEB_DIST is read at call time so
+        config.reload() keeps working across fixtures.
+        """
+        dist_index = config.WEB_DIST / "index.html"
+        if not dist_index.is_file():
+            error_msg = (
+                "built dashboard missing — run npm run build in ui/web"
+            )
+            self.send_response(500)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+            self.end_headers()
+            self.wfile.write(error_msg.encode('utf-8'))
+            return
+
+        html = render_dashboard(csrf.SESSION_TOKEN, template_path=dist_index)
         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_asset(self):
+        """GET /assets/* — static files from the built dist (config.WEB_DIST/assets).
+
+        Security: path-traversal containment via resolve() + is_relative_to,
+        mirroring the pattern in agents.py — the resolved candidate must stay
+        inside WEB_DIST/assets or the request is refused. URL-encoded (%2e%2e,
+        %2f, %5c) and absolute-path inputs are decoded first so the containment
+        check sees the real target.
+
+        Caching: filenames are content-hashed by the Vite build, so responses
+        are immutable (Cache-Control: public, max-age=31536000, immutable).
+        """
+        try:
+            assets_root = config.WEB_DIST / "assets"
+            if not assets_root.is_dir():
+                # No built dist present (pre-cutover main) — nothing to serve.
+                self.send_error(404)
+                return
+
+            raw_path = urllib.parse.urlparse(self.path).path
+            rel = urllib.parse.unquote(raw_path[len("/assets/"):])
+            if not rel or "\x00" in rel:
+                self.send_error(404)
+                return
+
+            candidate = (assets_root / rel).resolve()
+
+            # Containment check: the resolved target must stay inside
+            # WEB_DIST/assets. Same belt-and-suspenders shape as agents.py.
+            try:
+                is_contained = candidate.is_relative_to(assets_root.resolve())
+            except AttributeError:
+                # Path.is_relative_to requires Python 3.9+; fall back for older runtimes.
+                try:
+                    candidate.relative_to(assets_root.resolve())
+                    is_contained = True
+                except ValueError:
+                    is_contained = False
+            if not is_contained:
+                self.send_error(403)
+                return
+
+            if not candidate.is_file():
+                self.send_error(404)
+                return
+
+            content = candidate.read_bytes()
+            mime = _ASSET_MIME.get(candidate.suffix.lower(), "application/octet-stream")
+            self.send_response(200)
+            self.send_header("Content-Type", mime)
+            self.send_header("Content-Length", str(len(content)))
+            self.send_header("Cache-Control", "public, max-age=31536000, immutable")
+            self.end_headers()
+            self.wfile.write(content)
+        except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
+            pass  # client went away mid-response — normal, not an error
+        except Exception as e:
+            print(f"[serve_asset] Uncaught exception: {e}", file=sys.stderr)
+            self.send_error(500)
+
+    def serve_api_state(self):
+        """GET /api/state — consolidated snapshot of all six SSE sections.
+
+        One round trip for the frontend's first paint (plan D3.1). Reuses the
+        collectors' latest-snapshot mechanism: sections the background collector
+        has already produced are returned as-is; anything not yet snapshotted
+        (first-ever request) is computed inline, mirroring serve_events.
+        """
+        try:
+            sse.start_collector_thread()
+            with _latest_lock:
+                latest = dict(_latest_snapshots)
+
+            computers = {
+                "data": _snapshot_data,
+                "backlog": parse_audit_backlog,
+                "agents": get_fleet_agents,
+                "tracker": _snapshot_tracker,
+                "status": _snapshot_orchestrator_status,
+                "cost": cost.get_cost_summary,
+            }
+            state = {}
+            for name in _STATE_SECTIONS:
+                payload = latest.get(name)
+                if payload is not None:
+                    state[name] = json.loads(payload)
+                else:
+                    state[name] = computers[name]()
+
+            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(state, 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_api_session(self):
+        """GET /api/session — the CSRF token for same-origin JS (plan D3.3).
+
+        Exists so the Vite dev server (which cannot do the sentinel
+        substitution) still gets a working token; the built app keeps the
+        sentinel-injection path as primary.
+
+        SECURITY — Origin-checked FAIL-CLOSED: unlike the mutation endpoints
+        (where a missing Origin is tolerated because the token itself gates the
+        write), this endpoint HANDS OUT the token, so absence of an Origin
+        header is a refusal. Only the same local allowlist csrf.py uses
+        (127.0.0.1 / localhost / [::1]) is accepted.
+        """
+        origin = self.headers.get("Origin", "").strip()
+        if not _is_local_origin(origin):
+            self.send_response(403)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(json.dumps(
+                {"error": "Forbidden: /api/session requires a local Origin header"}
+            ).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({"token": csrf.SESSION_TOKEN}).encode('utf-8'))
+
+    def serve_api_cost(self):
+        """GET /api/cost — cost/scorecard summary from the outcomes ledger (plan D3.2)."""
+        try:
+            summary = cost.get_cost_summary()
+            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(summary, 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_data(self):
         """Serve dashboard data as JSON."""
         data = {
@@ -325,10 +539,11 @@ class DashboardHandler(http.server.BaseHTTPRequestHandler):
                 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)
+                initial["cost"] = json.dumps(cost.get_cost_summary(), default=str, sort_keys=True)
                 with _latest_lock:
                     _latest_snapshots.update(initial)
 
-            for name in ("data", "backlog", "agents", "tracker", "status"):
+            for name in _STATE_SECTIONS:
                 payload = initial.get(name)
                 if payload is not None:
                     self._write_sse_event(name, payload)
@@ -402,6 +617,39 @@ class DashboardHandler(http.server.BaseHTTPRequestHandler):
             self.end_headers()
             self.wfile.write(json.dumps({"error": str(e)}).encode('utf-8'))
 
+
+class QuietThreadingHTTPServer(http.server.ThreadingHTTPServer):
+    """ThreadingHTTPServer that suppresses expected socket disconnect exceptions.
+
+    During normal operation and especially during shutdown, ThreadingHTTPServer may
+    encounter ConnectionAbortedError (WinError 10053) or ConnectionResetError
+    (WinError 10054) when clients disconnect abruptly. These are expected, not errors,
+    and clutter stderr with tracebacks.
+
+    This server overrides handle_error() to suppress only these two exception types
+    while still reporting all other exceptions (real bugs, timeouts, etc.).
+    """
+
+    def handle_error(self, request, client_address):
+        """Suppress client disconnect exceptions; report all others.
+
+        Args:
+            request: The socket request object
+            client_address: The client address tuple
+        """
+        exc_type, exc_value, exc_tb = sys.exc_info()
+
+        # Suppress only the two disconnect exception types that occur during
+        # normal client aborts (especially on shutdown). All other exceptions
+        # (real bugs, timeouts, etc.) still get logged via super().
+        if exc_type in (ConnectionAbortedError, ConnectionResetError):
+            # Expected client disconnect; silent is correct.
+            return
+
+        # All other exceptions get the default handler (logged to stderr)
+        super().handle_error(request, client_address)
+
+
 def run_server():
     """Start the HTTP server.
 
@@ -409,9 +657,11 @@ def run_server():
     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.
+
+    Uses QuietThreadingHTTPServer to suppress expected socket disconnect exceptions.
     """
     addr = ("127.0.0.1", config.PORT)
-    httpd = http.server.ThreadingHTTPServer(addr, DashboardHandler)
+    httpd = QuietThreadingHTTPServer(addr, DashboardHandler)
     httpd.daemon_threads = True
     sse.start_collector_thread()
     print(f"Dashboard: http://localhost:{config.PORT}")

package/ui/render.py

@@ -2,10 +2,15 @@
 """
 Aesop UI template rendering — stdlib-only.
 
-The dashboard HTML/CSS/JS lives in templates/dashboard.html (extracted from
-serve.py in the wave-9 split). The only server-side substitution is the
-per-session CSRF token, injected via a unique sentinel so the template stays a
-plain static file (no .format()/% — the CSS/JS is full of { } and % literals).
+The legacy dashboard HTML/CSS/JS lives in templates/dashboard.html (extracted
+from serve.py in the wave-9 split). Wave-14 (dashboard rewrite, plan D3/D7)
+retargets the same mechanism at the built React app: the handler passes
+ui/web/dist/index.html as template_path when a committed dist is present, and
+falls back to the legacy template otherwise. The only server-side substitution
+is the per-session CSRF token, injected via a unique sentinel so the template
+stays a plain static file (no .format()/% — the CSS/JS is full of { } and %
+literals; the Vite build passes the sentinel-carrying inline script through
+verbatim).
 """
 import json
 import os
@@ -17,13 +22,28 @@ _DASHBOARD_HTML = os.path.join(_TEMPLATE_DIR, "dashboard.html")
 _CSRF_SENTINEL = "__AESOP_CSRF_SENTINEL__"
 
 
-def render_dashboard(session_token):
+def render_dashboard(session_token, template_path=None):
     """Return the dashboard HTML with the CSRF token substituted in.
 
+    Args:
+        session_token: the per-session CSRF token to inject.
+        template_path: path to the template file carrying the CSRF sentinel
+            (wave-14 U9 cutover: dist/index.html is always required; no
+            fallback to templates/dashboard.html).
+
     Reads the template fresh each call (cheap; keeps edits live in dev). The
     token is inserted as a JS string literal via json.dumps so it is always a
     valid, properly-quoted value.
+
+    Raises:
+        TypeError: if template_path is None (legacy fallback removed at U9).
+        FileNotFoundError: if the template file does not exist.
     """
-    with open(_DASHBOARD_HTML, encoding="utf-8") as f:
+    if template_path is None:
+        raise TypeError(
+            "render_dashboard() requires template_path after wave-14 U9 cutover; "
+            "legacy fallback to templates/dashboard.html has been removed"
+        )
+    with open(template_path, encoding="utf-8") as f:
         html = f.read()
     return html.replace(_CSRF_SENTINEL, json.dumps(session_token))