fix: recover from stale-chunk and DOM-desync SPA crashes

Two crashes seen in production, both reproduced on the live app:

- "Failed to fetch dynamically imported module": after a redeploy rotates the
  hashed chunk filenames, an open tab imports a deleted one. The server answered a
  missing /assets/* with 301 -> index.html (HTML for a JS module -> a MIME
  failure); it now returns 404 + no-store. The client listens for Vite's
  vite:preloadError and reloads once (debounced) to pull the current build. Hashed
  assets are served immutable; index.html and SPA routes no-cache.

- "Failed to execute 'removeChild' ... not a child of this node": an external
  agent (a browser extension or auto-translation) mutates the DOM React owns,
  desyncing reconciliation. A root react-router errorElement catches this
  commit-phase crash and self-heals with a debounced reload, instead of React
  Router's dead default error screen. translate="no" opts the English-only UI out
  of the one trigger it can prevent (browser translation); the errorElement covers
  the rest regardless of source.

Verified by reproducing both on the live old build (missing-chunk 301->HTML;
extension/translation DOM mutation -> the exact removeChild crash) and confirming
the fixed build recovers from each. Adds chunk-reload + RouteErrorBoundary unit
tests and a static-serving integration test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sirozha

backend/pkg/server/middleware.go

@@ -1,6 +1,9 @@
 package router
 
 import (
+	"net/http"
+	"strings"
+
 	"pentagi/pkg/server/models"
 	"pentagi/pkg/server/response"
 
@@ -34,3 +37,21 @@ func noCacheMiddleware() gin.HandlerFunc {
 		c.Next()
 	}
 }
+
+// staticCacheMiddleware sets cache policy for the locally-served SPA build:
+// content-hashed /assets/* are immutable; everything else resolving to the SPA
+// (index.html, client routes) is no-cache, so a redeploy is picked up instead of
+// replaying a stale index.html that imports chunks the deploy already deleted.
+func staticCacheMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if c.Request.Method == http.MethodGet && !strings.HasPrefix(c.Request.URL.Path, baseURL) {
+			if strings.HasPrefix(c.Request.URL.Path, "/assets/") {
+				c.Header("Cache-Control", "public, max-age=31536000, immutable")
+			} else {
+				c.Header("Cache-Control", "no-cache")
+			}
+		}
+
+		c.Next()
+	}
+}

backend/pkg/server/router.go

@@ -337,36 +337,55 @@ func NewRouter(
 			}
 		}())
 	} else {
-		router.Use(static.Serve("/", static.LocalFile(cfg.StaticDir, true)))
+		registerStaticFileServer(router, cfg.StaticDir)
+	}
 
-		indexExists := true
-		indexPath := filepath.Join(cfg.StaticDir, "index.html")
-		if _, err := os.Stat(indexPath); err != nil {
-			indexExists = false
-		}
+	return router
+}
 
-		router.NoRoute(func(c *gin.Context) {
-			if c.Request.Method == "GET" && !strings.HasPrefix(c.Request.URL.Path, baseURL) {
-				isFrontendRoute := false
-				path := c.Request.URL.Path
-				for _, prefix := range frontendRoutes {
-					if path == prefix || strings.HasPrefix(path, prefix+"/") {
-						isFrontendRoute = true
-						break
-					}
+// registerStaticFileServer serves the locally-built SPA (used when no STATIC_URL
+// upstream is set): cache headers, hashed assets via static.Serve, and an SPA
+// fallback that serves index.html for client routes but returns 404 for a missing
+// /assets/* — so the module loader fails cleanly and the app can reload to recover
+// instead of getting index.html and a MIME error. Split out to be unit-testable.
+func registerStaticFileServer(router *gin.Engine, staticDir string) {
+	router.Use(staticCacheMiddleware())
+	router.Use(static.Serve("/", static.LocalFile(staticDir, true)))
+
+	indexExists := true
+	indexPath := filepath.Join(staticDir, "index.html")
+	if _, err := os.Stat(indexPath); err != nil {
+		indexExists = false
+	}
+
+	router.NoRoute(func(c *gin.Context) {
+		if c.Request.Method == http.MethodGet && !strings.HasPrefix(c.Request.URL.Path, baseURL) {
+			isFrontendRoute := false
+			path := c.Request.URL.Path
+			for _, prefix := range frontendRoutes {
+				if path == prefix || strings.HasPrefix(path, prefix+"/") {
+					isFrontendRoute = true
+					break
 				}
+			}
 
-				if isFrontendRoute && indexExists {
-					c.File(indexPath)
-					return
-				}
+			if isFrontendRoute && indexExists {
+				c.File(indexPath)
+				return
 			}
 
-			c.Redirect(http.StatusMovedPermanently, "/")
-		})
-	}
+			if strings.HasPrefix(path, "/assets/") {
+				// A missing hashed asset may be a transient rolling-deploy
+				// race, so override the immutable directive set above —
+				// never cache this 404 as a permanent negative.
+				c.Header("Cache-Control", "no-store")
+				c.Status(http.StatusNotFound)
+				return
+			}
+		}
 
-	return router
+		c.Redirect(http.StatusMovedPermanently, "/")
+	})
 }
 
 func setKnowledgeGroup(parent *gin.RouterGroup, svc *services.KnowledgeService) {

backend/pkg/server/static_serving_test.go

@@ -0,0 +1,89 @@
+package router
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// newStaticTestServer builds a gin engine wired exactly like the production
+// local-serving branch (registerStaticFileServer) over a throwaway dist dir
+// holding one hashed asset and an index.html.
+func newStaticTestServer(t *testing.T) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "index.html"), []byte("<!doctype html><title>app</title>"), 0o600))
+	require.NoError(t, os.Mkdir(filepath.Join(dir, "assets"), 0o750))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "assets", "app-abc123.js"), []byte("export const x = 1;\n"), 0o600))
+
+	engine := gin.New()
+	registerStaticFileServer(engine, dir)
+
+	return engine
+}
+
+func getStatic(t *testing.T, engine *gin.Engine, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	engine.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+
+	return rec
+}
+
+func TestStaticFileServer(t *testing.T) {
+	engine := newStaticTestServer(t)
+
+	t.Run("existing hashed asset is served immutable", func(t *testing.T) {
+		rec := getStatic(t, engine, "/assets/app-abc123.js")
+
+		assert.Equal(t, http.StatusOK, rec.Code)
+		assert.Equal(t, "public, max-age=31536000, immutable", rec.Header().Get("Cache-Control"))
+	})
+
+	t.Run("missing asset is 404 and never cached as a permanent negative", func(t *testing.T) {
+		rec := getStatic(t, engine, "/assets/missing-deadbeef.js")
+
+		// 404 (not 301->HTML) so the browser module loader fails cleanly and
+		// the SPA reloads; no-store (not immutable) so a transient rolling
+		// deploy isn't cached as a permanent miss.
+		assert.Equal(t, http.StatusNotFound, rec.Code)
+		assert.Equal(t, "no-store", rec.Header().Get("Cache-Control"))
+		assert.NotContains(t, rec.Header().Get("Cache-Control"), "immutable")
+	})
+
+	t.Run("index.html is served revalidated", func(t *testing.T) {
+		rec := getStatic(t, engine, "/")
+
+		assert.Equal(t, http.StatusOK, rec.Code)
+		assert.Equal(t, "no-cache", rec.Header().Get("Cache-Control"))
+	})
+
+	t.Run("SPA deep-link falls back to index.html with no-cache", func(t *testing.T) {
+		rec := getStatic(t, engine, "/templates")
+
+		assert.Equal(t, http.StatusOK, rec.Code)
+		assert.Equal(t, "no-cache", rec.Header().Get("Cache-Control"))
+		assert.Contains(t, rec.Body.String(), "<!doctype html>")
+	})
+
+	t.Run("unknown non-asset path redirects to root", func(t *testing.T) {
+		rec := getStatic(t, engine, "/favicon-not-there.ico")
+
+		assert.Equal(t, http.StatusMovedPermanently, rec.Code)
+		assert.Equal(t, "/", rec.Header().Get("Location"))
+	})
+
+	t.Run("api paths are untouched by the static cache policy", func(t *testing.T) {
+		rec := getStatic(t, engine, baseURL+"/anything")
+
+		assert.Empty(t, rec.Header().Get("Cache-Control"))
+	})
+}

frontend/index.html

@@ -1,7 +1,18 @@
 <!doctype html>
-<html lang="en">
+<html
+    lang="en"
+    translate="no"
+>
     <head>
         <meta charset="UTF-8" />
+        <!-- The UI is English-only. Browser auto-translation is one known trigger of
+             a DOM desync (it swaps text nodes React owns), so opt the document out of
+             it. Defense-in-depth only: the route errorElement recovers from such
+             desyncs (extension or translation) regardless of source. -->
+        <meta
+            name="google"
+            content="notranslate"
+        />
         <meta
             name="viewport"
             content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"

frontend/src/app.tsx

@@ -17,6 +17,7 @@ import ProtectedRoute from '@/components/routes/protected-route';
 import PublicRoute from '@/components/routes/public-route';
 import { DocumentTitle } from '@/components/shared/document-title';
 import PageLoader from '@/components/shared/page-loader';
+import RouteErrorBoundary from '@/components/shared/route-error-boundary';
 import { Toaster } from '@/components/ui/sonner';
 import client from '@/lib/apollo';
 import { routeTitles } from '@/lib/route-titles';
@@ -126,7 +127,10 @@ function RootLayout() {
 
 const router = createBrowserRouter(
     createRoutesFromElements(
-        <Route element={<RootLayout />}>
+        <Route
+            element={<RootLayout />}
+            errorElement={<RouteErrorBoundary />}
+        >
             {/* private routes */}
             <Route element={<ProtectedAppLayout />}>
                 {/* Main layout for chat pages */}

