From fd9ac96566ebec8177cd9954ad6f530fff2a21c9 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Sun, 23 Aug 2026 22:18:17 +0200
Subject: [PATCH 1/2] fix(serve,ui): keep the UI session alive across server
 restarts

Live-observed during the PR #665 UI audit: after a kbagent serve --ui
restart (new bearer token), a browser reload could serve the cached
index.html without contacting the server. No request means no fresh
Set-Cookie, so the stale kbagent_session cookie 401'd every /api/* call
and the SPA silently rendered empty lists with no visible error.

Two complementary layers:

- Server: GET / and GET /index.html now answer Cache-Control: no-cache,
  so the browser revalidates the shell on every load -- and since the
  bootstrap route implements no conditional handling, revalidation is
  always a full 200 that re-sets the session cookie. Scoped to the shell
  only; hashed build assets keep their default caching.
- SPA: the API client treats a 401 as a possibly-stale cookie. It
  re-fetches the shell once with cache: 'reload' (single-flight across
  concurrent 401s), retries the request, and only if the retry still
  401s dispatches kbagent:session-expired -- rendered by a new
  SessionExpiredBanner in the shell instead of failing silently. For
  SESSION_EXPIRED / SESSION_NOT_FOUND the banner carries the server
  message, which names the on-host 'kbagent auth login' remedy.

Also corrects the _install_ui docstrings: Starlette's html=True
not-found fallback serves 404.html (absent from a Vite build), not
index.html -- the SPA is hash-routed, so every shell load goes through
GET /.

Verified live: restarted serve --ui with a new token; the deployed
client healed a 401 via GET / re-bootstrap and retried to 200 without
a manual reload.
---
 docs/web-server.md                            |  23 +++
 src/keboola_agent_cli/server/app.py           |  36 +++--
 tests/test_serve_ui.py                        |  33 ++++
 web/frontend/src/api/client.test.ts           | 151 ++++++++++++++++++
 web/frontend/src/api/client.ts                |  54 +++++++
 .../src/components/SessionExpiredBanner.tsx   |  62 +++++++
 web/frontend/src/layout/Shell.tsx             |   3 +
 7 files changed, 352 insertions(+), 10 deletions(-)
 create mode 100644 web/frontend/src/api/client.test.ts
 create mode 100644 web/frontend/src/components/SessionExpiredBanner.tsx

diff --git a/docs/web-server.md b/docs/web-server.md
index 33bb5b4d..50af7115 100644
--- a/docs/web-server.md
+++ b/docs/web-server.md
@@ -315,6 +315,29 @@ stdout, and refuses any request that does not present it as
 `Authorization: Bearer <token>`. Public paths: `/health/ping`,
 `/health/auth-info`, `/openapi.json`, `/docs`, `/redoc`.
 
+### Session cookie in single-process UI mode
+
+With `kbagent serve --ui`, the browser never sees the bearer token:
+`GET /` (and `GET /index.html`) answers the SPA shell with a
+`Set-Cookie: kbagent_session=<token>; HttpOnly; SameSite=Strict; Path=/`
+session cookie, and the auth middleware accepts that cookie whenever no
+`Authorization` header is present. Scripted callers keep using the header.
+
+Two layers keep that cookie from going stale across server restarts
+*(since vNEXT)* — previously a restart (new token) could leave a tab that
+reloaded from the browser cache silently 401-ing on every API call, with
+each list rendering as empty:
+
+- The shell is served with `Cache-Control: no-cache`, so a reload always
+  revalidates against the server — and the bootstrap route always answers
+  a full `200` with a fresh `Set-Cookie`.
+- The SPA's API client treats a `401` as "cookie may be stale": it
+  re-fetches `/` once with `cache: "reload"` (bypassing every cache
+  layer), retries the request, and only if the retry still answers `401`
+  shows a visible **Session expired** banner (for `SESSION_EXPIRED` /
+  `SESSION_NOT_FOUND` the banner carries the server message, which names
+  the on-host `kbagent auth login` remedy).
+
 ### What's-new popup *(since vNEXT)*
 
 The web UI shows a curated per-version highlights modal on load, once per
