fix(chat): keep in-flight answers alive across in-app view switches

Root cause (owner repro, verified in a real browser 2026-09-06): the
five navbar views (Chat, RAG, Sources, Tuning, History) were separate
HTML documents, so a navbar click was a REAL cross-document navigation
— the chat page unloaded, the in-flight SSE fetch was aborted, and the
phase-48 teardown (app/api/chat.py `finally`, "chat: turn cancelled")
stopped the model. Observed: send question -> click RAG mid-stream ->
click Chat -> the answer never finished: no `query_log` row, and on
return a dangling question with no brain record (the pre-token pagehide
partial persist skips because `acc` is empty).

Phase-48 LOCKED-DECISION REFINEMENT (owner-confirmed 2026-09-06,
flagged per AGENTS.md rule 3, not silently deviated): "real navigation
cancels the fetch" now means LEAVING THE APP — tab close,
external/other-document navigation, the Stop button. In-app navbar
switches are client-side view switches and no longer cancel.

Fix — Option A (SPA shell), chosen over B (Service Worker owns the
stream) and C (server-side turn registry + resume):
- frontend/index.html is the shell: ONE `<main id="main">` holds the
  five `<section class="view">` blocks; hidden views carry BOTH
  `hidden` and `inert` (WCAG — no focus/keyboard traversal). The
  shared header, the single `doc-modal-*` skeleton, and the
  `#app-version` footer each exist exactly once; the per-view copies
  from the four folded pages are dropped.
- New frontend/assets/router.js (vanilla module — no framework, no
  bundler, No-CDN rule intact): lazy-imports a view module on FIRST
  show only (mount-once, hide-forever — the chat view's in-flight SSE
  reader persists across switches; that persistence IS the fix);
  intercepts same-shell navbar links with preventDefault +
  history.pushState (never a document load); handles popstate; single
  writer of `.nav-link` active state (is-active + aria-current),
  document.title, and the per-view meta description (values carried
  over from the old pages' heads, brand-resolved at write time).
- Each folded page's JS becomes `export async function mount(root)` —
  root-scoped queries; `initSharedHeader()` dropped (the header boots
  once in the shell via the chat module; the admin flag comes from the
  same cached `fetchIsAdmin()` promise — zero extra requests).
- app/main.py: a small list-driven route factory serves the shell for
  /tuning.html, /sources.html, /git-sources.html, /history.html —
  registered AFTER the API routers and BEFORE the static catch-all
  (routes-first). The phase-33 caching middleware applies no-cache +
  `?v=` rewriting unchanged; app/core/caching.py needed NO change
  (the view paths did not change — pinned by the integration tests).
- The four old view .html files are DELETED (one source of truth);
  deep links to the old URLs keep working (the router picks the view
  from the pathname); `/?chat=<id>` is unaffected; the Containerfile
  bundles router.js (inlining the lazy view modules) and drops the
  folded page files.
- app/schemas.py: HistoryTurn.text cap 4000 -> 32000 — the shell
  keeps long saved answers in the chat, and the old cap (stricter than
  the 24_000-char total history budget) 422-rejected any second turn
  in such a chat (found by the phase-42 E2E suite on the shell).

Boundaries: login.html, shared.html, doc-edit.html, document.html
REMAIN separate documents (flow pages, not navbar tabs); a mid-stream
navigation to doc-edit/document.html still cancels per phase 48
(follow-up candidate, out of scope). The SSE API is unchanged. Real
departures still cancel the turn — phase 48 intact (pinned by
tests/e2e/test_stop_generation.py, unchanged, and by the new suite's
real-departure control).

Tests:
- Phase-20 suite REWRITTEN to the new semantics
  (tests/e2e/test_sources_midstream_bug.py): a navbar switch no longer
  cancels — the stream survives the switch and the FULL answer
  settles; the pagehide partial persist REMAINS for real departures
  (the partial's exact shape — first streamed chunk prefix, no done
  metadata — is still pinned there).
- NEW story suite tests/e2e/test_nav_switch_keeps_stream.py (mock
  LLM): the owner repro (send -> RAG mid-stream -> Chat: window
  sentinel survives = same document, FULL answer, exactly one brain
  turn in bor.chat.v1, exactly one settled query_log row, auto-saved
  row matches) + the same mid-stream switch against the other three
  views + the real-departure-still-cancels control + the no-switch
  baseline.
- tests/unit/test_frontend_router.py: source-level pins of the router
  invariants (click interceptor targets ONLY same-shell view paths,
  pushState-only switches, mount-once guard, hidden+inert pair,
  single-writer active state/title); shell-route integration tests
  (each folded path serves the shell with no-cache + `?v=` body; a
  non-view path still 404s); the file-reading unit pins re-pointed at
  the shell (the four view files are gone — the shell is the source
  of truth).

Verification (this commit): full suite green — 1565 unit+integration
tests, app/ coverage 99% (>90% floor); ruff + pyright clean; the
phase's E2E suites green in isolation (house protocol, AGENTS.md rule
9). Owner repro verified in a real browser against the real LLM
(dev server :8010, headful Chromium): "tell me about everquest" ->
RAG mid-stream -> Chat — the answer completed with one brain bubble
and no error banner, `query_log` gained exactly one settled row
(deflected=True: the dev KB holds no EverQuest docs — the settle, not
the topic, is the proof), zero "chat: turn cancelled" lines for that
turn; the control (real navigation to /shared.html mid-stream) still
cancelled (no settled row, the cancel line logged, the partial
persisted on return). Screenshots: .agents/screenshots/76_manual_*.