frontend/src/components/shared/route-error-boundary.test.tsx

@@ -0,0 +1,96 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createMemoryRouter, RouterProvider } from 'react-router-dom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import RouteErrorBoundary from './route-error-boundary';
+
+// A loader that throws routes react-router to our `errorElement`, so
+// `useRouteError` inside the boundary receives exactly this value — the same
+// path a real chunk-load or render failure takes.
+const renderWithRouteError = (error: unknown) => {
+    const router = createMemoryRouter(
+        [
+            {
+                element: <div>page</div>,
+                errorElement: <RouteErrorBoundary />,
+                loader: () => {
+                    throw error;
+                },
+                path: '/',
+            },
+        ],
+        { initialEntries: ['/'] },
+    );
+
+    return render(<RouterProvider router={router} />);
+};
+
+const chunkError = () =>
+    new Error('Failed to fetch dynamically imported module: https://app/assets/templates-D01Ouz7C.js');
+const renderError = () => new TypeError('Cannot read properties of undefined (reading length)');
+const domDesyncError = () =>
+    new DOMException(
+        "Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.",
+        'NotFoundError',
+    );
+
+describe('RouteErrorBoundary', () => {
+    const originalLocation = window.location;
+    let reloadSpy: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        sessionStorage.clear();
+        reloadSpy = vi.fn();
+        // jsdom's `location.reload` is non-configurable, so swap the whole
+        // `location` object — the same workaround chunk-reload.test.ts uses.
+        Object.defineProperty(window, 'location', {
+            configurable: true,
+            value: { ...originalLocation, reload: reloadSpy },
+            writable: true,
+        });
+        // react-router logs loader errors it routes to the boundary; keep the
+        // test output clean without hiding real assertion failures.
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+        Object.defineProperty(window, 'location', {
+            configurable: true,
+            value: originalLocation,
+            writable: true,
+        });
+        sessionStorage.clear();
+    });
+
+    it('shows the redeploy message and auto-reloads once for a chunk-load error', async () => {
+        renderWithRouteError(chunkError());
+
+        expect(await screen.findByText(/a new version was likely just deployed/i)).toBeInTheDocument();
+        expect(screen.getByRole('alert')).toBeInTheDocument();
+        await waitFor(() => expect(reloadSpy).toHaveBeenCalledTimes(1));
+    });
+
+    it('shows the glitch message and auto-reloads once for a DOM-desync (removeChild) error', async () => {
+        renderWithRouteError(domDesyncError());
+
+        expect(await screen.findByText(/display glitch/i)).toBeInTheDocument();
+        await waitFor(() => expect(reloadSpy).toHaveBeenCalledTimes(1));
+    });
+
+    it('shows the generic message and does not auto-reload for a non-chunk error', async () => {
+        renderWithRouteError(renderError());
+
+        expect(await screen.findByText(/ran into an unexpected error/i)).toBeInTheDocument();
+        expect(reloadSpy).not.toHaveBeenCalled();
+    });
+
+    it('reloads when the user clicks Reload', async () => {
+        renderWithRouteError(renderError());
+
+        await userEvent.click(await screen.findByRole('button', { name: /reload/i }));
+
+        expect(reloadSpy).toHaveBeenCalledTimes(1);
+    });
+});