diff --git a/src/keboola_agent_cli/server/app.py b/src/keboola_agent_cli/server/app.py
index f6b92e74..5f5b872d 100644
--- a/src/keboola_agent_cli/server/app.py
+++ b/src/keboola_agent_cli/server/app.py
@@ -747,19 +747,26 @@ def _install_ui(app: FastAPI, *, ui_dist: str, token: str) -> None:
        (auth doesn't care about path, but PUBLIC_PATHS exact-matches do).
     2) **Cookie-setting** ``GET /`` and ``GET /index.html``: read the built
        ``index.html``, return it with a ``Set-Cookie: kbagent_session=<token>;
-       HttpOnly; SameSite=Strict; Path=/`` header. Public (no auth) so the
-       SPA can bootstrap. The browser then attaches the cookie to every
-       same-origin REST + SSE request automatically. The token is HttpOnly
-       (no JS access -- XSS-resistant), SameSite=Strict (no cross-origin
-       sends -- CSRF-resistant), and lives only for the browser session.
+       HttpOnly; SameSite=Strict; Path=/`` header and ``Cache-Control:
+       no-cache`` (revalidate-always -- a cached shell served without a
+       request would keep a stale cookie alive across server restarts).
+       Public (no auth) so the SPA can bootstrap. The browser then attaches
+       the cookie to every same-origin REST + SSE request automatically. The
+       token is HttpOnly (no JS access -- XSS-resistant), SameSite=Strict
+       (no cross-origin sends -- CSRF-resistant), and lives only for the
+       browser session.
 
        This replaces the older "inject ``window.__KBAGENT_TOKEN`` into a
        ``<script>`` tag" approach. The injected token landed in the JS heap
        (XSS-readable) and the EventSource fallback (``?_kbagent_token=...``
        query param) put it into uvicorn's access log -- both attack surfaces
        are gone with the cookie-only design.
-    3) **StaticFiles mount at ``/``** with ``html=True`` so missing paths fall
-       through to ``index.html`` for SPA client-side routing.
+    3) **StaticFiles mount at ``/``** serving the built assets. The SPA is
+       hash-routed (deep links are ``/#/jobs/...``), so every shell load goes
+       through the ``GET /`` route above; the mount only ever serves real
+       files. (``html=True`` is kept for directory-index behavior -- note
+       Starlette's not-found fallback serves ``404.html``, which a Vite build
+       does not emit, so unknown non-API paths answer 404, not the shell.)
 
     The mount is appended *after* all API routers, so any registered route
     (``/projects``, ``/configs``, ``/agents``, ...) wins over a hypothetical
@@ -811,6 +818,15 @@ async def dispatch(self, request, call_next):  # type: ignore[override]
     async def _serve_ui_index() -> HTMLResponse:
         html = (dist / "index.html").read_text(encoding="utf-8")
         response = HTMLResponse(html)
+        # The shell is the cookie-delivery vehicle, so a browser must never
+        # satisfy a reload from its cache without asking the server: after a
+        # `kbagent serve` restart (new bearer token) a heuristically-cached
+        # index.html boots the SPA with the stale cookie and every /api/*
+        # call answers 401 with nothing visibly wrong. `no-cache` means
+        # "store, but revalidate every time" -- and since this route
+        # implements no conditional-request handling, revalidation is always
+        # a full 200 that re-sets the cookie below.
+        response.headers["Cache-Control"] = "no-cache"
         # Browser session cookie: HttpOnly + SameSite=Strict + Path=/. No
         # ``Secure`` flag because kbagent serve defaults to plain http on
         # 127.0.0.1; setting Secure would prevent the cookie from ever being
@@ -828,9 +844,9 @@ async def _serve_ui_index() -> HTMLResponse:
         )
         return response
 
-    # SPA fallback + assets. ``html=True`` makes StaticFiles serve index.html
-    # for unknown paths (so /workspaces, /jobs, etc. client-side routes work
-    # on direct navigation). The auth middleware will still gate API calls;
+    # Assets + directory-index. The SPA is hash-routed, so client-side
+    # routes never reach this mount as paths -- it serves the built files
+    # only. The auth middleware will still gate API calls;
     # static files are served before it sees them only because StaticFiles
     # is the LAST mount and middleware runs on the unified scope -- so we
     # widen PUBLIC_PATHS via prefix logic in the auth middleware itself.
