htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/server.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 HtmlGraph REST API Server.
 
@@ -13,20 +17,20 @@ Or via CLI:
 """
 
 import json
-import re
+import socket
+import sys
 import urllib.parse
 from datetime import datetime, timezone
-from http.server import HTTPServer, SimpleHTTPRequestHandler
+from http.server import SimpleHTTPRequestHandler
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, cast
 
-from htmlgraph.graph import HtmlGraph
-from htmlgraph.models import Node, Edge, Step
-from htmlgraph.converter import node_to_dict, dict_to_node
 from htmlgraph.analytics_index import AnalyticsIndex
+from htmlgraph.converter import dict_to_node, node_to_dict
 from htmlgraph.event_log import JsonlEventLog
-from htmlgraph.file_watcher import GraphWatcher
+from htmlgraph.graph import HtmlGraph
 from htmlgraph.ids import generate_id
+from htmlgraph.models import Node
 
 
 class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
@@ -39,9 +43,19 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     analytics_db: AnalyticsIndex | None = None
 
     # Work item types (subfolders in .htmlgraph/)
-    COLLECTIONS = ["features", "bugs", "spikes", "chores", "epics", "sessions", "agents", "tracks"]
-
-    def __init__(self, *args, **kwargs):
+    COLLECTIONS = [
+        "features",
+        "bugs",
+        "spikes",
+        "chores",
+        "epics",
+        "sessions",
+        "agents",
+        "tracks",
+        "task-delegations",
+    ]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         # Set directory for static file serving
         self.directory = str(self.static_dir)
         super().__init__(*args, **kwargs)
@@ -54,14 +68,14 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
             # Tracks support both file-based (track-xxx.html) and directory-based (track-xxx/index.html)
             if collection == "tracks":
-                from htmlgraph.planning import Track
                 from htmlgraph.converter import html_to_node
+                from htmlgraph.planning import Track
 
                 graph = HtmlGraph(
                     collection_dir,
                     stylesheet_path="../styles.css",
                     auto_load=False,  # Manual load to convert to Track objects
-                    pattern=["*.html", "*/index.html"]
+                    pattern=["*.html", "*/index.html"],
                 )
 
                 # Helper to convert Node to Track with has_spec/has_plan detection
@@ -74,41 +88,62 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                         # Consolidated format: spec/plan are in the same file
                         # Check for data-section attributes in the file
                         content = filepath.read_text(encoding="utf-8")
-                        has_spec = 'data-section="overview"' in content or 'data-section="requirements"' in content
+                        has_spec = (
+                            'data-section="overview"' in content
+                            or 'data-section="requirements"' in content
+                        )
                         has_plan = 'data-section="plan"' in content
                     else:
                         # Directory format: separate spec.html and plan.html files
-                        has_spec = (track_dir / "spec.html").exists() if track_dir else False
-                        has_plan = (track_dir / "plan.html").exists() if track_dir else False
+                        has_spec = (
+                            (track_dir / "spec.html").exists() if track_dir else False
+                        )
+                        has_plan = (
+                            (track_dir / "plan.html").exists() if track_dir else False
+                        )
+
+                    # Map Node status to Track status
+                    track_status: Literal["planned", "active", "completed", "abandoned"]
+                    if node.status in ["planned", "active", "completed", "abandoned"]:
+                        track_status = cast(
+                            Literal["planned", "active", "completed", "abandoned"],
+                            node.status,
+                        )
+                    else:
+                        track_status = "planned"
 
                     return Track(
                         id=node.id,
                         title=node.title,
                         description=node.content or "",
-                        status=node.status if node.status in ["planned", "active", "completed", "abandoned"] else "planned",
+                        status=track_status,
                         priority=node.priority,
                         created=node.created,
                         updated=node.updated,
                         has_spec=has_spec,
                         has_plan=has_plan,
                         features=[],
-                        sessions=[]
+                        sessions=[],
                     )
 
                 # Load and convert tracks
-                patterns = graph.pattern if isinstance(graph.pattern, list) else [graph.pattern]
+                patterns = (
+                    graph.pattern
+                    if isinstance(graph.pattern, list)
+                    else [graph.pattern]
+                )
                 for pat in patterns:
                     for filepath in collection_dir.glob(pat):
                         if filepath.is_file():
                             try:
                                 node = html_to_node(filepath)
                                 track = node_to_track(node, filepath)
-                                graph._nodes[track.id] = track
+                                graph._nodes[track.id] = track  # type: ignore[assignment]
                             except Exception:
                                 continue
 
                 # Override reload to maintain Track conversion
-                def reload_tracks():
+                def reload_tracks() -> int:
                     graph._nodes.clear()
                     for pat in patterns:
                         for filepath in collection_dir.glob(pat):
@@ -116,22 +151,20 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                                 try:
                                     node = html_to_node(filepath)
                                     track = node_to_track(node, filepath)
-                                    graph._nodes[track.id] = track
+                                    graph._nodes[track.id] = track  # type: ignore[assignment]
                                 except Exception:
                                     continue
                     return len(graph._nodes)
 
-                graph.reload = reload_tracks
+                graph.reload = reload_tracks  # type: ignore[method-assign]
                 self.graphs[collection] = graph
             else:
                 self.graphs[collection] = HtmlGraph(
-                    collection_dir,
-                    stylesheet_path="../styles.css",
-                    auto_load=True
+                    collection_dir, stylesheet_path="../styles.css", auto_load=True
                 )
         return self.graphs[collection]
 
-    def _send_json(self, data: Any, status: int = 200):
+    def _send_json(self, data: Any, status: int = 200) -> None:
         """Send JSON response."""
         body = json.dumps(data, indent=2, default=str).encode("utf-8")
         self.send_response(status)
@@ -141,7 +174,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
-    def _send_error_json(self, message: str, status: int = 400):
+    def _send_error_json(self, message: str, status: int = 400) -> None:
         """Send JSON error response."""
         self._send_json({"error": message, "status": status}, status)
 
@@ -181,7 +214,15 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         return "api", collection, node_id, query_params
 
     def _serve_packaged_dashboard(self) -> bool:
-        """Serve the bundled dashboard HTML if available."""
+        """
+        DEPRECATED: Serve the bundled dashboard HTML if available.
+
+        NOTE: This server is LEGACY. The active server is FastAPI-based.
+        See: src/python/htmlgraph/operations/fastapi_server.py
+
+        The dashboard.html file was archived to .archived-templates/
+        Active templates are in src/python/htmlgraph/api/templates/
+        """
         dashboard_path = Path(__file__).parent / "dashboard.html"
         if not dashboard_path.exists():
             return False
@@ -193,17 +234,22 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         self.wfile.write(body)
         return True
 
-    def do_OPTIONS(self):
+    def do_OPTIONS(self) -> None:
         """Handle CORS preflight."""
         self.send_response(200)
         self.send_header("Access-Control-Allow-Origin", "*")
-        self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
+        self.send_header(
+            "Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS"
+        )
         self.send_header("Access-Control-Allow-Headers", "Content-Type")
         self.end_headers()
 
-    def do_GET(self):
+    def do_GET(self) -> None:
         """Handle GET requests."""
         api, collection, node_id, params = self._parse_path()
+        logger.debug(
+            f"do_GET: api={api}, collection={collection}, node_id={node_id}, params={params}"
+        )
 
         # Not an API request - serve static files
         if api != "api":
@@ -229,6 +275,15 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         if collection == "analytics":
             return self._handle_analytics(node_id, params)
 
+        # GET /api/orchestration - Get delegation chains and agent coordination
+        if collection == "orchestration":
+            logger.info(f"DEBUG: Handling orchestration request, params={params}")
+            return self._handle_orchestration_view(params)
+
+        # GET /api/task-delegations/stats - Get aggregated delegation statistics
+        if collection == "task-delegations" and params.get("stats") == "true":
+            return self._handle_task_delegations_stats()
+
         # GET /api/tracks/{track_id}/features - Get features for a track
         if collection == "tracks" and node_id and params.get("features") == "true":
             return self._handle_track_features(node_id)
@@ -237,6 +292,10 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         if collection == "features" and node_id and params.get("context") == "true":
             return self._handle_feature_context(node_id)
 
+        # GET /api/sessions/{session_id}?transcript=true - Get transcript stats
+        if collection == "sessions" and node_id and params.get("transcript") == "true":
+            return self._handle_session_transcript(node_id)
+
         # GET /api/collections - List available collections
         if collection == "collections":
             return self._send_json({"collections": self.COLLECTIONS})
@@ -251,7 +310,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         self._send_error_json(f"Unknown endpoint: {self.path}", 404)
 
-    def do_POST(self):
+    def do_POST(self) -> None:
         """Handle POST requests (create)."""
         api, collection, node_id, params = self._parse_path()
 
@@ -260,7 +319,11 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             return
 
         # POST /api/tracks/{track_id}/generate-features - Generate features from plan
-        if collection == "tracks" and node_id and params.get("generate-features") == "true":
+        if (
+            collection == "tracks"
+            and node_id
+            and params.get("generate-features") == "true"
+        ):
             try:
                 self._handle_generate_features(node_id)
                 return
@@ -289,7 +352,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(str(e), 500)
 
-    def do_PUT(self):
+    def do_PUT(self) -> None:
         """Handle PUT requests (full update)."""
         api, collection, node_id, params = self._parse_path()
 
@@ -309,7 +372,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(str(e), 500)
 
-    def do_PATCH(self):
+    def do_PATCH(self) -> None:
         """Handle PATCH requests (partial update)."""
         api, collection, node_id, params = self._parse_path()
 
@@ -329,7 +392,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(str(e), 500)
 
-    def do_DELETE(self):
+    def do_DELETE(self) -> None:
         """Handle DELETE requests."""
         api, collection, node_id, params = self._parse_path()
 
@@ -347,9 +410,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     # API Handlers
     # =========================================================================
 
-    def _handle_status(self):
+    def _handle_status(self) -> None:
         """Return overall graph status."""
-        status = {
+        status: dict[str, Any] = {
             "collections": {},
             "total_nodes": 0,
             "by_status": {},
@@ -390,14 +453,16 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     def _rebuild_analytics_db(self, db_path: Path) -> None:
         events_dir = self.graph_dir / "events"
         if not events_dir.exists() or not any(events_dir.glob("*.jsonl")):
-            raise FileNotFoundError("No event logs found under .htmlgraph/events/*.jsonl")
+            raise FileNotFoundError(
+                "No event logs found under .htmlgraph/events/*.jsonl"
+            )
 
         log = JsonlEventLog(events_dir)
         index = AnalyticsIndex(db_path)
         events = (event for _, event in log.iter_events())
         index.rebuild_from_events(events)
 
-    def _handle_analytics(self, endpoint: str | None, params: dict):
+    def _handle_analytics(self, endpoint: str | None, params: dict) -> None:
         """
         Analytics endpoints.
 
