fix(*): a rebuilt page reaches the tab, and a stale one says so

[0xKT]

Summary

A tester's report, in two halves: after a rebuild the browser may still show the old page, and after a git pull nothing rebuilds the page or says that it is stale. This PR closes both.

A rebuilt page reaches the tab. raven serve sent dist/index.html from / with an ETag and a Last-Modified date but no Cache-Control. A browser then guesses a freshness lifetime from that date (about a tenth of the file's age) and answers a navigation to / from its cache without asking the server. The sign-in page at /auth ends by navigating the tab to / (location.replace('/') after the nonce exchange), and a browser answers that navigation from the copy it still guesses fresh, so a rebuilt or upgraded page kept opening as the build before it until a hard reload. Three rebuilds in a row went unseen this way on the architecture branch; a released install is exposed the same way after raven upgrade whenever raven web is run again inside that guessed lifetime, which for a weeks-old install is days. The assets already carried Cache-Control: no-cache for exactly this reason (the provider icons, 2026-09-11); the same on_response_prepare hook now covers / too, registers whenever the page is served rather than only when an assets directory exists, and no-cache keeps the 304 path (an unchanged 1.3 MB page still costs no bytes; no-store would re-download it on every navigation). The upgrade watcher's HEAD probe of / already used cache: 'no-store' and was never affected.

A stale page says so. Only a source checkout can serve a page older than the code beside it: ui-web/dist is git-ignored, so a pull brings ui-web/src and the message catalogue but not a rebuild, and the served page silently stays on the old build. resolve_ui_dist now judges that the way make would, by mtime: when the checkout's dist/index.html is older than anything under ui-web/src (tests, the src/test harness layer and snapshots excluded, since they change without changing the page), than the build's own files (build.py, vite.config.ts, package.json, package-lock.json, icon/raven.svg) or than i18n/messages.json, it logs one WARNING naming make build-ui, and both page hosts (standalone raven serve and the gateway's page mount behind raven web) hand that judgement to build_app, which answers / with X-Raven-Page-Behind: sources -- asked per response, so a rebuild takes the header away without a restart. The page's existing 30-second HEAD probe of / reads it and raises the rail-foot notice row with a third wording, "Stale page build / How to rebuild"; the click opens the confirm sheet with the command instead of reloading a page that would come back the same, and the row goes back down when a later look no longer carries the header. It outranks the rebuilt-page notice ("UI updated on disk / Reload"), because the reload that one offers would come back behind as well: the row asks for the rebuild first, and the probe that sees it land hands the row to the reload. A newer release outranks both. The wheel's copy ships beside the code it was built with, so a raven web user of an installed raven never sees the warning or the header.

The terminal alone was not enough for the hint: raven web detaches the gateway and its log goes to web.log, so the page is the one place both launch paths can show it.

Also in this change: showUpNote now writes the row's two texts through one wording(kind) helper (four textContent writes down to two), so the DOM-touch ratchet's pin for app/updates.ts drops from 4 to 2 and the debt row in ui-web/CONTRIBUTING.md follows. The TUI's generated copy of the catalogue (ui-tui/src/i18n/messages.generated.ts) is regenerated for the four new keys, which its lint:i18n gate requires.

Reviewed before opening by read-only panels (HTTP caching semantics, aiohttp mechanics and test quality, page integration, completeness), with adversarial refutation of every blocking claim; what survived is in. One follow-up came out of it and is deliberately not here: /files/download (raven/rpc/transports/deliverables.py) has the same shape as the page had -- ETag and Last-Modified, no Cache-Control, a token URL that stays the same when the deliverable is regenerated, fetched by <img src> and <a download> in default cache mode. Same one-header fix, separate PR.

Type

• Fix
• Feature
• Docs
• CI / tooling
• Refactor
• Other

Verification

Run from the branch checkout, base origin/refactor/ui_web_architecture:

• uv run --frozen --extra dev pytest tests/test_cli_serve_commands.py tests/test_rpc_transport.py tests/test_cli_gateway_page.py -q -> 133 passed in 5.06s

• make lint-python -> ruff check: All checks passed!; ruff format --check: 2019 files already formatted

• make test-python -> 24034 passed, 109 skipped in 254.85s

• npm run --prefix ui-web gen:check -> generated.ts matches the contract (189 methods); npm run --prefix ui-web type-check -> clean; npm run --prefix ui-web lint -> 0 errors (5 pre-existing react-hooks warnings in files this PR does not touch)

• npm test --prefix ui-web -> 189 files, 2594 tests passed in 19.68s (includes the new src/app/updates.test.ts and the state-dom-touch, i18n-keys, first-frame-literals gates)

• npm run --prefix ui-tui lint, lint:rpc, lint:i18n, type-check, test, build -> 0 errors (23 pre-existing warnings), both generated tables in sync, 144 files / 2074 tests passed in 12.19s, bundle built

• npm run --prefix ui-web build, python3 ui-web/build.py, node ui-web/scripts/check-page.mjs, node ui-web/scripts/check-css.mjs, node ui-web/scripts/check-class-namespace.mjs -> all OK, both boot snapshots match their goldens

• uv run pre-commit run --from-ref origin/refactor/ui_web_architecture --to-ref HEAD -> every hook Passed or Skipped; commitlint, scripts/check_commit_messages.py, scripts/check_large_files.py, scripts/check_source_language.py -> OK

• Live, raven serve from this branch with an isolated RAVEN_HOME: curl -sI http://127.0.0.1:<port>/ answers 200 with Cache-Control: no-cache and an ETag, the same request with that ETag in If-None-Match answers 304 also carrying the directive; with dist/index.html backdated below its sources the startup log carries the WARNING and the same request adds X-Raven-Page-Behind: sources, which disappears after touch dist/index.html with no restart; /assets/raven.svg carries no-cache and never the behind header

• Live, both install shapes for the no-cache half: a wheel built from this branch and installed into a fresh venv (resolve_ui_dist resolves to the venv's raven/ui/dist), and the raven gateway --page-port child that raven web starts from a source checkout -- both answer / with no-cache and 304 with the directive

• Relevant tests pass locally

• Relevant lint / type checks pass locally

• User-facing docs or screenshots are updated when needed (ui-web/CONTRIBUTING.md debt row; the notice text itself is in the catalogue)

Risk

• Security impact considered (two response headers on /; the behind header only ever appears on a source checkout and names no path; auth, origin checks and the nonce flow are untouched)
• Backward compatibility considered (browsers now send If-None-Match on each navigation and get a 304 for an unchanged page; build_app gains an optional keyword; no RPC contract or config change)
• Rollback path is clear for risky changes (revert the three commits)

A tab that already holds the old copy does not see the new header until it next asks the server: it may open the old build once more, until a hard reload or until its guessed lifetime runs out. Verify from a fresh browser profile or after one hard reload, not from the tab that showed the bug. The mtime judgement is make's: a checkout or pull that rewrites a source file with unchanged content also makes the page read as behind until the next make build-ui, which is a spurious warning rather than a missed one.

Related Issues

N/A

[gloryfromca]

No blockers; this can merge as far as I am concerned.

Reviewed the full target diff and the surrounding build_app routes and response hook, the /auth navigation caller, the history that introduced asset revalidation, compatibility with the target branch's newer commit, and the repository's AGENTS.md and Context Map/Web UI architecture rules. The hook now covers the served root page even when there is no assets directory, keeps ETag-based 304 responses, and does not change the no-static placeholder or unrelated routes. I found no weakened tests or backward-compatibility issue.

Verification: uv run pytest tests/test_rpc_transport.py -x (32 passed). git diff --check github/refactor/ui_web_architecture...HEAD passed, and a merge-tree check against the current target completed without conflicts.

[gloryfromca]

No blockers; suggestions only, and they are marked inline.

The new revision's source-checkout freshness signal, both page-host wiring paths, response-header behavior, Web UI notice arbitration, target-branch compatibility, and the relevant AGENTS.md/CLAUDE.md and Context Map/Web UI architecture rules are sound. I also checked the history and callers, backward compatibility with packaged pages and callers that omit page_behind, and that the tests add coverage rather than weakening existing assertions.

Named nonblocking follow-up (kept here rather than as an open thread): add ui-web/tsconfig.json to _PAGE_BUILD_FILES. Vite reads emit-affecting compiler options from it, so a pull that changes only such an option can currently leave dist/index.html stale without either warning. This is narrow because build-config changes normally accompany a source edit, so it does not hold this improvement.

Verification: uv run pytest tests/test_rpc_transport.py tests/test_cli_serve_commands.py tests/test_cli_gateway_page.py -x passed (133 tests); npm test --prefix ui-web passed (189 files, 2594 tests); and npm run type-check --prefix ui-web passed. The first focused UI attempt reported vitest: not found before the locked dependencies were installed; after npm ci --prefix ui-web, the full suite passed. The canonical source-language script, git diff --check, and a merge-tree check against the current target also passed.

[gloryfromca]

No blockers; suggestions only, and they are marked inline.

No new findings. The new commit only regenerates the TUI message table for the four catalog entries already reviewed, and the generated English and Chinese values match i18n/messages.json without unrelated movement. I checked the delta, generator ownership and history, source-language exemption behavior, target compatibility, and that no prior tests were weakened. The previously recorded named follow-up remains the only nonblocking item.

Verification: npm run lint:i18n --prefix ui-tui passed; npm test --prefix ui-tui -- src/__tests__/i18n.test.ts passed (8 tests); the canonical source-language check and git diff --check passed; and a merge-tree check against the current target completed without conflicts. The first generator-check attempt reported missing prettier because this worktree lacked TUI dependencies; after npm ci --prefix ui-tui, both checks passed.