feat(phase-3): web UI served same-origin by the API

Add a no-build, same-origin web frontend so an operator can open a URL,
see every agent's state, and answer a paused question with no terminal
(Phase 3 DoD). The UI is a client of the existing API — no endpoint,
schema, or auth change — so the 106 existing tests pass unchanged.

- app.py serves the bundled UI from / and /static, gated on UI_ENABLED
  (default on); optional CORS_ORIGINS (default empty => no middleware)
  for hosting the UI on a separate origin. Dedicated /static prefix +
  explicit / route so API routes are never shadowed. Zero new runtime
  deps (StaticFiles/CORSMiddleware ship with Starlette).
- static/: vanilla fetch + plain CSS + vendored alpine.min.js (v3.14.8,
  no CDN). Token captured once into localStorage; all API values render
  via x-text (never x-html) to block agent-authored markup injection.
  Project switcher, agent list, checkmark panel, paginated log, shared
  feed, and Answer / Answer & Resume. Polling scoped to the selected
  agent to avoid an N+1 over the fleet.
- config.py: ui_enabled, cors_origins (+ cors_origin_list); documented
  in .env.example.
- tests/test_api_ui.py: serving, unauthenticated shell, non-shadowing
  401 regression, CORS toggle, UI_ENABLED=false. 114 tests, ruff clean.

The static assets ship in the wheel by default (they live inside the
packaged src/handler tree) — no force-include needed.

tests/test_api_ui.py

@@ -0,0 +1,99 @@
+"""Phase 3 UI serving: the bundled web UI is served same-origin and, critically, is
+*additive* — it must not shadow any existing API route, and both the toggle (UI_ENABLED)
+and the optional CORS behave as documented. The frontend JS itself has no test runner
+(by design) and is verified via the manual e2e walkthrough in docs/PLAN.md.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+def _reset_caches() -> None:
+    from handler import config
+    from handler.db import engine
+
+    config.get_settings.cache_clear()
+    engine.get_engine.cache_clear()
+
+
+def _fresh_client(monkeypatch, **overrides) -> TestClient:
+    """Build an app after applying env overrides — the shared `client` fixture bakes in
+    defaults, so toggle tests need their own app constructed post-setenv."""
+    for key, value in overrides.items():
+        monkeypatch.setenv(key, value)
+    _reset_caches()
+    from handler.api.app import create_app
+
+    return TestClient(create_app())
+
+
+# --- shell + assets are served, unauthenticated -------------------------------------
+
+
+def test_index_served_unauthenticated(client):
+    res = client.get("/")  # no Authorization header
+    assert res.status_code == 200
+    assert res.headers["content-type"].startswith("text/html")
+    assert "<title>Handler" in res.text
+    # the shell must never inline data or a token
+    assert "Bearer" not in res.text
+
+
+@pytest.mark.parametrize(
+    "path, marker",
+    [
+        ("/static/app.js", "function app("),
+        ("/static/styles.css", ".badge"),
+        ("/static/alpine.min.js", "Alpine.js"),
+    ],
+)
+def test_static_assets_served_unauthenticated(client, path, marker):
+    res = client.get(path)  # no auth
+    assert res.status_code == 200
+    assert marker in res.text
+
+
+# --- the static surface must NOT shadow the API ------------------------------------
+
+
+def test_api_routes_not_shadowed(client, auth):
+    # /health still open
+    assert client.get("/health").json() == {"status": "ok"}
+    # /projects still requires auth (the static mount didn't swallow it)
+    assert client.get("/projects").status_code == 401
+    res = client.get("/projects", headers=auth)
+    assert res.status_code == 200
+    assert res.json() == []
+    # "/" is an explicit route, not a catch-all: unknown paths still 404
+    assert client.get("/does-not-exist").status_code == 404
+
+
+# --- CORS: off by default, on when configured --------------------------------------
+
+
+def test_cors_absent_by_default(client):
+    res = client.get("/health", headers={"Origin": "https://example.com"})
+    assert res.status_code == 200
+    assert "access-control-allow-origin" not in {k.lower() for k in res.headers}
+
+
+def test_cors_present_when_configured(env, monkeypatch):
+    origin = "https://handler.example.ts.net"
+    client = _fresh_client(monkeypatch, CORS_ORIGINS=origin)
+    res = client.get("/health", headers={"Origin": origin})
+    assert res.status_code == 200
+    assert res.headers.get("access-control-allow-origin") == origin
+
+
+# --- UI_ENABLED=false => headless, API intact --------------------------------------
+
+
+def test_ui_disabled_serves_no_shell_but_api_works(env, monkeypatch, auth):
+    client = _fresh_client(monkeypatch, UI_ENABLED="false")
+    assert client.get("/").status_code == 404
+    assert client.get("/static/app.js").status_code == 404
+    # API is untouched
+    assert client.get("/health").status_code == 200
+    assert client.get("/projects", headers=auth).status_code == 200