Phase 76 (76_spa_nav_shell) complete — moved to
.agents/phases/complete/.

tests/integration/test_api.py

@@ -150,12 +150,23 @@ def test_suggestions_honors_bor_suggestions_env_override(monkeypatch) -> None:
     ("path", "marker"),
     [
         ("/", "Brain of Reese"),
-        ("/sources.html", "Knowledge base"),
+        # Phase 76 (task 02): /sources.html + /git-sources.html are SHELL
+        # routes — the body is the shell (index.html) whose static
+        # <title> is "Brain of Reese" (the per-view title is set
+        # CLIENT-side by the router, invisible to httpx). The marker
+        # asserts the shell body (the view section is inside it) instead
+        # of the old page's title.
+        ("/sources.html", 'id="view-rag"'),  # phase 76: shell route (was "Knowledge base")
         ("/document.html", "Brain of Reese"),  # phase 10: viewer page
         ("/login.html", "Sign in"),  # phase 16: admin sign-in page
-        ("/tuning.html", "Global Tuning"),  # phase 27: global tuning page
-        ("/git-sources.html", "Git sources"),  # phase 35: admin git sources page
-        ("/history.html", "Saved chats"),  # phase 50: admin saved-chats page
+        # Phase 76 (task 01): /tuning.html is a SHELL route — same
+        # shell-body marker pattern as the two task-02 paths above.
+        ("/tuning.html", 'id="view-tuning"'),  # phase 76: shell route (was "Global Tuning")
+        ("/git-sources.html", 'id="view-git-sources"'),  # phase 76: shell route (was "Git sources")
+        # Phase 76 (task 03): /history.html is a SHELL route too — the
+        # shell-body marker (the History view section is inside the
+        # shell; the old standalone page's title is client-side now).
+        ("/history.html", 'id="view-history"'),  # phase 76: shell route (was "Saved chats")
         ("/shared.html", "Shared conversation"),  # phase 51: anonymous shared page
     ],
 )
@@ -194,7 +205,7 @@ def test_index_page_no_cache_with_versioned_asset_refs(client) -> None:
 @pytest.mark.parametrize(
     "path",
     ["/sources.html", "/document.html", "/login.html", "/tuning.html",
-     "/git-sources.html", "/history.html",  # phase 50: + the History page
+     "/git-sources.html", "/history.html",  # phase 50: + History (shell route, task 03)
      "/shared.html"],  # phase 51: + the anonymous shared page
 )
 def test_html_pages_no_cache_with_versioned_refs(client, path: str) -> None:
@@ -208,6 +219,51 @@ def test_html_pages_no_cache_with_versioned_refs(client, path: str) -> None:
     assert f"?v={asset_version()}" in r.text
 
 