@@ -405,7 +470,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         If the index doesn't exist yet, we build it on-demand from `.htmlgraph/events/*.jsonl`.
         """
         if endpoint is None:
-            return self._send_error_json("Specify an analytics endpoint (overview, features, session)", 400)
+            return self._send_error_json(
+                "Specify an analytics endpoint (overview, features, session)", 400
+            )
 
         db_path = self.graph_dir / "index.sqlite"
 
@@ -424,7 +491,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                     404,
                 )
             except Exception as e:
-                return self._send_error_json(f"Failed to build analytics index: {e}", 500)
+                return self._send_error_json(
+                    f"Failed to build analytics index: {e}", 500
+                )
 
         def should_reset_index(err: Exception) -> bool:
             msg = str(err).lower()
@@ -436,7 +505,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 or "schema_version" in msg
             )
 
-        def with_rebuild(fn):
+        def with_rebuild(fn: Any) -> Any:
             try:
                 return fn()
             except Exception as e:
@@ -454,16 +523,32 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         if endpoint == "overview":
             try:
-                return self._send_json(with_rebuild(lambda: self._get_analytics().overview(since=since, until=until)))
+                return self._send_json(
+                    with_rebuild(
+                        lambda: self._get_analytics().overview(since=since, until=until)
+                    )
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (overview): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (overview): {e}", 500
+                )
 
         if endpoint == "features":
             limit = int(params.get("limit", 50))
             try:
-                return self._send_json({"features": with_rebuild(lambda: self._get_analytics().top_features(since=since, until=until, limit=limit))})
+                return self._send_json(
+                    {
+                        "features": with_rebuild(
+                            lambda: self._get_analytics().top_features(
+                                since=since, until=until, limit=limit
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (features): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (features): {e}", 500
+                )
 
         if endpoint == "session":
             session_id = params.get("id")
@@ -471,9 +556,19 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 return self._send_error_json("Missing required param: id", 400)
             limit = int(params.get("limit", 500))
             try:
-                return self._send_json({"events": with_rebuild(lambda: self._get_analytics().session_events(session_id=session_id, limit=limit))})
+                return self._send_json(
+                    {
+                        "events": with_rebuild(
+                            lambda: self._get_analytics().session_events(
+                                session_id=session_id, limit=limit
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (session): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (session): {e}", 500
+                )
 
         if endpoint == "continuity":
             feature_id = params.get("feature_id") or params.get("feature")
@@ -481,17 +576,43 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 return self._send_error_json("Missing required param: feature_id", 400)
             limit = int(params.get("limit", 200))
             try:
-                return self._send_json({"sessions": with_rebuild(lambda: self._get_analytics().feature_continuity(feature_id=feature_id, since=since, until=until, limit=limit))})
+                return self._send_json(
+                    {
+                        "sessions": with_rebuild(
+                            lambda: self._get_analytics().feature_continuity(
+                                feature_id=feature_id,
+                                since=since,
+                                until=until,
+                                limit=limit,
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (continuity): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (continuity): {e}", 500
+                )
 
         if endpoint == "transitions":
             limit = int(params.get("limit", 50))
             feature_id = params.get("feature_id") or params.get("feature")
             try:
-                return self._send_json({"transitions": with_rebuild(lambda: self._get_analytics().top_tool_transitions(since=since, until=until, feature_id=feature_id, limit=limit))})
+                return self._send_json(
+                    {
+                        "transitions": with_rebuild(
+                            lambda: self._get_analytics().top_tool_transitions(
+                                since=since,
+                                until=until,
+                                feature_id=feature_id,
+                                limit=limit,
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (transitions): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (transitions): {e}", 500
+                )
 
         if endpoint == "commits":
             feature_id = params.get("feature_id") or params.get("feature")
@@ -499,9 +620,19 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 return self._send_error_json("Missing required param: feature_id", 400)
             limit = int(params.get("limit", 200))
             try:
-                return self._send_json({"commits": with_rebuild(lambda: self._get_analytics().feature_commits(feature_id=feature_id, limit=limit))})
+                return self._send_json(
+                    {
+                        "commits": with_rebuild(
+                            lambda: self._get_analytics().feature_commits(
+                                feature_id=feature_id, limit=limit
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (commits): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (commits): {e}", 500
+                )
 
         if endpoint == "commit-graph":
             feature_id = params.get("feature_id") or params.get("feature")
@@ -509,13 +640,23 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 return self._send_error_json("Missing required param: feature_id", 400)
             limit = int(params.get("limit", 200))
             try:
-                return self._send_json({"graph": with_rebuild(lambda: self._get_analytics().feature_commit_graph(feature_id=feature_id, limit=limit))})
+                return self._send_json(
+                    {
+                        "graph": with_rebuild(
+                            lambda: self._get_analytics().feature_commit_graph(
+                                feature_id=feature_id, limit=limit
+                            )
+                        )
+                    }
+                )
             except Exception as e:
-                return self._send_error_json(f"Failed analytics query (commit-graph): {e}", 500)
+                return self._send_error_json(
+                    f"Failed analytics query (commit-graph): {e}", 500
+                )
 
         return self._send_error_json(f"Unknown analytics endpoint: {endpoint}", 404)
 
-    def _handle_query(self, params: dict):
+    def _handle_query(self, params: dict) -> None:
         """Handle CSS selector query across collections."""
         selector = params.get("selector", "")
         collection = params.get("collection")  # Optional filter to single collection
@@ -525,7 +666,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             selector = self._build_selector_from_params(params)
 
         results = []
-        collections = [collection] if collection in self.COLLECTIONS else self.COLLECTIONS
+        collections = (
+            [collection] if collection in self.COLLECTIONS else self.COLLECTIONS
+        )
 
         for coll in collections:
             graph = self._get_graph(coll)
@@ -545,7 +688,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                 parts.append(f"[data-{key}='{params[key]}']")
         return "".join(parts)
 
-    def _handle_list(self, collection: str, params: dict):
+    def _handle_list(self, collection: str, params: dict) -> None:
         """List all nodes in a collection."""
         graph = self._get_graph(collection)
 
@@ -571,7 +714,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         if sort_by == "priority":
             priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
-            nodes.sort(key=lambda n: priority_order.get(n.priority, 99), reverse=not reverse)
+            nodes.sort(
+                key=lambda n: priority_order.get(n.priority, 99), reverse=not reverse
+            )
         elif sort_by == "created":
             nodes.sort(key=lambda n: ensure_tz_aware(n.created), reverse=reverse)
         else:  # default: updated
@@ -582,17 +727,19 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         offset = int(params.get("offset", 0))
 
         total = len(nodes)
-        nodes = nodes[offset:offset + limit]
-
-        self._send_json({
-            "collection": collection,
-            "total": total,
-            "limit": limit,
-            "offset": offset,
-            "nodes": [node_to_dict(n) for n in nodes]
-        })
+        nodes = nodes[offset : offset + limit]
+
+        self._send_json(
+            {
+                "collection": collection,
+                "total": total,
+                "limit": limit,
+                "offset": offset,
+                "nodes": [node_to_dict(n) for n in nodes],
+            }
+        )
 
-    def _handle_get(self, collection: str, node_id: str):
+    def _handle_get(self, collection: str, node_id: str) -> None:
         """Get a single node."""
         graph = self._get_graph(collection)
         node = graph.get(node_id)
@@ -607,7 +754,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         self._send_json(data)
 
-    def _handle_create(self, collection: str, data: dict):
+    def _handle_create(self, collection: str, data: dict) -> None:
         """Create a new node."""
         # Set defaults based on collection
         type_map = {
@@ -636,7 +783,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         # Convert steps if provided as strings
         if "steps" in data and data["steps"]:
             if isinstance(data["steps"][0], str):
-                data["steps"] = [{"description": s, "completed": False} for s in data["steps"]]
+                data["steps"] = [
+                    {"description": s, "completed": False} for s in data["steps"]
+                ]
 
         try:
             node = dict_to_node(data)
@@ -651,7 +800,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except ValueError as e:
             self._send_error_json(str(e), 400)
 
-    def _handle_update(self, collection: str, node_id: str, data: dict, partial: bool):
+    def _handle_update(
+        self, collection: str, node_id: str, data: dict, partial: bool
+    ) -> None:
         """Update a node (full or partial)."""
         graph = self._get_graph(collection)
         existing = graph.get(node_id)
@@ -686,7 +837,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
                         from htmlgraph.session_manager import SessionManager
 
                         sm = SessionManager(self.graph_dir)
-                        session = sm.get_active_session_for_agent(agent) or sm.start_session(agent=agent, title="API session")
+                        session = sm.get_active_session_for_agent(
+                            agent
+                        ) or sm.start_session(agent=agent, title="API session")
                         step_desc = None
                         try:
                             step_desc = existing.steps[step_idx].description
@@ -718,19 +871,30 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             node = dict_to_node(data)
             graph.update(node)
             new_status = node.status
-            if agent and (collection in {"features", "bugs", "spikes", "chores", "epics"}) and (new_status != old_status):
+            if (
+                agent
+                and (collection in {"features", "bugs", "spikes", "chores", "epics"})
+                and (new_status != old_status)
+            ):
                 try:
                     from htmlgraph.session_manager import SessionManager
 
                     sm = SessionManager(self.graph_dir)
-                    session = sm.get_active_session_for_agent(agent) or sm.start_session(agent=agent, title="API session")
+                    session = sm.get_active_session_for_agent(
+                        agent
+                    ) or sm.start_session(agent=agent, title="API session")
                     sm.track_activity(
                         session_id=session.id,
                         tool="WorkItemStatus",
                         summary=f"Status {old_status} → {new_status}: {collection}/{node_id}",
                         success=True,
                         feature_id=node_id,
-                        payload={"collection": collection, "node_id": node_id, "from": old_status, "to": new_status},
+                        payload={
+                            "collection": collection,
+                            "node_id": node_id,
+                            "from": old_status,
+                            "to": new_status,
+                        },
                     )
                 except Exception:
                     pass
@@ -738,11 +902,12 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(str(e), 400)
 
-    def _handle_delete(self, collection: str, node_id: str):
+    def _handle_delete(self, collection: str, node_id: str) -> None:
         """Delete a node."""
         # Special handling for tracks (directories, not single files)
         if collection == "tracks":
             from htmlgraph.track_manager import TrackManager
+
             manager = TrackManager(self.graph_dir)
             try:
                 manager.delete_track(node_id)
@@ -764,7 +929,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     # Track-Feature Integration Handlers
     # =========================================================================
 
-    def _handle_track_features(self, track_id: str):
+    def _handle_track_features(self, track_id: str) -> None:
         """Get all features for a track."""
         features_graph = self._get_graph("features")
 
@@ -772,16 +937,18 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         track_features = [
             node_to_dict(node)
             for node in features_graph
-            if hasattr(node, 'track_id') and node.track_id == track_id
+            if hasattr(node, "track_id") and node.track_id == track_id
         ]
 
-        self._send_json({
-            "track_id": track_id,
-            "features": track_features,
-            "count": len(track_features)
-        })
+        self._send_json(
+            {
+                "track_id": track_id,
+                "features": track_features,
+                "count": len(track_features),
+            }
+        )
 
-    def _handle_feature_context(self, feature_id: str):
+    def _handle_feature_context(self, feature_id: str) -> None:
         """Get track/plan/spec context for a feature."""
         features_graph = self._get_graph("features")
 
@@ -795,27 +962,40 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             self._send_error_json(f"Feature not found: {feature_id}", 404)
             return
 
-        context = {
+        context: dict[str, str | list[str] | bool | None] = {
             "feature_id": feature_id,
             "feature_title": feature.title,
-            "track_id": feature.track_id if hasattr(feature, 'track_id') else None,
-            "plan_task_id": feature.plan_task_id if hasattr(feature, 'plan_task_id') else None,
-            "spec_requirements": feature.spec_requirements if hasattr(feature, 'spec_requirements') else [],
+            "track_id": feature.track_id if hasattr(feature, "track_id") else None,
+            "plan_task_id": feature.plan_task_id
+            if hasattr(feature, "plan_task_id")
+            else None,
+            "spec_requirements": feature.spec_requirements
+            if hasattr(feature, "spec_requirements")
+            else [],
+            "track_exists": False,
+            "has_spec": False,
+            "has_plan": False,
+            "is_consolidated": False,
         }
 
         # Load track info if linked
-        if context["track_id"]:
+        track_id = context["track_id"]
+        if track_id and isinstance(track_id, str):
             from htmlgraph.track_manager import TrackManager
+
             manager = TrackManager(self.graph_dir)
-            track_dir = manager.tracks_dir / context["track_id"]
-            track_file = manager.tracks_dir / f"{context['track_id']}.html"
+            track_dir = manager.tracks_dir / track_id
+            track_file = manager.tracks_dir / f"{track_id}.html"
 
             # Support both consolidated (single file) and directory-based tracks
             if track_file.exists():
                 # Consolidated format
                 context["track_exists"] = True
                 content = track_file.read_text(encoding="utf-8")
-                context["has_spec"] = 'data-section="overview"' in content or 'data-section="requirements"' in content
+                context["has_spec"] = (
+                    'data-section="overview"' in content
+                    or 'data-section="requirements"' in content
+                )
                 context["has_plan"] = 'data-section="plan"' in content
                 context["is_consolidated"] = True
             elif track_dir.exists():
@@ -831,10 +1011,33 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
         self._send_json(context)
 
-    def _handle_generate_features(self, track_id: str):
+    def _handle_session_transcript(self, session_id: str) -> None:
+        """Get transcript stats for a session."""
+        try:
+            from htmlgraph.session_manager import SessionManager
+
+            manager = SessionManager(self.graph_dir)
+            stats = manager.get_transcript_stats(session_id)
+
+            if stats is None:
+                self._send_json(
+                    {
+                        "session_id": session_id,
+                        "transcript_linked": False,
+                        "message": "No transcript linked to this session",
+                    }
+                )
+                return
+
+            self._send_json(
+                {"session_id": session_id, "transcript_linked": True, **stats}
+            )
+        except Exception as e:
+            self._send_error_json(f"Error getting transcript stats: {e}", 500)
+
+    def _handle_generate_features(self, track_id: str) -> None:
         """Generate features from plan tasks."""
         from htmlgraph.track_manager import TrackManager
-        from htmlgraph.planning import Plan
 
         manager = TrackManager(self.graph_dir)
 
@@ -848,23 +1051,204 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         # Generate features
         try:
             features = manager.generate_features_from_plan(
-                track_id=track_id,
-                plan=plan,
-                features_dir=self.graph_dir / "features"
+                track_id=track_id, plan=plan, features_dir=self.graph_dir / "features"
             )
 
             # Reload features graph to include new features
             self.graphs.pop("features", None)
 
-            self._send_json({
-                "track_id": track_id,
-                "generated": len(features),
-                "feature_ids": [f.id for f in features]
-            })
+            self._send_json(
+                {
+                    "track_id": track_id,
+                    "generated": len(features),
+                    "feature_ids": [f.id for f in features],
+                }
+            )
         except Exception as e:
             self._send_error_json(f"Failed to generate features: {str(e)}", 500)
 
-    def _handle_sync_track(self, track_id: str):
+    def _handle_orchestration_view(self, params: dict) -> None:
+        """
+        Get delegation chains and agent coordination information.
+
+        Queries the SQLite database for delegation events and builds
+        a view of agent coordination and handoff patterns.
+
+        Returns:
+            {
+                "delegation_count": int,
+                "unique_agents": int,
+                "agents": [str],
+                "delegation_chains": {
+                    "from_agent": [
+                        {
+                            "to_agent": str,
+                            "event_type": str,
+                            "timestamp": str,
+                            "task": str,
+                            "status": str
+                        }
+                    ]
+                }
+            }
+        """
+        try:
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            # Use unified index.sqlite database
+            db_path = str(self.graph_dir / "index.sqlite")
+            db = HtmlGraphDB(db_path=db_path)
+            db.connect()
+
+            # Get all delegation events
+            delegations = db.get_delegations(limit=1000)
+            db.close()
+
+            # Build delegation chains grouped by from_agent
+            delegation_chains: dict[str, list[dict]] = {}
+            agents = set()
+            delegation_count = 0
+
+            for delegation in delegations:
+                from_agent = delegation.get("from_agent", "unknown")
+                to_agent = delegation.get("to_agent", "unknown")
+                timestamp = delegation.get("timestamp", "")
+                reason = delegation.get("reason", "")
+                status = delegation.get("status", "pending")
+
+                agents.add(from_agent)
+                agents.add(to_agent)
+                delegation_count += 1
+
+                if from_agent not in delegation_chains:
+                    delegation_chains[from_agent] = []
+
+                delegation_chains[from_agent].append(
+                    {
+                        "to_agent": to_agent,
+                        "event_type": "delegation",
+                        "timestamp": timestamp,
+                        "task": reason or "Unnamed task",
+                        "status": status,
+                    }
+                )
+
+            self._send_json(
+                {
+                    "delegation_count": delegation_count,
+                    "unique_agents": len(agents),
+                    "agents": sorted(list(agents)),
+                    "delegation_chains": delegation_chains,
+                }
+            )
+
+        except Exception as e:
+            self._send_error_json(f"Failed to get orchestration view: {str(e)}", 500)
+
+    def _handle_task_delegations_stats(self) -> None:
+        """Get aggregated statistics about task delegations."""
+        try:
+            delegations_graph = self._get_graph("task-delegations")
+
+            # Get all delegations
+            all_delegations = list(delegations_graph)
+
+            if not all_delegations:
+                self._send_json(
+                    {
+                        "total_delegations": 0,
+                        "by_agent_type": {},
+                        "by_status": {},
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "average_duration": 0.0,
+                        "agent_stats": [],
+                    }
+                )
+                return
+
+            # Aggregate by agent type
+            agent_stats: dict = {}
+            by_status: dict[str, int] = {}
+            total_tokens = 0
+            total_cost = 0.0
+            durations = []
+
+            for delegation in all_delegations:
+                agent_type = str(getattr(delegation, "agent_type", "unknown"))
+                status = str(getattr(delegation, "status", "unknown"))
+                tokens_val = getattr(delegation, "tokens_used", 0)
+                tokens = int(tokens_val) if tokens_val else 0
+                cost_val = getattr(delegation, "cost_usd", 0)
+                cost = float(cost_val) if cost_val else 0.0
+                duration_val = getattr(delegation, "duration_seconds", 0)
+                duration = int(duration_val) if duration_val else 0
+
+                # Track by agent
+                if agent_type not in agent_stats:
+                    agent_stats[agent_type] = {
+                        "agent_type": agent_type,
+                        "tasks_completed": 0,
+                        "total_duration": 0,
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "success_count": 0,
+                        "failure_count": 0,
+                    }
+
+                agent_stats[agent_type]["tasks_completed"] += 1
+                agent_stats[agent_type]["total_duration"] += duration
+                agent_stats[agent_type]["total_tokens"] += tokens
+                agent_stats[agent_type]["total_cost"] += cost
+
+                if status == "success":
+                    agent_stats[agent_type]["success_count"] += 1
+                else:
+                    agent_stats[agent_type]["failure_count"] += 1
+
+                # Track by status
+                by_status[status] = by_status.get(status, 0) + 1
+
+                # Aggregate totals
+                total_tokens += tokens
+                total_cost += cost
+                if duration:
+                    durations.append(duration)
+
+            # Calculate success rate for each agent
+            for agent_stats_item in agent_stats.values():
+                total = agent_stats_item["tasks_completed"]
+                if total > 0:
+                    agent_stats_item["success_rate"] = (
+                        agent_stats_item["success_count"] / total
+                    )
+                else:
+                    agent_stats_item["success_rate"] = 0.0
+
+            average_duration = sum(durations) / len(durations) if durations else 0.0
+
+            self._send_json(
+                {
+                    "total_delegations": len(all_delegations),
+                    "by_agent_type": {
+                        agent: stats["tasks_completed"]
+                        for agent, stats in agent_stats.items()
+                    },
+                    "by_status": by_status,
+                    "total_tokens": total_tokens,
+                    "total_cost": round(total_cost, 4),
+                    "average_duration": round(average_duration, 2),
+                    "agent_stats": sorted(
+                        agent_stats.values(),
+                        key=lambda x: x["total_cost"],
+                        reverse=True,
+                    ),
+                }
+            )
+        except Exception as e:
+            self._send_error_json(f"Failed to get delegation stats: {str(e)}", 500)
+
+    def _handle_sync_track(self, track_id: str) -> None:
         """Sync task and spec completion based on features."""
         from htmlgraph.track_manager import TrackManager
 
@@ -881,19 +1265,111 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             # Reload tracks graph
             self.graphs.pop("tracks", None)
 
-            self._send_json({
-                "track_id": track_id,
-                "plan_updated": True,
-                "spec_updated": True,
-                "plan_completion": plan.completion_percentage,
-                "spec_status": spec.status
-            })
+            self._send_json(
+                {
+                    "track_id": track_id,
+                    "plan_updated": True,
+                    "spec_updated": True,
+                    "plan_completion": plan.completion_percentage,
+                    "spec_status": spec.status,
+                }
+            )
         except Exception as e:
             self._send_error_json(f"Failed to sync track: {str(e)}", 500)
 
-    def log_message(self, format: str, *args):
+    def log_message(self, format: str, *args: str) -> None:
         """Custom log format."""
-        print(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
+        logger.info(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
+
+
+def find_available_port(start_port: int = 8080, max_attempts: int = 10) -> int:
+    """
+    Find an available port starting from start_port.
+
+    Args:
+        start_port: Port to start searching from
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        Available port number
+
+    Raises:
+        OSError: If no available port found in range
+    """
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("", port))
+                return port
+        except OSError:
+            continue
+    raise OSError(
+        f"No available ports found in range {start_port}-{start_port + max_attempts}"
+    )
+
+
+def check_port_in_use(port: int, host: str = "localhost") -> bool:
+    """
+    Check if a port is already in use.
+
+    Args:
+        port: Port number to check
+        host: Host to check on
+
+    Returns:
+        True if port is in use, False otherwise
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind((host, port))
+            return False
+    except OSError:
+        return True
+
+
+def sync_dashboard_files(
+    static_dir: Path = Path("."),
+) -> bool:
+    """
+    Sync dashboard.html to index.html if they differ.
+
+    Args:
+        static_dir: Directory containing index.html
+
+    Returns:
+        True if sync was performed, False if already in sync
+
+    Raises:
+        PermissionError: If unable to write to index.html
+        OSError: If file operations fail
+    """
+    dashboard_file = Path(__file__).parent / "dashboard.html"
+    index_file = static_dir / "index.html"
+
+    # Dashboard file must exist (packaged with htmlgraph)
+    if not dashboard_file.exists():
+        return False
+
+    # If index.html doesn't exist, or content differs, sync
+    if not index_file.exists():
+        # Create new index.html
+        import shutil
+
+        shutil.copy2(dashboard_file, index_file)
+        return True
+
+    # Check if files differ (compare content, not just timestamps)
+    import filecmp
+
+    if not filecmp.cmp(dashboard_file, index_file, shallow=False):
+        # Files differ, sync them
+        import shutil
+
+        shutil.copy2(dashboard_file, index_file)
+        return True
+
+    # Already in sync
+    return False
 
 
 def serve(
@@ -901,22 +1377,41 @@ def serve(
     graph_dir: str | Path = ".htmlgraph",
     static_dir: str | Path = ".",
     host: str = "localhost",
-    watch: bool = True
-):
+    watch: bool = True,
+    auto_port: bool = False,
+    show_progress: bool = False,
+    quiet: bool = False,
+) -> None:
     """
-    Start the HtmlGraph server.
+    Start the HtmlGraph server (FastAPI-based with WebSocket support).
+
+    This function launches the FastAPI server which provides:
+    - REST API for CRUD operations on graph nodes
+    - WebSocket endpoint at /ws/events for real-time event streaming
+    - HTMX-powered dashboard for agent observability
 
     Args:
-        port: Port to listen on
+        port: Port to listen on (default: 8080)
         graph_dir: Directory containing graph data (.htmlgraph/)
-        static_dir: Directory for static files (index.html, etc.)
-        host: Host to bind to
-        watch: Enable file watching for auto-reload (default: True)
+        static_dir: Directory for static files (index.html, etc.) - preserved for compatibility
+        host: Host to bind to (default: localhost)
+        watch: Enable file watching for auto-reload (default: True) - maps to reload in FastAPI
+        auto_port: Automatically find available port if specified port is in use
+        show_progress: Show Rich progress during startup (not used with FastAPI)
+        quiet: Suppress progress output when true
     """
