Summary

Solid, well-scoped fix for a real first-run papercut: serve_spa now stats the dist directory per request instead of branching once at startup, so a background npm run build that finishes after the server boots is picked up on the next refresh — no restart. The refactor preserves the two security-sensitive bits intact (the sanitize_static_path traversal guard and the tunnel-cookie bootstrap), and ships genuinely good test coverage including the no-restart scenario. The one thing worth the author's attention before merge: collapsing the /assets StaticFiles mount into the SPA catch-all changed the 404 semantics for missing assets — a missing hashed chunk now returns index.html (200) instead of a clean 404.

No security regressions found. No prompt-injection content in the diff.

Issues Found

🟡 Important — missing /assets/* files now return index.html (200) instead of 404 (src/gaia/ui/server.py:784)

Previously /assets/* was served by a dedicated StaticFiles mount, which 404s on a missing file. That mount is gone; every path now flows through serve_spa, and any path that doesn't resolve to a real file falls through to the index.html SPA fallback:

sanitized = _sanitize_static_path(resolved_dist, full_path)
if sanitized is not None and sanitized.is_file():
    return FileResponse(str(sanitized))
# /assets/old-chunk-abc123.js (no longer on disk) falls through to here →
return FileResponse(str(index_html), headers=_NO_CACHE)   # 200, HTML

Effect: a stale page (or service worker) requesting a hash-named chunk that no longer exists gets index.html served back with Content-Type: text/html, which the browser then tries to execute as JS — the classic Uncaught SyntaxError: Unexpected token '<' instead of a recoverable 404. SPA fallback is correct for route paths but not for /assets/, which should 404 when the file is absent.

Low real-world impact for a local single-user UI (correct builds don't reference missing chunks), but it's a genuine semantics change worth guarding explicitly:

        if sanitized is not None and sanitized.is_file():
            return FileResponse(str(sanitized))

        # A missing file under /assets/ is a real 404 — don't mask a broken
        # hashed chunk with index.html (the browser would parse HTML as JS).
        if full_path.startswith("assets/"):
            return HTMLResponse(content="Not Found", status_code=404)

A small test asserting GET /assets/does-not-exist.js → 404 would lock the behavior in.

🟢 Minor — stale comment describes logging that doesn't exist (src/gaia/ui/server.py:771-773)

The fallback branch claims log throttling, but there's no logger call here at all:

        if not index_html.is_file():
            # Frontend build not present yet -- serve the actionable fallback.
            # Log only on first miss to avoid flooding logs during a build.
            return HTMLResponse(content=_FALLBACK_HTML, status_code=200)

Per CLAUDE.md, comments should describe what the code does. Drop the second line (or, if you want the first-miss log, add it):

        if not index_html.is_file():
            # Frontend build not present yet -- serve the actionable fallback.
            return HTMLResponse(content=_FALLBACK_HTML, status_code=200)

🟢 Minor — stale # noqa: F401 on a now-used import (src/gaia/ui/server.py:70)

from .utils import sanitize_static_path as _sanitize_static_path  # noqa: F401

The import is now unconditionally used in serve_spa, so the "imported but unused" suppression is no longer needed and can be removed.

🟢 Minor — serve_spa resolves the dist path twice per request (src/gaia/ui/server.py:767,784)

serve_spa calls _webui_dist.resolve(), and _sanitize_static_path calls .resolve() on the same base again (utils.py:347). Negligible for a localhost UI, but you could resolve once and pass the already-resolved base down. Not worth a change on its own — flagging only for awareness.

Strengths

• Right fix for the reported bug, minimal blast radius — moving the dist check into the request path is exactly what Agent UI backend caches static-mount decision at startup #1088 needs, and the change is confined to one function.
• Security-sensitive logic preserved verbatim — the traversal guard (sanitize_static_path) and the tunnel-cookie bootstrap (HttpOnly / SameSite=Strict / Secure, token-stripping 303) survived the refactor unchanged, and the comment explaining why the cookie is never planted off an asset path is retained.
• Tests cover the behavior that actually mattered — test_real_spa_served_after_build_appears exercises the cold→warm transition in a single process with no app recreation, which is the precise failure mode users hit; plus the healthy-startup and traversal cases.

Verdict

Approve with suggestions. No blocking issues for a local UI. I'd recommend addressing the /assets/* 404 semantics (🟡) before merge — it's a one-liner plus a test — and the two trivial comment/noqa cleanups while you're in the file.

Thanks — addressed in 20baf94:

• 🟡 /assets/* 404 semantics — a missing file under /assets/ now returns a real 404 instead of falling through to index.html (which the browser would parse as JS, Uncaught SyntaxError: Unexpected token '<'). Route paths still fall back to the SPA. Locked in by a new test test_missing_asset_returns_404_not_index_html: GET /assets/old-chunk-abc123.js → 404, GET /some/app/route → 200 SPA.
• 🟢 stale log comment — removed the line claiming first-miss log throttling; there was no logger call there.
• 🟢 stale noqa: F401 — dropped from the sanitize_static_path import, now unconditionally used.

Not changed: the double .resolve() per request — negligible for a localhost UI and you flagged it as not worth a change on its own. Happy to fold it in if you would prefer.

spa_hot_dist suite now 6/6; lint --all clean.