diff --git a/tests/test_serve_ui.py b/tests/test_serve_ui.py
index fde34c7d..defd3c4e 100644
--- a/tests/test_serve_ui.py
+++ b/tests/test_serve_ui.py
@@ -89,6 +89,39 @@ def test_assets_served_unauthenticated(self, tmp_path: Path, ui_dist: Path) -> N
         assert "console.log" in resp.text
 
 
+class TestUiShellCaching:
+    """The SPA shell must never be trusted to a browser cache without revalidation.
+
+    Live-observed during the PR #665 UI audit: after a ``kbagent serve --ui``
+    restart (new bearer token), a browser reload served the *cached*
+    ``index.html`` without contacting the server. No request means no fresh
+    ``Set-Cookie``, so the stale session cookie 401'd every ``/api/*`` call
+    and the SPA silently rendered empty lists. ``Cache-Control: no-cache``
+    forces the browser to revalidate the shell on every load -- and because
+    the bootstrap route always answers a full 200 (it implements no
+    conditional-request handling), every revalidation re-sets the cookie.
+    """
+
+    def test_shell_responses_always_revalidate(self, tmp_path: Path, ui_dist: Path) -> None:
+        client = _make_client(tmp_path, ui_dist=ui_dist)
+        for path in ("/", "/index.html"):
+            resp = client.get(path)
+            assert resp.status_code == 200, path
+            assert resp.headers.get("cache-control") == "no-cache", (
+                f"GET {path} must answer 'Cache-Control: no-cache' so a browser "
+                "revalidates the shell (and picks up a fresh session cookie) "
+                "after a server restart"
+            )
+
+    def test_assets_keep_default_caching(self, tmp_path: Path, ui_dist: Path) -> None:
+        # Build assets are content-hashed by Vite (a new build means new
+        # URLs), so the no-cache stamp is scoped to the shell only.
+        client = _make_client(tmp_path, ui_dist=ui_dist)
+        resp = client.get("/assets/main.js")
+        assert resp.status_code == 200
+        assert resp.headers.get("cache-control") != "no-cache"
+
+
 class TestApiAlias:
     def test_api_prefix_routes_to_bare_endpoint(self, tmp_path: Path, ui_dist: Path) -> None:
         client = _make_client(tmp_path, ui_dist=ui_dist, token="t")