+    import asyncio
+
+    from htmlgraph.operations.fastapi_server import (
+        FastAPIServerError,
+        PortInUseError,
+        run_fastapi_server,
+        start_fastapi_server,
+    )
+
     graph_dir = Path(graph_dir)
-    static_dir = Path(static_dir)
 
-    # Create graph directory structure
+    # Ensure graph directory exists
     graph_dir.mkdir(parents=True, exist_ok=True)
     for collection in HtmlGraphAPIHandler.COLLECTIONS:
         (graph_dir / collection).mkdir(exist_ok=True)
@@ -928,75 +1423,85 @@ def serve(
         if styles_src.exists():
             styles_dest.write_text(styles_src.read_text())
 
-    # Configure handler
-    HtmlGraphAPIHandler.graph_dir = graph_dir
-    HtmlGraphAPIHandler.static_dir = static_dir
-    HtmlGraphAPIHandler.graphs = {}
-    HtmlGraphAPIHandler.analytics_db = None
-
-    server = HTTPServer((host, port), HtmlGraphAPIHandler)
-
-    # Start file watcher if enabled
-    watcher = None
-    if watch:
-        def get_graph(collection: str) -> HtmlGraph:
-            """Callback to get graph instance for a collection."""
-            handler = HtmlGraphAPIHandler
-            if collection not in handler.graphs:
-                collection_dir = handler.graph_dir / collection
-                handler.graphs[collection] = HtmlGraph(
-                    collection_dir,
-                    stylesheet_path="../styles.css",
-                    auto_load=True
-                )
-            return handler.graphs[collection]
+    # Database path - use htmlgraph.db in the graph directory
+    db_path = str(graph_dir / "htmlgraph.db")
 
-        watcher = GraphWatcher(
-            graph_dir=graph_dir,
-            collections=HtmlGraphAPIHandler.COLLECTIONS,
-            get_graph_callback=get_graph
+    try:
+        result = start_fastapi_server(
+            port=port,
+            host=host,
+            db_path=db_path,
+            auto_port=auto_port,
+            reload=watch,  # Map watch to reload for FastAPI
         )
-        watcher.start()
 
-    watch_status = "Enabled" if watch else "Disabled"
-    print(f"""
+        # Print warnings if any
+        for warning in result.warnings:
+            if not quiet:
+                logger.info(f"⚠️  {warning}")
+
+        # Print server info
+        if not quiet:
+            actual_port = result.config_used["port"]
+            print(f"""
 ╔══════════════════════════════════════════════════════════════╗
-║                    HtmlGraph Server                          ║
+║              HtmlGraph Server (FastAPI)                      ║
 ╠══════════════════════════════════════════════════════════════╣
-║  Dashboard:  http://{host}:{port}/
-║  API:        http://{host}:{port}/api/
-║  Graph Dir:  {graph_dir}
-║  Auto-reload: {watch_status}
+║  Dashboard:   http://{host}:{actual_port}/
+║  API:         http://{host}:{actual_port}/api/
+║  WebSocket:   ws://{host}:{actual_port}/ws/events
+║  Graph Dir:   {graph_dir}
+║  Database:    {db_path}
+║  Auto-reload: {"Enabled" if watch else "Disabled"}
 ╚══════════════════════════════════════════════════════════════╝
 
+Features:
+  • Real-time agent activity feed (HTMX + WebSocket)
+  • Orchestration chains visualization
+  • Feature tracker with Kanban view
+  • Session metrics & performance analytics
+
 API Endpoints:
-  GET    /api/status              - Overall status
-  GET    /api/collections         - List collections
-  GET    /api/query?status=todo   - Query across collections
-  GET    /api/analytics/overview  - Analytics overview (requires index)
-  GET    /api/analytics/features  - Top features (requires index)
-  GET    /api/analytics/continuity?feature_id=... - Feature continuity (requires index)
-  GET    /api/analytics/transitions - Tool transitions (requires index)
-
-  GET    /api/{{collection}}        - List nodes
-  POST   /api/{{collection}}        - Create node
-  GET    /api/{{collection}}/{{id}}    - Get node
-  PUT    /api/{{collection}}/{{id}}    - Replace node
-  PATCH  /api/{{collection}}/{{id}}    - Update node
-  DELETE /api/{{collection}}/{{id}}    - Delete node
-
-Collections: {', '.join(HtmlGraphAPIHandler.COLLECTIONS)}
+  GET    /api/events              - List events
+  GET    /api/sessions            - List sessions
+  GET    /api/orchestration       - Orchestration data
+  GET    /api/initial-stats       - Dashboard statistics
+  WS     /ws/events               - Real-time event stream
+
+Collections: {", ".join(HtmlGraphAPIHandler.COLLECTIONS)}
 
 Press Ctrl+C to stop.
 """)
 
-    try:
-        server.serve_forever()
+        # Run the server
+        asyncio.run(run_fastapi_server(result.handle))
+
+    except PortInUseError:
+        logger.info(f"\n❌ Port {port} is already in use\n")
+        logger.info("Solutions:")
+        logger.info("  1. Use a different port:")
+        logger.info(f"     htmlgraph serve --port {port + 1}\n")
+        logger.info("  2. Let htmlgraph automatically find an available port:")
+        logger.info("     htmlgraph serve --auto-port\n")
+        logger.info(f"  3. Find and kill the process using port {port}:")
+        logger.info(f"     lsof -ti:{port} | xargs kill -9\n")
+
+        # Try to find and suggest an available port
+        try:
+            alt_port = find_available_port(port + 1)
+            logger.info(f"💡 Found available port: {alt_port}")
+            logger.info(f"   Run: htmlgraph serve --port {alt_port}\n")
+        except OSError:
+            pass
+
+        sys.exit(1)
+
+    except FastAPIServerError as e:
+        logger.info(f"\n❌ Server error: {e}\n")
+        sys.exit(1)
+
     except KeyboardInterrupt:
-        print("\nShutting down...")
-        if watcher:
-            watcher.stop()
-        server.shutdown()
+        logger.info("\nShutting down...")
 
 
 if __name__ == "__main__":