feat(ui): one consistent navbar on every page (TODO.md L3)

tests/e2e/test_admin_auth.py

@@ -101,9 +101,11 @@ def test_anonymous_chat_without_tuning(
 
     # Header: Sign in offered, Sign out not.
     expect(page.locator("#sign-in-link")).to_be_visible()
-    expect(page.locator("#sign-in-link")).to_have_attribute(
-        "href", "/login.html?next=/sources.html"
-    )
+    # Phase 34 task 02: the shared header module rewrites the static
+    # ?next= fallback to the CURRENT pathname ("return to where you
+    # were") — on the chat page that is "/" (the markup keeps
+    # ?next=/sources.html as the no-JS fallback only).
+    expect(page.locator("#sign-in-link")).to_have_attribute("href", "/login.html?next=/")
     expect(page.locator("#sign-out-btn")).to_be_hidden()
 
     # Chat still streams a grounded answer (with source chips) for

tests/e2e/test_header_consistency.py

@@ -18,6 +18,14 @@ Phase 16 adaptation: the auth control (Sign in / Sign out) joins the chat
 header's ``.header-inner`` — the desktop test verifies its presence in
 both auth states without the bar's height moving (height assertions
 unchanged).
+
+Phase 34 adaptation (two-row viewer header, owner confirmation
+2026-08-26): the viewer's ``<header>`` is now TWO rows — row 1 is the
+standard shared bar (``.doc-header .app-header``, the phase-12/19
+``--header-h`` contract) and row 2 is the ``.doc-titlebar`` (back +
+title + meta, content-sized). The height assertions are pointed at ROW
+1 — the standard bar — which must equal the chat/sources bars exactly;
+the titlebar row is asserted present (height > 0), not height-pinned.
 """
 from __future__ import annotations
 
@@ -95,7 +103,9 @@ def _header_heights(page: Page, app_url: str) -> dict[str, float]:
 
     page.goto(app_url + VIEWER_URL)
     expect(page.locator("#doc-title")).to_have_text("Kubernetes Homelab Cluster", timeout=15_000)
-    heights["document"] = _box_height(page, ".doc-header")
+    # Phase 34: the viewer header is two rows — measure ROW 1 (the
+    # standard bar), which must equal the other pages' bars exactly.
+    heights["document"] = _box_height(page, ".doc-header .app-header")
     return heights
 
 
@@ -158,6 +168,9 @@ def test_header_height_identical_across_pages_mobile(
 def test_viewer_header_content_still_fits(
     page: Page, app_url: str, mock_llm: int, db_ready: None
 ) -> None:
+    """Phase 34: the phase-10 viewer content (title, badges, back link)
+    survives in the titlebar ROW, and row 1 stays the pinned standard
+    bar — single-line on both desktop and mobile."""
     _seed_db(mock_llm)
 
     for width, expected_h in ((1280, DESKTOP_HEADER_H), (375, MOBILE_HEADER_H)):
@@ -176,10 +189,14 @@ def test_viewer_header_content_still_fits(
         expect(page.locator(".format-badge", has_text="md")).to_be_visible()
         expect(page.locator(".doc-path", has_text="homelab/kubernetes.md")).to_be_visible()
 
-        # Back link still there, ≥44px touch target, in the shared bar.
+        # Back link still there, ≥44px touch target, in the titlebar row.
         back = page.locator("#doc-back")
         expect(back).to_be_visible()
         assert _box_height(page, "#doc-back") >= 44
-        expect(page.locator(".doc-header")).to_have_css(
+
+        # Phase 34 two-row contract: ROW 1 is the standard bar (the
+        # pinned --header-h), and the titlebar row is present below it.
+        expect(page.locator(".doc-header .app-header")).to_have_css(
             "height", f"{expected_h}px"
         )
+        assert _box_height(page, ".doc-titlebar") > 0, ("the titlebar row must render")

tests/e2e/test_nav_consistency.py

@@ -0,0 +1,493 @@
+"""Phase 34 story E2E (Playwright): ONE navbar on every page.
+
+Story: ``.agent/user_stories/nav-consistency.md``
+Run in isolation (DB must be up: ``podman compose up -d db``):
+
+    uv run pytest tests/e2e/test_nav_consistency.py -v --no-cov
+
+TODO.md L3 (owner 2026-08-26): "I want the navbar to be consistent
+between every page. I don't want buttons to pop in and out of existance.
+Just keep all those buttons active across all tabs."
+
+Contract under test — the header is IDENTICAL on all five pages (chat,
+sources, document viewer, global tuning, login): one shared markup block
+(phase 34 task 03), one owner of all control behavior (header.js, tasks
+01/02), the viewer's back + title preserved in a second titlebar row
+(task 04), and the phase-12/19 height contract (64px desktop / 58px at
+≤640px) on the standard row everywhere.
+
+Per role, the VISIBLE inventory:
+
+* admin: brand + nav [Chat, #nav-sources, #nav-tuning] + #steering-toggle
+  + #sync-btn + #new-chat-btn + #sign-out-btn (with #sign-in-link
+  hidden) — on all five pages, same id+class inventory, same DOM order;
+* anonymous: brand + nav [Chat] (#nav-sources / #nav-tuning hidden —
+  locked A10 UI revision) + #new-chat-btn + #sign-in-link (with
+  #sync-btn hidden, #sign-out-btn hidden) on all five pages — and the
+  steering toggle + panel are ABSENT from the DOM (phase 16 "absent,
+  not hidden" treatment, carried into phase 34 task 01; test_admin_auth
+  pins it).
+
+Normalization for the inventory comparison: the current-page ``is-active``
+nav marker and the sign-in ``?next=`` value legitimately differ per page,
+so both are stripped (the href is compared by pathname only).
+
+Viewer specifics: row 1 (the standard bar) is exactly as tall as the chat
+page's bar (64px / 58px) and row 2 (``.doc-titlebar``) is present with
+#doc-back + #doc-title + #doc-meta badges; #doc-back target resolution
+(phase 13) is honored — ``back=`` accepted for same-origin relative
+URLs, rejected (→ /sources.html) otherwise.
+
+Steering works off-chat: on /tuning.html (admin, zero notes) the toggle
+opens/closes #steering-panel with the empty state and a 0 count badge —
+no chat needed. Sync is present, not triggered: #sync-btn is visible on
+/tuning.html but is never clicked here (a real sync clones real repos —
+the full state machine is test_sync_button.py's job).
+
+Determinism note: every assertion is settled-state — each page visit
+first waits for the whoami toggle to land (exactly one of Sign in /
+Sign out visible; the anonymous removal of the steering toggle happens
+in the SAME initSharedHeader pass) and, on the viewer, for the document
+title to render. The seed truncates steering_notes, so the count badge is
+0 on every admin page. No chat turn is ever submitted; #sync-btn is
+never clicked.
+
+Test → story mapping (Playwright Mapping Rule):
+1. ``test_admin_inventory_identical_on_all_five_pages``
+2. ``test_anonymous_inventory_identical_on_all_five_pages``
+3. ``test_viewer_row1_height_matches_chat_and_titlebar_present``
+4. ``test_viewer_back_link_honors_back_param``
+5. ``test_steering_panel_works_off_chat_on_tuning_page``
+6. ``test_sync_button_present_on_tuning_page_without_triggering``
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from threading import Thread
+from typing import Any
+
+from playwright.sync_api import Page, expect
+from sqlalchemy import text
+
+from app.config import Settings
+from app.db import SessionLocal
+from app.rag.importer import ImportSummary, import_sources
+from app.rag.llm import LLMClient
+from e2e.auth_helpers import login
+
+REPO = Path(__file__).resolve().parents[2]
+FIXTURES = REPO / "tests" / "fixtures" / "docs"
+
+#: The five pages of the app (acceptance criterion 2 of the story).
+CHAT_URL = "/"
+SOURCES_URL = "/sources.html"
+TUNING_URL = "/tuning.html"
+LOGIN_URL = "/login.html"
+#: A seeded fixture doc (source=docs), URL-encoded — the same document
+#: every viewer suite uses (title "Kubernetes Homelab Cluster").
+VIEWER_URL = "/document.html?source=docs&path=homelab%2Fkubernetes.md"
+DOC_TITLE = "Kubernetes Homelab Cluster"
+
+#: The phase-12/19 pinned bar heights (frontend/assets/styles.css
+#: --header-h, desktop and ≤640px).
+DESKTOP_HEADER_H = 64
+MOBILE_HEADER_H = 58
+
+
+async def _import_fixtures(mock_port: int) -> ImportSummary:
+    kwargs: dict[str, Any] = {"_env_file": None, "llm_base_url": f"http://127.0.0.1:{mock_port}/v1"}
+    settings = Settings(**kwargs)  # pyright: ignore[reportCallIssue]
+    return await import_sources([FIXTURES], LLMClient(settings))
+
+
+def _run_in_thread(coro: Any) -> Any:
+    """Run a coroutine on a worker thread (Playwright owns the test loop)."""
+    box: dict[str, Any] = {}
+
+    def runner() -> None:
+        try:
+            box["value"] = asyncio.run(coro)
+        except BaseException as e:  # noqa: BLE001 — re-raised on the test thread
+            box["error"] = e
+
+    t = Thread(target=runner)
+    t.start()
+    t.join()
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+def _seed_db(mock_port: int) -> None:
+    """Fresh KB + ZERO steering notes (deterministic count badge on
+    every admin page) + the fixture docs for the viewer URL."""
+    with SessionLocal() as db:
+        db.execute(text("TRUNCATE chunks, documents, query_log, steering_notes"))
+        db.commit()
+    _run_in_thread(_import_fixtures(mock_port))
+
+
+def _box_height(page: Page, selector: str) -> float:
+    box = page.locator(selector).bounding_box()
+    assert box is not None, f"{selector} not rendered"
+    return box["height"]
+
+
+# ---------------------------------------------------------------------------
+# The heart of the suite: the normalized header-control inventory
+# ---------------------------------------------------------------------------
+
+#: The header controls, in their shipped DOM order. The inventory is
+#: normalized per the task: the current-page ``is-active`` nav marker is
+#: stripped from the class list, and anchor hrefs are compared by
+#: pathname only (the sign-in ``?next=`` value legitimately differs per
+#: page — it is rewritten to the current page by header.js).
+_INVENTORY_JS = """() => {
+    const inner = document.querySelector("header .header-inner");
+    if (!inner) return null;
+    const sel = [
+        ".brand",
+        ".app-nav > a.nav-link",
+        "#steering-toggle",
+        "#sync-btn",
+        "#new-chat-btn",
+        "#sign-in-link",
+        "#sign-out-btn",
+    ].join(",");
+    return [...inner.querySelectorAll(sel)].map((el) => {
+        const classes = [...el.classList].filter((c) => c !== "is-active");
+        const id = el.id ? "#" + el.id : "";
+        const href = el.tagName === "A" ? (el.getAttribute("href") || "").split("?")[0] : "";
+        const text = (el.textContent || "").replace(/\\s+/g, " ").trim();
+        return el.tagName.toLowerCase() + id + "." + classes.join(".") + "::" + text + "::" + href;
+    });
+}"""
+
+
+def _header_inventory(page: Page) -> list[str]:
+    """The ordered id+class inventory of the header controls on the page
+    ``page`` is showing (normalized — see _INVENTORY_JS)."""
+    inv = page.evaluate(_INVENTORY_JS)
+    assert inv is not None, "no `header .header-inner` on this page"
+    assert len(inv) >= 8, f"header control inventory unexpectedly short: {inv}"
+    return inv
+
+
+def _wait_settled(page: Page, admin: bool) -> None:
+    """Wait for initSharedHeader's whoami toggle to land: exactly one of
+    Sign in / Sign out is visible (both ship hidden in the HTML). For
+    anonymous visitors the steering toggle + panel removal happens in
+    the SAME pass, so they are already gone when this returns."""
+    if admin:
+        expect(page.locator("#sign-out-btn")).to_be_visible(timeout=15_000)
+        expect(page.locator("#sign-in-link")).to_be_hidden()
+    else:
+        expect(page.locator("#sign-in-link")).to_be_visible(timeout=15_000)
+        expect(page.locator("#sign-out-btn")).to_be_hidden()
+
+
+def _assert_landmarks(page: Page, label: str) -> None:
+    """UI Structure Check (AGENTS.md rule 5): the page's landmarks — a
+    <header>, the labeled <nav>, and <main> — survive on every page."""
+    assert page.locator("header").count() >= 1, f"{label}: no <header> landmark"
+    assert page.locator('nav[aria-label="Primary"]').count() == 1, (
+        f"{label}: no labeled <nav aria-label> landmark"
+    )
+    assert page.locator("main").count() >= 1, f"{label}: no <main> landmark"
+
+
+def _visit(page: Page, app_url: str, name: str, url: str, admin: bool) -> list[str]:
+    """Goto a page, wait for the settled header state (+ the document on
+    the viewer), check the per-role visible inventory, and return the
+    normalized control inventory."""
+    page.goto(app_url + url)
+    _wait_settled(page, admin=admin)
+    if name == "viewer":
+        # The document itself has settled (rendered, not Loading…/
+        # not-found) so the bar is measured on the real page.
+        expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
+
+    # The per-role VISIBLE inventory (the story: no button pops in or
+    # out because of which page you are on).
+    expect(page.locator(".app-nav a[href='/']")).to_be_visible()  # Chat
+    if admin:
+        expect(page.locator("#nav-sources")).to_be_visible()
+        expect(page.locator("#nav-tuning")).to_be_visible()
+        expect(page.locator("#steering-toggle")).to_be_visible()
+        expect(page.locator("#sync-btn")).to_be_visible()
+        expect(page.locator("#sign-out-btn")).to_be_visible()
+        expect(page.locator("#sign-in-link")).to_be_hidden()
+    else:
+        # Locked A10 UI revision: admin-only links ship hidden, never
+        # revealed for anonymous…
+        expect(page.locator("#nav-sources")).to_be_hidden()
+        expect(page.locator("#nav-tuning")).to_be_hidden()
+        expect(page.locator("#sync-btn")).to_be_hidden()
+        expect(page.locator("#sign-out-btn")).to_be_hidden()
+        expect(page.locator("#sign-in-link")).to_be_visible()
+        # …and the steering surface is ABSENT (phase 16 "absent, not
+        # hidden", carried into the shared module by phase 34 task 01
+        # — test_admin_auth pins the same contract).
+        assert page.locator("#steering-toggle").count() == 0, (
+            f"{name}: the steering toggle must be absent for anonymous"
+        )
+        assert page.locator("#steering-panel").count() == 0, (
+            f"{name}: the steering panel must be absent for anonymous"
+        )
+    expect(page.locator("#new-chat-btn")).to_be_visible()
+
+    _assert_landmarks(page, name)
+    return _header_inventory(page)
+
+
+LOGIN_JS_ROUTE = re.compile(r"/assets/login\.js(\?.*)?$")
+
+
+def _admin_login_page_inventory(page: Page, app_url: str) -> list[str]:
+    """The login page's header IN THE ADMIN STATE. A signed-in admin is
+    redirected off the login form by login.js (``location.replace`` →
+    the default next, /sources.html — phase 16, pinned by
+    test_admin_auth), so this ONE visit serves the page script with the
+    redirect lines suppressed (a test-local route on the login.js
+    script; the page's header — settled by the same initSharedHeader
+    pass — is what gets measured, and the page stays put).
+
+    The browser cache is cleared first: phase 33 caches ``/assets/*``
+    ``immutable`` for a year, and the earlier form login already fetched
+    the (unmodified) login.js — a cache hit would bypass the route.
+    """
+    login_js = (REPO / "frontend" / "assets" / "login.js").read_text(encoding="utf-8")
+    assert "window.location.replace(safeNext())" in login_js
+    suppressed = login_js.replace(
+        "window.location.replace(safeNext())",
+        "window.__e2e_redirectSuppressed = true; // test: observe the header",
+    )
+    page.route(
+        LOGIN_JS_ROUTE,
+        lambda route: route.fulfill(
+            status=200, content_type="text/javascript", body=suppressed
+        ),
+    )
+    try:
+        cdp = page.context.new_cdp_session(page)
+        try:
+            cdp.send("Network.clearBrowserCache")
+        finally:
+            cdp.detach()
+        page.goto(app_url + LOGIN_URL)
+        expect(page).to_have_url(app_url + LOGIN_URL, timeout=15_000)
+        _wait_settled(page, admin=True)
+        expect(page.locator(".app-nav a[href='/']")).to_be_visible()
+        expect(page.locator("#nav-sources")).to_be_visible()
+        expect(page.locator("#nav-tuning")).to_be_visible()
+        expect(page.locator("#steering-toggle")).to_be_visible()
+        expect(page.locator("#sync-btn")).to_be_visible()
+        expect(page.locator("#sign-out-btn")).to_be_visible()
+        expect(page.locator("#sign-in-link")).to_be_hidden()
+        expect(page.locator("#new-chat-btn")).to_be_visible()
+        _assert_landmarks(page, "login")
+        return _header_inventory(page)
+    finally:
+        page.unroute(LOGIN_JS_ROUTE)
+
+
+# ---------------------------------------------------------------------------
+# 1. Admin: the same visible controls, same inventory, same DOM order,
+#    on all five pages
+# ---------------------------------------------------------------------------
+
+
+def test_admin_inventory_identical_on_all_five_pages(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    page.set_viewport_size({"width": 1280, "height": 800})
+    _seed_db(mock_llm)
+
+    login(page, app_url, next=CHAT_URL)
+    expect(page).to_have_url(app_url + CHAT_URL, timeout=30_000)
+
+    inventories: dict[str, list[str]] = {}
+    for name, url in (
+        ("chat", CHAT_URL),
+        ("sources", SOURCES_URL),
+        ("viewer", VIEWER_URL),
+        ("tuning", TUNING_URL),
+    ):
+        inventories[name] = _visit(page, app_url, name, url, admin=True)
+    # The login page redirects a signed-in admin away — measure it with
+    # the redirect aborted (see the helper).
+    inventories["login"] = _admin_login_page_inventory(page, app_url)
+
+    reference = inventories["chat"]
+    for name, inv in inventories.items():
+        assert inv == reference, (
+            f"admin header control inventory differs on {name}:\n"
+            f"  chat:   {reference}\n  {name}: {inv}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 2. Anonymous: the reduced bar — identically — on all five pages
+# ---------------------------------------------------------------------------
+
+
+def test_anonymous_inventory_identical_on_all_five_pages(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    page.set_viewport_size({"width": 1280, "height": 800})
+    _seed_db(mock_llm)
+
+    # No login: a fresh context is anonymous by construction.
+    inventories: dict[str, list[str]] = {}
+    for name, url in (
+        ("chat", CHAT_URL),
+        ("sources", SOURCES_URL),
+        ("viewer", VIEWER_URL),
+        ("tuning", TUNING_URL),
+        ("login", LOGIN_URL),
+    ):
+        inventories[name] = _visit(page, app_url, name, url, admin=False)
+
+    reference = inventories["chat"]
+    for name, inv in inventories.items():
+        assert inv == reference, (
+            f"anonymous header control inventory differs on {name}:\n"
+            f"  chat:   {reference}\n  {name}: {inv}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 3. Viewer: row 1 is exactly the chat bar's height (64px / 58px) and
+#    the titlebar row (back + title + meta) is present
+# ---------------------------------------------------------------------------
+
+
+def test_viewer_row1_height_matches_chat_and_titlebar_present(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    _seed_db(mock_llm)
+
+    for width, expected_h in ((1280, DESKTOP_HEADER_H), (375, MOBILE_HEADER_H)):
+        page.set_viewport_size({"width": width, "height": 800})
+
+        page.goto(app_url + CHAT_URL)
+        chat_h = _box_height(page, ".app-header")
+
+        page.goto(app_url + VIEWER_URL)
+        expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
+        # Row 1 IS the standard bar — the same --header-h as chat…
+        row1 = _box_height(page, ".doc-header .app-header")
+        assert row1 == expected_h, f"viewer row 1 is {row1}px at {width}px"
+        assert chat_h == expected_h, f"chat bar is {chat_h}px at {width}px"
+        assert row1 == chat_h, "viewer row 1 must match the chat bar exactly"
+        # …and the titlebar row exists below it (content-sized, > 0)…
+        titlebar = _box_height(page, ".doc-titlebar")
+        assert titlebar > 0, "the .doc-titlebar row is not rendered"
+        # …with the back link + the rendered title + the meta badges.
+        expect(page.locator("#doc-back")).to_be_visible()
+        expect(page.locator("#doc-title")).to_have_text(DOC_TITLE)
+        expect(page.locator("#doc-meta .doc-source-badge", has_text="docs")).to_be_visible()
+        expect(page.locator("#doc-meta .format-badge", has_text="md")).to_be_visible()
+
+
+# ---------------------------------------------------------------------------
+# 4. Viewer: #doc-back target resolution (phase 13) — one positive, one
+#    rejection case, both by clicking the link
+# ---------------------------------------------------------------------------
+
+
+def test_viewer_back_link_honors_back_param(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    page.set_viewport_size({"width": 1280, "height": 800})
+    _seed_db(mock_llm)
+
+    # Positive: back=/ (same-origin relative) is honored — href "/",
+    # label "Chat", and the click returns to the chat page.
+    page.goto(app_url + VIEWER_URL + "&back=%2F")
+    expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
+    back = page.locator("#doc-back")
+    expect(back).to_have_attribute("href", "/")
+    expect(back.locator("span")).to_have_text("Chat")
+    back.click()
+    expect(page).to_have_url(app_url + CHAT_URL, timeout=30_000)
+
+    # Rejection: an absolute URL is NOT same-origin-relative — the
+    # target falls back to the Sources page (label "Sources") and the
+    # click goes there.
+    page.goto(app_url + VIEWER_URL + "&back=https%3A%2F%2Fevil.example")
+    expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
+    back = page.locator("#doc-back")
+    expect(back).to_have_attribute("href", "/sources.html")
+    expect(back.locator("span")).to_have_text("Sources")
+    back.click()
+    expect(page).to_have_url(app_url + SOURCES_URL, timeout=30_000)
+
+
+# ---------------------------------------------------------------------------
+# 5. Steering works off-chat: on /tuning.html (admin, zero notes) the
+#    header toggle drives the panel — open/close cycle, empty state,
+#    count badge 0. No chat turn is needed.
+# ---------------------------------------------------------------------------
+
+
+def test_steering_panel_works_off_chat_on_tuning_page(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    page.set_viewport_size({"width": 1280, "height": 800})
+    _seed_db(mock_llm)  # truncates steering_notes → zero notes
+
+    login(page, app_url, next=TUNING_URL)
+    expect(page).to_have_url(app_url + TUNING_URL, timeout=30_000)
+    expect(page.locator("#sign-out-btn")).to_be_visible(timeout=15_000)
+
+    # Settled admin state: the toggle is on the bar, the panel ships
+    # hidden, and the count badge reads 0 (zero seeded notes).
+    expect(page.locator("#steering-toggle")).to_be_visible()
+    expect(page.locator("#steering-panel")).to_be_hidden()
+    expect(page.locator("#steering-count")).to_have_text("0")
+
+    # Open: the panel shows, the toggle's aria-expanded follows, and
+    # the empty state is visible (the re-open refresh fetched 0 notes).
+    page.click("#steering-toggle")
+    expect(page.locator("#steering-panel")).to_be_visible()
+    expect(page.locator("#steering-toggle")).to_have_attribute("aria-expanded", "true")
+    expect(page.locator("#steering-empty")).to_be_visible()
+    expect(page.locator("#steering-list .steering-note")).to_have_count(0)
+    expect(page.locator("#steering-count")).to_have_text("0")
+
+    # Close: the cycle completes, the count badge still reads 0.
+    page.click("#steering-toggle")
+    expect(page.locator("#steering-panel")).to_be_hidden()
+    expect(page.locator("#steering-toggle")).to_have_attribute("aria-expanded", "false")
+    expect(page.locator("#steering-count")).to_have_text("0")
+
+
+# ---------------------------------------------------------------------------
+# 6. Sync is present (admin) on a non-Sources page — and is NOT
+#    triggered: a real sync clones real repos; the full state machine
+#    is test_sync_button.py's job.
+# ---------------------------------------------------------------------------
+
+
+def test_sync_button_present_on_tuning_page_without_triggering(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    page.set_viewport_size({"width": 1280, "height": 800})
+    _seed_db(mock_llm)
+
+    login(page, app_url, next=TUNING_URL)
+    expect(page).to_have_url(app_url + TUNING_URL, timeout=30_000)
+    expect(page.locator("#sign-out-btn")).to_be_visible(timeout=15_000)
+
+    btn = page.locator("#sync-btn")
+    expect(btn).to_be_visible(timeout=15_000)
+    # Idle, retry-ready state — the boot re-attach (GET /api/sync/status,
+    # idle on the fresh app) must not have left it busy or labeled as a
+    # finished run.
+    expect(btn).to_be_enabled()
+    assert btn.get_attribute("aria-busy") is None, "a fresh idle sync must not be busy"
+    expect(page.locator("#sync-label")).to_have_text("Sync sources")
+    # Deliberately NOT clicked.

tests/e2e/test_shared_header.py

@@ -8,16 +8,20 @@ Run in isolation (DB must be up: ``podman compose up -d db``):
 Contract under test (owner report 2026-08-23, phase 19) — ONE bar per
 page, the same controls everywhere:
 
-* chat / sources: brand + nav [Chat, Sources — admin only] + New Chat
-  + Sign in / Sign out;
-* document viewer: back + title + New Chat + Sign in / Sign out (the
-  viewer has no nav, so no Sources link at all);
+* chat / sources / viewer: brand + nav [Chat, Sources — admin only] +
+  New Chat + Sign in / Sign out;
+* document viewer: the standard bar (row 1) + back + title + meta in a
+  second titlebar row (phase 34, owner confirmation 2026-08-26 — the
+  viewer's old "no nav" single-row bar is superseded; it now carries
+  the SAME nav contract as every other page);
 * the "Sources" nav link (``#nav-sources``) is HIDDEN for anonymous
-  users on every page that has a nav and shown for admin (phase-16 UX
-  revision with owner permission; the soft-gate page and the A10 API
-  split are untouched);
+  users on every page and shown for admin (phase-16 UX revision with
+  owner permission; the soft-gate page and the A10 API split are
+  untouched) — now on the viewer as well (phase 34);
 * the bar height never moves: 64px desktop / 58px at ≤640px (phase-12
-  ``--header-h`` contract, bounding-box measurement convention).
+  ``--header-h`` contract, bounding-box measurement convention) — on
+  the viewer this is ROW 1 (``.doc-header .app-header``); the
+  titlebar row is content-sized.
 
 Determinism note: every assertion is settled-state — ``assert_shared_bar``
 first waits for the whoami toggle to land (exactly one of Sign in /
@@ -109,7 +113,10 @@ def _expected_h(page: Page) -> int:
 
 
 def _bar_selector(page_kind: str) -> str:
-    return ".doc-header" if page_kind == "viewer" else ".app-header"
+    """The STANDARD bar element on each page kind. Phase 34: the
+    viewer's header is two rows — the height contract applies to row 1
+    (the standard bar), not the whole two-row <header>."""
+    return ".doc-header .app-header" if page_kind == "viewer" else ".app-header"
 
 
 def assert_shared_bar(page: Page, admin: bool, page_kind: str) -> None:
@@ -134,24 +141,26 @@ def assert_shared_bar(page: Page, admin: bool, page_kind: str) -> None:
     # New Chat is on the bar on every page kind (the owner's ask).
     expect(page.locator("#new-chat-btn")).to_be_visible()
 
-    if page_kind == "viewer":
-        # The viewer has no nav — no Sources link in the DOM at all.
-        assert page.locator("#nav-sources").count() == 0, (
-            "the viewer bar must not carry a Sources nav link"
-        )
-        # The document itself has settled (rendered, not Loading…/not-found)
-        # so the bar is being measured on the real page.
-        expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
-    else:
-        # The Sources nav link: admin-only (phase-16 revision, owner
-        # permission 2026-08-23) — hidden for anonymous, shown for admin.
-        nav = page.locator("#nav-sources")
-        assert nav.count() == 1, f"one #nav-sources expected on the {page_kind} page"
+    # Phase 34: EVERY page kind — viewer included — carries the SAME
+    # nav contract: the Chat link always visible; the admin-only
+    # #nav-sources / #nav-tuning links (phase 19 / phase 29) ship
+    # hidden and are revealed for admin (phase-16 UX revision, owner
+    # permission 2026-08-23; the soft-gate page and the A10 API split
+    # are untouched).
+    expect(page.locator(".app-nav a[href='/']")).to_be_visible()
+    for link_id in ("#nav-sources", "#nav-tuning"):
+        nav = page.locator(link_id)
+        assert nav.count() == 1, f"one {link_id} expected on the {page_kind} page"
         if admin:
             expect(nav).to_be_visible()
         else:
             expect(nav).to_be_hidden()
 
+    if page_kind == "viewer":
+        # The document itself has settled (rendered, not Loading…/not-found)
+        # so the bar is being measured on the real page.
+        expect(page.locator("#doc-title")).to_have_text(DOC_TITLE, timeout=15_000)
+
     # The bar height never moves: 64px desktop / 58px ≤640px (phase 12),
     # bounding-box measurement — the new pills must fit inside it.
     box = page.locator(_bar_selector(page_kind)).bounding_box()
@@ -238,8 +247,9 @@ def test_sources_nav_hidden_for_anonymous_everywhere(
         assert nav.count() == 1
         expect(nav).to_be_hidden()
 
-    # The login page has no chat controls — header.js only toggles the
-    # nav link there; for anonymous it stays hidden (it ships hidden).
+    # The login page carries the full shared header too (phase 34);
+    # for anonymous the admin-only nav links stay hidden (they ship
+    # hidden and are revealed only for the admin).
     page.goto(app_url + "/login.html")
     page.wait_for_load_state("networkidle")  # the whoami round-trip has settled
     nav = page.locator("#nav-sources")

tests/unit/test_caching.py

@@ -59,6 +59,8 @@ def _make_git_repo(base: Path) -> tuple[Path, str]:
         "user.name=test",
         "-c",
         "user.email=test@example.com",
+        "-c",
+        "commit.gpgsign=false",  # the fixture commit never signs (env gpg)
         "commit",
         "-q",
         "-m",

tests/unit/test_shared_header.py

@@ -3,9 +3,10 @@
 The browser behavior is E2E-covered (tests/e2e/test_shared_header.py);
 here we pin the source-level wiring — the header.js exports, the cached
 whoami promise, the per-page HTML ids (anonymous-safe hidden-by-default
-controls), the sign-out binding move out of app.js, the non-chat New
-Chat bindings, and the viewer-bar CSS — so a silent regression is caught
-without a browser.
+controls), the sign-out binding move out of app.js, the SINGLE
+module-owned New chat binding (phase 34 task 02) + the sign-in
+?next= rewrite, and the viewer-bar CSS — so a silent regression is
+catched without a browser.
 """
 from __future__ import annotations
 
@@ -109,17 +110,75 @@ def test_sign_out_binding_lives_in_the_shared_module() -> None:
 
 
 def test_nav_sources_ships_hidden_on_every_nav_page() -> None:
-    """Phase 19 UX revision (owner permission 2026-08-23): the Sources
-    nav link is hidden for anonymous — so it SHIPS with the hidden
-    attribute (anonymous-safe default) on every page that has a nav
-    (chat, sources, login)."""
-    for html in (INDEX_HTML, SOURCES_HTML, LOGIN_HTML, TUNING_HTML):
+    """Phase 19 UX revision (owner permission 2026-08-23), completed on
+    all five pages by phase 34 task 03 (owner confirmation 2026-08-26):
+    the Sources nav link is hidden for anonymous — so it SHIPS with the
+    hidden attribute (anonymous-safe default) on every page (they all
+    carry the nav now, viewer included)."""
+    for html in (INDEX_HTML, SOURCES_HTML, DOCUMENT_HTML, LOGIN_HTML, TUNING_HTML):
         text = _text(html)
         assert re.search(r'id="nav-sources"[^>]*\bhidden\b', text), (
             f"{html.name}: #nav-sources must ship hidden"
         )
 
 
+def test_all_five_pages_share_the_header_control_order() -> None:
+    """Phase 34 task 03 (owner confirmation 2026-08-26): every page
+    ships the IDENTICAL header control inventory in the IDENTICAL
+    order — brand, nav [Chat, Sources, Tuning], #steering-toggle,
+    #sync-btn, #new-chat-btn, Sign in, Sign out — inside the shared
+    .header-inner row (the document viewer's row 1). Only the
+    current-page is-active nav marker and the static ?next= fallback
+    may differ per page (task 05's story E2E pins the rendered
+    result)."""
+    markers = (
+        'class="brand"',
+        '<nav class="app-nav"',
+        'href="/"',
+        'id="nav-sources"',
+        'id="nav-tuning"',
+        'id="steering-toggle"',
+        'id="sync-btn"',
+        'id="new-chat-btn"',
+        'id="sign-in-link"',
+        'id="sign-out-btn"',
+    )
+    for html in (INDEX_HTML, SOURCES_HTML, DOCUMENT_HTML, TUNING_HTML, LOGIN_HTML):
+        text = _text(html)
+        start = text.find('<div class="container header-inner">')
+        assert start != -1, f"{html.name}: missing the shared .header-inner row"
+        region = text[start : text.find("</header>", start)]
+        missing = [m for m in markers if m not in region]
+        assert not missing, f"{html.name}: header controls missing {missing}"
+        for m in markers:
+            assert region.count(m) == 1, f"{html.name}: {m} must appear exactly once"
+        # Same order on every page: each control follows the previous one.
+        pos = -1
+        for m in markers:
+            idx = region.find(m, pos + 1)
+            assert idx > pos, f"{html.name}: {m} out of order in the shared bar"
+            pos = idx
+
+
+def test_all_five_pages_carry_the_steering_panel() -> None:
+    """Phase 34 task 03: the #steering-panel section (+ the
+    #steering-announcer live region) ships on every page — after
+    #kb-banner in the chat shell, first child of <main> on the other
+    four pages — ship hidden, driven by assets/header.js."""
+    for html in (INDEX_HTML, SOURCES_HTML, DOCUMENT_HTML, TUNING_HTML, LOGIN_HTML):
+        text = _text(html)
+        tag = re.search(r'<section[^>]*id="steering-panel"[^>]*>', text)
+        assert tag, f"{html.name}: missing the #steering-panel section"
+        assert re.search(r'\bhidden\b', tag.group(0)), "the panel ships hidden"
+        assert 'id="steering-list"' in text
+        assert 'id="steering-empty"' in text
+        assert re.search(r'<p[^>]*id="steering-announcer"[^>]*role="status"[^>]*>', text), (
+            f"{html.name}: missing the #steering-announcer live region"
+        )
+        # The announcer follows the panel (the copied index.html block).
+        assert text.find('id="steering-panel"') < text.find('id="steering-announcer"')
+
+
 def test_nav_tuning_ships_hidden_on_the_tuning_page() -> None:
     """Phase 27: the Global Tuning page reuses the shared header — the
     "Tuning" nav link is admin-only, so it SHIPS hidden (revealed by
@@ -139,10 +198,38 @@ def test_nav_tuning_ships_hidden_on_the_tuning_page() -> None:
     assert [s for s in srcs if "tuning.js" in s]
 
 
-def test_nav_sources_is_absent_from_the_viewer() -> None:
-    """The document viewer has no nav — no #nav-sources element there (the
-    module's missing-element no-op keeps it out)."""
-    assert 'id="nav-sources"' not in _text(DOCUMENT_HTML)
+def test_viewer_carries_the_standard_nav() -> None:
+    """Phase 34 task 03 (owner confirmation 2026-08-26): the document
+    viewer carries the SAME standard bar as every other page — row 1 is
+    the shared .header-inner block, so the nav (Chat + the admin-only
+    #nav-sources / #nav-tuning links, ship hidden) is there too. No nav
+    link is "current" on the viewer: a document is a detail view
+    reachable from chat or Sources, and the phase-13 back link (row 2)
+    carries the return affordance. The phase-19 single-row bar
+    (.doc-header-actions) is superseded by the two-row layout —
+    .doc-titlebar keeps #doc-back / #doc-title / #doc-meta, so
+    document.js needs no render change."""
+    text = _text(DOCUMENT_HTML)
+    chat = re.search(r'<a[^>]*href="/"[^>]*>Chat</a>', text)
+    assert chat, "the viewer bar carries the standard nav"
+    assert "is-active" not in chat.group(0), "no nav link is current on the viewer"
+    for link in ("nav-sources", "nav-tuning"):
+        tag = re.search(rf'<a[^>]*id="{link}"[^>]*>', text)
+        assert tag, f"the viewer bar must carry #{link}"
+        assert "hidden" in tag.group(0), f"#{link} must ship hidden (admin-only)"
+        assert "is-active" not in tag.group(0)
+    # Row 1 is the standard bar inside the two-row viewer header.
+    assert re.search(r'<header[^>]*class="doc-header"', text), "the header keeps .doc-header"
+    assert 'class="app-header"' in text, "row 1 reuses the .app-header bar"
+    assert 'doc-header-inner' not in text, "the old single-row wrapper is gone"
+    assert 'doc-header-actions' not in text, "the old actions wrapper is gone"
+    # Row 2: the .doc-titlebar keeps the back link + title + meta.
+    assert 'class="doc-titlebar"' in text, "row 2 must be the .doc-titlebar"
+    assert 'id="doc-back"' in text
+    assert 'id="doc-title"' in text
+    assert 'id="doc-meta"' in text
+    back = re.search(r'<a[^>]*id="doc-back"[^>]*href="/sources.html"', text)
+    assert back, "the back link keeps its /sources.html no-JS fallback"
 
 
 def test_sources_and_viewer_carry_the_shared_controls() -> None:
@@ -197,14 +284,31 @@ def test_header_module_loads_before_the_page_script() -> None:
         )
 
 
-def test_login_page_carries_no_chat_controls() -> None:
-    """Noted boundary (owner-confirmed): the login page is the auth page,
-    not an app page — no New Chat / Sign in / Sign out controls there;
-    header.js only toggles the Sources link."""
+def test_login_page_carries_the_full_header() -> None:
+    """Phase 34 task 03 (owner confirmation 2026-08-26): the noted
+    boundary is reversed by owner decision — the login page finally
+    carries the FULL shared header: the nav gains the #nav-tuning link
+    (same ship-hidden markup as the other pages), plus the Tuning
+    toggle, the admin-only Sync button, New chat, and the Sign in /
+    Sign out pair (ship hidden — initSharedHeader reveals exactly one
+    after whoami; the static ?next= fallback is the login page itself).
+    No nav link is "current" on the auth page."""
     text = _text(LOGIN_HTML)
-    assert "new-chat-btn" not in text
-    assert "sign-in-link" not in text
-    assert "sign-out-btn" not in text
+    for marker in (
+        'id="nav-sources"',
+        'id="nav-tuning"',
+        'id="steering-toggle"',
+        'id="sync-btn"',
+        'id="new-chat-btn"',
+        'id="sign-in-link"',
+        'id="sign-out-btn"',
+    ):
+        assert marker in text, f"login.html must carry {marker} (phase 34 full header)"
+    assert 'href="/login.html?next=/login.html"' in text, (
+        "the login page's Sign in returns to the login page (no-JS fallback)"
+    )
+    for tag in re.findall(r'<a[^>]*class="nav-link[^"]*"[^>]*>', text):
+        assert "is-active" not in tag, "no nav link is current on the login page"
 
 
 # ---------- page-script adaptations ----------
@@ -249,40 +353,206 @@ def test_login_js_uses_the_shared_fetch_is_admin() -> None:
     assert "window.location.replace(safeNext())" in js
 
 
-def test_non_chat_pages_bind_new_chat_to_the_chat_page() -> None:
-    """On sources, the viewer, and the tuning page, New Chat means "go to
-    the chat, fresh": the binding clears the phase-14 key
-    (clearChatStorage) and navigates to "/" — and each page runs
-    initSharedHeader() at boot on the shared cached whoami. Phase 23:
+def test_new_chat_binding_is_single_and_module_owned() -> None:
+    """Phase 34 task 02: header.js owns the SINGLE #new-chat-btn binding
+    (module import, like the sign-out binding): on the chat page
+    (#messages exists) it dispatches window "bor:new-chat" — app.js acts
+    through its own in-flight-turn guard + list reset; on every other
+    page it means "go to the chat, fresh" (clearChatStorage + navigate
+    to "/"). NO page script binds #new-chat-btn anymore, and each page
+    still runs initSharedHeader() on the shared cached whoami. Phase 23:
     the import is relative (`./header.js`)."""
+    js = _text(HEADER_JS)
+    assert 'querySelector("#new-chat-btn")' in js
+    assert "newChatBtn.addEventListener" in js
+    assert 'querySelector("#messages")' in js, "the chat-page branch key"
+    assert 'new CustomEvent("bor:new-chat")' in js
+    assert "clearChatStorage();" in js
+    assert 'window.location.href = "/"' in js
     for js_file in (SOURCES_JS, DOCUMENT_JS, TUNING_JS):
-        js = _text(js_file)
-        assert 'from "./header.js"' in js
-        assert "initSharedHeader()" in js
-        btn_idx = js.find("new-chat-btn")
-        clear_idx = js.find("clearChatStorage();")
-        nav_idx = js.find('window.location.href = "/"')
-        assert -1 < btn_idx < clear_idx < nav_idx, (
-            f"{js_file.name}: #new-chat-btn must clear storage then navigate to '/'"
+        page_js = _text(js_file)
+        assert 'from "./header.js"' in page_js
+        assert "initSharedHeader()" in page_js
+        assert "new-chat-btn" not in page_js, (
+            f"{js_file.name}: no #new-chat-btn binding (the module owns it)"
         )
-        assert 'fetch("/api/whoami")' not in js, (
+        assert 'fetch("/api/whoami")' not in page_js, (
             f"{js_file.name}: whoami goes through the shared cached promise"
         )
-
-
-# ---------- viewer-bar CSS ----------
-
-
-def test_viewer_bar_css_pushes_actions_right_and_title_clips() -> None:
-    """styles.css defines .doc-header-actions (margin-left:auto flex
-    cluster) and the title block keeps min-width: 0 so
-    #doc-title/#doc-meta clip instead of overflowing the --header-h bar."""
-    css = _text(STYLES_CSS)
-    block = re.search(r"\.doc-header-actions\s*\{([^}]*)\}", css)
-    assert block, "styles.css must define .doc-header-actions"
-    body = block.group(1)
-    assert "margin-left: auto" in body
-    assert "display: flex" in body
-    assert re.search(r"\.doc-title-block\s*\{[^}]*min-width:\s*0", css), (
-        "the title block must keep clipping while the pills fit"
+    app_js = _text(APP_JS)
+    assert 'window.addEventListener("bor:new-chat", startNewChat)' in app_js
+    assert "newChatBtn.addEventListener" not in app_js, (
+        "app.js acts off the module's event, not its own binding"
     )
+
+
+def test_init_shared_header_rewrites_sign_in_next_to_current_page() -> None:
+    """Phase 34 task 02: initSharedHeader points #sign-in-link at
+    /login.html?next=<current pathname> (default "/") — the admin lands
+    back on the page they signed in from. The page markup keeps its own
+    static ?next= as the no-JS fallback."""
+    js = _text(HEADER_JS)
+    fn = js.find("function initSharedHeader")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    # raw pathname (always a query-safe "/…" string — never "//", and ?
+    # # / spaces stay percent-encoded inside it; login.js safeNext
+    # re-validates), same shape as the static markup fallbacks
+    assert '"/login.html?next=" + (window.location.pathname || "/")' in body
+
+
+# ---------- phase 34 task 01: the steering controls move to the module ----------
+# (task 02 — the sync machine + New chat + sign-in next — is pinned in
+# test_sync_button.py / above)
+
+
+def test_header_module_owns_the_steering_panel() -> None:
+    """header.js owns the steering panel behavior (moved from app.js in
+    phase 34 task 01): the module-level null-safe element refs, the
+    newest-first textContent render (XSS contract), the labeled
+    per-note delete, the count badge, the announcer, and the toggle
+    binding that runs at module import (like the sign-out binding)."""
+    js = _text(HEADER_JS)
+    for selector in (
+        "#steering-toggle",
+        "#steering-count",
+        "#steering-panel",
+        "#steering-list",
+        "#steering-empty",
+        "#steering-announcer",
+    ):
+        assert f'querySelector("{selector}")' in js, f"missing {selector} ref"
+    assert "function renderSteeringPanel" in js
+    assert "text.className = \"steering-note-text\"" in js
+    assert "text.textContent = n.note" in js, (
+        "XSS contract: the note renders via textContent, never innerHTML"
+    )
+    assert 'del.setAttribute("aria-label", `Delete tuning note: ${n.note}`)' in js
+    assert "async function deleteSteeringNote" in js
+    assert 'fetch(`/api/steering/${encodeURIComponent(id)}`, { method: "DELETE" })' in js
+    assert "steeringToggle.addEventListener" in js, "the toggle binding is module-owned"
+    assert 'setAttribute("aria-expanded"' in js
+    assert "refreshSteering()" in js  # re-open refreshes the list
+
+
+def test_header_module_exports_refresh_and_announce_steering() -> None:
+    """refreshSteering() (fetch + render; non-2xx / unreachable API →
+    the empty list state) and announceSteering() (the polite live
+    region) are exported for the chat page's per-bubble Tune form.
+    """
+    js = _text(HEADER_JS)
+    assert "export async function refreshSteering" in js
+    fn = js.find("function refreshSteering")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    assert 'fetch("/api/steering")' in body
+    assert "renderSteeringPanel(notes)" in body
+    assert "export function announceSteering" in js
+    ann = js.find("function announceSteering")
+    assert ann != -1
+    ann_body = js[ann : js.find("\n}", ann)]
+    assert "steeringAnnouncer.textContent = message" in ann_body
+
+
+def test_init_shared_header_gates_the_steering_surface() -> None:
+    """Inside initSharedHeader: admin → the list refreshes (count badge
+    right before the panel is ever opened; only when the page ships the
+    panel markup); anonymous → the toggle + panel are REMOVED from the
+    DOM (phase-16 'absent, not hidden') and /api/steering is never
+    fetched."""
+    js = _text(HEADER_JS)
+    fn = js.find("function initSharedHeader")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    assert "if (steeringPanel) refreshSteering();" in body
+    assert "steeringToggle?.remove();" in body
+    assert "steeringPanel?.remove();" in body
+
+
+def test_app_js_no_longer_owns_the_steering_panel() -> None:
+    """app.js keeps only the chat-specific per-bubble Tune button +
+    inline form: the panel refs + logic are gone (header.js owns them
+    now), and the form's success path awaits the module's
+    refreshSteering() (announcing through the module's
+    announceSteering()). The form's POST /api/steering + error handling
+    stay in app.js, untouched."""
+    js = _text(APP_JS)
+    for gone in (
+        "steeringToggle",
+        "steeringCount",
+        "steeringPanel",
+        "steeringList",
+        "steeringEmpty",
+        "steeringAnnouncer",
+        "loadSteering",
+        "renderSteeringPanel",
+        "deleteSteeringNote",
+        "setSteeringPanel",
+        'querySelector("#steering-toggle")',
+    ):
+        assert gone not in js, f"{gone!r} must be gone from app.js (header.js owns it)"
+    # the chat-specific part survives and is wired to the shared module
+    assert "function appendTuneButton" in js
+    assert "function openTuneForm" in js
+    assert "TUNE_ICON" in js
+    assert 'from "./header.js"' in js
+    assert "refreshSteering" in js and "announceSteering" in js
+    assert "await refreshSteering()" in js
+    assert 'fetch("/api/steering", {' in js  # the form's POST still lives here
+
+
+# ---------- viewer two-row-header CSS (phase 34 task 04) ----------
+
+
+def test_viewer_two_row_header_css() -> None:
+    """Phase 34 task 04: the viewer header is two rows — row 1 reuses
+    the .app-header / .header-inner rules verbatim (the pinned
+    --header-h height still applies to row 1), row 2 is the
+    .doc-titlebar: a quiet --line border-top separator, a flex
+    .container row, its own content-sized height. The old single-row
+    .doc-header-actions / .doc-header-inner rules are gone, .doc-header
+    no longer pins a fixed height, and .doc-title-block keeps
+    min-width: 0 so #doc-title / #doc-meta ellipsize in the row."""
+    css = _text(STYLES_CSS)
+    block = re.search(r"\.doc-titlebar\s*\{([^}]*)\}", css)
+    assert block, "styles.css must define .doc-titlebar"
+    body = block.group(1)
+    assert "border-top: 1px solid var(--line)" in body, (
+        "the titlebar separates from row 1 with the quiet hairline"
+    )
+    assert "height: var(--header-h)" not in body, (
+        "the titlebar row is content-sized (title line + meta line)"
+    )
+    assert re.search(r"\.doc-titlebar\s*\.container\s*\{[^}]*display:\s*flex", css), (
+        "the titlebar row must be a flex row (back link + title block)"
+    )
+    assert re.search(r"\.doc-header-actions\s*\{", css) is None, (
+        "the old single-row actions cluster rule is gone"
+    )
+    assert re.search(r"\.doc-header-inner\s*\{", css) is None, (
+        "the old single-row wrapper rule is gone"
+    )
+    header_block = re.search(r"\.doc-header\s*\{([^}]*)\}", css)
+    assert header_block, "styles.css must still style the .doc-header header element"
+    assert "height: var(--header-h)" not in header_block.group(1), (
+        "the two-row header is content-sized — row 1 keeps the pinned height"
+    )
+    assert re.search(r"\.doc-title-block\s*\{[^}]*min-width:\s*0", css), (
+        "the title block must keep clipping while the row stays tidy"
+    )
+
+
+def test_failed_sync_button_carries_the_error_look() -> None:
+    """Phase 34 task 04: the #sync-btn now lives on every page, and the
+    non-Sources pages have no error banner — the failed state must be
+    visible on the button itself. header.js adds .is-error (with the
+    sanitized error in title / aria-label); styles.css must render it
+    with the phase-08 error pair (--err-ink on --err-bg ≈9.1:1,
+    --err-line border — never the amber deflection accent)."""
+    css = _text(STYLES_CSS)
+    block = re.search(r"\.sync-btn\.is-error\s*\{([^}]*)\}", css)
+    assert block, "styles.css must define the failed .sync-btn look"
+    body = block.group(1)
+    assert "var(--err-bg)" in body
+    assert "var(--err-ink)" in body
+    assert "var(--accent-" not in body, "the amber deflection accent is never on errors"

tests/unit/test_sync_button.py

@@ -3,10 +3,13 @@
 The browser behavior is E2E-covered (tests/e2e/test_sync_button.py,
 task 03); here we pin the source-level wiring — the anonymous-safe
 ship-hidden button markup, the header.js admin reveal on the SAME
-cached whoami (no extra fetch), the sources.js sync state machine
-(2 s poll, 202 start / 409 adoption / 403 hide, terminal labels,
-the aria-live result, the single-poll-loop guard, no client-side hard
-timeout), the §7.4 never-stale CSS (spin + reduced-motion opt-out,
+cached whoami (no extra fetch), the header.js sync state machine
+(moved here from sources.js in phase 34 task 02: 2 s poll, 202 start
+/ 409 adoption / 403 hide, terminal labels, the "bor:sync-status"
+event with the status object as detail, the single-poll-loop guard, no
+client-side hard timeout), the Sources page's event-driven
+#sync-result line + #sync-error-banner, and the §7.4 never-stale CSS
+(spin + reduced-motion opt-out,
 disabled state, 44px floor, contrast pair) — so a silent regression is
 caught without a browser.
 """
@@ -117,103 +120,114 @@ def test_sources_page_stays_cdn_free() -> None:
 
 def test_header_reveals_sync_btn_on_the_admin_branch() -> None:
     """initSharedHeader reveals #sync-btn in the SAME admin branch as
-    #nav-sources (querySelector + hidden = !admin) — one cached whoami,
-    no extra whoami call; anonymous users never leave the hidden
-    default."""
+    #nav-sources (hidden = !admin) — one cached whoami, no extra
+    whoami call; anonymous users never leave the hidden default. The
+    ref is the module-level one — the state machine shares it."""
     js = _text(HEADER_JS)
+    assert 'querySelector("#sync-btn")' in js, "module-level #sync-btn ref"
     fn = js.find("function initSharedHeader")
     assert fn != -1
     body = js[fn : js.find("\n}", fn)]
-    assert 'querySelector("#sync-btn")' in body, "#sync-btn must join the admin reveal"
-    assert "syncBtn.hidden = !admin" in body
+    assert "syncBtn.hidden = !admin" in body, "#sync-btn must join the admin reveal"
     # The reveal must not introduce a second whoami call site.
     assert js.count('fetch("/api/whoami")') == 1
 
 
-# ---------- sources.js: the sync state machine ----------
+# ---------- header.js: the sync state machine (moved here from
+# ---------- sources.js in phase 34 task 02) ----------
 
 
-def test_sources_js_calls_the_sync_api() -> None:
+def test_header_js_owns_the_sync_button_elements() -> None:
+    """The button refs are module-level and null-safe: #sync-btn,
+    #sync-label, the .sync-icon inside the button — a page without the
+    markup is a complete no-op, exactly like the rest of the module."""
+    js = _text(HEADER_JS)
+    assert 'querySelector("#sync-btn")' in js
+    assert 'querySelector("#sync-label")' in js
+    assert 'syncBtn.querySelector(".sync-icon")' in js
+
+
+def test_header_js_calls_the_sync_api() -> None:
     """The click posts to POST /api/sync and the poll loop GETs
     /api/sync/status — both through the same-origin API (A10)."""
-    js = _text(SOURCES_JS)
+    js = _text(HEADER_JS)
     assert 'fetch("/api/sync", { method: "POST" })' in js
     assert 'fetch("/api/sync/status")' in js
 
 
-def test_sources_js_polls_every_2000ms() -> None:
+def test_header_js_polls_every_2000ms() -> None:
     """The feedback loop is a 2000 ms poll of the status endpoint,
     re-scheduled one tick at a time (setTimeout, not setInterval — an
     in-flight fetch can never overlap the next tick)."""
-    js = _text(SOURCES_JS)
+    js = _text(HEADER_JS)
     assert "SYNC_POLL_MS = 2000" in js
     assert "setTimeout(tick, SYNC_POLL_MS)" in js
     assert "setInterval" not in js
 
 
-def test_sources_js_adopts_409_and_starts_on_202() -> None:
+def test_header_js_adopts_409_and_starts_on_202() -> None:
     """202 (started) and 409 (a run started elsewhere — e.g. a second
     tab) both enter the running state and start polling: the UI never
     starts a second run, it adopts the in-flight one."""
-    js = _text(SOURCES_JS)
+    js = _text(HEADER_JS)
     assert "r.status === 202 || r.status === 409" in js
     idx = js.find("r.status === 202 || r.status === 409")
-    branch = js[idx : idx + 200]
-    assert "enterRunningState()" in branch
+    branch = js[idx : idx + 400]
+    assert "enterSyncRunningState()" in branch
     assert "startSyncPolling()" in branch
 
 
-def test_sources_js_hides_the_button_on_403() -> None:
-    """A 403 anywhere (POST or poll) is treated as not-admin: the
-    button hides — defense in depth behind header.js's whoami reveal."""
-    js = _text(SOURCES_JS)
-    for occurrence in re.finditer(r"r\.status === 403", js):
-        window = js[occurrence.start() : occurrence.start() + 400]
-        assert "syncBtn.hidden = true" in window, "every 403 branch must hide the button"
+def test_header_js_hides_the_button_on_403() -> None:
+    """A 403 anywhere (POST, the status poll, the load re-attach) is
+    treated as not-admin: the button hides — defense in depth behind
+    the whoami reveal (the primary gate)."""
+    js = _text(HEADER_JS)
     assert len(re.findall(r"r\.status === 403", js)) >= 3, (
         "POST, the status poll, and the load re-attach must all handle 403"
     )
+    assert js.count("syncBtn.hidden = true") >= 3, (
+        "every 403 branch must hide the button"
+    )
 
 
-def test_sources_js_running_state_is_never_stale() -> None:
+def test_header_js_running_state_is_never_stale() -> None:
     """Entering the running state disables the button, sets aria-busy,
     spins the icon, and swaps the label to 'Syncing…' (the §7.4
-    feedback while the poll waits)."""
-    js = _text(SOURCES_JS)
-    fn = js.find("function enterRunningState")
-    assert fn != -1
-    body = js[fn : js.find("\n}", fn)]
+    feedback while the poll waits) — and a fresh run starts clean: the
+    previous failure's title / aria-label / .is-error come off NOW,
+    not when the run settles."""
+    js = _text(HEADER_JS)
+    body = _body(js, "enterSyncRunningState")
     assert "syncBtn.disabled = true" in body
     assert 'syncBtn.setAttribute("aria-busy", "true")' in body
+    assert 'syncBtn.removeAttribute("title")' in body
+    assert 'syncBtn.setAttribute("aria-label", "Sync sources")' in body
+    assert "syncBtn.classList.remove(\"is-error\")" in body
     assert "syncIcon.classList.add(\"is-spinning\")" in body
     assert '"Syncing…"' in body
 
 
-def test_sources_js_terminal_states() -> None:
+def test_header_js_terminal_states() -> None:
     """Terminal rendering: success → enabled + 'Synced HH:MM' (local
-    time of finished_at) + the last-result counts ('added' always
-    announced, zero terms omitted — a no-op re-sync reads '0 added ·
-    1 unchanged', never an empty live region) + a live catalog refresh
-    (the KB just changed — never a stale table); failed → enabled +
-    retry-ready 'Sync sources' label + the role='alert' banner with
-    the error; the result is cleared on a failure."""
-    js = _text(SOURCES_JS)
+    time of finished_at); failed → enabled + retry-ready 'Sync sources'
+    label + the sanitized error in the button's title + aria-label +
+    the .is-error class (non-Sources pages: that is where the failure
+    is visible). The counts formatting (fmtSyncResult) lives here and
+    is EXPORTED for the Sources page ('added' always announced, zero
+    terms omitted — a no-op re-sync reads '0 added · 1 unchanged')."""
+    js = _text(HEADER_JS)
 
     success = _body(js, "applySyncSuccess")
     assert '"Synced"' in success and "fmtSyncTime(status.finished_at)" in success
-    assert "fmtSyncResult(status.detail)" in success
-    # A successful sync just changed the KB: the catalog re-fetches live
-    # (table / stats / empty state never sit stale under "Synced").
-    assert "loadDocs()" in success
 
     failure = _body(js, "applySyncFailure")
     assert 'settleSyncButton("Sync sources")' in failure  # retry-ready
-    assert "showSyncError(status.error)" in failure
+    assert "syncBtn.title = error" in failure
+    assert 'syncBtn.setAttribute("aria-label", error)' in failure
+    assert "syncBtn.classList.add(\"is-error\")" in failure
+    assert "sanitizeSyncError(status.error)" in failure
 
     result = _body(js, "fmtSyncResult")
-    # "added" is the always-announced headline term; "unchanged" covers
-    # the no-op case ("0 added · 1 unchanged"); updated/pruned are
-    # zero-omitted.
     assert "added" in result and "unchanged" in result
     assert " · " in result
     assert "> 0" in result, "zero terms must be omitted"
@@ -222,26 +236,38 @@ def test_sources_js_terminal_states() -> None:
     assert "getHours()" in time and "getMinutes()" in time, "local HH:MM of finished_at"
 
 
-def test_sources_js_settles_the_button_on_terminal() -> None:
-    """settleSyncButton re-enables the control, drops aria-busy, and
-    un-spins the icon — the button can never sit disabled after a run
-    reaches a terminal state (failed included: retry-ready)."""
-    js = _text(SOURCES_JS)
-    fn = js.find("function settleSyncButton")
-    assert fn != -1
-    body = js[fn : js.find("\n}", fn)]
+def test_header_js_failed_error_is_sanitized() -> None:
+    """The button's title/aria-label error is sanitized for the
+    attributes: the server already masks credentials (sync.py
+    _sanitize_error); the module collapses whitespace to a single line
+    and caps the length, and a missing error still names a failure."""
+    js = _text(HEADER_JS)
+    body = _body(js, "sanitizeSyncError")
+    assert "replace(/\\s+/g, \" \")" in body, "single line for the attributes"
+    assert "200" in body, "long errors (chatty git stderr) are capped"
+    assert '"The sync failed."' in body
+
+
+def test_header_js_settles_the_button_on_terminal() -> None:
+    """settleSyncButton re-enables the control, drops aria-busy, the
+    title, and the failed affordances, and un-spins the icon — the
+    button can never sit disabled after a run reaches a terminal state
+    (failed included: retry-ready)."""
+    js = _text(HEADER_JS)
+    body = _body(js, "settleSyncButton")
     assert "syncBtn.disabled = false" in body
     assert 'syncBtn.removeAttribute("aria-busy")' in body
+    assert 'syncBtn.removeAttribute("title")' in body
+    assert 'syncBtn.setAttribute("aria-label", "Sync sources")' in body
     assert "syncIcon.classList.remove(\"is-spinning\")" in body
 
 
-def test_sources_js_never_starts_a_second_poll_loop() -> None:
+def test_header_js_never_starts_a_second_poll_loop() -> None:
     """startSyncPolling is guarded by the module-level timer: a 409
     adoption, a reload re-attach, or a stray call can never run two
     poll loops at once (phase completion criterion)."""
-    js = _text(SOURCES_JS)
+    js = _text(HEADER_JS)
     fn = js.find("function startSyncPolling")
-    assert fn != -1
     head = js[fn : js.find("const tick", fn)]
     assert re.search(r"if\s*\(\s*syncPollTimer\s*!==\s*null\s*\)\s*return", head), (
         "the single-loop guard must be the first statement"
@@ -249,37 +275,103 @@ def test_sources_js_never_starts_a_second_poll_loop() -> None:
     assert "clearTimeout(syncPollTimer)" in _body(js, "stopSyncPolling")
 
 
-def test_sources_js_has_no_client_side_hard_timeout() -> None:
-    """Phase locked decision: a sync can legitimately run for minutes,
-    so there is NO client-side hard timeout — the 2 s poll is the
-    feedback loop and the server state is authoritative (the 120 s
-    LLM-turn guard must not leak into the sync path)."""
-    js = _text(SOURCES_JS)
+def test_header_js_has_no_client_side_hard_timeout() -> None:
+    """Phase locked decision: a sync can legitimately run for minutes
+    (and outlive the page), so there is NO client-side hard timeout —
+    the 2 s poll is the feedback loop and the server state is
+    authoritative (the 120 s LLM-turn guard must not leak into the
+    sync path)."""
+    js = _text(HEADER_JS)
     assert "TURN_TIMEOUT" not in js
-    assert "120" not in js[js.find("Phase 32") :], (
-        "no turn-timeout constant in the sync section"
-    )
+    sync_start = js.find("sync sources (phase 32")
+    assert sync_start != -1, "the sync section marker comment"
+    assert "120" not in js[sync_start:]
 
 
-def test_sources_js_reattaches_on_load() -> None:
-    """initSyncButton (run from the IIFE on the admin path, after
-    initSharedHeader) fetches the status once and re-enters the running
-    state on 'running' (reload mid-sync) or renders the last result on
-    a terminal state; the click binding wires startSync to the button."""
-    js = _text(SOURCES_JS)
+def test_header_js_reattaches_on_load_admin_only() -> None:
+    """initSyncButton (run at module import, button pages only) awaits
+    the SAME cached whoami — ADMIN ONLY (non-admins never poll, the
+    status endpoint is admin-only): a running run re-enters the
+    running state (reload mid-sync), a terminal run renders its last
+    result, idle settles retry-ready; the click binding wires
+    startSync to the button."""
+    js = _text(HEADER_JS)
     fn = js.find("function initSyncButton")
     assert fn != -1
     body = js[fn : js.find("\n}\n", fn)]
+    assert "await fetchIsAdmin()" in body, "admin-only boot (no extra fetch)"
     assert 'fetch("/api/sync/status")' in body
     assert 'status.state === "running"' in body
     assert 'status.state === "success"' in body
     assert 'status.state === "failed"' in body
     assert "syncBtn.addEventListener(\"click\", startSync)" in js
-    # The IIFE runs it on the admin path only (after the whoami gate).
-    iife = js[js.find("(async () => {") :]
-    admin_idx = iife.find("await isAdmin()")
-    init_idx = iife.find("initSyncButton();")
-    assert -1 < admin_idx < init_idx, "re-attach must run only for the admin"
+    tail = js[js.rfind("if (syncBtn)") :]
+    assert "initSyncButton()" in tail, "boot re-attach runs at module import"
+
+
+def test_header_js_emits_bor_sync_status_on_state_changes() -> None:
+    """Every state change dispatches window 'bor:sync-status' with the
+    status object as detail — the channel the Sources page's
+    banner/result line subscribe to. The click path emits the
+    synthetic running frame IMMEDIATELY (no 2 s poll lag — the exact
+    old enterRunningState clear behavior, now event-driven)."""
+    js = _text(HEADER_JS)
+    assert (
+        'window.dispatchEvent(new CustomEvent("bor:sync-status", { detail: status }))'
+        in js
+    )
+    for fn in ("applySyncSuccess", "applySyncFailure", "applySyncIdle"):
+        assert "emitSyncStatus" in _body(js, fn), f"{fn} must emit its frame"
+    # the running frame: synthetic on click, the real object on boot
+    assert 'emitSyncStatus({ state: "running" })' in js
+    assert "emitSyncStatus(status)" in _body(js, "initSyncButton")
+
+
+# ---------- sources.js: the event-driven result line + banner ----------
+
+
+def test_sources_js_renders_off_the_sync_status_event() -> None:
+    """The Sources page keeps ONLY its page-specific rendering:
+    #sync-result (aria-live) + #sync-error-banner (role=alert), driven
+    by the module's 'bor:sync-status' event (detail = the status
+    object): running → clear + hide; success → the counts (the
+    imported fmtSyncResult) + a live catalog refresh; failed → the
+    banner with the error; idle → hide + clear."""
+    js = _text(SOURCES_JS)
+    assert 'window.addEventListener("bor:sync-status"' in js
+    assert 'status.state === "running"' in js
+    assert 'status.state === "success"' in js
+    assert 'status.state === "failed"' in js
+    assert "fmtSyncResult(status.detail)" in js
+    assert "loadDocs()" in js, "the catalog re-fetches live on a successful sync"
+    assert "showSyncError(status.error)" in js
+    assert "syncResult.textContent" in js
+
+
+def test_sources_js_no_longer_owns_the_sync_machine() -> None:
+    """The state machine is GONE from sources.js (header.js owns it):
+    no button refs, no POST, no status poll, no button-state helpers,
+    no click binding, no load re-attach."""
+    js = _text(SOURCES_JS)
+    for gone in (
+        "SYNC_POLL_MS",
+        "syncPollTimer",
+        "startSyncPolling",
+        "stopSyncPolling",
+        "enterRunningState",
+        "settleSyncButton",
+        "applySyncSuccess",
+        "applySyncFailure",
+        "applySyncIdle",
+        "initSyncButton",
+        "startSync",
+        'fetch("/api/sync", { method: "POST" })',
+        'fetch("/api/sync/status")',
+        'querySelector("#sync-btn")',
+        'querySelector("#sync-label")',
+        'querySelector(".sync-icon")',
+    ):
+        assert gone not in js, f"{gone!r} must be gone from sources.js (header.js owns it)"
 
 
 # ---------- styles.css: the §7.4 states ----------