diff --git a/web/frontend/src/api/client.test.ts b/web/frontend/src/api/client.test.ts
new file mode 100644
index 00000000..1e133067
--- /dev/null
+++ b/web/frontend/src/api/client.test.ts
@@ -0,0 +1,151 @@
+/**
+ * Tests for the 401 self-heal path in the API client.
+ *
+ * In single-process UI mode (`kbagent serve --ui`) auth rides on the
+ * HttpOnly `kbagent_session` cookie set by `GET /`. After a server restart
+ * the cookie is stale, every API call answers 401, and -- before this fix --
+ * the SPA silently rendered empty lists. The client now re-fetches the shell
+ * once (`cache: "reload"` so no browser cache can swallow the request, which
+ * is exactly how the bug happened in the first place), retries the request,
+ * and only then surfaces a visible "session expired" signal.
+ *
+ * Runs in the default vitest node environment: `window` is stubbed with a
+ * real EventTarget so `dispatchEvent`/`addEventListener` behave like the
+ * browser's, and `fetch` is a vi.fn() -- no jsdom dependency needed.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { api, ApiError, SESSION_EXPIRED_EVENT } from "./client";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function unauthorized(message = "Invalid Bearer token."): Response {
+  return jsonResponse(401, {
+    status: "error",
+    error: { code: "UNAUTHORIZED", message },
+  });
+}
+
+function shellResponse(): Response {
+  return new Response("<!doctype html>", {
+    status: 200,
+    headers: { "content-type": "text/html" },
+  });
+}
+
+/** URL of a fetch call, whether invoked with a string or a Request. */
+function calledUrl(input: unknown): string {
+  return typeof input === "string" ? input : (input as Request).url;
+}
+
+beforeEach(() => {
+  const fakeWindow = new EventTarget() as unknown as Window & typeof globalThis;
+  (fakeWindow as unknown as { location: { origin: string } }).location = {
+    origin: "http://127.0.0.1:8001",
+  };
+  vi.stubGlobal("window", fakeWindow);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("request 401 retry", () => {
+  it("re-bootstraps the session cookie and retries once after a 401", async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(unauthorized()) // GET /api/projects -> stale cookie
+      .mockResolvedValueOnce(shellResponse()) // GET / -> fresh Set-Cookie
+      .mockResolvedValueOnce(jsonResponse(200, { projects: [] })); // retry
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(api.get("/projects")).resolves.toEqual({ projects: [] });
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    const [shellUrl, shellInit] = fetchMock.mock.calls[1];
+    expect(calledUrl(shellUrl)).toBe("/");
+    // cache: "reload" is the load-bearing part -- a plain fetch("/") could be
+    // answered from the very browser cache that made the cookie go stale.
+    expect(shellInit).toMatchObject({ cache: "reload", credentials: "include" });
+  });
+
+  it("dispatches a session-expired event when the retry still 401s", async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(unauthorized())
+      .mockResolvedValueOnce(shellResponse())
+      .mockResolvedValueOnce(unauthorized("Invalid Bearer token."));
+    vi.stubGlobal("fetch", fetchMock);
+    const events: CustomEvent[] = [];
+    window.addEventListener(SESSION_EXPIRED_EVENT, (evt) => {
+      events.push(evt as CustomEvent);
+    });
+
+    await expect(api.get("/projects")).rejects.toMatchObject({ status: 401 });
+
+    // Exactly one retry -- no loop of shell re-fetches on a genuinely
+    // broken session.
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(events).toHaveLength(1);
+    expect(events[0].detail).toMatchObject({
+      code: "UNAUTHORIZED",
+      message: "Invalid Bearer token.",
+    });
+  });
+
+  it("does not retry or dispatch on non-401 errors", async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        jsonResponse(502, {
+          status: "error",
+          error: { code: "API_ERROR", message: "upstream down" },
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+    const events: Event[] = [];
+    window.addEventListener(SESSION_EXPIRED_EVENT, (evt) => events.push(evt));
+
+    await expect(api.get("/projects")).rejects.toBeInstanceOf(ApiError);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(events).toHaveLength(0);
+  });
+
+  it("shares a single shell re-fetch across concurrent 401s", async () => {
+    let releaseShell: (() => void) | undefined;
+    const shellGate = new Promise<void>((resolve) => {
+      releaseShell = resolve;
+    });
+    const seen401 = new Set<string>();
+    let shellFetches = 0;
+    const fetchMock = vi.fn<typeof fetch>((input) => {
+      const url = calledUrl(input);
+      if (url === "/") {
+        shellFetches += 1;
+        return shellGate.then(shellResponse);
+      }
+      if (!seen401.has(url)) {
+        seen401.add(url);
+        return Promise.resolve(unauthorized());
+      }
+      return Promise.resolve(jsonResponse(200, { ok: url }));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const inFlight = Promise.all([api.get("/projects"), api.get("/jobs")]);
+    // Let both requests hit their 401 and pile onto the shell fetch.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    releaseShell?.();
+
+    await expect(inFlight).resolves.toEqual([
+      { ok: "/api/projects" },
+      { ok: "/api/jobs" },
+    ]);
+    expect(shellFetches).toBe(1);
+  });
+});
diff --git a/web/frontend/src/api/client.ts b/web/frontend/src/api/client.ts
index 1e4bd55f..8a690199 100644
--- a/web/frontend/src/api/client.ts
+++ b/web/frontend/src/api/client.ts
@@ -35,6 +35,45 @@ export class ApiError extends Error {
 
 const API_BASE = "/api";
 
+/**
+ * Fired on `window` when an API call still answers 401 after the session
+ * cookie has been re-bootstrapped. At that point the client cannot
+ * self-heal; the shell shows a visible "session expired" banner instead of
+ * letting every list silently render empty.
+ */
+export const SESSION_EXPIRED_EVENT = "kbagent:session-expired";
+
+export interface SessionExpiredDetail {
+  code: string;
+  message: string;
+}
+
+let shellRefresh: Promise<void> | null = null;
+
+/**
+ * Re-fetch the SPA shell to pick up a fresh `kbagent_session` cookie.
+ *
+ * `GET /` is the cookie-setting bootstrap route in single-process UI mode.
+ * `cache: "reload"` is load-bearing: a plain `fetch("/")` could be answered
+ * from the browser cache without any request reaching the server -- which is
+ * exactly how the cookie went stale in the first place (a reload after a
+ * `kbagent serve` restart served the cached shell, so no fresh Set-Cookie
+ * ever happened).
+ *
+ * Single-flight: a burst of parallel queries that all 401 shares one
+ * bootstrap fetch. Failures are swallowed -- the caller's retry surfaces
+ * the real error.
+ */
+function refreshSessionCookie(): Promise<void> {
+  shellRefresh ??= fetch("/", { cache: "reload", credentials: "include" })
+    .then(() => undefined)
+    .catch(() => undefined)
+    .finally(() => {
+      shellRefresh = null;
+    });
+  return shellRefresh;
+}
+
 interface RequestOptions {
   manageToken?: string;
   signal?: AbortSignal;
@@ -61,6 +100,7 @@ async function request<T>(
   method: string,
   path: string,
   opts: RequestOptions = {},
+  isRetry = false,
 ): Promise<T> {
   const headers: Record<string, string> = {};
   if (opts.body !== undefined) {
@@ -79,6 +119,13 @@ async function request<T>(
     // is a no-op (browser sends an empty cookie jar for the BFF origin).
     credentials: "include",
   });
+  if (res.status === 401 && !isRetry) {
+    // Stale session cookie (server restarted with a new bearer token):
+    // re-bootstrap the cookie and retry exactly once. Safe for mutations
+    // too -- a 401 means the request was rejected on auth, not applied.
+    await refreshSessionCookie();
+    return request<T>(method, path, opts, true);
+  }
   if (!res.ok) {
     let payload: KbagentError | null = null;
     try {
@@ -88,6 +135,13 @@ async function request<T>(
     }
     const message = payload?.error?.message ?? res.statusText;
     const code = payload?.error?.code ?? "HTTP_ERROR";
+    if (res.status === 401) {
+      window.dispatchEvent(
+        new CustomEvent<SessionExpiredDetail>(SESSION_EXPIRED_EVENT, {
+          detail: { code, message },
+        }),
+      );
+    }
     throw new ApiError(code, message, res.status);
   }
   // 204 No Content
diff --git a/web/frontend/src/components/SessionExpiredBanner.tsx b/web/frontend/src/components/SessionExpiredBanner.tsx
new file mode 100644
index 00000000..55ad9428
--- /dev/null
+++ b/web/frontend/src/components/SessionExpiredBanner.tsx
@@ -0,0 +1,62 @@
+/**
+ * Global "session expired" banner.
+ *
+ * Rendered when an API call answered 401 even after the client re-fetched
+ * the shell to refresh the `kbagent_session` cookie (see
+ * `SESSION_EXPIRED_EVENT` in api/client.ts). At that point the tab cannot
+ * self-heal: either `kbagent serve` restarted and a full reload is needed
+ * to re-bootstrap, or a session-registered project expired on the host
+ * (the server message then names the `kbagent auth login` remedy). Without
+ * this banner the failure mode is silent -- every list renders empty and
+ * nothing says why.
+ */
+import { TriangleAlert, X } from "lucide-react";
+import { useEffect, useState } from "react";
+import { SESSION_EXPIRED_EVENT, type SessionExpiredDetail } from "../api/client";
+
+export function SessionExpiredBanner() {
+  const [detail, setDetail] = useState<SessionExpiredDetail | null>(null);
+  useEffect(() => {
+    const onExpired = (evt: Event) => {
+      const incoming = (evt as CustomEvent<SessionExpiredDetail>).detail;
+      setDetail(incoming ?? { code: "UNAUTHORIZED", message: "" });
+    };
+    window.addEventListener(SESSION_EXPIRED_EVENT, onExpired);
+    return () => window.removeEventListener(SESSION_EXPIRED_EVENT, onExpired);
+  }, []);
+  if (!detail) return null;
+  // The middleware's "Invalid Bearer token." is phrased for API callers; for
+  // a browser tab the actionable truth is "the server restarted under you".
+  // Session-login expiries (SESSION_EXPIRED / SESSION_NOT_FOUND) keep the
+  // server message verbatim -- it names the on-host remedy.
+  const text =
+    detail.code === "UNAUTHORIZED"
+      ? "The server was restarted and this tab's session is stale. Reload to reconnect."
+      : detail.message || "The server rejected this session.";
+  return (
+    <div
+      role="alert"
+      className="flex items-center gap-3 border-b border-amber-300 bg-amber-50 px-4 py-1.5 text-xs text-amber-900 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-neon-amber"
+    >
+      <TriangleAlert className="h-3.5 w-3.5 shrink-0" />
+      <span className="min-w-0 truncate">
+        <span className="font-semibold">Session expired.</span> {text}
+      </span>
+      <button
+        type="button"
+        onClick={() => window.location.reload()}
+        className="ml-auto shrink-0 rounded border border-amber-400 px-2 py-0.5 font-medium hover:bg-amber-100 dark:border-amber-500/50 dark:hover:bg-amber-500/20"
+      >
+        Reload
+      </button>
+      <button
+        type="button"
+        aria-label="Dismiss"
+        onClick={() => setDetail(null)}
+        className="shrink-0 rounded p-0.5 hover:bg-amber-100 dark:hover:bg-amber-500/20"
+      >
+        <X className="h-3.5 w-3.5" />
+      </button>
+    </div>
+  );
+}
diff --git a/web/frontend/src/layout/Shell.tsx b/web/frontend/src/layout/Shell.tsx
index a9736d89..a8ba8138 100644
--- a/web/frontend/src/layout/Shell.tsx
+++ b/web/frontend/src/layout/Shell.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { CommandPalette } from "../components/CommandPalette";
+import { SessionExpiredBanner } from "../components/SessionExpiredBanner";
 import { WhatsNew } from "../components/WhatsNew";
 import { Sidebar } from "./Sidebar";
 import { StatusBar } from "./StatusBar";
@@ -8,6 +9,8 @@ import { TopBar } from "./TopBar";
 export function Shell({ children }: { children: ReactNode }) {
   return (
     <div className="h-screen flex flex-col">
+      {/* Above everything, full width: an auth failure concerns every pane. */}
+      <SessionExpiredBanner />
       <div className="flex-1 flex overflow-hidden">
         <Sidebar />
         <main className="flex-1 flex flex-col overflow-hidden">

From 8012cc7711e5e9160e557eadece088de0df45afe Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Sun, 23 Aug 2026 22:22:54 +0200
Subject: [PATCH 2/2] docs(serve): align _allow_static_through_auth docstring
 with hash-routed reality

Devin Review on #668 caught the third stale docstring: it still described
client-side routes resolving to index.html via the StaticFiles html=True
fallback. The predicate's behavior is unchanged -- unmatched paths stay
auth-public -- only the description now matches what actually happens
(hash-routed SPA, unknown paths 404 from the static mount).
---
 src/keboola_agent_cli/server/app.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/keboola_agent_cli/server/app.py b/src/keboola_agent_cli/server/app.py
index 5f5b872d..02060532 100644
--- a/src/keboola_agent_cli/server/app.py
+++ b/src/keboola_agent_cli/server/app.py
@@ -862,8 +862,10 @@ def _allow_static_through_auth(app: FastAPI) -> None:
 
     The auth middleware exempts ``PUBLIC_PATHS`` (docs, openapi, health). In UI
     mode the SPA also needs ``GET /``, ``GET /index.html``, ``GET /assets/*``,
-    favicons, and the SPA's client-side routes (which resolve to index.html via
-    the StaticFiles ``html=True`` fallback) to load without a token.
+    favicons, and any path matching no registered endpoint to load without a
+    token. (The SPA is hash-routed, so its client-side routes never reach the
+    server as paths; an unknown path 404s from the static mount -- the property
+    that matters here is that it is *not* auth-walled into a 401.)
 
     Route-aware (GHSA-ffpq-prmh-3gx2): a real endpoint must authenticate; only
     genuine client-side SPA routes fall through to the public index.html shell.