V2: put the open conversation back in the address bar

[Paul Lizer (paullizer)]

Adds conversation deep linking to the V2 interface, so a link opens the conversation it names.

Reported against https://…/chats?conversationId=67553a4a-… — that link works in the classic interface but had no V2 equivalent.

The gap

The classic interface has supported this since v0.237.001: chat-onload.js reads ?conversationId= (or the older ?conversation_id=) on load, and chat-conversations.js writes the open conversation back with history.replaceState.

The V2 SPA had neither half. useSearchParams appeared exactly once in all of V2, in SettingsPage.tsx for ?tab=. So /v2/chat never named what was open, copying the address bar shared nothing, and a refresh landed in an empty chat.

Approach

The read and the write are deliberately asymmetric, and that is the whole design: the URL is read once, during the chat page's first render, and written on every change of the open conversation after that.

Two ordering hazards are handled explicitly, because both fail silently:

• The incoming id is captured in a lazy useState initialiser, which runs during the first render. The write effect also runs on mount and would otherwise strip the parameter before the read effect ever saw it.
• The write is held until the open settles, either way, so it never observes the moment before the conversation exists and clears the parameter that named it.

replace rather than a push, matching classic's replaceState: opening ten conversations should not put ten entries behind the back button.

Changes

File	What
lib/conversationUrl.ts (new)	Parameter names and rules in one place. Both spellings read, only the canonical one written. A "no change needed" return is what keeps the sync effect from re-entering itself.
pages/ChatPage.tsx	useConversationUrlSync()
stores/chatStore.ts	openLinkedConversation(), plus a conversation-list backfill
components/layout/Sidebar.tsx	"Back to classic UI" carries the conversation across

Both spellings are accepted on arrival because the server emits both — conversationId from functions_notifications.py and functions_workflow_runner.py, conversation_id from route_frontend_chats.py and functions_documents.py. An incoming legacy link is rewritten to the canonical spelling, so a URL never carries both.

First send, fork, New Chat and delete all came free, since they all end at activeConversationId.

A conversation reached by link need not be in the loaded list — it can be older than the first feed page (FEED_PAGE_SIZE = 30) or hidden (include_hidden defaults false). Its row is built from the metadata the chat page already fetches, so the rail highlights it rather than the header reading "New chat" for a thread that is plainly open.

Worth a reviewer's attention

The first cut detected a bad link by checking messagesError after loading. That misses deleted conversations: /api/get_messages catches the not-found LookupError and answers {'messages': []} with a 200 (route_backend_conversations.py:1068). A deleted conversation would have opened as an empty chat, kept its id in the address bar, and stayed the target of the next message sent.

Existence is now checked against /api/conversations/<id>/metadata, which answers 404 when the conversation is gone and 403 when it is someone else's — the question actually being asked. That costs one extra request on a path that runs once per page load.

Scope

V2 only, as agreed. Server-generated links (notifications, workflow runs, document sources) still point at the classic /chats and are not made interface-aware.

Validation

• npm run typecheck and npm run build clean
• 19 runtime behaviour checks on the pure helpers, including proving normalisation converges so the sync effect cannot loop
• New functional_tests/test_v2_conversation_deep_link.py: 8/8
• Full V2 suite (22 files) plus test_docs_app_surface_coverage.py and test_docs_site_quality.py: 0 failures

Also in this change

config.py → 0.261.028, a "Linking to a conversation" section in REACT_V2_UI.md with a row in its testing table, and a release-notes entry.

No docs/_data/app_surface.yml regeneration needed: scripts/build_docs_inventory.py scans application/single_app only, and this adds no enable_* key, admin tab, action plugin or chat control.