+@pytest.mark.parametrize(
+    ("path", "view_id", "old_title"),
+    [
+        ("/tuning.html", 'id="view-tuning"', "Global Tuning · Brain of Reese"),
+        ("/sources.html", 'id="view-rag"', "Sources · Brain of Reese"),
+        ("/git-sources.html", 'id="view-git-sources"', "Git sources · Brain of Reese"),
+        ("/history.html", 'id="view-history"', "Saved chats · Brain of Reese"),  # phase 76 task 03
+    ],
+)
+def test_shell_routes_serve_the_shell_no_cache_versioned(
+    client, path: str, view_id: str, old_title: str
+) -> None:
+    """Phase 76 (task 01: /tuning.html; task 02: /sources.html +
+    /git-sources.html; task 03: /history.html — all four non-chat
+    navbar views): every shell route serves the shell
+    (``frontend/index.html``), so the phase-33 page contract applies to
+    it exactly as to a static page: 200, text/html, ``Cache-Control:
+    no-cache``, ``?v=<token>`` asset refs, no validators (the
+    middleware wraps the whole app and lists the path in ``HTML_PAGES``
+    — unchanged). The body IS the shell: the view section is inside it,
+    the old standalone page's title is gone. The static catch-all stays
+    intact: an unknown path still 404s. (The conditional-GET
+    revalidation contract for these paths is pinned by
+    ``tests/integration/test_caching_revalidation.py``.)"""
+    from app.core.caching import asset_version
+
+    r = client.get(path)
+    assert r.status_code == 200
+    assert r.headers["content-type"].split(";", 1)[0] == "text/html"
+    assert r.headers["cache-control"] == "no-cache"
+    assert "etag" not in r.headers
+    assert "last-modified" not in r.headers
+    assert f"?v={asset_version()}" in r.text
+    # The body is the SHELL: the chat view AND the route's view section
+    # are inside it…
+    assert 'id="view-chat"' in r.text
+    assert view_id in r.text
+    # …with the shell's static title (the per-view title is the
+    # router's client-side job), and the old page's own <title> is gone.
+    assert "<title>Brain of Reese</title>" in r.text
+    assert f"{old_title}</title>" not in r.text
+    # The catch-all is intact: an unknown path still 404s.
+    assert client.get("/nonexistent.html").status_code == 404
+
+
 def test_index_html_variant_no_cache_versioned(client) -> None:
     """/index.html is the same page as / — same caching treatment."""
     from app.core.caching import asset_version

tests/integration/test_caching_revalidation.py

@@ -68,9 +68,30 @@ def file_validators(page_file: Path) -> tuple[str, str]:
     return headers["etag"], headers["last-modified"]
 
 
+#: Phase 76 (task 01): the shell-served view paths — the URL is a
+#: navbar view, the file on disk is the SHELL (the shell route in
+#: app/main.py serves frontend/index.html for it). The etag
+#: computation below must use the file that actually backs the
+#: response, or the conditional-GET probe would carry a validator no
+#: browser ever saw. Tasks 02/03 extended this as the remaining views
+#: folded in (task 03 — History — completes the set: all four
+#: non-chat navbar views). The page CONTRACT itself is unchanged: the
+#: phase-33 middleware wraps the whole app and lists the path in
+#: HTML_PAGES, so the shell-route response is normalized exactly like
+#: a static page (200, no-cache, ?v=, no validators — asserted by
+#: _assert_page_contract below).
+SHELL_BACKED_PAGES = {
+    "/tuning.html": "index.html",  # phase 76 task 01
+    "/sources.html": "index.html",  # phase 76 task 02
+    "/git-sources.html": "index.html",  # phase 76 task 02
+    "/history.html": "index.html",  # phase 76 task 03
+}
+
+
 def _page_file(path: str) -> Path:
-    """The static file backing a page path (``/`` → ``index.html``)."""
-    name = path.lstrip("/") or "index.html"
+    """The static file backing a page path (``/`` → ``index.html``;
+    the shell-served view paths → the shell, ``SHELL_BACKED_PAGES``)."""
+    name = SHELL_BACKED_PAGES.get(path, path.lstrip("/") or "index.html")
     file = FRONTEND / name
     assert file.is_file(), f"missing page file for {path}: {file}"
     return file

tests/integration/test_containerfile_assets.py

@@ -242,6 +242,18 @@ def test_header_module_is_imported_not_directly_loaded() -> None:
         js_path = ASSETS / name
         assert js_path.is_file(), f"page script missing: {js_path}"
         body = js_path.read_text(encoding="utf-8")
+        # Phase 76: the shell's router (router.js) is NOT a view module
+        # — the shell's shared header boots via the chat module (app.js,
+        # which imports header.js), and the view modules the router
+        # lazy-imports (tuning.js, …) import header.js themselves, so
+        # the single-evaluation contract holds without the router
+        # importing it (it owns the view switch, not the header).
+        if name == "router.js":
+            assert 'from "./header.js"' not in body, (
+                "router.js must not import the header module — the chat "
+                "module boots the shell's ONE header"
+            )
+            continue
         assert re.search(r"""from\s+["']\./header\.js["']""", body), (
             f"{name}: must import the shared header module relatively "
             f'("from \\"./header.js\\"")'