Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

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

Sergey Kozyrenko99c8b6786caf
diff --git a/backend/pkg/server/middleware.go b/backend/pkg/server/middleware.go
index 507b6103..0baee1f9 100644
--- a/backend/pkg/server/middleware.go
+++ b/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()
+ }
+}
diff --git a/backend/pkg/server/router.go b/backend/pkg/server/router.go
index 5404e35d..cd567632 100644
--- a/backend/pkg/server/router.go
+++ b/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) {
diff --git a/backend/pkg/server/static_serving_test.go b/backend/pkg/server/static_serving_test.go
new file mode 100644
index 00000000..c124772d
--- /dev/null
+++ b/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"))
+ })
+}
diff --git a/frontend/index.html b/frontend/index.html
index c6941843..d6509fc7 100644
--- a/frontend/index.html
+++ b/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"
diff --git a/frontend/src/app.tsx b/frontend/src/app.tsx
index 7e3e9d93..012be1fb 100644
--- a/frontend/src/app.tsx
+++ b/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 */}
diff --git a/frontend/src/components/shared/route-error-boundary.test.tsx b/frontend/src/components/shared/route-error-boundary.test.tsx
new file mode 100644
index 00000000..afda64cb
--- /dev/null
+++ b/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);
+ });
+});
diff --git a/frontend/src/components/shared/route-error-boundary.tsx b/frontend/src/components/shared/route-error-boundary.tsx
new file mode 100644
index 00000000..fdc33dff
--- /dev/null
+++ b/frontend/src/components/shared/route-error-boundary.tsx
@@ -0,0 +1,63 @@
+import { TriangleAlert } from 'lucide-react';
+import { useEffect } from 'react';
+import { useRouteError } from 'react-router-dom';
+
+import { Button } from '@/components/ui/button';
+import { StatusCard } from '@/components/ui/status-card';
+import { isChunkLoadError, isDomDesyncError, reloadOnce } from '@/lib/chunk-reload';
+
+/**
+ * Root `errorElement` for the data router — replaces React Router's built-in
+ * dev crash screen. Two production failures land here: a code-split chunk that
+ * 404s after a redeploy (auto-reload once, unless `vite:preloadError` in
+ * `main.tsx` already did), and any other render/commit crash (e.g. a `removeChild`
+ * desync from browser auto-translation) — both shown as a recoverable card.
+ */
+function RouteErrorBoundary() {
+ const error = useRouteError();
+ const isChunk = isChunkLoadError(error);
+ const isDesync = isDomDesyncError(error);
+
+ useEffect(() => {
+ // A stale code-split chunk and a transient DOM desync (e.g. an extension or
+ // auto-translation mutated the tree) both self-heal with a debounced reload;
+ // any other error stays on the card for the user to retry.
+ if (isChunk || isDesync) {
+ reloadOnce();
+ }
+ }, [isChunk, isDesync]);
+
+ return (
+ <div
+ className="grid min-h-svh w-full place-items-center p-4"
+ role="alert"
+ >
+ <StatusCard
+ action={
+ <Button
+ onClick={() => window.location.reload()}
+ variant="secondary"
+ >
+ Reload
+ </Button>
+ }
+ description={
+ isChunk
+ ? 'A new version was likely just deployed. Reloading will load the latest one.'
+ : isDesync
+ ? 'The page hit a display glitch. Reloading usually clears it.'
+ : 'The page ran into an unexpected error. Reloading usually clears it.'
+ }
+ icon={
+ <TriangleAlert
+ aria-hidden
+ className="text-muted-foreground size-10"
+ />
+ }
+ title="Something went wrong"
+ />
+ </div>
+ );
+}
+
+export default RouteErrorBoundary;
diff --git a/frontend/src/lib/chunk-reload.test.ts b/frontend/src/lib/chunk-reload.test.ts
new file mode 100644
index 00000000..72a664be
--- /dev/null
+++ b/frontend/src/lib/chunk-reload.test.ts
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { isChunkLoadError, isDomDesyncError, reloadOnce } from './chunk-reload';
+
+describe('isChunkLoadError', () => {
+ it('matches the dynamic-import failures browsers throw for a stale chunk', () => {
+ expect(
+ isChunkLoadError(new Error('Failed to fetch dynamically imported module: https://x/assets/login-AbC1.js')),
+ ).toBe(true);
+ expect(isChunkLoadError(new Error('error loading dynamically imported module'))).toBe(true);
+ // Safari's wording differs from Chromium's.
+ expect(isChunkLoadError(new Error('Importing a module script failed.'))).toBe(true);
+ // A server that serves index.html for a missing chunk trips the MIME check.
+ expect(
+ isChunkLoadError(
+ new Error(
+ 'Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html".',
+ ),
+ ),
+ ).toBe(true);
+ });
+
+ it('does not match unrelated runtime errors', () => {
+ expect(isChunkLoadError(new Error("Failed to execute 'removeChild' on 'Node'"))).toBe(false);
+ expect(isChunkLoadError(new TypeError('x is not a function'))).toBe(false);
+ expect(isChunkLoadError('a bare string')).toBe(false);
+ expect(isChunkLoadError(null)).toBe(false);
+ expect(isChunkLoadError(undefined)).toBe(false);
+ });
+});
+
+describe('isDomDesyncError', () => {
+ it('matches the removeChild/insertBefore "not a child" reconciliation crash', () => {
+ expect(
+ isDomDesyncError(
+ new Error(
+ "Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.",
+ ),
+ ),
+ ).toBe(true);
+ // React surfaces it as a DOMException (not an `instanceof Error`) — match via toString.
+ expect(
+ isDomDesyncError(
+ new DOMException(
+ "Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node.",
+ 'NotFoundError',
+ ),
+ ),
+ ).toBe(true);
+ expect(
+ isDomDesyncError(
+ new DOMException(
+ "Failed to execute 'replaceChild' on 'Node': The node to be replaced is not a child of this node.",
+ 'NotFoundError',
+ ),
+ ),
+ ).toBe(true);
+ });
+
+ it('does not match chunk-load or generic errors', () => {
+ expect(isDomDesyncError(new Error('Failed to fetch dynamically imported module: /assets/x.js'))).toBe(false);
+ expect(isDomDesyncError(new TypeError('Cannot read properties of undefined (reading length)'))).toBe(false);
+ expect(isDomDesyncError(null)).toBe(false);
+ });
+});
+
+describe('reload guard', () => {
+ let reloadSpy: ReturnType<typeof vi.fn>;
+ const originalLocation = window.location;
+ let now = 1_000_000;
+
+ beforeEach(() => {
+ sessionStorage.clear();
+ now = 1_000_000;
+ vi.spyOn(Date, 'now').mockImplementation(() => now);
+ reloadSpy = vi.fn();
+ // jsdom's `location.reload` is non-configurable, so swap the whole
+ // `location` object — the standard jsdom workaround for asserting reloads.
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: { ...originalLocation, reload: reloadSpy },
+ writable: true,
+ });
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ Object.defineProperty(window, 'location', {
+ configurable: true,
+ value: originalLocation,
+ writable: true,
+ });
+ sessionStorage.clear();
+ });
+
+ it('reloads, then debounces a rapid second attempt so it cannot loop', () => {
+ expect(reloadOnce()).toBe(true);
+ now += 500;
+ expect(reloadOnce()).toBe(false);
+ expect(reloadSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it('reloads again once the debounce window has passed (a later deploy)', () => {
+ expect(reloadOnce()).toBe(true);
+ now += 11_000;
+ expect(reloadOnce()).toBe(true);
+ expect(reloadSpy).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/frontend/src/lib/chunk-reload.ts b/frontend/src/lib/chunk-reload.ts
new file mode 100644
index 00000000..5962972f
--- /dev/null
+++ b/frontend/src/lib/chunk-reload.ts
@@ -0,0 +1,56 @@
+const LAST_RELOAD_AT_KEY = 'pentagi:chunk-reload-at';
+const RELOAD_DEBOUNCE_MS = 10_000;
+
+// The error browsers throw when a dynamically imported chunk can't be loaded —
+// usually a redeploy rotated the hashed filenames this document still references.
+export function isChunkLoadError(error: unknown): boolean {
+ const message = error instanceof Error ? error.message : String(error ?? '');
+
+ return (
+ /failed to fetch dynamically imported module/i.test(message) ||
+ /error loading dynamically imported module/i.test(message) ||
+ /importing a module script failed/i.test(message) ||
+ // A server that answers a missing chunk with index.html (HTML, not JS)
+ // trips the module loader's MIME check instead.
+ /failed to load module script/i.test(message) ||
+ /expected a javascript[- ]module script/i.test(message)
+ );
+}
+
+// React reconciliation desync: it tried to remove/insert/replace a node whose real
+// parent no longer matches the one it tracked, because something outside React (a
+// browser extension, auto-translation) rewrote the DOM React owns. Transient — a
+// reload rebuilds a consistent tree. This is the exact wording Chrome and Firefox use.
+export function isDomDesyncError(error: unknown): boolean {
+ const message = error instanceof Error ? error.message : String(error ?? '');
+
+ return /the node (to be removed|before which the new node is to be inserted|to be replaced) is not a child of this node/i.test(
+ message,
+ );
+}
+
+// Hard-reload, debounced so the two recovery paths (vite:preloadError and the route
+// error boundary) firing for one failure can't double-reload. Returns true if it reloaded.
+export function reloadOnce(): boolean {
+ if (Date.now() - lastReloadAt() < RELOAD_DEBOUNCE_MS) {
+ return false;
+ }
+
+ try {
+ sessionStorage.setItem(LAST_RELOAD_AT_KEY, String(Date.now()));
+ } catch {
+ /* best-effort: without storage the debounce can't persist */
+ }
+
+ window.location.reload();
+
+ return true;
+}
+
+function lastReloadAt(): number {
+ try {
+ return Number(sessionStorage.getItem(LAST_RELOAD_AT_KEY)) || 0;
+ } catch {
+ return 0;
+ }
+}
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index e1ca04f4..b5ce65ee 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -4,6 +4,15 @@ import * as React from 'react';
import ReactDOM from 'react-dom/client';
import App from '@/app';
+import { reloadOnce } from '@/lib/chunk-reload';
+
+// Vite fires this when a code-split chunk fails to load — almost always a redeploy
+// that rotated the hashed filenames this document still references. Reload once to
+// pull the current build; RouteErrorBoundary is the fallback for failures that
+// bypass this event, and both share reloadOnce's debounce so at most one fires.
+window.addEventListener('vite:preloadError', () => {
+ reloadOnce();
+});
ReactDOM.createRoot(document.querySelector('#root')!).render(
<React.StrictMode>