hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/app.py

@@ -0,0 +1,2538 @@
+"""ASGI app exposing /v1/sims/* and the static SPA.
+
+This is a standalone app (not bound to any HyperMindAgent). It re-uses
+the helpers from ``hypermind.api.app`` (``_send_json``, ``_err``, etc.)
+and follows the same manual-dispatch pattern.
+
+Mounted at ``/`` by ``hmctl simlab``. Routes:
+
+    GET  /                          → index.html (SPA)
+    GET  /assets/*                  → static SPA bundle
+    GET  /v1/healthz                → liveness
+    GET  /v1/sims                   → list of summaries
+    POST /v1/sims                   → enqueue new sim, returns {sim_id}
+    GET  /v1/sims/{id}              → full trace.json (200 once done)
+    GET  /v1/sims/{id}/status       → status.json
+    GET  /v1/sims/{id}/events/stream → SSE per-sim recorder events
+    GET  /v1/stats                   → namespace + federation summary
+    GET  /v1/disputes                → dispute records across all sims
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import mimetypes
+import re
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Any
+
+from hypermind import __version__
+from hypermind.api.app import (
+    _read_body,
+)
+
+from .config import SimConfig
+from .knowledge import KnowledgeIndex, _ingest_trace, build_knowledge_index
+from .registry import (
+    _write_json_atomic,
+    list_sims,
+    load_status,
+    load_trace,
+    sim_dir,
+    update_status,
+)
+from .runner import get_runner
+
+_Scope = dict
+_Receive = Callable[[], Awaitable[dict]]
+_Send = Callable[[dict], Awaitable[None]]
+
+# Validate sim_id to prevent path traversal attacks
+_SIM_ID_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]{10}$")
+
+# Maximum number of sims that may be queued at once.
+MAX_QUEUE = 10
+
+_CORS_HEADERS = [
+    (b"access-control-allow-origin", b"*"),
+    (b"access-control-allow-methods", b"GET, POST, PUT, DELETE, OPTIONS"),
+    (b"access-control-allow-headers", b"Content-Type, Authorization"),
+]
+
+
+def _add_cors(headers: list) -> list:
+    """Return a copy of *headers* with CORS headers appended."""
+    return list(headers) + _CORS_HEADERS
+
+
+async def _send_json(send: _Send, *, status: int, payload: Any) -> None:
+    """Like api._send_json but always includes CORS headers."""
+    import json as _json
+
+    def _json_default(obj: Any) -> Any:
+        if isinstance(obj, (bytes, bytearray)):
+            return obj.hex()
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+        if hasattr(obj, "__dict__"):
+            return obj.__dict__
+        return str(obj)
+
+    body = _json.dumps(payload, default=_json_default).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": _add_cors(
+                [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body)).encode()),
+                ]
+            ),
+        }
+    )
+    await send({"type": "http.response.body", "body": body, "more_body": False})
+
+
+async def _err(send: _Send, status: int, message: str) -> None:
+    """Like api._err but always includes CORS headers."""
+    await _send_json(send, status=status, payload={"error": message})
+
+
+# ---- SPA static dispatch ---------------------------------------------------
+
+
+def _ui_dist_dir() -> Path | None:
+    """Locate the bundled SPA dist directory.
+
+    Resolution order:
+    1. The dev-source webui/dist (when running from a checkout)
+    2. The package's bundled simlab/ui/dist (after pip install)
+    """
+    pkg_path = Path(__file__).resolve().parent / "ui" / "dist"
+    if pkg_path.exists():
+        return pkg_path
+    # Dev tree: webui/dist sibling of src/
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "webui" / "dist"
+        if candidate.exists():
+            return candidate
+        if (parent / "pyproject.toml").exists():
+            break
+    return None
+
+
+_PLACEHOLDER_INDEX = b"""<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>HyperMind SimLab</title>
+<style>body{font-family:system-ui;max-width:720px;margin:80px auto;padding:24px;
+color:#11161D;background:#FDFDFC}h1{font-weight:500}code{background:#F6F7F9;
+padding:2px 6px;border-radius:4px}</style></head>
+<body><h1>HyperMind SimLab</h1>
+<p>The Vue SPA has not been built yet.</p>
+<p>From the repository root, run:</p>
+<pre>cd webui && npm ci && npm run build</pre>
+<p>Then refresh this page. The API is live at
+<a href="/v1/sims"><code>/v1/sims</code></a>.</p>
+</body></html>
+"""
+
+
+async def _serve_static(scope: _Scope, send: _Send, *, dist: Path | None) -> bool:
+    """Serve a static file from the SPA dist. Returns True if handled."""
+    path: str = scope.get("path", "/")
+    method: str = scope.get("method", "GET").upper()
+    if method != "GET":
+        return False
+
+    if dist is None:
+        # No SPA built yet — return placeholder for /, 404 for assets.
+        if path in ("/", "/index.html"):
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 200,
+                    "headers": [(b"content-type", b"text/html; charset=utf-8")],
+                }
+            )
+            await send(
+                {"type": "http.response.body", "body": _PLACEHOLDER_INDEX, "more_body": False}
+            )
+            return True
+        return False
+
+    if path in ("/", "/index.html"):
+        target = dist / "index.html"
+    else:
+        # Strip leading /
+        target = dist / path.lstrip("/")
+
+    # Resolve symlinks; reject path traversal.
+    try:
+        resolved = target.resolve()
+        resolved.relative_to(dist.resolve())
+    except (OSError, ValueError):
+        return False
+
+    if not resolved.exists() or not resolved.is_file():
+        # SPA fallback: any unknown route serves index.html for client routing
+        if path.startswith("/v1/") or path.startswith("/assets/"):
+            return False
+        target = dist / "index.html"
+        if not target.exists():
+            return False
+        resolved = target.resolve()
+
+    ct = mimetypes.guess_type(resolved.name)[0] or "application/octet-stream"
+    body = resolved.read_bytes()
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                (b"content-type", ct.encode()),
+                (b"content-length", str(len(body)).encode()),
+                (b"cache-control", b"no-cache"),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body, "more_body": False})
+    return True
+
+
+# ---- /v1/namespaces handlers -----------------------------------------------
+
+
+async def _handle_create_namespace(body: bytes, send: _Send) -> None:
+    import time
+
+    from .namespace import (
+        DeploymentProfile,
+        Namespace,
+        get_namespace,
+        save_namespace,
+        validate_slug,
+    )
+
+    try:
+        payload = json.loads(body) if body else {}
+        slug = payload.get("slug", "").strip()
+        validate_slug(slug)
+        if get_namespace(slug) is not None:
+            await _send_json(
+                send, status=409, payload={"error": f"namespace {slug!r} already exists"}
+            )
+            return
+        profile = DeploymentProfile.from_dict(
+            {
+                "tier": payload.get("tier", "local"),
+                "storage_url": payload.get("storage_url"),
+                "visibility": payload.get("visibility", "private"),
+                "anchor_chain": payload.get("anchor_chain"),
+                "anchor_contract": payload.get("anchor_contract"),
+                "anchor_rpc_url": payload.get("anchor_rpc_url"),
+            }
+        )
+        ns = Namespace(
+            slug=slug,
+            label=payload.get("label", slug),
+            profile=profile,
+            created_at_ms=int(time.time() * 1000),
+        )
+        save_namespace(ns)
+        await _send_json(send, status=201, payload=ns.to_dict())
+    except ValueError as e:
+        await _send_json(send, status=422, payload={"error": str(e)})
+    except Exception as e:
+        await _send_json(send, status=500, payload={"error": str(e)})
+
+
+# ---- /v1/modes handler -----------------------------------------------------
+
+
+async def _handle_list_modes(send: _Send) -> None:
+    """GET /v1/modes — return the registered deliberation modes.
+
+    Powers the schema-driven SimNew form: the SPA reads this on page
+    load, renders a dropdown, and (for modes with input_schema != null)
+    renders a dynamic form based on the schema.
+    """
+    from .modes import list_modes
+
+    payload = [m.to_dict() for m in list_modes()]
+    await _send_json(send, status=200, payload=payload)
+
+
+# ---- /v1/sims handlers -----------------------------------------------------
+
+
+async def _handle_list_sims(send: _Send) -> None:
+    sims = [s.to_dict() for s in list_sims(limit=1000)]
+    await _send_json(send, status=200, payload=sims)
+
+
+async def _handle_create_sim(body: bytes, send: _Send) -> None:
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    if not isinstance(payload, dict):
+        await _err(send, 400, "expected JSON object")
+        return
+
+    # Topic-adaptive configuration: if the caller supplied only a topic
+    # (or left numeric params at sentinel defaults), infer the right
+    # n_questions / personas / replicas / deliberation_rounds from the topic.
+    topic = (payload.get("topic") or "").strip()
+    if topic:
+        from .topic_adapter import apply_profile_to_config, infer_topic_profile
+        from .topic_questions import generate_questions_for_topic
+        model = payload.get("model") or SimConfig.model
+        no_llm = bool(payload.get("no_llm", False))
+        n_questions_hint = int(payload.get("n_questions") or 8)
+        try:
+            # Run profile inference and question generation in parallel
+            # so both LLM round-trips overlap instead of serialising.
+            import asyncio as _asyncio
+            profile, pregenerated = await _asyncio.gather(
+                infer_topic_profile(topic, model=model, no_llm=no_llm),
+                generate_questions_for_topic(topic, n_questions_hint, model=model, no_llm=no_llm),
+                return_exceptions=True,
+            )
+            if isinstance(profile, BaseException):
+                profile = None
+            if isinstance(pregenerated, BaseException):
+                pregenerated = None
+            if profile is not None:
+                payload = apply_profile_to_config(payload, profile)
+            if pregenerated:
+                payload["_pregenerated_questions"] = pregenerated
+        except Exception:
+            pass  # never block a sim because adaptation failed
+
+    try:
+        cfg = SimConfig.from_dict(payload)
+    except ValueError as exc:
+        await _err(send, 400, str(exc))
+        return
+    runner = get_runner()
+    if runner.queue_size >= MAX_QUEUE:
+        body = json.dumps({"error": "queue_full", "message": "Too many sims queued"}).encode(
+            "utf-8"
+        )
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 503,
+                "headers": _add_cors(
+                    [
+                        (b"content-type", b"application/json"),
+                        (b"content-length", str(len(body)).encode()),
+                        (b"retry-after", b"30"),
+                    ]
+                ),
+            }
+        )
+        await send({"type": "http.response.body", "body": body, "more_body": False})
+        return
+    try:
+        sim_id = await runner.submit(cfg)
+    except asyncio.QueueFull:
+        body = json.dumps({"error": "queue_full", "message": "Too many sims queued"}).encode(
+            "utf-8"
+        )
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 503,
+                "headers": _add_cors(
+                    [
+                        (b"content-type", b"application/json"),
+                        (b"content-length", str(len(body)).encode()),
+                        (b"retry-after", b"30"),
+                    ]
+                ),
+            }
+        )
+        await send({"type": "http.response.body", "body": body, "more_body": False})
+        return
+    await _send_json(send, status=202, payload={"sim_id": sim_id})
+
+
+async def _handle_get_status(sim_id: str, send: _Send) -> None:
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    status = load_status(sim_id)
+    # Enrich with the topic the user entered (so the live view can show
+    # "Watching: <topic>" without a second request to /sims).
+    try:
+        from .registry import load_config as _load_cfg
+
+        cfg = _load_cfg(sim_id)
+        if cfg.get("topic"):
+            status["topic"] = cfg["topic"]
+        if cfg.get("questions"):
+            status["questions_set"] = cfg["questions"]
+        status["model"] = cfg.get("model")
+        status["no_llm"] = cfg.get("no_llm")
+    except Exception:
+        pass
+    await _send_json(send, status=200, payload=status)
+
+
+async def _handle_get_stderr(sim_id: str, send: _Send) -> None:
+    """GET /v1/sims/{id}/stderr — returns the captured stderr log
+    (last ~64KB) so a failed sim's detail page can show what went wrong.
+    """
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    log_path = sim_dir(sim_id) / "stderr.log"
+    if not log_path.exists():
+        await _send_json(send, status=200, payload={"stderr": "", "size": 0})
+        return
+    # Read last 64KB only — these can grow
+    size = log_path.stat().st_size
+    with log_path.open("rb") as f:
+        if size > 65536:
+            f.seek(-65536, 2)
+            f.readline()  # discard partial line
+        data = f.read().decode("utf-8", errors="replace")
+    await _send_json(
+        send, status=200, payload={"stderr": data, "size": size, "truncated": size > 65536}
+    )
+
+
+async def _handle_get_trace(sim_id: str, send: _Send) -> None:
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    status = load_status(sim_id)
+    state = status.get("state")
+    if state == "failed":
+        await _err(send, 410, status.get("error", "sim failed"))
+        return
+    if state != "done":
+        await _err(send, 404, f"sim not done yet (state={state})")
+        return
+    trace = load_trace(sim_id)
+    if trace is None:
+        await _err(send, 404, "trace.json missing")
+        return
+    await _send_json(send, status=200, payload=trace)
+
+
+# ---- /v1/knowledge handlers (federation memory across all sims) ----
+
+
+def _build_knowledge_index_for_namespace(namespace_slug: str) -> KnowledgeIndex:
+    """Return a KnowledgeIndex appropriate for *namespace_slug*.
+
+    - If the namespace has tier=="server" and a storage_url is set:
+      reads sim IDs + traces from the ServerBackend (SQLite).
+    - Otherwise (tier=="local" or namespace not found):
+      delegates to the standard disk-walk ``build_knowledge_index()``.
+
+    The local path is 100% unchanged — no disk reads are altered.
+    """
+    from .namespace import get_namespace
+
+    ns = get_namespace(namespace_slug) if namespace_slug else None
+    if ns is not None and ns.profile.tier == "server" and ns.profile.storage_url:
+        import time as _time
+
+        from .backends.server import ServerBackend
+
+        backend = ServerBackend(ns.profile.storage_url)
+        idx = KnowledgeIndex()
+        for sim_id in backend.list_sim_ids():
+            trace = backend.read_trace(sim_id)
+            if trace is None:
+                continue
+            try:
+                _ingest_trace(idx, sim_id, trace)
+                idx.n_sims += 1
+            except Exception:
+                continue
+        idx.last_built_ts_ms = int(_time.time() * 1000)
+        return idx
+    # Default: use the existing cached disk-walk index
+    return build_knowledge_index()
+
+
+async def _handle_knowledge_overview(send: _Send) -> None:
+    idx = build_knowledge_index()
+    await _send_json(send, status=200, payload=idx.overview())
+
+
+def _qs_param(qs: bytes, key: str, default: str = "") -> str:
+    """Tiny query-string getter; mirrors api/app.py:_parse_qs but
+    avoids a circular import."""
+    for pair in qs.split(b"&"):
+        if not pair or b"=" not in pair:
+            continue
+        k, v = pair.split(b"=", 1)
+        if k.decode() == key:
+            from urllib.parse import unquote_plus
+
+            return unquote_plus(v.decode())
+    return default
+
+
+async def _handle_knowledge_claims(qs: bytes, send: _Send) -> None:
+    namespace_slug = _qs_param(qs, "namespace", "default")
+    idx = _build_knowledge_index_for_namespace(namespace_slug)
+    try:
+        limit = max(1, min(2000, int(_qs_param(qs, "limit", "100"))))
+        offset = max(0, int(_qs_param(qs, "offset", "0")))
+    except ValueError:
+        await _err(send, 400, "limit/offset must be ints")
+        return
+    payload = idx.list_claims(
+        q=_qs_param(qs, "q"),
+        persona=_qs_param(qs, "persona"),
+        topic=_qs_param(qs, "topic"),
+        sim_id=_qs_param(qs, "sim_id"),
+        limit=limit,
+        offset=offset,
+    )
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_knowledge_agents(send: _Send) -> None:
+    idx = build_knowledge_index()
+    await _send_json(send, status=200, payload=idx.list_agents())
+
+
+async def _handle_knowledge_topics(send: _Send) -> None:
+    idx = build_knowledge_index()
+    await _send_json(send, status=200, payload=idx.list_topics())
+
+
+async def _handle_knowledge_ask(qs: bytes, send: _Send) -> None:
+    """GET /v1/knowledge/ask?q=… — federation Q&A across all claims."""
+    idx = build_knowledge_index()
+    q = _qs_param(qs, "q", "")
+    try:
+        top_k = max(1, min(500, int(_qs_param(qs, "top_k", "20"))))
+    except ValueError:
+        top_k = 20
+    payload = idx.ask(q, top_k=top_k)
+    await _send_json(send, status=200, payload=payload)
+
+
+# ---- /v1/personas + /v1/swarms ---------------------------------------------
+
+
+async def _handle_list_personas(send: _Send) -> None:
+    from .personas import load_personas
+
+    payload = [p.to_dict() for p in load_personas()]
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_get_persona(slug: str, send: _Send) -> None:
+    from .personas import get_persona
+
+    p = get_persona(slug)
+    if p is None:
+        await _err(send, 404, f"unknown persona: {slug}")
+        return
+    await _send_json(send, status=200, payload=p.to_dict())
+
+
+async def _handle_create_persona(body: bytes, send: _Send) -> None:
+    from .personas import PersonaSpec, is_builtin, save_persona
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    if not isinstance(data, dict):
+        await _err(send, 400, "expected JSON object")
+        return
+    try:
+        spec = PersonaSpec.from_dict(data)
+        if is_builtin(spec.slug):
+            await _err(send, 422, f"slug {spec.slug!r} is a built-in; pick another")
+            return
+        save_persona(spec)
+    except ValueError as exc:
+        await _err(send, 400, str(exc))
+        return
+    await _send_json(send, status=201, payload=spec.to_dict())
+
+
+async def _handle_update_persona(slug: str, body: bytes, send: _Send) -> None:
+    from .personas import PersonaSpec, get_persona, is_builtin, save_persona
+
+    if is_builtin(slug):
+        await _err(send, 422, f"persona {slug!r} is built-in and immutable")
+        return
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    existing = get_persona(slug)
+    if existing is None:
+        await _err(send, 404, f"unknown persona: {slug}")
+        return
+    merged = {**existing.to_dict(), **data, "slug": slug}
+    try:
+        spec = PersonaSpec.from_dict(merged)
+        save_persona(spec)
+    except ValueError as exc:
+        await _err(send, 400, str(exc))
+        return
+    await _send_json(send, status=200, payload=spec.to_dict())
+
+
+async def _handle_delete_persona(slug: str, send: _Send) -> None:
+    from .personas import delete_persona, is_builtin
+
+    if is_builtin(slug):
+        await _err(send, 422, f"cannot delete built-in persona {slug!r}")
+        return
+    delete_persona(slug)
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 204,
+            "headers": [(b"content-length", b"0")],
+        }
+    )
+    await send({"type": "http.response.body", "body": b"", "more_body": False})
+
+
+async def _handle_batch_generate_personas(body: bytes, send: _Send) -> None:
+    """POST /v1/personas/batch-generate — generate a population of personas."""
+    from .personas import get_persona, is_builtin, save_persona
+    from .prompt_generator import generate_persona
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    if not isinstance(data, dict):
+        await _err(send, 400, "expected JSON object")
+        return
+
+    population = data.get("population", [])
+    if not isinstance(population, list) or not population:
+        await _err(send, 400, "population must be a non-empty list")
+        return
+
+    model = data.get("model")
+    no_llm = bool(data.get("no_llm", False))
+
+    # Build the flat list of (description, idx_within_group) tuples
+    tasks: list[tuple[str, str]] = []  # (varied_description, base_description)
+    for entry in population:
+        if not isinstance(entry, dict):
+            continue
+        raw_desc = str(entry.get("description", "")).strip()
+        if not raw_desc:
+            continue
+        try:
+            count = max(1, min(10, int(entry.get("count", 1))))
+        except (TypeError, ValueError):
+            count = 1
+        for i in range(count):
+            if i == 0:
+                varied = raw_desc
+            elif i == 1:
+                varied = f"{raw_desc} (variant 2: slightly more optimistic)"
+            elif i == 2:
+                varied = f"{raw_desc} (variant 3: more conservative on macro)"
+            else:
+                varied = f"{raw_desc} (variant {i + 1}: distinct perspective)"
+            tasks.append((varied, raw_desc))
+
+    total = len(tasks)
+    if total == 0:
+        await _err(send, 400, "no valid population entries")
+        return
+
+    # Generate all personas in parallel
+    async def _gen(desc: str) -> Any:
+        try:
+            return await generate_persona(desc, model=model, no_llm=no_llm)
+        except Exception as exc:
+            return exc
+
+    results = await asyncio.gather(*[_gen(desc) for desc, _ in tasks])
+
+    saved_specs: list[dict] = []
+    errors: list[str] = []
+
+    for spec_or_exc in results:
+        if isinstance(spec_or_exc, Exception):
+            errors.append(str(spec_or_exc))
+            continue
+        spec = spec_or_exc
+        # Resolve slug collisions by appending -01, -02, etc.
+        base_slug = spec.slug
+        candidate = base_slug
+        if is_builtin(candidate) or get_persona(candidate) is not None:
+            for n in range(1, 100):
+                candidate = f"{base_slug}-{n:02d}"
+                if not is_builtin(candidate) and get_persona(candidate) is None:
+                    break
+        spec.slug = candidate
+        try:
+            save_persona(spec)
+            saved_specs.append(spec.to_dict())
+        except Exception as exc:
+            errors.append(f"{spec.slug}: {exc}")
+
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "saved": len(saved_specs),
+            "personas": saved_specs,
+            "errors": errors,
+        },
+    )
+
+
+async def _handle_generate_persona(body: bytes, send: _Send) -> None:
+    from .prompt_generator import generate_persona
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    description = str(data.get("description", "")).strip()
+    if not description:
+        await _err(send, 400, "description is required")
+        return
+    model = data.get("model")
+    no_llm = bool(data.get("no_llm", False))
+    try:
+        spec = await generate_persona(description, model=model, no_llm=no_llm)
+    except Exception as exc:
+        await _err(send, 502, f"generator failed: {exc}")
+        return
+    await _send_json(send, status=200, payload=spec.to_dict())
+
+
+# ---------------------------------------------------------------------------
+# Tool library handlers
+# ---------------------------------------------------------------------------
+
+
+async def _handle_list_tool_catalog(send: _Send) -> None:
+    from .tool_registry import list_catalog
+
+    await _send_json(send, status=200, payload=[t.to_dict() for t in list_catalog()])
+
+
+async def _handle_get_tool_def(slug: str, send: _Send) -> None:
+    from .tool_registry import get_tool_def
+
+    t = get_tool_def(slug)
+    if t is None:
+        await _err(send, 404, f"unknown tool: {slug}")
+        return
+    await _send_json(send, status=200, payload=t.to_dict())
+
+
+async def _handle_list_activated_tools(send: _Send) -> None:
+    from .tool_registry import load_activated_tools
+
+    await _send_json(send, status=200, payload=[t.to_api_dict() for t in load_activated_tools()])
+
+
+async def _handle_activate_tool(body: bytes, send: _Send) -> None:
+    import time as _time
+
+    from .tool_registry import (
+        ActivatedTool,
+        encode_credential,
+        get_activated_tool,
+        get_tool_def,
+        save_activated_tool,
+    )
+
+    try:
+        data = json.loads(body or b"{}")
+    except Exception:
+        await _err(send, 400, "invalid JSON")
+        return
+    tool_slug = str(data.get("tool_slug", ""))
+    if not get_tool_def(tool_slug):
+        await _err(send, 422, f"unknown tool slug: {tool_slug}")
+        return
+    existing = get_activated_tool(tool_slug)
+    if existing and existing.status != "disabled":
+        await _err(send, 409, f"tool already activated: {tool_slug} (status={existing.status})")
+        return
+    raw_creds: dict = data.get("credentials", {})
+    encoded_creds = {k: encode_credential(str(v)) for k, v in raw_creds.items()}
+    t = ActivatedTool(
+        tool_slug=tool_slug,
+        status="pending",
+        credentials=encoded_creds,
+        label=str(data.get("label", "") or tool_slug),
+        activated_at_ms=int(_time.time() * 1000),
+    )
+    save_activated_tool(t)
+    await _send_json(send, status=201, payload=t.to_api_dict())
+
+
+async def _handle_test_tool(slug: str, send: _Send) -> None:
+    import importlib
+    import time as _time
+
+    from .tool_registry import (
+        decode_credential,
+        get_activated_tool,
+        get_tool_def,
+        save_activated_tool,
+    )
+
+    tool_def = get_tool_def(slug)
+    if tool_def is None:
+        await _err(send, 404, f"unknown tool: {slug}")
+        return
+    activated = get_activated_tool(slug)
+    if activated is None:
+        await _err(send, 404, f"tool not activated: {slug}")
+        return
+    # No-key tools don't need a live network test — auto-verify immediately.
+    if tool_def.auth_type == "none":
+        ok, message = True, "No API key required — auto-verified"
+    else:
+        creds = {k: decode_credential(v) for k, v in activated.credentials.items()}
+        try:
+            mod = importlib.import_module(tool_def.handler_module)
+            ok, message = await mod.test_connection(creds)
+        except Exception as e:
+            ok, message = False, str(e)
+    activated.last_tested_ms = int(_time.time() * 1000)
+    activated.error_msg = None if ok else message
+    if ok and activated.status == "pending":
+        activated.status = "verified"
+    save_activated_tool(activated)
+    await _send_json(
+        send, status=200, payload={"ok": ok, "message": message, "status": activated.status}
+    )
+
+
+async def _handle_set_tool_active(slug: str, send: _Send) -> None:
+    import time as _time
+
+    from .tool_registry import get_activated_tool, get_tool_def, save_activated_tool
+
+    tool_def = get_tool_def(slug)
+    activated = get_activated_tool(slug)
+    if activated is None:
+        await _err(send, 404, f"tool not activated: {slug}")
+        return
+    # No-key tools skip the verify step — promote from pending or verified.
+    no_key = tool_def is not None and tool_def.auth_type == "none"
+    if activated.status not in ("verified", "pending" if no_key else "__never__"):
+        await _err(
+            send,
+            422,
+            f"tool must be verified before activating; current status: {activated.status}",
+        )
+        return
+    if activated.status == "pending" and no_key:
+        activated.last_tested_ms = int(_time.time() * 1000)
+    activated.status = "active"
+    save_activated_tool(activated)
+    await _send_json(send, status=200, payload=activated.to_api_dict())
+
+
+async def _handle_update_tool_credentials(slug: str, body: bytes, send: _Send) -> None:
+    from .tool_registry import encode_credential, get_activated_tool, save_activated_tool
+
+    activated = get_activated_tool(slug)
+    if activated is None:
+        await _err(send, 404, f"tool not activated: {slug}")
+        return
+    try:
+        data = json.loads(body or b"{}")
+    except Exception:
+        await _err(send, 400, "invalid JSON")
+        return
+    raw_creds: dict = data.get("credentials", {})
+    activated.credentials = {k: encode_credential(str(v)) for k, v in raw_creds.items()}
+    activated.status = "pending"
+    activated.error_msg = None
+    save_activated_tool(activated)
+    await _send_json(send, status=200, payload=activated.to_api_dict())
+
+
+async def _handle_deactivate_tool(slug: str, send: _Send) -> None:
+    from .tool_registry import get_activated_tool, save_activated_tool
+
+    activated = get_activated_tool(slug)
+    if activated is None:
+        await _err(send, 404, f"tool not activated: {slug}")
+        return
+    activated.status = "disabled"
+    save_activated_tool(activated)
+    await _send_json(send, status=200, payload={"ok": True, "status": "disabled"})
+
+
+# ---------------------------------------------------------------------------
+# Swarm handlers
+# ---------------------------------------------------------------------------
+
+
+async def _handle_list_swarms(send: _Send) -> None:
+    from .swarms import load_swarms
+
+    payload = [s.to_dict() for s in load_swarms()]
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_get_swarm(slug: str, send: _Send) -> None:
+    from .swarms import get_swarm
+
+    s = get_swarm(slug)
+    if s is None:
+        await _err(send, 404, f"unknown swarm: {slug}")
+        return
+    await _send_json(send, status=200, payload=s.to_dict())
+
+
+async def _handle_create_swarm(body: bytes, send: _Send) -> None:
+    from .swarms import Swarm, save_swarm
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    try:
+        s = Swarm.from_dict(data)
+        save_swarm(s)
+    except (TypeError, ValueError) as exc:
+        await _err(send, 400, str(exc))
+        return
+    await _send_json(send, status=201, payload=s.to_dict())
+
+
+async def _handle_update_swarm(slug: str, body: bytes, send: _Send) -> None:
+    from .swarms import Swarm, get_swarm, save_swarm
+
+    existing = get_swarm(slug)
+    if existing is None:
+        await _err(send, 404, f"unknown swarm: {slug}")
+        return
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    merged = {**existing.to_dict(), **data, "slug": slug}
+    try:
+        s = Swarm.from_dict(merged)
+        save_swarm(s)
+    except (TypeError, ValueError) as exc:
+        await _err(send, 400, str(exc))
+        return
+    await _send_json(send, status=200, payload=s.to_dict())
+
+
+async def _handle_delete_swarm(slug: str, send: _Send) -> None:
+    from .swarms import delete_swarm
+
+    delete_swarm(slug)
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 204,
+            "headers": [(b"content-length", b"0")],
+        }
+    )
+    await send({"type": "http.response.body", "body": b"", "more_body": False})
+
+
+async def _handle_knowledge_claim(kid: str, send: _Send) -> None:
+    idx = build_knowledge_index()
+    payload = idx.claim(kid)
+    if payload is None:
+        await _err(send, 404, f"unknown claim kid: {kid}")
+        return
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_lineage(send: _Send) -> None:
+    """S4 — Cross-sim KernelStore lineage summary.
+
+    Returns one row per persona that has accumulated Brier observations
+    across sims. Powers the Lineage section on SimDetail Trust tab and
+    the Home page lifetime-Brier headline.
+    """
+    from hypermind.knowledge.kernel_store import KernelStore
+
+    rows = []
+    for persona in KernelStore.list_personas():
+        s = KernelStore.lifetime_summary(persona)
+        rows.append(s)
+    rows.sort(key=lambda r: r.get("mean_brier") if r.get("mean_brier") is not None else 1.0)
+    await _send_json(send, status=200, payload={"lineage": rows})
+
+
+async def _handle_knowledge_scoreboard(send: _Send) -> None:
+    """Per-persona-replica calibration scoreboard.
+
+    Returns a list of agents with their accuracy, Brier score, and
+    claim count, sorted by Brier (lower = better).
+    """
+    idx = build_knowledge_index()
+    rows = []
+    for ag in idx.agents.values():
+        if ag.oracle_total == 0:
+            continue  # only score agents that have resolved claims
+        # Brier across resolved claims for this agent
+        briers = []
+        for c in idx.claims.values():
+            if c.agent != ag.name or c.resolved_outcome is None:
+                continue
+            target = 1.0 if c.resolved_outcome else 0.0
+            briers.append((c.confidence - target) ** 2)
+        if not briers:
+            continue
+        brier = sum(briers) / len(briers)
+        rows.append(
+            {
+                "name": ag.name,
+                "persona": ag.persona,
+                "accuracy": ag.accuracy,
+                "brier": brier,
+                "n_resolved": len(briers),
+                "n_claims": ag.claims_published,
+                "citations_received": ag.citations_received,
+                "last_reputation": ag.last_reputation,
+                "runs": ag.runs_participated,
+            }
+        )
+    rows.sort(key=lambda r: r["brier"])
+    await _send_json(send, status=200, payload=rows)
+
+
+async def _handle_knowledge_similar(kid: str, qs: bytes, send: _Send) -> None:
+    """Find claims with similar query text to the one identified by kid.
+
+    Useful for cross-sim synthesis: an analyst opens a claim and wants
+    to see "what else has the federation said on this question?"
+    """
+    idx = build_knowledge_index()
+    target = idx.claim(kid)
+    if target is None:
+        await _err(send, 404, f"unknown claim kid: {kid}")
+        return
+    try:
+        top_k = max(1, min(50, int(_qs_param(qs, "top_k", "10"))))
+    except ValueError:
+        top_k = 10
+    payload = idx.ask(target["claim"]["query"], top_k=top_k + 1)  # +1 to drop self
+    # Remove self from results
+    payload["items"] = [c for c in payload["items"] if c["kid"] != target["claim"]["kid"]][:top_k]
+    payload["seed_kid"] = target["claim"]["kid"]
+    payload["seed_query"] = target["claim"]["query"]
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _send_bytes(
+    send: _Send,
+    data: bytes,
+    *,
+    content_type: str = "application/octet-stream",
+    filename: str = "file",
+) -> None:
+    """Send a raw bytes response with Content-Disposition."""
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                [b"content-type", content_type.encode()],
+                [b"content-length", str(len(data)).encode()],
+                [b"content-disposition", f'attachment; filename="{filename}"'.encode()],
+                [b"access-control-allow-origin", b"*"],
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": data, "more_body": False})
+
+
+async def _handle_knowledge_synthesis(qs: bytes, send: _Send) -> None:
+    """GET /v1/knowledge/synthesis — cross-sim consensus synthesis per question."""
+    from collections import defaultdict
+
+    idx = build_knowledge_index()
+    topic = _qs_param(qs, "topic", "")
+    q = _qs_param(qs, "q", "")
+    try:
+        top_k = max(1, min(100, int(_qs_param(qs, "top_k", "20"))))
+    except ValueError:
+        top_k = 20
+
+    all_claims_resp = idx.list_claims(
+        q=q or "",
+        topic=topic or "",
+        sim_id="",
+        limit=2000,
+        offset=0,
+    )
+    all_claims = all_claims_resp.get("items", [])
+
+    if not all_claims:
+        await _send_json(
+            send,
+            status=200,
+            payload={
+                "topic": topic,
+                "n_sims_contributing": 0,
+                "questions": [],
+                "contradiction_map": [],
+            },
+        )
+        return
+
+    # Group claims by query (first 80 chars, lowercased)
+    query_groups: dict[str, list] = defaultdict(list)
+    for claim in all_claims:
+        key = claim.get("query", "")[:80].lower().strip()
+        query_groups[key].append(claim)
+
+    questions = []
+    for query_key, claims in sorted(query_groups.items(), key=lambda x: -len(x[1])):
+        if not claims:
+            continue
+        confs = [c.get("confidence", 0.5) for c in claims if c.get("confidence") is not None]
+        if not confs:
+            continue
+
+        mean_conf = sum(confs) / len(confs)
+        spread = max(confs) - min(confs) if len(confs) > 1 else 0.0
+
+        sim_map: dict[str, list] = defaultdict(list)
+        for c in claims:
+            sim_map[c.get("sim_id", "unknown")].append(c)
+
+        confidence_history = []
+        for sim_id_key, sim_claims in sim_map.items():
+            sim_confs = [c.get("confidence", 0.5) for c in sim_claims]
+            sim_ts = min(c.get("ts_wall_ms", 0) for c in sim_claims)
+            confidence_history.append(
+                {
+                    "sim_id": sim_id_key,
+                    "ts": sim_ts / 1000.0,
+                    "mean_conf": sum(sim_confs) / len(sim_confs),
+                    "spread": max(sim_confs) - min(sim_confs) if len(sim_confs) > 1 else 0.0,
+                    "n_claims": len(sim_claims),
+                }
+            )
+        confidence_history.sort(key=lambda x: x["ts"])
+
+        n_sims = len(sim_map)
+        if n_sims >= 3 and spread < 0.10:
+            status_val = "settled"
+        elif spread >= 0.30:
+            status_val = "contested"
+        else:
+            status_val = "emerging"
+
+        cited_claims = sorted(claims, key=lambda c: c.get("citations_received", 0), reverse=True)
+        best_reasoning = [
+            c.get("reasoning", "")[:400] for c in cited_claims[:3] if c.get("reasoning", "")
+        ]
+
+        n_supporting = sum(1 for c in claims if c.get("confidence", 0.5) >= mean_conf + 0.15)
+        n_contradicting = sum(1 for c in claims if c.get("confidence", 0.5) <= mean_conf - 0.15)
+
+        questions.append(
+            {
+                "query": claims[0].get("query", query_key),
+                "status": status_val,
+                "confidence_history": confidence_history,
+                "current_consensus": round(mean_conf, 4),
+                "current_spread": round(spread, 4),
+                "n_sims": n_sims,
+                "n_claims": len(claims),
+                "n_supporting_claims": n_supporting,
+                "n_contradicting_claims": n_contradicting,
+                "best_reasoning": best_reasoning,
+            }
+        )
+
+    questions.sort(key=lambda qt: -qt["n_claims"])
+    questions = questions[:top_k]
+
+    # Build contradiction map
+    contradiction_map = []
+    for qt in questions:
+        query_claims = [
+            c
+            for c in all_claims
+            if c.get("query", "")[:80].lower().strip() == qt["query"][:80].lower().strip()
+        ]
+        persona_confs: dict[str, list[float]] = defaultdict(list)
+        for c in query_claims:
+            p = c.get("persona", "unknown")
+            persona_confs[p].append(c.get("confidence", 0.5))
+
+        persona_means = {p: sum(v) / len(v) for p, v in persona_confs.items()}
+        sorted_personas = sorted(persona_means.items(), key=lambda x: x[1])
+
+        if len(sorted_personas) >= 2:
+            low_p, low_v = sorted_personas[0]
+            high_p, high_v = sorted_personas[-1]
+            delta = high_v - low_v
+            if delta >= 0.20:
+                contradiction_map.append(
+                    {
+                        "query": qt["query"],
+                        "high_persona": high_p,
+                        "high_conf": round(high_v, 4),
+                        "low_persona": low_p,
+                        "low_conf": round(low_v, 4),
+                        "delta": round(delta, 4),
+                    }
+                )
+
+    contradiction_map.sort(key=lambda x: -x["delta"])
+
+    n_sims_contributing = len({c.get("sim_id") for c in all_claims})
+
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "topic": topic,
+            "n_sims_contributing": n_sims_contributing,
+            "questions": questions,
+            "contradiction_map": contradiction_map[:20],
+        },
+    )
+
+
+async def _handle_knowledge_followup(qs: bytes, send: _Send) -> None:
+    """GET /v1/knowledge/followup — autonomous follow-up question generation."""
+    from collections import defaultdict
+
+    from hypermind.simlab._scenario_impl import generate_followup_questions
+
+    idx = build_knowledge_index()
+    sim_id = _qs_param(qs, "sim_id", "") or ""
+    topic = _qs_param(qs, "topic", "") or ""
+    try:
+        top_k = max(1, min(50, int(_qs_param(qs, "top_k", "10"))))
+    except ValueError:
+        top_k = 10
+
+    claims_resp = idx.list_claims(
+        topic=topic,
+        sim_id=sim_id,
+        limit=500,
+        offset=0,
+    )
+    claims = claims_resp.get("items", [])
+
+    if not claims:
+        await _send_json(send, status=200, payload={"questions": []})
+        return
+
+    query_claims: dict[str, list] = defaultdict(list)
+    for c in claims:
+        query_claims[c.get("query", "")].append(c)
+
+    panel_records = []
+    for query, qclaims in query_claims.items():
+        confs = [c.get("confidence", 0.5) for c in qclaims if c.get("confidence") is not None]
+        if not confs:
+            continue
+        disputed = [c for c in qclaims if c.get("disputes_received", 0) > 0]
+        panel_records.append(
+            {
+                "query": query,
+                "mean_confidence": sum(confs) / len(confs),
+                "spread": max(confs) - min(confs) if len(confs) > 1 else 0.0,
+                "disputes": [
+                    {"from_persona": c.get("persona", "unknown"), "delta": 0.35} for c in disputed
+                ],
+                "per_agent": [
+                    {
+                        "persona": c.get("persona", ""),
+                        "reasoning": c.get("reasoning", ""),
+                        "confidence": c.get("confidence", 0.5),
+                    }
+                    for c in qclaims
+                ],
+            }
+        )
+
+    followups = generate_followup_questions(panel_records, top_k=top_k)
+    await _send_json(send, status=200, payload={"questions": followups})
+
+
+def _render_report_markdown(report: dict) -> str:
+    """Render a report data dict to a Markdown string."""
+    import datetime
+
+    lines = []
+    dt = datetime.datetime.fromtimestamp(report.get("generated_at", 0)).strftime(
+        "%Y-%m-%d %H:%M UTC"
+    )
+    topic = report.get("topic") or "All Topics"
+
+    lines.append("# Swarm Intelligence Report")
+    lines.append("")
+    lines.append(
+        f"**Topic:** {topic}  |  **Generated:** {dt}  |  "
+        f"**Simulations:** {report.get('n_sims', 0)}  |  **Agents:** {report.get('n_agents', 0)}"
+    )
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("## Abstract")
+    lines.append("")
+    lines.append(report.get("abstract", ""))
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("## Key Findings")
+    lines.append("")
+    lines.append("| # | Question | Confidence | Spread | Verdict | Sims | Calibration |")
+    lines.append("|---|----------|-----------|--------|---------|------|-------------|")
+
+    verdict_emoji = {"YES": "✅", "LEAN YES": "🟢", "SPLIT": "🟡", "LEAN NO": "🟠", "NO": "❌"}
+
+    for i, kf in enumerate(report.get("key_findings", []), 1):
+        ve = verdict_emoji.get(kf.get("verdict", ""), "")
+        q_short = kf.get("query", "")[:80] + ("…" if len(kf.get("query", "")) > 80 else "")
+        cal = f"{kf['calibration_error']:.3f}" if kf.get("calibration_error") is not None else "—"
+        lines.append(
+            f"| {i} | {q_short} | {kf.get('mean_conf', 0):.1%} | ±{kf.get('spread', 0):.1%} "
+            f"| {ve} {kf.get('verdict', '')} | {kf.get('n_sims', 0)} | {cal} |"
+        )
+
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("## Per-Question Analysis")
+    lines.append("")
+
+    for i, pq in enumerate(report.get("per_question", []), 1):
+        lines.append(f"### Q{i}: {pq.get('query', '')}")
+        lines.append("")
+        lines.append(
+            f"**Panel consensus:** {pq.get('mean_conf', 0):.1%} "
+            f"(spread: ±{pq.get('spread', 0):.1%})  |  **Verdict:** {pq.get('verdict', '')}"
+        )
+        lines.append("")
+        lines.append(
+            f"**Disputes:** {pq.get('n_disputes', 0)}  |  **Citations:** {pq.get('n_citations', 0)}"
+        )
+        lines.append("")
+        for pr in pq.get("per_persona_reasoning", []):
+            lines.append(f"**{pr.get('persona', '')}** ({pr.get('mean_confidence', 0):.1%})")
+            reasoning = pr.get("reasoning", "").strip()
+            if reasoning:
+                lines.append(f"> {reasoning[:500]}")
+            lines.append("")
+
+    lines.append("---")
+    lines.append("")
+    lines.append("## Persona Forensics")
+    lines.append("")
+    lines.append("| Persona | Brier Score | Claims | Citations | Resolved | Runs |")
+    lines.append("|---------|------------|--------|-----------|----------|------|")
+
+    for pf in report.get("persona_forensics", []):
+        lines.append(
+            f"| {pf.get('emoji', '🤖')} {pf.get('label', pf.get('persona', ''))} "
+            f"| {pf.get('brier', 0):.4f} | {pf.get('n_claims', 0)} "
+            f"| {pf.get('citations_received', 0)} | {pf.get('n_resolved', 0)} "
+            f"| {pf.get('runs', 0)} |"
+        )
+
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("## Autonomous Follow-Up Questions")
+    lines.append("")
+    lines.append(
+        "*The following questions were autonomously identified by the swarm "
+        "as highest-priority for further investigation.*"
+    )
+    lines.append("")
+
+    trigger_labels = {
+        "high_spread": "⚡ HIGH UNCERTAINTY",
+        "dispute": "⚔️ DISPUTED",
+        "low_confidence": "🌫️ AMBIGUOUS",
+        "gap": "🔭 KNOWLEDGE GAP",
+    }
+
+    for i, fq in enumerate(report.get("follow_up_questions", []), 1):
+        label = trigger_labels.get(fq.get("trigger", ""), "❓")
+        lines.append(f"{i}. **[{label}]** {fq.get('text', '')}")
+        lines.append(f"   > *{fq.get('rationale', '')[:200]}*")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+async def _handle_report(body_bytes: bytes, send: _Send, *, force_markdown: bool = False) -> None:
+    """POST /v1/report — generate a JSON (or Markdown) synthesis report."""
+    import time as _time
+    from collections import defaultdict
+
+    from hypermind.simlab._scenario_impl import generate_followup_questions
+
+    try:
+        body = json.loads(body_bytes) if body_bytes else {}
+    except Exception:
+        body = {}
+
+    sim_ids = body.get("sim_ids")
+    topic = body.get("topic") or ""
+    persona_filter = body.get("persona") or ""
+    fmt = "markdown" if force_markdown else body.get("format", "json")
+
+    idx = build_knowledge_index()
+
+    sim_id_filter = sim_ids[0] if sim_ids and len(sim_ids) == 1 else ""
+
+    overview = idx.overview()
+    claims_resp = idx.list_claims(
+        persona=persona_filter,
+        topic=topic or "",
+        sim_id=sim_id_filter,
+        limit=2000,
+        offset=0,
+    )
+    claims = claims_resp.get("items", [])
+
+    # Build scoreboard inline (mirrors _handle_knowledge_scoreboard)
+    scoreboard_rows: list[dict] = []
+    for ag in idx.agents.values():
+        briers = []
+        for c in idx.claims.values():
+            if c.agent != ag.name or c.resolved_outcome is None:
+                continue
+            target = 1.0 if c.resolved_outcome else 0.0
+            briers.append((c.confidence - target) ** 2)
+        brier = sum(briers) / len(briers) if briers else 0.0
+        scoreboard_rows.append(
+            {
+                "name": ag.name,
+                "persona": ag.persona,
+                "accuracy": ag.accuracy,
+                "brier": brier,
+                "n_resolved": len(briers),
+                "n_claims": ag.claims_published,
+                "citations_received": ag.citations_received,
+                "last_reputation": ag.last_reputation,
+                "runs": ag.runs_participated,
+            }
+        )
+
+    query_map: dict[str, list] = defaultdict(list)
+    for c in claims:
+        query_map[c.get("query", "")].append(c)
+
+    key_findings = []
+    per_question = []
+
+    for query, qclaims in sorted(query_map.items(), key=lambda x: -len(x[1])):
+        confs = [c.get("confidence", 0.5) for c in qclaims if c.get("confidence") is not None]
+        if not confs:
+            continue
+        mean_conf = sum(confs) / len(confs)
+        spread = max(confs) - min(confs) if len(confs) > 1 else 0.0
+
+        if mean_conf >= 0.70:
+            verdict = "YES"
+        elif mean_conf >= 0.55:
+            verdict = "LEAN YES"
+        elif mean_conf >= 0.45:
+            verdict = "SPLIT"
+        elif mean_conf >= 0.30:
+            verdict = "LEAN NO"
+        else:
+            verdict = "NO"
+
+        gt_vals = [c.get("ground_truth") for c in qclaims if c.get("ground_truth") is not None]
+        gt = gt_vals[0] if gt_vals else None
+        cal_error = abs(mean_conf - gt) if gt is not None else None
+
+        resolved = [c for c in qclaims if c.get("resolved_outcome") is not None]
+        n_sims_q = len({c.get("sim_id") for c in qclaims})
+
+        key_findings.append(
+            {
+                "query": query,
+                "mean_conf": round(mean_conf, 4),
+                "spread": round(spread, 4),
+                "verdict": verdict,
+                "n_sims": n_sims_q,
+                "n_claims": len(qclaims),
+                "calibration_error": round(cal_error, 4) if cal_error is not None else None,
+                "ground_truth": gt,
+                "n_resolved": len(resolved),
+            }
+        )
+
+        persona_map_q: dict[str, list] = defaultdict(list)
+        for c in qclaims:
+            persona_map_q[c.get("persona", "unknown")].append(c)
+
+        persona_reasoning: list[dict] = []
+        for p, pclaims in persona_map_q.items():
+            pconfs = [c.get("confidence", 0.5) for c in pclaims]
+            per_persona_mean = sum(pconfs) / len(pconfs)
+            best = max(pclaims, key=lambda c: c.get("citations_received", 0))
+            persona_reasoning.append(
+                {
+                    "persona": p,
+                    "mean_confidence": round(per_persona_mean, 4),
+                    "n_claims": len(pclaims),
+                    "reasoning": best.get("reasoning", "")[:1000],
+                }
+            )
+
+        disputes_q = [c for c in qclaims if c.get("disputes_received", 0) > 0]
+        citations_q = sum(c.get("citations_received", 0) for c in qclaims)
+
+        per_question.append(
+            {
+                "query": query,
+                "mean_conf": round(mean_conf, 4),
+                "spread": round(spread, 4),
+                "verdict": verdict,
+                "per_persona_reasoning": persona_reasoning,
+                "n_disputes": len(disputes_q),
+                "n_citations": citations_q,
+                "convergence_curve": [],
+            }
+        )
+
+    key_findings.sort(key=lambda x: x["n_claims"], reverse=True)
+
+    # Persona forensics: aggregate by slug from scoreboard
+    persona_agg: dict[str, dict] = {}
+    for ag_row in scoreboard_rows:
+        slug = ag_row.get("persona", "")
+        if not slug:
+            continue
+        if slug not in persona_agg:
+            persona_agg[slug] = {
+                "persona": slug,
+                "label": slug,
+                "emoji": "🤖",
+                "total_brier": 0.0,
+                "n_brier": 0,
+                "n_claims": 0,
+                "citations_received": 0,
+                "n_resolved": 0,
+                "runs": 0,
+            }
+        pa = persona_agg[slug]
+        if ag_row["brier"] > 0:
+            pa["total_brier"] += ag_row["brier"]
+            pa["n_brier"] += 1
+        pa["n_claims"] += ag_row.get("n_claims", 0)
+        pa["citations_received"] += ag_row.get("citations_received", 0)
+        pa["n_resolved"] += ag_row.get("n_resolved", 0)
+        pa["runs"] += ag_row.get("runs", 0)
+
+    try:
+        from hypermind.simlab._scenario_impl import PERSONAS as _PERSONAS
+
+        for slug, pa in persona_agg.items():
+            if slug in _PERSONAS:
+                pa["label"] = _PERSONAS[slug].get("label", slug)
+                pa["emoji"] = _PERSONAS[slug].get("emoji", "🤖")
+    except Exception:
+        pass
+
+    forensics_list: list[dict] = []
+    for slug, pa in persona_agg.items():
+        mean_brier = pa["total_brier"] / pa["n_brier"] if pa["n_brier"] > 0 else 0.0
+        forensics_list.append(
+            {
+                "persona": slug,
+                "label": pa["label"],
+                "emoji": pa["emoji"],
+                "brier": round(mean_brier, 4),
+                "n_claims": pa["n_claims"],
+                "citations_received": pa["citations_received"],
+                "n_resolved": pa["n_resolved"],
+                "runs": pa["runs"],
+            }
+        )
+    forensics_list.sort(key=lambda x: x["brier"])
+
+    n_sims = overview.get("n_sims", 0)
+    n_agents = overview.get("n_agents", 0)
+    n_claims_total = len(claims)
+    n_questions_total = len(key_findings)
+    panel_accuracy = overview.get("panel_accuracy")
+
+    yes_count = sum(1 for kf in key_findings if kf["verdict"] in ("YES", "LEAN YES"))
+    no_count = sum(1 for kf in key_findings if kf["verdict"] in ("NO", "LEAN NO"))
+    split_count = sum(1 for kf in key_findings if kf["verdict"] == "SPLIT")
+
+    topic_str = f" on the topic of '{topic}'" if topic else ""
+    accuracy_str = f" Panel calibration accuracy: {panel_accuracy:.1%}." if panel_accuracy else ""
+    verdict_str = (
+        f"The swarm reached affirmative verdicts (YES or LEAN YES) on {yes_count} of "
+        f"{n_questions_total} questions, negative verdicts on {no_count}, "
+        f"and split verdicts on {split_count}."
+        if n_questions_total > 0
+        else ""
+    )
+
+    abstract = (
+        f"This report synthesizes the deliberations of a {n_agents}-agent intelligence swarm "
+        f"across {n_sims} simulation(s){topic_str}. "
+        f"The swarm evaluated {n_questions_total} distinct question(s), producing {n_claims_total} total claims "
+        f"with {overview.get('total_citations', 0)} citations and {overview.get('total_disputes', 0)} disputes. "
+        f"{verdict_str}"
+        f"{accuracy_str} "
+        f"Personas contributing to this report: "
+        f"{', '.join(pa['label'] for pa in forensics_list[:6])}."
+    ).strip()
+
+    panel_records_for_followup = []
+    for kf in key_findings:
+        q_claims = query_map.get(kf["query"], [])
+        disputed = [c for c in q_claims if c.get("disputes_received", 0) > 0]
+        panel_records_for_followup.append(
+            {
+                "query": kf["query"],
+                "mean_confidence": kf["mean_conf"],
+                "spread": kf["spread"],
+                "disputes": [
+                    {"from_persona": c.get("persona", ""), "delta": 0.35} for c in disputed
+                ],
+                "per_agent": [],
+            }
+        )
+    followup_questions = generate_followup_questions(panel_records_for_followup, top_k=10)
+
+    report_data = {
+        "generated_at": _time.time(),
+        "topic": topic,
+        "n_sims": n_sims,
+        "n_agents": n_agents,
+        "n_claims": n_claims_total,
+        "n_questions": n_questions_total,
+        "abstract": abstract,
+        "key_findings": key_findings,
+        "per_question": per_question,
+        "persona_forensics": forensics_list,
+        "follow_up_questions": followup_questions,
+    }
+
+    if fmt == "markdown":
+        md = _render_report_markdown(report_data)
+        await _send_bytes(
+            send,
+            md.encode("utf-8"),
+            content_type="text/markdown; charset=utf-8",
+            filename="swarm-intelligence-report.md",
+        )
+        return
+
+    await _send_json(send, status=200, payload=report_data)
+
+
+async def _handle_stats(send: _Send) -> None:
+    """GET /v1/stats — simlab-level federation summary.
+
+    Aggregates stats across all namespaces found in the sim registry.
+    If all sims share a single namespace the response reflects that
+    namespace; otherwise ``namespace`` is ``"all"``.
+    """
+    import hashlib
+
+    from .registry import load_config as _load_cfg
+
+    idx = build_knowledge_index()
+    sealed_count = len(idx.claims)
+    dispute_count = sum(len(v) for v in idx.disputes_to.values())
+
+    # Collect distinct namespaces from sim configs; fall back gracefully.
+    namespaces: set[str] = set()
+    rooms: set[str] = set()
+    for sim in list_sims(limit=500):
+        try:
+            cfg = _load_cfg(sim.sim_id)
+            ns = cfg.get("namespace")
+            if ns:
+                namespaces.add(ns)
+            room = cfg.get("room")
+            if room:
+                rooms.add(room)
+        except Exception:
+            pass
+
+    if not namespaces:
+        # Fall back to the default scenario namespace when no sim configs exist.
+        try:
+            from ._scenario_impl import NAMESPACE as _NS
+            from ._scenario_impl import ROOM as _ROOM
+
+            namespaces = {_NS}
+            rooms = {_ROOM}
+        except Exception:
+            namespaces = {"default"}
+
+    namespace = next(iter(namespaces)) if len(namespaces) == 1 else "all"
+    ns_id = hashlib.sha256(namespace.encode()).hexdigest()[:32]
+    payload = {
+        "agent_kid": ns_id,
+        "did_key": f"did:key:z{ns_id[:24]}",
+        "namespace": namespace,
+        "rooms": sorted(rooms) if rooms else [],
+        "role": "operator",
+        "ramp_paused": False,
+        "world": {
+            "namespace_id": ns_id,
+            "sealed_count": sealed_count,
+            "dispute_count": dispute_count,
+            "tree_size": sealed_count,
+        },
+    }
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_disputes(send: _Send) -> None:
+    """GET /v1/disputes — collect dispute records across all completed sims."""
+    all_sims = list_sims()
+    disputes: list[dict] = []
+    for sim in all_sims:
+        if sim.state != "done":
+            continue
+        try:
+            trace = load_trace(sim.sim_id)
+            if trace is None:
+                continue
+            raw = trace if isinstance(trace, dict) else {}
+            for pr in raw.get("panel_records", []):
+                for d in pr.get("disputes", []):
+                    disputes.append(
+                        {
+                            "kid": d.get("dispute_kid", ""),
+                            "initiator": d.get("initiator_kid", d.get("kid", "")),
+                            "state": d.get("state", "CLOSED"),
+                            "bond_topic_scope": d.get("topic", pr.get("query", "")[:60]),
+                            "bond_amount": d.get("bond_amount", 0),
+                            "transitions": d.get("transitions", []),
+                            "sim_id": sim.sim_id,
+                        }
+                    )
+        except Exception:
+            continue
+    await _send_json(send, status=200, payload={"count": len(disputes), "disputes": disputes})
+
+
+async def _handle_sim_agents(sim_id: str, send: _Send) -> None:
+    """Return the agent roster for a sim (live or completed).
+
+    Sourced from the in-process persona registry populated when the
+    runner builds profiles. Lets the live Activity canvas seed bubbles
+    before the first event arrives.
+    """
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    from . import _persona_registry
+
+    seen: dict[str, dict[str, str]] = {}
+    # Walk the registry, emitting one row per unique display_name.
+    with _persona_registry._LOCK:
+        bucket = _persona_registry._REGISTRY.get(sim_id, {})
+        for key, meta in bucket.items():
+            name = meta.get("display_name") or key
+            if name in seen:
+                continue
+            seen[name] = {
+                "name": name,
+                "persona": meta.get("persona", ""),
+                "persona_emoji": meta.get("persona_emoji", ""),
+                "role": meta.get("role", ""),  # S5
+            }
+    await _send_json(send, status=200, payload={"agents": list(seen.values())})
+
+
+async def _handle_resolve_outcomes(sim_id: str, body_bytes: bytes, send: _Send) -> None:
+    """POST /v1/sims/{id}/resolve — apply ground-truth resolutions, recompute EIG/Q + Brier."""
+    import math
+    import time as _time
+
+    from hypermind.eval.calibration import brier_score
+    from hypermind.eval.swarm_iq import effective_information_gain_per_question
+
+    sd = sim_dir(sim_id)
+    if not sd.exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    status = load_status(sim_id)
+    if status.get("state") == "unknown":
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    if status.get("state") != "done":
+        await _err(send, 409, f"sim {sim_id!r} is not done (state={status.get('state')!r})")
+        return
+    trace = load_trace(sim_id)
+    if trace is None:
+        await _err(send, 404, f"no trace for sim: {sim_id}")
+        return
+
+    try:
+        payload = json.loads(body_bytes or b"{}")
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    resolutions = payload.get("resolutions")
+    if not isinstance(resolutions, list) or not resolutions:
+        await _err(send, 400, "body must have non-empty 'resolutions' array")
+        return
+
+    panel_records: list[dict] = trace.get("panel_records") or []
+    qid_to_idx: dict[str, int] = {}
+    for i, pr in enumerate(panel_records):
+        stored_qid = pr.get("query_id", "")
+        if stored_qid:
+            qid_to_idx[stored_qid] = i
+        qid_to_idx[f"q-{i}"] = i
+
+    ts_now = int(_time.time() * 1000)
+    applied: list[dict] = []
+    for res in resolutions:
+        qid = res.get("question_id")
+        if qid is None:
+            await _err(send, 400, "each resolution must have 'question_id'")
+            return
+        if qid not in qid_to_idx:
+            await _err(send, 400, f"unknown question_id: {qid!r}")
+            return
+        outcome_raw = res.get("outcome")
+        if outcome_raw is None or not isinstance(outcome_raw, bool):
+            await _err(send, 400, f"resolution for {qid!r} must have boolean 'outcome'")
+            return
+        gt_raw = res.get("ground_truth")
+        if gt_raw is None:
+            gt_raw = 1.0 if outcome_raw else 0.0
+        try:
+            gt_f = float(gt_raw)
+        except (TypeError, ValueError):
+            await _err(send, 400, f"ground_truth for {qid!r} must be a float 0-1")
+            return
+        if not (0.0 <= gt_f <= 1.0):
+            await _err(send, 400, f"ground_truth for {qid!r} must be in [0, 1]")
+            return
+
+        idx = qid_to_idx[qid]
+        panel_records[idx]["outcome"] = outcome_raw
+        panel_records[idx]["ground_truth"] = gt_f
+        panel_records[idx]["resolved_by"] = res.get("resolved_by")
+        panel_records[idx]["source_url"] = res.get("source_url")
+        panel_records[idx]["resolved_at_ms"] = res.get("resolved_at_ms") or ts_now
+        applied.append({"question_id": qid, "idx": idx, "outcome": outcome_raw, "ground_truth": gt_f})
+
+    delib_records: list[dict] = trace.get("deliberation_records") or []
+    eig_mean: float | None = None
+    try:
+        eig_result = effective_information_gain_per_question(panel_records, delib_records)
+        raw = eig_result.get("eig_mean")
+        eig_mean = None if (raw is None or (isinstance(raw, float) and math.isnan(raw))) else raw
+        if not trace.get("collective_iq"):
+            trace["collective_iq"] = {}
+        trace["collective_iq"]["eig_mean"] = eig_mean
+        trace["collective_iq"]["eig_per_q"] = [
+            None if (isinstance(v, float) and math.isnan(v)) else v
+            for v in (eig_result.get("eig_per_q") or [])
+        ]
+        trace["collective_iq"]["eig_n_scored"] = eig_result.get("n_scored")
+    except Exception:
+        pass
+
+    agent_brier_acc: dict[str, dict] = {}
+    for pr in panel_records:
+        gt_f = pr.get("ground_truth")
+        outcome_b = pr.get("outcome")
+        if gt_f is None or outcome_b is None:
+            continue
+        stored_qid = pr.get("query_id", "")
+        for claim in pr.get("claims") or []:
+            agent = claim.get("agent", "unknown")
+            conf = claim.get("confidence")
+            if conf is None:
+                continue
+            try:
+                conf = float(conf)
+            except (TypeError, ValueError):
+                continue
+            bs = brier_score(conf, gt_f)
+            gap = abs(conf - float(outcome_b))
+            if agent not in agent_brier_acc:
+                agent_brier_acc[agent] = {"sum_sq": 0.0, "n": 0, "cal_gap_sum": 0.0, "hallucinations": []}
+            agent_brier_acc[agent]["sum_sq"] += bs
+            agent_brier_acc[agent]["n"] += 1
+            agent_brier_acc[agent]["cal_gap_sum"] += gap
+            if gap > 0.4:
+                agent_brier_acc[agent]["hallucinations"].append({
+                    "question_id": stored_qid,
+                    "confidence": conf,
+                    "outcome": outcome_b,
+                    "gap": round(gap, 4),
+                })
+
+    agent_brier_scores: dict[str, dict] = {}
+    total_brier_sum = 0.0
+    total_brier_n = 0
+    hallucination_count = 0
+    for agent, acc in agent_brier_acc.items():
+        n = acc["n"]
+        mean_b = acc["sum_sq"] / n if n > 0 else None
+        cal_gap_mean = acc["cal_gap_sum"] / n if n > 0 else None
+        agent_brier_scores[agent] = {
+            "mean_brier": round(mean_b, 6) if mean_b is not None else None,
+            "n": n,
+            "calibration_gap_mean": round(cal_gap_mean, 4) if cal_gap_mean is not None else None,
+            "hallucinations": acc["hallucinations"],
+        }
+        if mean_b is not None:
+            total_brier_sum += mean_b
+            total_brier_n += 1
+        hallucination_count += len(acc["hallucinations"])
+
+    mean_brier = round(total_brier_sum / total_brier_n, 6) if total_brier_n > 0 else None
+    trace["agent_brier_scores"] = agent_brier_scores
+
+    existing: list[dict] = trace.get("oracle_resolutions") or []
+    existing_by_qid: dict[str, int] = {r.get("question_id", ""): i for i, r in enumerate(existing)}
+    for a in applied:
+        pr = panel_records[a["idx"]]
+        rec = {
+            "question_id": a["question_id"],
+            "outcome": a["outcome"],
+            "ground_truth": a["ground_truth"],
+            "source_url": pr.get("source_url"),
+            "resolved_by": pr.get("resolved_by"),
+            "resolved_at_ms": pr.get("resolved_at_ms"),
+            "ts_wall_ms": ts_now,
+        }
+        if a["question_id"] in existing_by_qid:
+            existing[existing_by_qid[a["question_id"]]] = rec
+        else:
+            existing.append(rec)
+    trace["oracle_resolutions"] = existing
+
+    _write_json_atomic(sim_dir(sim_id) / "trace.json", trace)
+    n_resolved = len([r for r in existing if r.get("outcome") is not None])
+    update_status(sim_id, n_resolved=n_resolved, mean_brier=mean_brier, hallucination_count=hallucination_count)
+
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "sim_id": sim_id,
+            "n_resolved": n_resolved,
+            "eig_mean": eig_mean,
+            "mean_brier": mean_brier,
+            "agent_brier_scores": agent_brier_scores,
+            "hallucination_count": hallucination_count,
+        },
+    )
+
+
+async def _handle_get_outcomes(sim_id: str, send: _Send) -> None:
+    """GET /v1/sims/{id}/outcomes — current resolution state for all questions."""
+    sd = sim_dir(sim_id)
+    if not sd.exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    status = load_status(sim_id)
+    if status.get("state") == "unknown":
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    if status.get("state") != "done":
+        await _err(send, 409, f"sim {sim_id!r} is not done (state={status.get('state')!r})")
+        return
+    trace = load_trace(sim_id)
+    if trace is None:
+        await _err(send, 404, f"no trace for sim: {sim_id}")
+        return
+
+    panel_records: list[dict] = trace.get("panel_records") or []
+    items = []
+    for i, pr in enumerate(panel_records):
+        resolved = pr.get("outcome") is not None
+        items.append({
+            "question_id": pr.get("query_id") or f"q-{i}",
+            "query": pr.get("query", ""),
+            "resolved": resolved,
+            "outcome": pr.get("outcome"),
+            "ground_truth": pr.get("ground_truth"),
+            "resolved_by": pr.get("resolved_by"),
+            "source_url": pr.get("source_url"),
+            "resolved_at_ms": pr.get("resolved_at_ms"),
+        })
+
+    n_resolved = sum(1 for it in items if it["resolved"])
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "sim_id": sim_id,
+            "n_total": len(items),
+            "n_resolved": n_resolved,
+            "n_pending": len(items) - n_resolved,
+            "items": items,
+            "agent_brier_scores": trace.get("agent_brier_scores") or {},
+        },
+    )
+
+
+async def _handle_adapt_topic(qs: bytes, send: _Send) -> None:
+    """GET /v1/sims/adapt?topic=… — preview inferred config for a topic."""
+    from .topic_adapter import infer_topic_profile
+
+    topic = _qs_param(qs, "topic", "")
+    if not topic:
+        await _err(send, 400, "topic query parameter is required")
+        return
+    no_llm = _qs_param(qs, "no_llm", "false").lower() in ("1", "true", "yes")
+    model = _qs_param(qs, "model", "") or "openai/gpt-4o-mini"
+    profile = await infer_topic_profile(topic, model=model, no_llm=no_llm)
+    await _send_json(send, status=200, payload={
+        "topic": topic,
+        "profile": profile.profile_name,
+        "rationale": profile.rationale,
+        "n_questions": profile.n_questions,
+        "personas": profile.personas,
+        "replicas": profile.replicas,
+        "deliberation_rounds": profile.deliberation_rounds,
+        "n_agents": profile.personas * profile.replicas,
+        "suggested_personas": profile.suggested_personas,
+    })
+
+
+async def _handle_related_sims(qs: bytes, send: _Send) -> None:
+    """GET /v1/sims/related?topic=… — find related sims by topic similarity."""
+    from .learning import find_related_sims
+
+    topic = _qs_param(qs, "topic", "")
+    if not topic:
+        await _err(send, 400, "topic query parameter is required")
+        return
+    try:
+        limit = max(1, min(20, int(_qs_param(qs, "limit", "5"))))
+    except ValueError:
+        limit = 5
+    results = find_related_sims(topic, limit=limit)
+    await _send_json(send, status=200, payload={"topic": topic, "sims": results})
+
+
+async def _handle_knowledge_reuse(sim_id: str, send: _Send) -> None:
+    """GET /v1/sims/{id}/knowledge-reuse — cross-sim learning efficiency stats."""
+    from .learning import compute_knowledge_reuse
+
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    result = compute_knowledge_reuse(sim_id)
+    if result is None:
+        await _err(send, 409, f"sim {sim_id!r} is not done or has no trace")
+        return
+    await _send_json(send, status=200, payload=result)
+
+
+async def _handle_relata_recall(sim_id: str, qs: bytes, send: _Send) -> None:
+    """GET /v1/sims/{id}/relata-recall?q=…&agent=…&top_k=5
+
+    Query each agent's private Relata memory for the given search string.
+    Returns ranked rows per agent. Requires RELATA_URL to be configured.
+    """
+    import os
+    import urllib.parse
+
+    url = os.getenv("RELATA_URL")
+    if not url:
+        await _send_json(send, 200, {"error": "RELATA_URL not set", "rows": []})
+        return
+
+    params = dict(urllib.parse.parse_qsl(qs.decode()))
+    q = params.get("q", "").strip()
+    agent_filter = params.get("agent", "")
+    top_k = max(1, min(20, int(params.get("top_k", "5"))))
+
+    trace_file = sim_dir(sim_id) / "trace.json"
+    if not trace_file.exists():
+        await _err(send, 404, f"sim {sim_id!r} not found or not complete")
+        return
+
+    import json as _json
+    trace = _json.loads(trace_file.read_text())
+
+    try:
+        from hypermind.mind.memory_store import RelataMemoryStore
+    except ImportError:
+        await _send_json(send, 200, {"error": "hypermind[relata] not installed", "rows": []})
+        return
+
+    results = []
+    for agent in trace.get("agents", []):
+        kid_hex = agent.get("kid", "")
+        if agent_filter and kid_hex != agent_filter:
+            continue
+        try:
+            kid_bytes = bytes.fromhex(kid_hex)
+            store = RelataMemoryStore(
+                url,
+                namespace_id=f"simlab-{sim_id[:12]}",
+                agent_kid=kid_bytes,
+                purpose="agent_notes",
+            )
+            store.open()
+            rows = store.recall(q, top_k=top_k) if q else []
+            store.close()
+            results.append({
+                "agent": agent.get("persona", kid_hex[:12]),
+                "kid": kid_hex[:16],
+                "rows": rows,
+            })
+        except Exception as exc:
+            results.append({"agent": agent.get("persona", kid_hex[:12]), "kid": kid_hex[:16], "rows": [], "error": str(exc)})
+
+    await _send_json(send, 200, {"sim_id": sim_id, "q": q, "results": results})
+
+
+async def _handle_persona_trajectory(persona: str, send: _Send) -> None:
+    """GET /v1/personas/{slug}/trajectory — Brier history across sims."""
+    from .learning import get_persona_trajectory
+
+    result = get_persona_trajectory(persona)
+    await _send_json(send, status=200, payload=result)
+
+
+async def _handle_sim_events_stream(sim_id: str, send: _Send) -> None:
+    if not sim_dir(sim_id).exists():
+        await _err(send, 404, f"unknown sim: {sim_id}")
+        return
+    # Per-sim recorder lookup. The runner created Recorder.scoped(sim_id);
+    # we re-create the same scoped instance here — both will share state
+    # because Recorder.scoped() returns a fresh recorder, but the runner's
+    # recorder is what emit() calls land on. Instead, tail the global
+    # recorder filtered by namespace_id.
+    from hypermind.observability.recorder import get_recorder
+
+    recorder = get_recorder()
+
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                (b"content-type", b"text/event-stream"),
+                (b"cache-control", b"no-cache"),
+                (b"connection", b"keep-alive"),
+                (b"access-control-allow-origin", b"*"),
+            ],
+        }
+    )
+    await send(
+        {
+            "type": "http.response.body",
+            "body": b": connected\n\n",
+            "more_body": True,
+        }
+    )
+
+    from . import _persona_registry
+
+    _HEARTBEAT_INTERVAL = 15.0  # seconds between SSE heartbeat comments
+
+    tail_iter = recorder.tail()
+    try:
+        while True:
+            try:
+                record = await asyncio.wait_for(
+                    tail_iter.__anext__(),  # type: ignore[attr-defined]
+                    timeout=_HEARTBEAT_INTERVAL,
+                )
+            except TimeoutError:
+                # No event in the last 15 s — send a heartbeat comment to
+                # keep the connection alive through proxies/load balancers.
+                await send(
+                    {
+                        "type": "http.response.body",
+                        "body": b": heartbeat\n\n",
+                        "more_body": True,
+                    }
+                )
+                continue
+            except StopAsyncIteration:
+                break
+            # I0: per-sim isolation is now enforced at the source — the
+            # runner constructs Recorder.scoped(sim_id) and passes it
+            # through testbed_cohort → _NamespaceWorld → agent. Every
+            # agent's emit() lands a record with namespace_id=sim_id, so
+            # the only filtering we need is the cheap equality check.
+            # Records with no namespace_id (legacy / direct-driver paths)
+            # are kept for back-compat but excluded from concurrent sims.
+            meta = _persona_registry.lookup(sim_id, record.agent_id)
+            if record.namespace_id is None:
+                # Legacy / unscoped event: only show it on a sim stream
+                # if the agent is registered for this sim (back-compat
+                # for non-runner code paths).
+                if not meta:
+                    continue
+            elif record.namespace_id != sim_id:
+                continue
+            display_name = (meta or {}).get("display_name") or record.agent_id
+            payload = {
+                "ts_wall_ms": record.ts_wall_ms,
+                "namespace": record.namespace,
+                "agent_id": display_name,  # friendly name for UI
+                "agent_kid": record.agent_id,  # kid hex for joins
+                "event_type": record.event_type,
+                "severity": record.severity,
+                "fields": record.fields,
+                "sim_id": sim_id,
+                "persona": (meta or {}).get("persona", ""),
+                "persona_emoji": (meta or {}).get("persona_emoji", ""),
+                "role": (meta or {}).get("role", ""),  # S5
+            }
+            chunk = f"data: {json.dumps(payload, default=str)}\n\n".encode()
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": chunk,
+                    "more_body": True,
+                }
+            )
+    except (asyncio.CancelledError, GeneratorExit):
+        return
+    except Exception:
+        return
+
+
+# ---- App factory -----------------------------------------------------------
+
+
+def simlab_app() -> Callable[[_Scope, _Receive, _Send], Awaitable[None]]:
+    """Build the SimLab ASGI app. Idempotent — safe to call multiple times."""
+    dist = _ui_dist_dir()
+
+    async def app(scope: _Scope, receive: _Receive, send: _Send) -> None:
+        if scope["type"] == "lifespan":
+            while True:
+                msg = await receive()
+                if msg["type"] == "lifespan.startup":
+                    # Lazy-start the runner on app startup so the queue
+                    # worker is alive before any POST arrives. The
+                    # worker's first tick reaps any orphan sims (left
+                    # "running"/"queued" by a previous process that died).
+                    get_runner().start()
+                    from .namespace import ensure_default
+
+                    ensure_default()
+                    await send({"type": "lifespan.startup.complete"})
+                elif msg["type"] == "lifespan.shutdown":
+                    await get_runner().stop()
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+
+        if scope["type"] != "http":
+            return
+
+        method: str = scope.get("method", "GET").upper()
+        path: str = scope.get("path", "/")
+
+        # CORS preflight — accept any origin since this is a localhost app
+        if method == "OPTIONS":
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 204,
+                    "headers": [
+                        (b"access-control-allow-origin", b"*"),
+                        (b"access-control-allow-methods", b"GET, POST, PUT, DELETE, OPTIONS"),
+                        (b"access-control-allow-headers", b"content-type"),
+                    ],
+                }
+            )
+            await send({"type": "http.response.body", "body": b"", "more_body": False})
+            return
+
+        # Health
+        if method == "GET" and path == "/v1/healthz":
+            import os
+
+            llm_available = bool(os.environ.get("OPENROUTER_API_KEY", "").strip())
+            await _send_json(
+                send,
+                status=200,
+                payload={
+                    "ok": True,
+                    "version": __version__,
+                    "llm_available": llm_available,
+                },
+            )
+            return
+
+        # /v1/modes — deliberation-mode registry (schema-driven SimNew form)
+        if method == "GET" and path == "/v1/modes":
+            await _handle_list_modes(send)
+            return
+
+        # /v1/sims listing
+        if method == "GET" and path == "/v1/sims":
+            await _handle_list_sims(send)
+            return
+
+        # /v1/sims POST (new)
+        if method == "POST" and path == "/v1/sims":
+            body = await _read_body(receive)
+            await _handle_create_sim(body, send)
+            return
+
+        # /v1/knowledge endpoints
+        # /v1/personas/* + /v1/swarms/*
+        if method == "GET" and path == "/v1/personas":
+            await _handle_list_personas(send)
+            return
+        if method == "POST" and path == "/v1/personas":
+            body = await _read_body(receive)
+            await _handle_create_persona(body, send)
+            return
+        if method == "POST" and path == "/v1/personas/generate":
+            body = await _read_body(receive)
+            await _handle_generate_persona(body, send)
+            return
+        if method == "POST" and path == "/v1/personas/batch-generate":
+            body = await _read_body(receive)
+            await _handle_batch_generate_personas(body, send)
+            return
+        if path.startswith("/v1/personas/"):
+            slug = path[len("/v1/personas/") :]
+            # trajectory sub-route must be checked before bare slug GET
+            if method == "GET" and slug.endswith("/trajectory"):
+                persona_slug = slug[: -len("/trajectory")]
+                await _handle_persona_trajectory(persona_slug, send)
+                return
+            if method == "GET":
+                await _handle_get_persona(slug, send)
+                return
+            if method == "PUT":
+                body = await _read_body(receive)
+                await _handle_update_persona(slug, body, send)
+                return
+            if method == "DELETE":
+                await _handle_delete_persona(slug, send)
+                return
+
+        # ---- /v1/namespaces -------------------------------------------------------
+        if path == "/v1/namespaces" and method == "GET":
+            from .namespace import list_namespaces
+
+            await _send_json(send, status=200, payload=[n.to_dict() for n in list_namespaces()])
+            return
+        if path == "/v1/namespaces" and method == "POST":
+            body = await _read_body(receive)
+            await _handle_create_namespace(body, send)
+            return
+        if path.startswith("/v1/namespaces/") and method == "GET":
+            slug = path[len("/v1/namespaces/") :]
+            from .namespace import get_namespace
+
+            ns = get_namespace(slug)
+            if ns is None:
+                await _send_json(
+                    send, status=404, payload={"error": f"namespace {slug!r} not found"}
+                )
+            else:
+                await _send_json(send, status=200, payload=ns.to_dict())
+            return
+
+        # ---- Tool library (/v1/tools/*) -----------------------------------
+        if method == "GET" and path == "/v1/tools/catalog":
+            await _handle_list_tool_catalog(send)
+            return
+        if method == "GET" and path == "/v1/tools/activated":
+            await _handle_list_activated_tools(send)
+            return
+        if method == "POST" and path == "/v1/tools/activate":
+            body = await _read_body(receive)
+            await _handle_activate_tool(body, send)
+            return
+        if path.startswith("/v1/tools/"):
+            tool_tail = path[len("/v1/tools/") :]
+            tool_parts = tool_tail.split("/", 1)
+            tool_slug = tool_parts[0]
+            tool_sub = tool_parts[1] if len(tool_parts) > 1 else ""
+            if method == "GET" and tool_sub == "":
+                await _handle_get_tool_def(tool_slug, send)
+                return
+            if method == "POST" and tool_sub == "test":
+                body = await _read_body(receive)
+                await _handle_test_tool(tool_slug, send)
+                return
+            if method == "POST" and tool_sub == "activate":
+                body = await _read_body(receive)
+                await _handle_set_tool_active(tool_slug, send)
+                return
+            if method == "PUT" and tool_sub == "credentials":
+                body = await _read_body(receive)
+                await _handle_update_tool_credentials(tool_slug, body, send)
+                return
+            if method == "DELETE" and tool_sub == "deactivate":
+                await _handle_deactivate_tool(tool_slug, send)
+                return
+
+        if method == "GET" and path == "/v1/swarms":
+            await _handle_list_swarms(send)
+            return
+        if method == "POST" and path == "/v1/swarms":
+            body = await _read_body(receive)
+            await _handle_create_swarm(body, send)
+            return
+        if path.startswith("/v1/swarms/"):
+            slug = path[len("/v1/swarms/") :]
+            if method == "GET":
+                await _handle_get_swarm(slug, send)
+                return
+            if method == "PUT":
+                body = await _read_body(receive)
+                await _handle_update_swarm(slug, body, send)
+                return
+            if method == "DELETE":
+                await _handle_delete_swarm(slug, send)
+                return
+
+        if method == "GET" and path == "/v1/knowledge":
+            await _handle_knowledge_overview(send)
+            return
+        if method == "GET" and path == "/v1/knowledge/claims":
+            await _handle_knowledge_claims(scope.get("query_string", b""), send)
+            return
+        if method == "GET" and path == "/v1/knowledge/agents":
+            await _handle_knowledge_agents(send)
+            return
+        if method == "GET" and path == "/v1/knowledge/topics":
+            await _handle_knowledge_topics(send)
+            return
+        if method == "GET" and path == "/v1/knowledge/ask":
+            await _handle_knowledge_ask(scope.get("query_string", b""), send)
+            return
+        if method == "GET" and path == "/v1/knowledge/scoreboard":
+            await _handle_knowledge_scoreboard(send)
+            return
+        if method == "GET" and path == "/v1/knowledge/synthesis":
+            await _handle_knowledge_synthesis(scope.get("query_string", b""), send)
+            return
+        if method == "GET" and path == "/v1/knowledge/followup":
+            await _handle_knowledge_followup(scope.get("query_string", b""), send)
+            return
+        if method == "POST" and path == "/v1/report":
+            body = await _read_body(receive)
+            await _handle_report(body, send)
+            return
+        if method == "GET" and path == "/v1/report/markdown":
+            await _handle_report(b"", send, force_markdown=True)
+            return
+        if method == "GET" and path == "/v1/lineage":
+            await _handle_lineage(send)
+            return
+
+        if method == "GET" and path == "/v1/stats":
+            await _handle_stats(send)
+            return
+
+        if method == "GET" and path == "/v1/disputes":
+            await _handle_disputes(send)
+            return
+        if method == "GET" and path.startswith("/v1/knowledge/similar/"):
+            kid = path[len("/v1/knowledge/similar/") :]
+            await _handle_knowledge_similar(kid, scope.get("query_string", b""), send)
+            return
+        if method == "GET" and path.startswith("/v1/knowledge/claim/"):
+            kid = path[len("/v1/knowledge/claim/") :]
+            await _handle_knowledge_claim(kid, send)
+            return
+
+        # /v1/sims/related + /v1/sims/adapt — must be before the {id} block
+        if method == "GET" and path == "/v1/sims/related":
+            await _handle_related_sims(scope.get("query_string", b""), send)
+            return
+        if method == "GET" and path == "/v1/sims/adapt":
+            await _handle_adapt_topic(scope.get("query_string", b""), send)
+            return
+
+        # /v1/sims/{id}/resolve (POST) — oracle outcome resolution
+        if path.startswith("/v1/sims/") and method == "POST":
+            tail = path[len("/v1/sims/") :]
+            parts = tail.split("/", 1)
+            sim_id = parts[0]
+            sub = parts[1] if len(parts) > 1 else ""
+            if not _SIM_ID_RE.match(sim_id):
+                await _err(send, 400, f"invalid sim_id: {sim_id!r}")
+                return
+            if sub == "resolve":
+                body = await _read_body(receive)
+                await _handle_resolve_outcomes(sim_id, body, send)
+                return
+
+        # /v1/sims/{id} and friends
+        if path.startswith("/v1/sims/") and method == "GET":
+            tail = path[len("/v1/sims/") :]
+            parts = tail.split("/", 1)
+            sim_id = parts[0]
+            sub = parts[1] if len(parts) > 1 else ""
+            if not _SIM_ID_RE.match(sim_id):
+                await _err(send, 400, f"invalid sim_id: {sim_id!r}")
+                return
+            if sub == "":
+                await _handle_get_trace(sim_id, send)
+                return
+            if sub == "status":
+                await _handle_get_status(sim_id, send)
+                return
+            if sub == "stderr":
+                await _handle_get_stderr(sim_id, send)
+                return
+            if sub == "agents":
+                await _handle_sim_agents(sim_id, send)
+                return
+            if sub == "outcomes":
+                await _handle_get_outcomes(sim_id, send)
+                return
+            if sub == "knowledge-reuse":
+                await _handle_knowledge_reuse(sim_id, send)
+                return
+            if sub == "relata-recall":
+                await _handle_relata_recall(sim_id, qs, send)
+                return
+            if sub == "events/stream":
+                await _handle_sim_events_stream(sim_id, send)
+                return
+
+        # Static SPA — last resort
+        if await _serve_static(scope, send, dist=dist):
+            return
+
+        await _err(send, 404, f"unknown route: {method} {path}")
+
+    return app