@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/docs/onboarding.md

@@ -0,0 +1,202 @@
+# First-run onboarding guide
+
+This guide explains what happens the first time Hermes WebUI starts, which
+setup path to choose, and how to recover when the wizard cannot finish.
+
+If an AI assistant is helping with install, reinstall, bootstrap, provider
+setup, or first-run support, read
+[`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md) before
+running commands or inspecting logs.
+
+The short version: run the bootstrap, open the WebUI, choose a provider, choose
+a workspace, optionally set a password, then start a chat. If you are using a
+local model server from Docker, pay special attention to the Base URL section
+below.
+
+## Before you start
+
+Hermes WebUI is only the browser interface. The actual agent runtime, memory,
+skills, config, cron jobs, and provider credentials belong to Hermes Agent.
+
+The bootstrap supports Linux, macOS, and WSL2. Native Windows is not supported
+by the bootstrap yet. A community native Windows setup is being tracked in
+[#1952](https://github.com/nesquena/hermes-webui/issues/1952), including:
+
+- [Native Windows guide](https://github.com/markwang2658/hermes-windows-native-guide)
+- [Native Windows setup scripts](https://github.com/markwang2658/hermes-windows-native)
+
+For Windows users who want the supported path today, use WSL2 and see
+[Windows / WSL auto-start](wsl-autostart.md).
+
+## Install path choices
+
+| Path | Use it when | Notes |
+|---|---|---|
+| Local bootstrap | You run WebUI directly on Linux, macOS, or WSL2 | Best for a personal server, Mac mini, VPS, or homelab host. |
+| Docker single-container | You want the simplest container setup | Recommended first Docker path. WebUI runs the agent in-process. |
+| Docker two-container | You already run the agent gateway separately | More isolated, but tools launched from WebUI run in the WebUI container. |
+| Docker three-container | You want agent gateway plus dashboard plus WebUI | Same caveats as two-container, plus the dashboard service. |
+| Native Windows community path | You are intentionally testing unsupported native Windows | Community-maintained for now, not the official bootstrap path. |
+
+If a Docker install gets confusing, start again with the single-container setup.
+It avoids most UID/GID, source-volume, and tool-location surprises. See
+[Docker setup guide](docker.md) for the full container reference.
+
+## Re-running onboarding safely
+
+Do not delete `~/.hermes` just to see the wizard again. That directory can hold
+your real Hermes config, credentials, memory, skills, profiles, sessions, and
+cron state.
+
+For a clean local trial, use an isolated Hermes home and WebUI state directory:
+
+```bash
+mkdir -p ~/hermes-onboarding-test
+HERMES_HOME=~/hermes-onboarding-test/.hermes \
+HERMES_WEBUI_STATE_DIR=~/hermes-onboarding-test/webui \
+HERMES_WEBUI_PORT=8789 \
+python3 bootstrap.py
+```
+
+Then open `http://127.0.0.1:8789`.
+
+For an assistant-led trial run, follow the safety rules, evidence commands, and
+pass/fail criteria in
+[`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md).
+
+If your repo has a `.env` file, remember that the bootstrap loads it. Remove or
+adjust any `HERMES_HOME`, `HERMES_WEBUI_STATE_DIR`, or `HERMES_WEBUI_PORT`
+entries there before using the isolated command above.
+
+For managed hosting or fully preconfigured images, set
+`HERMES_WEBUI_SKIP_ONBOARDING=1` to bypass the wizard.
+
+## What the wizard checks
+
+The first screen reports the runtime state WebUI can see:
+
+- Hermes Agent importability: whether WebUI can import and run `AIAgent`.
+- Provider status: whether `config.yaml` and credential state are enough for a
+  chat request.
+- Password status: whether WebUI password protection is enabled.
+- Config paths: the active `config.yaml` and `.env` locations for this profile.
+
+If the agent check fails, use [Troubleshooting](troubleshooting.md), especially
+the `AIAgent not available` section. If provider setup is incomplete, continue
+through the wizard or run `hermes model` in the same machine environment that
+will run WebUI.
+
+## Choosing a provider
+
+The setup step groups providers by how much information they usually need.
+
+| Group | Examples | What you usually enter |
+|---|---|---|
+| Easy start | OpenRouter, Anthropic, OpenAI | API key and model. |
+| Open / self-hosted | Ollama, LM Studio, custom OpenAI-compatible | Base URL, model, optional API key. |
+| Specialized | Gemini, DeepSeek, Xiaomi MiMo, Z.AI / GLM, NVIDIA NIM, Mistral, xAI | Provider API key and default model. |
+
+For API-key providers, the wizard writes the key to the active Hermes `.env`
+file and writes the default model/provider to `config.yaml`.
+
+For local providers, the API key field can be blank when the server is keyless.
+Most LM Studio, Ollama, vLLM, llama-server, and TabbyAPI installs run this way.
+Use **Test connection** to verify the Base URL and populate the model list
+before continuing.
+
+Advanced provider flows such as Nous Portal and GitHub Copilot are still
+terminal-first. OpenAI Codex and Anthropic Claude Code OAuth can be started in
+the onboarding flow when your Hermes config selects the corresponding provider.
+If the wizard points you back to `hermes model`, use that CLI flow first, then
+refresh WebUI.
+
+## Base URL rules for local model servers
+
+For self-hosted providers, the Base URL should point to the OpenAI-compatible
+API root. Common examples:
+
+| Server | Typical Base URL |
+|---|---|
+| LM Studio on the same non-Docker host | `http://127.0.0.1:1234/v1` |
+| Ollama on the same non-Docker host | `http://127.0.0.1:11434/v1` |
+| LM Studio from Docker Desktop | `http://host.docker.internal:1234/v1` |
+| Ollama from Docker Desktop | `http://host.docker.internal:11434/v1` |
+| Local server from Linux Docker Engine | `http://api.local:<port>/v1` with `api.local:host-gateway` in Compose `extra_hosts` |
+| Local server on another LAN machine | `http://<lan-ip>:<port>/v1` |
+
+Inside Docker, `localhost` means the WebUI container itself, not your Mac,
+Windows host, Linux host, or another machine on your LAN. If LM Studio or Ollama
+is running outside the container, use `host.docker.internal` on Docker Desktop,
+use the server's LAN IP address, or add a Linux Docker host alias:
+
+```yaml
+services:
+  hermes-webui:
+    extra_hosts:
+      - "api.local:host-gateway"
+```
+
+Then use `http://api.local:<port>/v1` as the Base URL. The alias avoids writing
+`localhost` in WebUI config where it would resolve to the container loopback
+instead of the host service.
+
+The wizard probes `<base-url>/models` before saving. A successful probe fills
+the model dropdown. A failed probe blocks the setup step and shows an inline
+error such as DNS failure, connection refused, timeout, HTTP error, or
+unexpected response shape.
+
+## Workspace step
+
+The workspace is the filesystem location Hermes should use for new sessions.
+It can be a source checkout, a project directory, or a general workspace folder.
+
+In Docker, the default browsable path is `/workspace`, which maps to the host
+directory mounted by the compose file. If the workspace appears empty, check the
+Docker UID/GID and mount guidance in [Docker setup guide](docker.md).
+
+## Password step
+
+Password protection is optional for localhost-only installs. Enable it if you
+expose WebUI outside `127.0.0.1`, behind a reverse proxy, or on a LAN.
+
+The password is stored through the normal WebUI settings path and hashed
+server-side. You can change it later from Settings.
+
+## What gets written
+
+The wizard uses the same files and APIs as the normal app:
+
+- Active Hermes `config.yaml`: provider, default model, and Base URL when
+  relevant.
+- Active Hermes `.env`: provider API keys when you entered one.
+- WebUI `settings.json`: onboarding completion, workspace, password state, and
+  other WebUI preferences.
+
+State normally lives outside the repository. By default:
+
+- Hermes Agent state: Windows `%LOCALAPPDATA%\hermes`; POSIX `~/.hermes`
+- WebUI state: `$HERMES_HOME/webui` (Windows default `%LOCALAPPDATA%\hermes\webui`, POSIX default `~/.hermes/webui`)
+
+Override these with `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` when you need an
+isolated test install.
+
+## When to file an issue
+
+File an issue when the diagnostics point to WebUI rather than local
+configuration. Include:
+
+1. Install path: local bootstrap, Docker single-container, Docker
+   two-container, Docker three-container, WSL2, or community native Windows.
+2. Output from `/health`, or the startup banner if the server never starts.
+3. The provider selected in onboarding and the Base URL shape, with secrets
+   redacted.
+4. For Docker provider problems, the result of probing from inside the
+   container, for example:
+
+```bash
+docker exec hermes-webui sh -c 'curl -sS -w "\nHTTP %{http_code}\n" http://host.docker.internal:1234/v1/models | head -50'
+```
+
+5. Any inline wizard error text and relevant logs.
+
+Never paste API keys, OAuth tokens, or full `.env` contents into an issue.

package/vendor/agent-frontend-shell/docs/remote-access.md

@@ -0,0 +1,75 @@
+# Remote access
+
+How to reach a self-hosted Hermes WebUI from another machine or your phone.
+
+## Accessing from a remote machine
+
+The server binds to `127.0.0.1` by default (loopback only). If you are running
+Hermes on a VPS or remote server, use an SSH tunnel from your local machine:
+
+```bash
+ssh -N -L <local-port>:127.0.0.1:<remote-port> <user>@<server-host>
+```
+
+Example:
+
+```bash
+ssh -N -L 8787:127.0.0.1:8787 user@your.server.com
+```
+
+Then open `http://localhost:8787` in your local browser.
+
+`start.sh` will print this command for you automatically when it detects you
+are running over SSH.
+
+---
+
+## Accessing on your phone with Tailscale
+
+[Tailscale](https://tailscale.com) is a zero-config mesh VPN built on
+WireGuard. Install it on your server and your phone, and they join the same
+private network -- no port forwarding, no SSH tunnels, no public exposure.
+
+The Hermes Web UI is fully responsive with a mobile-optimized layout
+(hamburger sidebar, sidebar top tabs in the drawer, touch-friendly controls),
+so it works well as a daily-driver agent interface from your phone.
+
+**Setup:**
+
+1. Install [Tailscale](https://tailscale.com/download) on your server and
+   your iPhone/Android.
+2. Start the WebUI listening on all interfaces with password auth enabled:
+
+```bash
+HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secret ./start.sh
+```
+
+3. Open `http://<server-tailscale-ip>:8787` in your phone's browser
+   (find your server's Tailscale IP in the Tailscale app or with
+   `tailscale ip -4` on the server).
+
+That's it. Traffic is encrypted end-to-end by WireGuard, and password auth
+protects the UI at the application level. You can add it to your home screen
+for an app-like experience.
+
+### Community field report: ARM64 Android via AVF
+
+A community report in [#2364](https://github.com/nesquena/hermes-webui/issues/2364)
+documents Hermes Agent + WebUI running on a mid-range ARM64 Android phone inside
+a Debian 12 VM via Android Virtualization Framework (AVF). The reported setup
+used a Xiaomi Redmi Note 13 Pro 4G, 3.8 GiB RAM allocated to the VM, 8 visible
+CPU cores, Chrome on Android at `localhost:8787`, and cloud-hosted inference.
+
+This is not an official support baseline or provider/model benchmark, but it is
+a useful compatibility signal for mobile ARM64 experiments: the WebUI rendered
+smoothly in Chrome, ARM64 Debian worked for the agent stack, and the total local
+footprint was about 1.7 GB. Practical caveats from the report: first install can
+take longer when dependencies compile from source, Android browser tabs may
+reload when switching apps, and disabling battery optimization for the terminal
+or VM host may be needed for longer-running sessions.
+
+> **Tip:** If using Docker, set `HERMES_WEBUI_HOST=0.0.0.0` in your
+> `docker-compose.yml` environment (already the default) and set
+> `HERMES_WEBUI_PASSWORD`.
+
+---

package/vendor/agent-frontend-shell/docs/rfcs/README.md

@@ -0,0 +1,53 @@
+# RFCs
+
+This directory holds design documents for hermes-webui features that are
+worth thinking through in writing before (or alongside) implementation —
+typically when the change touches durability, recovery, schema, or cross-
+cutting infrastructure.
+
+## Conventions
+
+- One file per RFC. Filename is the topic (kebab-case), not a number.
+- Top of every RFC carries a small header:
+
+      - **Status:** Proposed | Accepted | Implemented | Withdrawn
+      - **Author:** @github-handle
+      - **Created:** YYYY-MM-DD
+
+- Sections usually include: Problem, Goals, Non-goals, Proposal, Open
+  questions, Rollout plan. Skip what doesn't apply.
+- An RFC is a starting point for review. Comments and revisions land via PR
+  edits, not separate discussion threads.
+- An RFC documents a design direction. It is **not** an invitation to file
+  implementation PRs against fragments of it. Before opening any PR that
+  implements an accepted RFC, confirm with a maintainer in the tracking
+  issue that the implementation slice is wanted and that no other
+  contributor is already building it. Speculative implementations of RFC
+  fragments without a confirmed integration site will be held.
+
+## When to file an RFC
+
+- The change is large enough that you want consensus before writing code.
+- The change touches data-at-rest formats or recovery semantics.
+- The change introduces a new architectural primitive (journal, queue,
+  scheduler, cache layer) that other features will build on.
+- A reviewer asks for one during code review.
+
+When in doubt, just ship the code — small features don't need RFCs.
+First-time contributor RFCs should be discussed in an issue before opening a PR.
+
+## Current RFCs
+
+- [`hermes-run-adapter-contract.md`](hermes-run-adapter-contract.md) — #1925
+  event/control contract, runtime-state ownership matrix, acceptance catalog,
+  and reversible migration gates for moving WebUI execution behind an explicit
+  adapter boundary.
+- [`webui-run-state-consistency-contract.md`](webui-run-state-consistency-contract.md)
+  — #2361 consistency rules for keeping transcript, model context, live streams,
+  replay, compression, and session metadata coherent during active and recovered
+  WebUI runs.
+- [`canonical-session-resolution.md`](canonical-session-resolution.md) — #2361
+  focused contract for resolving URL, query parameter, localStorage, sidebar,
+  and compression-lineage session IDs to one canonical visible chat target.
+- [`turn-journal.md`](turn-journal.md) — Crash-safe WebUI turn journal for
+  recovering interrupted chat submissions.

package/vendor/agent-frontend-shell/docs/rfcs/agent-source-boundary.md

@@ -0,0 +1,70 @@
+# Agent Source Boundary and API Decoupling Inventory
+
+- **Status:** Proposed
+- **Created:** 2026-05-17
+- **Tracking issue:** [#2453](https://github.com/nesquena/hermes-webui/issues/2453)
+
+## Problem
+
+The WebUI currently depends on Hermes Agent Python source being importable at
+runtime. In local installs this usually means a neighboring checkout; in the
+multi-container Docker setup it means the WebUI reads the `hermes-agent-src`
+volume that the agent container also uses.
+
+That source mount is a compatibility bridge, not the desired long-term contract.
+Even when mounted read-only on the WebUI side, it couples WebUI releases to
+Hermes Agent internal module layout and makes the multi-container setup look more
+isolated than it really is.
+
+## Current safety posture
+
+- The multi-container compose files mount `hermes-agent-src` read-only into the
+  WebUI service by default.
+- `docker_init.bash` prunes the agent source subtree from `chown` so read-only
+  mounts do not break startup.
+- If an operator overrides the compose files with a mutable agent-source mount,
+  startup now emits a notable warning. The WebUI still starts because local dev
+  checkouts and custom deployments may intentionally be writable, but the warning
+  makes the reduced boundary explicit.
+
+## Source-access inventory
+
+These are the current WebUI capabilities that still rely on Agent source or
+`hermes_cli`/`agent` modules being importable. Each item should eventually move
+behind an explicit, versioned Agent API or a packaged library contract that does
+not require mounting the live source checkout.
+
+| WebUI capability | Current dependency | Desired API / contract | Notes |
+|---|---|---|---|
+| Browser chat execution | `run_agent.AIAgent` imported by `api/streaming.py` | Run lifecycle API: start, observe, status, cancel, approval, clarify, final usage | Covered by the runtime-adapter migration in [#1925](https://github.com/nesquena/hermes-webui/issues/1925), but still source-backed today. |
+| Runtime event rendering | WebUI callbacks around Agent token/reasoning/tool events | Stable event envelope for tokens, reasoning, progress, tool lifecycle, approvals, clarify, errors, and final usage | The existing run-adapter RFC describes the browser-facing shape; Agent still needs a durable producer contract. |
+| Profile list/create/delete/seed | `hermes_cli.profiles` from `api/profiles.py` | Profile management API with profile metadata, env/runtime context, seed/delete operations, and validation errors | WebUI has fallback filesystem handling for some operations, but feature parity follows Hermes CLI internals. |
+| Goal command state | `hermes_cli.goals` from `api/goals.py` | Goal CRUD/control API: get, save, pause/resume/clear, and status | Should preserve current `/goal` WebUI behavior without direct module import. |
+| Slash command registry and plugin commands | `hermes_cli.commands` and `hermes_cli.plugins` from `api/commands.py` | Command/plugin capability discovery API scoped by active profile | WebUI should render command help from a stable capability response. |
+| Provider/auth/model catalogs | `hermes_cli.models`, `hermes_cli.auth`, and `agent.credential_pool` from `api/config.py` | Provider registry, model catalog, auth status, OAuth/credential-pool status APIs | WebUI has static fallbacks, but exact parity and custom provider state come from Agent internals. |
+| Redaction helper parity | `agent.redact.redact_sensitive_text` from `api/helpers.py` | Redaction service/library contract with signature/version compatibility | WebUI keeps a fallback redactor because this import has changed before. |
+| CLI/Gateway session bridge | Agent `state.db` schema and gateway metadata read by sidebar/session helpers | Session listing/transcript/metadata API for non-WebUI-originated sessions | Direct SQLite/schema coupling should narrow over time, especially for messaging/email/gateway sessions. |
+
+## Decoupling task list
+
+1. Keep the Docker default safe: WebUI-side `hermes-agent-src` stays read-only in
+   two- and three-container compose files.
+2. Keep documenting the boundary honestly: multi-container isolates process,
+   network, and resources, not filesystem/source compatibility.
+3. Warn loudly when the WebUI container sees a writable agent-source mount in
+   Docker, because that weakens the defense-in-depth posture.
+4. Convert runtime execution first through the #1925 RuntimeAdapter path instead
+   of adding new direct imports.
+5. For each inventory row, file or link a follow-up that defines the Agent API
+   response shape before replacing the import.
+6. Do not claim the source mount can be removed until chat execution, provider
+   catalogs/auth status, profiles, goals, commands/plugins, redaction, and
+   imported Agent/Gateway sessions all have stable replacement contracts.
+
+## Non-goals for this slice
+
+- Do not remove `HERMES_WEBUI_AGENT_DIR`.
+- Do not break local source-checkout development.
+- Do not fail startup solely because the agent source is writable.
+- Do not replace the runtime adapter or Hermes Agent API in this document-only
+  inventory slice.

package/vendor/agent-frontend-shell/docs/rfcs/canonical-session-resolution.md

@@ -0,0 +1,124 @@
+# Canonical Session Resolution Contract
+
+- **Status:** Proposed
+- **Author:** @ai-ag2026
+- **Created:** 2026-05-25
+- **Tracking issue:** [#2361](https://github.com/nesquena/hermes-webui/issues/2361)
+- **Related architecture:** [#1925](https://github.com/nesquena/hermes-webui/issues/1925), [`webui-run-state-consistency-contract.md`](webui-run-state-consistency-contract.md)
+
+## Problem
+
+WebUI can reach the same conversation through several browser-facing entrypoints:
+
+- a URL route such as `/session/<session_id>`,
+- a query parameter such as `?session=<session_id>` or `?session_id=<session_id>`,
+- the browser's `localStorage` active-session value,
+- sidebar rows built from `/api/sessions`,
+- direct session open actions from links, search, or imported session lists,
+- browser boot restore after reload, auth redirect, or PWA resume.
+
+After automatic compression, those entrypoints can point at different rows in one
+logical conversation lineage. A pre-compression parent snapshot can remain a
+valid archived session while the user-facing conversation tip has moved to a
+newer continuation. If each caller resolves IDs independently, the UI can appear
+to lose the session, reopen an old one-message snapshot, duplicate sidebar rows,
+or prefer the wrong transcript even though durable data is still present.
+
+This contract defines the expected resolution semantics for those entrypoints. It
+is intentionally narrower than the run adapter RFC: this is about choosing the
+correct visible session target, not moving execution ownership.
+
+## Goals
+
+- Define one canonical browser-facing resolution concept for sessions and
+  compression lineage.
+- Make URL, query parameter, localStorage, sidebar, and direct-open behavior use
+  the same mental model.
+- Preserve archived parent snapshots without letting them become the default
+  active target when a continuation exists.
+- Give reviewers a small checklist for future session-routing, sidebar, and
+  compression-lineage changes.
+
+## Non-goals
+
+- Do not delete archived `pre_compression_snapshot` rows.
+- Do not merge or rewrite session files as part of this contract.
+- Do not replace state.db/session sidecar reconciliation.
+- Do not require a new backend endpoint before narrow frontend guards can land.
+- Do not change explicit history browsing when the user deliberately opens an
+  archived snapshot as a record.
+
+## Terms
+
+| Term | Meaning |
+|---|---|
+| Requested session ID | The ID supplied by route, query parameter, localStorage, sidebar click, or direct session open. |
+| Canonical visible session | The session row WebUI should display by default for normal chat navigation. |
+| `canonical_visible_session_id` | Proposed field/name for an API or helper output that identifies the canonical visible session. |
+| Compression snapshot | A preserved archived parent row with `pre_compression_snapshot` set. |
+| Continuation session | The active child/tip created after compression, usually represented by `continuation_session_id`, `_lineage_tip_id`, or newer lineage metadata. |
+| Lineage relation | Links such as `parent_session_id`, `_lineage_root_id`, `_lineage_tip_id`, and `_compression_segment_count` that connect rows belonging to one logical conversation. |
+
+## Resolution Rules
+
+1. **Directly valid non-snapshot IDs stay stable.** If the requested session ID
+   exists and is not a `pre_compression_snapshot`, it should normally resolve to
+   itself.
+2. **Snapshot parents defer to visible continuation tips.** If the requested
+   session ID is a `pre_compression_snapshot` and the session list has a newer
+   non-snapshot continuation in the same lineage, normal chat navigation should
+   resolve to that continuation as the `canonical_visible_session_id`.
+3. **Explicit archive/history inspection remains possible.** A future UI affordance
+   may intentionally open a snapshot as a historical record, but that should be a
+   distinct mode from ordinary boot restore, URL restore, or sidebar continuation.
+4. **Local browser state is advisory.** `localStorage` may remember the last active
+   ID, but browser boot restore must treat it as a requested session ID and still
+   run canonical resolution before rendering.
+5. **Query aliases share the same resolver.** `?session=...`, `?session_id=...`,
+   and `/session/...` should feed the same requested-ID path instead of carrying
+   separate precedence rules.
+6. **Sidebar collapse and session loading agree.** The row chosen as the visible
+   representative for a lineage should match the target opened by `loadSession()`
+   for that lineage during ordinary navigation.
+7. **404 self-heal is separate from lineage resolution.** Missing/deleted sessions
+   should still use the stale-route recovery path. A present archived parent with
+   a live continuation is not a 404; it is a canonicalization problem.
+
+## Entry Point Matrix
+
+| Entry point | Input | Expected resolution |
+|---|---|---|
+| URL route | `/session/<id>` | Treat `<id>` as requested; resolve to canonical visible session before ordinary render. |
+| Query parameter | `?session=<id>` or `?session_id=<id>` | Same as URL route. Query spelling must not change the target semantics. |
+| localStorage | last active session ID | Advisory requested ID during browser boot restore; canonicalize before render. |
+| Sidebar click | visible row ID or lineage representative | Open the same canonical visible session that the row represents. |
+| Direct session open | programmatic call/search/import link | Use the shared requested-ID resolver unless the caller explicitly opts into archive inspection. |
+| Browser boot restore | URL and/or localStorage state after reload/auth/PWA resume | Prefer explicit URL/query input, then localStorage, then canonicalize the requested ID. |
+
+## Review Checklist
+
+For PRs that touch session routing, compression lineage, sidebar collapse, boot
+restore, direct session open, or URL parsing, answer:
+
+- Which entrypoints provide the requested session ID?
+- Does the code path accept both route and query parameter forms where relevant?
+- Does localStorage go through the same canonicalization path as URL restore?
+- Can a `pre_compression_snapshot` become the default active chat when a
+  non-snapshot `continuation_session_id` / `_lineage_tip_id` exists?
+- Do sidebar collapse and `loadSession()` pick the same visible representative?
+- Is missing-session 404 recovery kept distinct from present-but-archived lineage
+  canonicalization?
+- What regression proves route, query parameter, localStorage, and sidebar paths
+  agree for compressed lineage rows?
+
+## Rollout Plan
+
+1. Document this proposed contract and link it from the public contract index.
+2. Keep narrow bugfixes small while referencing the relevant rule they preserve.
+3. Add shared frontend helper coverage for URL/query/localStorage/sidebar
+   requested-ID inputs.
+4. If backend session APIs later expose `canonical_visible_session_id`, make the
+   frontend resolver prefer the backend value while preserving client fallback for
+   older WebUI servers.
+5. If #1925 moves execution/session ownership behind an adapter, carry this
+   contract forward as an adapter-facing session-navigation invariant.