Merge pull request #1544 from nesquena/fix-nous-models-and-provider-removal-staleness

fix(providers): Nous Portal full live catalog + dropdown cache invalidation on provider remove (#1538, #1539)

.env.docker.example

@@ -0,0 +1,89 @@
+# Hermes Web UI — Docker Compose configuration template
+#
+# Copy this file to `.env` next to your docker-compose.yml.
+# All variables are optional — Docker Compose substitutes defaults if unset.
+#
+#   cp .env.docker.example .env
+#   # edit values you care about, then:
+#   docker compose up -d
+
+# ──────────────────────────────────────────────────────────────────────────
+# UID / GID — host user mapping
+# ──────────────────────────────────────────────────────────────────────────
+# Critical when bind-mounting an EXISTING host directory (e.g. ~/.hermes).
+# The container runs as UID/GID and must match your host file ownership,
+# otherwise the container can't read your config.yaml or write sessions.
+#
+# Find yours:   id -u   (UID)   |   id -g   (GID)
+#
+# On macOS, UIDs start at 501 (not 1000), so you MUST set these.
+# On Linux, the default of 1000 usually matches the first interactive user.
+#
+# REPLACE THESE WITH YOUR ACTUAL VALUES (run `id -u` and `id -g`):
+UID=1000
+GID=1000
+
+# ──────────────────────────────────────────────────────────────────────────
+# Hermes home directory — single-container compose only
+# ──────────────────────────────────────────────────────────────────────────
+# Where on the host your config, sessions, skills, and state live.
+# Default: ~/.hermes (works for everyone with a standard install)
+# Override if your .hermes is elsewhere:
+# HERMES_HOME=/opt/hermes-data
+
+# ──────────────────────────────────────────────────────────────────────────
+# Workspace directory — single-container compose
+# ──────────────────────────────────────────────────────────────────────────
+# Path to your code/project directory. The WebUI's file browser shows
+# this at /workspace inside the container.
+# Default: ~/workspace
+# HERMES_WORKSPACE=/home/me/dev
+
+# ──────────────────────────────────────────────────────────────────────────
+# Password — protect remote access
+# ──────────────────────────────────────────────────────────────────────────
+# REQUIRED if you expose the container on anything other than 127.0.0.1.
+# Without a password, anyone who can reach the port can run commands as
+# the agent.
+# HERMES_WEBUI_PASSWORD=change-me-to-something-strong
+
+# ──────────────────────────────────────────────────────────────────────────
+# Permission handling for bind-mounted .hermes — advanced
+# ──────────────────────────────────────────────────────────────────────────
+# By default, the WebUI's startup credential-permission fixer enforces
+# 0600 mode on .env, auth.json, and similar credential files in HERMES_HOME.
+# This is the right behavior on a clean install, but it can clash with:
+#
+#   - Bind-mounting an EXISTING ~/.hermes whose .env is intentionally 0640
+#     (e.g. group-readable for a Docker user group)
+#   - HERMES_HOME_MODE configured at the agent level for a multi-user setup
+#
+# To bypass the WebUI's fixer entirely:
+# HERMES_SKIP_CHMOD=1
+#
+# OR to allow group bits while still stripping world-readable:
+# HERMES_HOME_MODE=0640
+#
+# ⚠️ MULTI-CONTAINER WARNING: HERMES_HOME_MODE has DIFFERENT semantics in
+# the WebUI vs. the agent image:
+#   - WebUI: credential FILE mode threshold (0640 = allow group bits)
+#   - Agent: HERMES_HOME *directory* mode (default 0700)
+# 0640 on a directory has NO execute bit, so the agent can't enter its own
+# home → broken. If you set HERMES_HOME_MODE for a multi-container setup,
+# use 0750 (group-traversable) or 0701 (x-only for non-owner traversal).
+# The compose files document both correctly per-service.
+
+# ──────────────────────────────────────────────────────────────────────────
+# Multi-container only — used by docker-compose.two-container.yml and
+# docker-compose.three-container.yml
+# ──────────────────────────────────────────────────────────────────────────
+# These compose files use named Docker volumes by default (recommended).
+# Set the variables above to your host UID/GID — both the agent container
+# (HERMES_UID/HERMES_GID) and the webui container (WANTED_UID/WANTED_GID)
+# are derived from $UID/$GID so files written by one are readable by the
+# other.
+#
+# If you switch to bind mounts (replacing `hermes-home: {}` with a `device:`
+# bind), ALL THREE containers must mount the SAME host path and run as the
+# SAME UID/GID. Mismatched UIDs → "Permission denied" → the WebUI crashes
+# on every HTTP request because it can't read its own auth signing key.

.env.example

@@ -16,7 +16,7 @@
 # HERMES_WEBUI_PORT=8787
 
 # Where to store sessions, workspaces, and other state (default: ~/.hermes/webui-mvp)
-# HERMES_WEBUI_STATE_DIR=~/.hermes/webui-mvp
+# HERMES_WEBUI_STATE_DIR=~/.hermes/webui
 
 # Default workspace directory shown on first launch
 # HERMES_WEBUI_DEFAULT_WORKSPACE=~/workspace
@@ -26,3 +26,6 @@
 
 # Path to your Hermes config.yaml (for toolsets and model config)
 # HERMES_CONFIG_PATH=~/.hermes/config.yaml
+
+# Display name for the assistant in the UI (default: Hermes)
+# HERMES_WEBUI_BOT_NAME=Hermes

.github/workflows/release.yml

@@ -52,5 +52,6 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: HERMES_VERSION=${{ github.ref_name }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyyaml>=6.0 pytest pytest-timeout
+
+      - name: Run tests
+        run: pytest tests/ -v --timeout=60

.gitignore

@@ -12,16 +12,40 @@ __pycache__/
 # Archive directory (pre-git backups, kept on disk but not tracked)
 archive/
 
-# Local environment and secrets (but keep the example template)
+# Local environment and secrets (but keep the example templates)
 .env
 .env.*
 !.env.example
-.claude/*
+!.env.docker.example
+.claude/
+CLAUDE.md
+AGENTS.md
+.cursorrules
+.windsurfrules
+.aider*
+copilot-instructions.md
 
 # Generated screenshots and transient artifacts
 screenshot-*.png
 full-UI.png
 
+# Version file written by Docker/CI build — generated, never committed
+api/_version.py
+
 # OS files
 .DS_Store
 Thumbs.db
+
+# Local reference clones — never committed (except tracked design/UI-UX reference pages)
+docs/*
+!docs/ui-ux/
+!docs/ui-ux/**
+!docs/docker.md
+!docs/supervisor.md
+
+# Local-only PR review harness: rendering drivers, sample bank, fixtures.
+# Used by Claude during deep reviews; never shared in the repo.
+.local-review/
+graphify-out/
+.graphify_cached.json
+.graphify_uncached.txt

AGENTS.md

@@ -1,53 +0,0 @@
-# Web UI MVP Instructions
-
-Canonical source: <repo>/
-Symlink (for imports): <agent-dir>/webui-mvp -> <repo>
-Runtime state: ~/.hermes/webui-mvp/sessions/
-
-Purpose:
-- Claude-style web UI for Hermes. Chat, workspace file browser, cron/skills/memory viewers.
-
-Start server:
-  cd <agent-dir>
-  nohup venv/bin/python <repo>/server.py > /tmp/webui-mvp.log 2>&1 &
-  # OR: <repo>/start.sh
-
-Run tests:
-  cd <agent-dir>
-  venv/bin/python -m pytest <repo>/tests/ -v
-
-Health check: curl http://127.0.0.1:8787/health
-Logs: tail -f /tmp/webui-mvp.log
-SSH tunnel from Mac: ssh -N -L 8787:127.0.0.1:8787 <user>@<your-server>
-
-Living documents (always update after a sprint):
-  <repo>/ROADMAP.md
-  <repo>/ARCHITECTURE.md
-  <repo>/TESTING.md
-
-Sprint process skill: webui-sprint-loop
-
-# Workspace Convention (Web UI Sessions)
-
-When running as an agent invoked from the web UI, each user message is prefixed with:
-
-  [Workspace: /absolute/path/to/workspace]
-
-This tag is the single authoritative source of the active workspace. It reflects
-whichever workspace the user has selected in the UI at the moment they sent that message.
-It updates on every message, so if the user switches workspaces mid-session, the very
-next message will carry the new path. Always use the value from the most recent tag.
-
-This tag overrides any prior workspace mentioned in the system prompt, memory, or
-conversation history. Never infer or fall back to a hardcoded path like
-~/workspace when this tag is present.
-
-Apply it as the default working directory for ALL file operations:
-
-  - write_file: resolve relative paths against this workspace
-  - read_file / search_files: resolve paths relative to this workspace
-  - terminal workdir: set to this path unless the user explicitly says otherwise
-  - patch: resolve file paths relative to this workspace
-
-If no [Workspace: ...] tag is present (e.g., CLI sessions), fall back to
-~/workspace as the default.

ARCHITECTURE.md

@@ -7,20 +7,37 @@
 >
 > Keep this document updated as architecture changes are made.
 
+> Current shipped build: `v0.50.245` (April 30, 2026).
+> Automated coverage: 3309 tests via `pytest tests/ --collect-only -q`. CI runs on Python 3.11, 3.12, and 3.13 against every PR.
+>
+> Notable architecture state as of v0.50.245: workspace panel closed/open state is preloaded via a `documentElement` dataset marker before `style.css` paints to avoid first-load flash; transcript disclosure cards animate via transitionable `max-height`/`opacity` states; thinking cards share rounded bordered card chrome with tool cards (gold palette); incremental streaming-markdown via vendored `streaming-markdown@0.2.15` (no CDN); HTTP byte-range streaming for large media; SSE-driven session sidebar with `pending_user_message` + `active_stream_id` lifecycle tracking; configurable model badges (`primary` / `fallback N`) computed in `_build_configured_model_badges()` and provider-aware in the dropdown picker.
+
 ---
 
 ## 1. Overview and Purpose
 
 The Hermes Web UI is a lightweight web application that gives you a browser-based
 interface to the Hermes agent that is functionally equivalent to the CLI. It is modeled on
-the Claude-style interface: a three-panel layout with a sidebar for session management,
-a central chat area, and a right panel for workspace file browsing.
+the Claude-style interface: a sidebar for session management, a central chat area,
+and a demand-driven right panel used for workspace browsing and preview surfaces.
+The right panel is closed by default on desktop and opens only when it is actively
+being used for browsing or previewing content.
+
+To prevent a visible first-paint mismatch on refresh, `static/index.html` preloads the
+saved workspace panel state into `document.documentElement.dataset.workspacePanel`
+before the main stylesheet loads. Desktop CSS honors that preload marker immediately,
+and `static/boot.js` keeps the dataset synchronized with the runtime panel state machine.
 
 The design philosophy is deliberately minimal. There is no build step, no bundler, no
 frontend framework. The Python server is split into a routing shell (server.py) and
 business logic modules (api/). The frontend is seven vanilla JS modules loaded from static/.
 This makes the code easy to modify from a terminal or by an agent.
 
+Hermes-level chrome is intentionally consolidated: the sidebar has no dedicated brand header.
+Instead, the footer exposes a single "Hermes WebUI" launch button that opens one tabbed
+control-center modal for global preferences, conversation import/export, and clear-conversation
+actions. The topbar remains focused on conversation context and the workspace/files toggle.
+
 ---
 
 ## 2. File Inventory
@@ -28,7 +45,8 @@ This makes the code easy to modify from a terminal or by an agent.
     <repo>/
     server.py              Thin routing shell + HTTP Handler + auth middleware. ~81 lines.
                            Delegates all route handling to api/routes.py.
-    start.sh               Discovery script: finds agent dir, Python, starts server.
+    bootstrap.py           One-shot launcher: optional agent install, deps, health wait, browser open.
+    start.sh               Thin wrapper around bootstrap.py for shell-based startup.
     Dockerfile             python:3.12-slim container image (~23 lines)
     docker-compose.yml     Compose config with named volume and optional auth (~22 lines)
     .dockerignore          Excludes .git, tests/, .env* from Docker builds
@@ -39,7 +57,9 @@ This makes the code easy to modify from a terminal or by an agent.
       helpers.py           HTTP helpers: j(), bad(), require(), safe_resolve(), security headers (~71 lines)
       models.py            Session model + CRUD, per-session profile tracking (~137 lines)
       profiles.py          Profile state management, hermes_cli wrapper (~246 lines)
+      onboarding.py        First-run onboarding status, real provider config writes, and readiness detection.
       routes.py            All GET + POST route handlers (~1180 lines)
+      startup.py           Startup helpers: auto_install_agent_deps() (~50 lines)
       streaming.py         SSE engine, run_agent, cancel, HERMES_HOME save/restore (~236 lines)
       upload.py            Multipart parser, file upload handler (~78 lines)
       workspace.py         File ops: list_dir, read_file_content, workspace helpers (~77 lines)
@@ -48,11 +68,12 @@ This makes the code easy to modify from a terminal or by an agent.
       style.css            All CSS incl. mobile responsive (~670 lines)
       ui.js                DOM helpers, renderMd, tool cards, model dropdown, file tree (~977 lines)
       workspace.js         File preview, file ops, loadDir, clearPreview (~185 lines)
-      sessions.js          Session CRUD, list rendering, search, SVG icons, overlay actions (~533 lines)
+      sessions.js          Session CRUD, list rendering, search, SVG icons, dropdown actions (~533 lines)
       messages.js          send(), SSE event handlers, approval, transcript (~297 lines)
       panels.js            Cron, skills, memory, workspace, profiles, todo, settings (~974 lines)
       commands.js          Slash command registry, parser, autocomplete dropdown (~156 lines)
-      boot.js              Event wiring, mobile nav, voice input, boot IIFE (~338 lines)
+      onboarding.js        First-run wizard overlay, provider setup flow, and settings/workspace orchestration.
+      boot.js              Event wiring, mobile sidebar/workspace nav, voice input, boot IIFE (~338 lines)
     tests/
       conftest.py          Isolated test server (port 8788, separate HERMES_HOME) (~240 lines)
       test_sprint{1-20b}.py Feature tests per sprint (21 files, 415 test functions)
@@ -347,7 +368,7 @@ highlighting) and Mermaid.js (diagrams) from CDN, both loaded async/deferred wit
 Six JS modules loaded in order at end of <body>:
   1. ui.js       (~846 lines) DOM helpers, renderMd, tool card rendering, global state
   2. workspace.js (~169 lines) File tree, preview, file operations
-  3. sessions.js  (~532 lines) Session CRUD, list rendering, search, SVG icons, overlay actions, project picker
+  3. sessions.js  (~532 lines) Session CRUD, list rendering, search, SVG icons, dropdown actions, project picker
   4. messages.js  (~293 lines) send(), SSE event handlers, approval, transcript
   5. panels.js    (~771 lines) Cron, skills, memory, workspace, todo, switchPanel
   6. boot.js      (~175 lines) Event wiring + boot IIFE
@@ -358,10 +379,19 @@ inherit `currentColor` for consistent theming.
 
 Three-panel layout (in static/index.html):
 
-    <aside class="sidebar">    Left panel: session list, nav tabs, model selector
+    <aside class="sidebar">    Left panel: session list, nav tabs, sidebar-footer Hermes WebUI trigger
     <main class="main">        Center: topbar, messages area, approval card, composer
     <aside class="rightpanel"> Right panel: workspace file tree and file preview
 
+Composer footer layout (current):
+
+    left cluster   attach button, mic button, per-conversation model selector
+    right cluster  compact circular context-usage badge, send button
+
+The model selector is still the authoritative control for new-session creation
+and session updates; it was moved out of the sidebar so model choice feels scoped
+to the active conversation rather than a global app setting.
+
 ### 5.2 Global State
 
     const S = {
@@ -406,11 +436,19 @@ Approval:
     stopApprovalPolling   clearInterval
 
 UI helpers:
-    setStatus(t)          Updates #statusText in composer footer
+    setStatus(t)          Fallback helper: shows a toast for non-chat status/error messages
+    setComposerStatus(t)  Updates the inline composer status label for turn-scoped states
     setBusy(v)            Sets S.busy, disables/enables Send button, clears status on false
     showToast(msg, ms)    Bottom-center fade toast (default 2800ms)
+    showConfirmDialog(o)  Shared in-app confirmation modal, resolves true/false
+    showPromptDialog(o)   Shared in-app input modal, resolves string/null
     autoResize()          Auto-resize #msg textarea up to 200px
 
+Dialog policy:
+    Native browser confirm()/prompt() are not used in the Web UI.
+    Destructive actions use showConfirmDialog(...), then a toast on success.
+    Lightweight naming flows (new file/folder/project) use showPromptDialog(...).
+
 Files:
     loadDir(path)         GET /api/list, rebuild #fileTree
     openFile(path)        GET /api/file, show in #previewArea
@@ -463,7 +501,7 @@ Known gaps:
 - Nested lists: single regex pass, multi-level indentation not handled
 - Mixed bold+link in same line: may produce garbled output
 
-### 5.5 Model Chip Label (Fixed in Sprint 1)
+### 5.5 Model Label Resolution (Fixed in Sprint 1, reused by composer selector)
 
 B3 was resolved in Sprint 1. Current code uses a MODEL_LABELS dict:
 
@@ -474,10 +512,10 @@ B3 was resolved in Sprint 1. Current code uses a MODEL_LABELS dict:
       'anthropic/claude-haiku-3-5': 'Haiku 3.5', 'google/gemini-2.5-pro': 'Gemini 2.5 Pro',
       'deepseek/deepseek-chat-v3-0324': 'DeepSeek V3', 'meta-llama/llama-4-scout': 'Llama 4 Scout',
     };
-    $('modelChip').textContent = MODEL_LABELS[m] || (m.split('/').pop() || 'Unknown');
+    getModelLabel(m) => MODEL_LABELS[m] || (m.split('/').pop() || 'Unknown');
 
 Fallback: any unlisted model shows its short ID (after the last /) rather than a wrong label.
-To add a new model: add an entry to MODEL_LABELS and add an <option> to the <select>.
+To add a new model: add an entry to MODEL_LABELS and add an <option> to the composer footer <select>.
 
 ### 5.6 Session Delete Rules (from skill)
 
@@ -1095,7 +1133,7 @@ The model chip label bug is now fixed. The MODEL_LABELS object in syncTopbar():
       'deepseek/deepseek-chat-v3-0324':  'DeepSeek V3',
       'meta-llama/llama-4-scout':        'Llama 4 Scout',
     };
-    $('modelChip').textContent = MODEL_LABELS[m] || (m.split('/').pop() || 'Unknown');
+    getModelLabel(m) => MODEL_LABELS[m] || (m.split('/').pop() || 'Unknown');
 
 Fallback: splits on '/' and uses the last segment, so any unlisted model shows its
 short identifier rather than a wrong hardcoded label.
@@ -1586,3 +1624,19 @@ and #rightpanelResize. On mousemove: computes delta and clamps to min/max. On mo
 saves width to localStorage. Widths restored at boot via localStorage.getItem().
 CSS: .resize-handle with position:absolute, width:5px, cursor:col-resize.
 body.resizing added during drag to suppress text selection.
+
+
+## Workspace path trust levels
+
+`api/workspace.py` has two distinct trust functions — do not collapse them:
+
+**`validate_workspace_to_add(path)`** — used by `/api/workspaces/add` (explicit user registration).
+Permissive: blocks only non-existent, non-directory, and system root paths. The user is
+consciously registering an external path (e.g. `/mnt/d/Projects` in WSL), so we trust intent.
+
+**`resolve_trusted_workspace(path)`** — used for actual file read/write operations inside
+an existing workspace. Strict: path must be under home, in the saved workspace list, or under
+`BOOT_DEFAULT_WORKSPACE`. Prevents path traversal and unauthorized file access.
+
+The distinction matters because add uses permissive validation to avoid the circular
+dependency: you cannot get a path into the saved list if you need the saved list to add it.

BUGS.md

@@ -10,6 +10,18 @@ This file tracks UI bugs and polish items. Fixed items are kept for reference.
 
 ---
 
+## Known Limitations
+
+- **Two-container Docker setup: tools run in WebUI container** — In the two-container setup (hermes-agent + hermes-webui as separate containers), WebUI-initiated agent sessions run tools in the WebUI container, not the agent container. This is a known architectural constraint. Workaround: use the combined single-image approach, or initiate sessions via the CLI in the agent container. (#681)
+
+- **Image-in-chat vs. saved-to-workspace mismatch** — When the agent displays an inline image (from a URL) and the user asks it to save that image, the agent issues a fresh download which may return a different file if the source URL is CDN-rotated or parameterized. The WebUI correctly renders whatever URL the agent provides. Fix requires agent-side URL caching. (#641)
+
+- **MCP tools not available in WebUI sessions** — MCP servers must be configured in the active profile's config.yaml under mcp_servers:. If MCP tools are not appearing, check that the profile is correct and the MCP server process is reachable from inside the WebUI container. (#628)
+
+- **os.environ race condition in concurrent sessions** — Concurrent agent sessions share process-level os.environ for TERMINAL_CWD, HERMES_SESSION_KEY, and HERMES_HOME. _ENV_LOCK serializes mutations but does not fully isolate env vars during agent execution. Upstream fix pending in hermes-agent. (#195)
+
+---
+
 ## Fixed
 
 ### ~~Session title truncation / hover actions~~ -- Fixed (Sprint 16)

CONTRIBUTING.md

@@ -0,0 +1,171 @@
+# Contributing to Hermes WebUI
+
+Thanks for contributing.
+
+Hermes WebUI is intentionally simple to work on: Python on the server, vanilla JS in the browser, no build step, no bundler, no frontend framework. The best pull requests preserve that simplicity while solving a real problem cleanly.
+
+## Two Paths to a Strong Pull Request
+
+### Path 1: Small, Focused Changes
+
+This is the fastest path to review and merge.
+
+- Fix one clear bug or add one tightly scoped improvement
+- Touch the fewest files you can
+- Avoid drive-by refactors mixed into functional changes
+- Run the relevant tests locally before opening the PR
+- Keep the PR description concise and specific
+
+These are the changes that are easiest to review and safest to merge quickly.
+
+### Path 2: Bigger Changes
+
+If you want to change architecture, reshape a workflow, add a substantial UI feature, or alter core behavior, align on direction first.
+
+- Open an issue, start a discussion, or open a draft PR early
+- Explain the problem you are solving, not just the implementation you want
+- Call out tradeoffs, migration risk, and any alternatives you considered
+- Keep the final PR easy to review by separating unrelated work
+
+Large changes are welcome, but surprise rewrites are hard to review well.
+
+## What We Expect in Every PR
+
+### 1. One Logical Change Per PR
+
+Keep each PR focused. A small related group of fixes is fine. A bug fix plus a CSS cleanup plus a refactor plus a docs rewrite is not.
+
+### 2. Local Verification
+
+Run the test suite locally:
+
+```bash
+pytest tests/ -v --timeout=60
+```
+
+CI also runs this suite on Python `3.11`, `3.12`, and `3.13`.
+
+If your change affects browser behavior, also run the relevant manual checks from [TESTING.md](TESTING.md).
+
+### 3. Clear PR Description
+
+There is currently no PR template in this repo, so include the important sections yourself:
+
+- Thinking Path
+- What Changed
+- Why It Matters
+- Verification
+- Risks / Follow-ups
+- Model Used
+
+If the change is user-visible, include screenshots or a short video.
+
+For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images will likely be ignored, or closed in a regular maintainer sweep without review.
+
+### 4. AI Usage Disclosure
+
+If AI helped produce the change, say so in the PR description.
+
+Include:
+
+- Provider
+- Exact model name or ID
+- Any notable mode or tool use that mattered
+
+If no AI was used, write: `None — human-authored`.
+
+### 5. Keep the Docs Honest
+
+If your change alters behavior, architecture, testing, setup, or user-facing workflows, update the relevant docs in the same PR.
+
+Common files:
+
+- [README.md](README.md) for setup, usage, and contributor-facing commands
+- [ROADMAP.md](ROADMAP.md) for shipped features and sprint history
+- [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details and design constraints
+- [TESTING.md](TESTING.md) for manual and automated verification guidance
+- [CHANGELOG.md](CHANGELOG.md) when maintainers want release-note-ready entries
+
+## Project-Specific Guidelines
+
+### Preserve the Design Constraints
+
+Hermes WebUI is deliberately:
+
+- No build step
+- No bundler
+- No frontend framework
+- Easy to modify from a terminal
+
+Do not introduce new infrastructure or dependencies unless the gain is clear and the tradeoff is justified.
+
+### Match the Existing Shape of the Codebase
+
+- Server logic belongs in `api/` with `server.py` staying thin
+- Frontend behavior belongs in the existing `static/*.js` modules
+- Prefer extending current patterns over introducing parallel abstractions
+- Keep changes legible to future contributors working directly from the repo in a terminal
+
+### Be Careful With User-Facing Changes
+
+This project is heavily UI-driven. If you change interaction flows, session behavior, workspace browsing, onboarding, or mobile layouts:
+
+- test the happy path
+- test reload behavior where relevant
+- test narrow/mobile layouts where relevant
+- include before/after images in the PR
+
+### Security and Safety Matter
+
+This app can expose workspace contents, run agent actions, and optionally sit behind a reverse proxy or Docker deployment. Treat auth, path handling, uploads, streaming, and environment handling as high-risk areas.
+
+If your PR touches security-sensitive behavior, say so explicitly in the PR description and explain how you verified it.
+
+## Writing a Good PR Message
+
+Start with a short Thinking Path that explains the chain from project goal to the specific fix.
+
+Example:
+
+> - Hermes WebUI aims for near 1:1 parity with the Hermes CLI in a browser
+> - Long-running chat turns rely on SSE streaming and session recovery
+> - Reloading during an in-flight turn can leave the UI in an inconsistent state
+> - The bug was that recovered sessions restored messages but not the live stream state
+> - This PR fixes the recovery path so in-flight turns reconnect cleanly after reload
+> - The benefit is that users can refresh or reconnect without losing visibility into active work
+
+Another example:
+
+> - Hermes WebUI is intentionally a simple Python + vanilla JS application
+> - The right panel is used for workspace browsing and previews
+> - On mobile, panel state changes need to be obvious and touch-friendly
+> - The existing close affordance was inconsistent with the bottom-nav flow
+> - This PR fixes the mobile panel close behavior and aligns it with the current navigation model
+> - The result is fewer dead-end UI states on phones
+
+After that, cover:
+
+- what you changed
+- why you changed it
+- how you verified it
+- what risks remain
+
+## Review Tips
+
+Want the smoothest review?
+
+- Keep diffs tight
+- Name things clearly
+- Avoid unnecessary rewrites
+- Add short comments only where the code would otherwise be hard to follow
+- Respond directly to review feedback and update the PR description if the scope changes
+
+## Development References
+
+- [README.md](README.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [TESTING.md](TESTING.md)
+- [ROADMAP.md](ROADMAP.md)
+- [SPRINTS.md](SPRINTS.md)
+
+Questions are best raised early, before a large change is finished.

CONTRIBUTORS.md

@@ -0,0 +1,61 @@
+# Contributors
+
+Hermes WebUI is a community project. **66 people** have shipped code that landed in a release tag, including the long tail of folks whose work was salvaged into batch releases. This file is the canonical credit roll. Numbers are merged-PR count plus release-batch credit (a contributor whose patch was extracted into a clean PR or merged via squash gets the same credit as a standalone PR).
+
+**Total contributors tracked:** 66  
+**Total PRs landed:** 142  
+**Last refreshed:** v0.50.245, 2026-04-30
+
+Generated from `git log` + `gh api repos/.../pulls?state=closed` + the `CHANGELOG.md` attribution lines. If your name is missing or wrong, open a PR against `CONTRIBUTORS.md` — we cross-check against the changelog on each release.
+
+---
+
+## Top contributors (5+ merged PRs)
+
+| # | Contributor | PRs | First release | Latest release |
+|---|---|---:|---|---|
+| 1 | [@franksong2702](https://github.com/franksong2702) | 22 | `v0.50.49` 2026-04-15 | `v0.50.245` 2026-04-30 |
+| 2 | [@bergeouss](https://github.com/bergeouss) | 18 | `v0.50.49` 2026-04-15 | `v0.50.240` 2026-04-30 |
+| 3 | [@aronprins](https://github.com/aronprins) | 8 | `v0.47.0` 2026-04-11 | `v0.50.77` 2026-04-17 |
+| 4 | [@iRonin](https://github.com/iRonin) | 6 | `v0.41.0` 2026-04-10 | `v0.41.0` 2026-04-10 |
+| 5 | [@24601](https://github.com/24601) | 6 | `v0.50.201` 2026-04-28 | `v0.50.201` 2026-04-28 |
+
+## Sustained contributors (3–4 merged PRs)
+
+| Contributor | PRs | Highlights |
+|---|---:|---|
+| [@renheqiang](https://github.com/renheqiang) | 4 | feat: add full Russian (ru-RU) localization — v0.50.93 |
+| [@KingBoyAndGirl](https://github.com/KingBoyAndGirl) | 4 | fix: trust custom provider base_url in SSRF validation; fix: fetch live models for custom provider from model.base_u |
+| [@ccqqlo](https://github.com/ccqqlo) | 3 | `v0.50.83` batch credit |
+| [@deboste](https://github.com/deboste) | 3 | fix(frontend): use URL origin for fetch/EventSource to suppo; fix(api): resolve model provider from config to prevent misr |
+| [@frap129](https://github.com/frap129) | 3 | fix(docker): Install Open SSH client; fix(docker): Install all dependencies for agent |
+
+## Two-PR contributors
+
+[@dso2ng](https://github.com/dso2ng), [@Michaelyklam](https://github.com/Michaelyklam), [@mmartial](https://github.com/mmartial), [@renatomott](https://github.com/renatomott), [@zichen0116](https://github.com/zichen0116), [@pavolbiely](https://github.com/pavolbiely), [@bsgdigital](https://github.com/bsgdigital), [@vansour](https://github.com/vansour), [@fecolinhares](https://github.com/fecolinhares).
+
+## Single-PR contributors
+
+Each of these folks landed exactly one merged change — bug fixes, locale work, doc improvements, infrastructure tweaks. Every one of them moved the project forward.
+
+[@Argonaut790](https://github.com/Argonaut790), [@betamod](https://github.com/betamod), [@bschmidy10](https://github.com/bschmidy10), [@carlytwozero](https://github.com/carlytwozero), [@cloudyun888](https://github.com/cloudyun888), [@davidsben](https://github.com/davidsben), [@DavidSchuchert](https://github.com/DavidSchuchert), [@DrMaks22](https://github.com/DrMaks22), [@eba8](https://github.com/eba8), [@fxd-jason](https://github.com/fxd-jason), [@gabogabucho](https://github.com/gabogabucho), [@GiggleSamurai](https://github.com/GiggleSamurai), [@hacker2005](https://github.com/hacker2005), [@halmisen](https://github.com/halmisen), [@happy5318](https://github.com/happy5318), [@hi-friday](https://github.com/hi-friday), [@Hinotoi-agent](https://github.com/Hinotoi-agent), [@huangzt](https://github.com/huangzt), [@jeffscottward](https://github.com/jeffscottward), [@JKJameson](https://github.com/JKJameson), [@KayZz69](https://github.com/KayZz69), [@kcclaw001](https://github.com/kcclaw001), [@kevin-ho](https://github.com/kevin-ho), [@mangodxd](https://github.com/mangodxd), [@mariosam95](https://github.com/mariosam95), [@MatzAgent](https://github.com/MatzAgent), [@mbac](https://github.com/mbac), [@migueltavares](https://github.com/migueltavares), [@nickgiulioni1](https://github.com/nickgiulioni1), [@octo-patch](https://github.com/octo-patch), [@qxxaa](https://github.com/qxxaa), [@ruxme](https://github.com/ruxme), [@SaulgoodMan-C](https://github.com/SaulgoodMan-C), [@smurmann](https://github.com/smurmann), [@Stampede](https://github.com/Stampede), [@starship-s](https://github.com/starship-s), [@suinia](https://github.com/suinia), [@TaraTheStar](https://github.com/TaraTheStar), [@tgaalman](https://github.com/tgaalman), [@thadreber-web](https://github.com/thadreber-web), [@the-own-lab](https://github.com/the-own-lab), [@vcavichini](https://github.com/vcavichini), [@vCillusion](https://github.com/vCillusion), [@woaijiadanoo](https://github.com/woaijiadanoo), [@xingyue52077](https://github.com/xingyue52077), [@yunyunyunyun-yun](https://github.com/yunyunyunyun-yun), [@yzp12138](https://github.com/yzp12138).
+
+---
+
+## How credit is tracked
+
+Most PRs in this repo land via one of three paths:
+
+1. **Direct merge** — your PR is reviewed and merged on its own. Author shows up directly in `git log`.
+2. **Squash into a batch release** — your PR is merged together with several other contributor PRs into a single release commit (e.g. `release: v0.50.245 — 10-PR batch`). The squashed commit carries a `Co-authored-by: <you>` trailer plus an entry in `CHANGELOG.md` crediting you by username and PR number.
+3. **Salvaged from a larger PR** — when a PR mixes one good change with several unrelated or risky ones, we sometimes split it: the good parts ship in a clean follow-up PR, you get credit in the CHANGELOG entry, and the original PR is closed with a salvage map showing what went where.
+
+All three paths count as a contribution. The number next to your name above is the total of merged PRs (path 1) plus PRs where you got attribution credit in CHANGELOG.md (paths 2 and 3).
+
+## Special thanks
+
+- **[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242). The CSS-only redesign that defined the design tokens, theme architecture, and three-panel layout that the rest of the app builds on. The PR didn't merge as-is — it was reshaped through `v0.50.0` — but it is the design language of the app.
+- **[@franksong2702](https://github.com/franksong2702)** — most prolific external contributor. Mobile/responsive layout, session sidebar polish, cron output preservation, streaming-session sidebar exemption, and a long tail of profile/workspace fixes.
+- **[@bergeouss](https://github.com/bergeouss)** — provider-management UI, OAuth status, two-container Docker docs, profile isolation hardening. Most of what users see when they touch Settings → Providers is bergeouss's work.
+
+If you've contributed and aren't here, **open a PR**. We cross-check the CHANGELOG, but if a credit fell through (a Co-authored-by trailer that didn't make it into the changelog entry, an attribution in a comment that should be on the PR), this list is the right place to fix it.

DESIGN.md

@@ -0,0 +1,173 @@
+---
+version: alpha
+name: Hermes Calm Console
+description: "A restrained agent control surface: conversational content first, tool traces as quiet metadata, minimal chrome."
+colors:
+  primary: "#EAE0D5"
+  secondary: "#C6AC8F"
+  tertiary: "#C6AC8F"
+  neutral: "#0A0908"
+  surface: "#22333B"
+  surfaceSubtle: "#11100E"
+  borderSubtle: "#3B4A50"
+  ink: "#0A0908"
+  success: "#86C08B"
+  warning: "#E0B15D"
+  error: "#F87171"
+typography:
+  body-md:
+    fontFamily: "Georgia, Times New Roman, serif"
+    fontSize: 15px
+    fontWeight: 400
+    lineHeight: 1.68
+  body-sm:
+    fontFamily: "-apple-system, BlinkMacSystemFont, Segoe UI, Inter, system-ui, sans-serif"
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 1.45
+  user-message:
+    fontFamily: "-apple-system, BlinkMacSystemFont, Segoe UI, Inter, system-ui, sans-serif"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.55
+  mono-xs:
+    fontFamily: "SF Mono, ui-monospace, monospace"
+    fontSize: 11px
+    fontWeight: 500
+    lineHeight: 1.55
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 12px
+  pill: 999px
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 12px
+  lg: 16px
+components:
+  app-shell:
+    backgroundColor: "{colors.neutral}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.sm}"
+    padding: 16px
+  panel:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.lg}"
+    padding: 16px
+  border-line:
+    backgroundColor: "{colors.borderSubtle}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-success:
+    backgroundColor: "{colors.success}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-warning:
+    backgroundColor: "{colors.warning}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-error:
+    backgroundColor: "{colors.error}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  tool-call-group:
+    backgroundColor: "{colors.neutral}"
+    textColor: "{colors.secondary}"
+    rounded: "{rounded.md}"
+    padding: 4px
+  tool-card:
+    backgroundColor: "{colors.surfaceSubtle}"
+    textColor: "{colors.secondary}"
+    rounded: "{rounded.md}"
+    padding: 8px
+  user-message:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.lg}"
+    padding: 12px
+---
+
+## Overview
+
+Hermes WebUI should feel like a calm developer console, not a demo page assembled from colorful cards. The primary artifact is the conversation. Tool calls, thinking traces, context compaction records, token usage, and runtime status are useful, but they are transcript metadata and should sit below the visual priority of user and assistant prose.
+
+The desired direction is Linear/Vercel precision with a little Claude-style conversational warmth: quiet surfaces, clear spacing, restrained accent use, and progressive disclosure for debugging detail.
+
+## Colors
+
+- **Primary (#EAE0D5):** main text on dark surfaces. The warm parchment should feel readable and grounded, not like bright white terminal text.
+- **Secondary/Tertiary (#C6AC8F):** metadata and restrained accent. Use sparingly for active state, focus, user bubbles, and quiet emphasis.
+- **Neutral (#0A0908):** app background and ink. This gives the WebUI depth without returning to the previous navy/gold theme.
+- **Surface (#22333B):** panels, sidebar, and stronger interactive surfaces. It should carry the structure while the conversation remains primary.
+- **Light surfaces (#EAE0D5 / #F4EEE7):** light mode uses the palette's parchment as the field and a slightly lifted derived surface for panels.
+- **Semantic colors:** success/warning/error/info are state colors only, not decorative palette choices.
+
+## Typography
+
+Use Claude-like split typography: assistant prose gets an editorial serif stack (Georgia as the available substitute for Anthropic Serif), while user bubbles and functional UI stay in a crisp sans stack. This keeps the bot voice calmer and more readable without making controls feel bookish. Use monospace only for code, file paths, commands, tool names, and compact metadata. Avoid making whole cards feel like terminal output unless they actually are logs.
+
+Scale should stay tight: 11px metadata, 12px labels, 14px body, 16–18px headings. Do not proliferate 10px/10.5px/12.5px one-offs unless there is a real layout constraint.
+
+## Layout
+
+Conversation rhythm:
+
+1. User message — right aligned, compact bubble.
+2. Assistant content — left aligned, prose-first, no heavy bubble.
+3. Tool/thinking/context traces — quiet disclosure rows inside the assistant turn.
+4. Raw logs/details — hidden until explicitly expanded.
+
+Metadata should not break the reading flow. A turn that used ten tools should read as one assistant turn with one compact `Used 10 tools` disclosure, not ten content cards.
+
+## Elevation & Depth
+
+Use almost no shadows in the transcript. Shadows are reserved for popovers, dropdowns, modal dialogs, and floating controls. Cards inside chat should use either a subtle border or a subtle tint, not both aggressively.
+
+## Shapes
+
+- Rows/list items: `4–8px` radius.
+- Cards/panels: `8–12px` radius.
+- Pills: only true chips/badges use `999px`.
+- Avoid stacks of nested rounded rectangles. If a card contains another card, one of them is probably unnecessary.
+
+## Components
+
+### Tool/thinking activity group
+
+Collapsed by default in settled history and during live runs. Summary line uses one disclosure for internals, e.g. `Activity: thinking + 4 tools · read_file, patch, terminal`. Expanding reveals thinking and individual tool cards together. Thinking and tools should not create separate transcript rows unless there is an error or approval state that needs attention.
+
+### Tool card
+
+A tool card is a debug event row, not a chat message. Show icon, name, short target/preview, and status. Arguments and result snippets stay behind expansion. Result snippets should be truncated; full logs belong behind “show more”.
+
+### Thinking/context cards
+
+Same visual family as tool-call metadata. They should be quieter than assistant prose and should not use bright tinted full cards unless the user expands them.
+
+### Composer
+
+The composer is the command surface. Keep it legible and focused: modest radius, subtle border, transparent inactive chips, no theatrical hover scaling.
+
+## Do's and Don'ts
+
+Do:
+
+- Collapse noisy agent internals by default.
+- Use one accent color at a time.
+- Prefer neutral borders and restrained surfaces.
+- Make debug traces accessible and inspectable without making them visually dominant.
+- Add stable class/data hooks for future visual regression tests.
+
+Don't:
+
+- Render every tool call as a first-class chat card.
+- Mix gold, cyan, purple, orange, red, and green as decorative colors in the same viewport.
+- Add new hardcoded radius/color values when a token exists.
+- Use shadows, gradients, and hover transforms for routine controls.
+- Hide important error or approval states; those are allowed to be prominent because they require action.

Dockerfile

@@ -3,21 +3,97 @@ FROM python:3.12-slim
 LABEL maintainer="nesquena"
 LABEL description="Hermes Web UI — browser interface for Hermes Agent"
 
-WORKDIR /app
+# Install system packages
+ENV DEBIAN_FRONTEND=noninteractive
 
-# Copy source
-COPY . /app
+# Make use of apt-cacher-ng if available
+RUN if [ "A${BUILD_APT_PROXY:-}" != "A" ]; then \
+        echo "Using APT proxy: ${BUILD_APT_PROXY}"; \
+        printf 'Acquire::http::Proxy "%s";\n' "$BUILD_APT_PROXY" > /etc/apt/apt.conf.d/01proxy; \
+    fi \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates wget gnupg \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
 
-# Install Python dependencies
-RUN pip install --no-cache-dir -r requirements.txt
+RUN apt-get update -y --fix-missing --no-install-recommends \
+    && apt-get install -y --no-install-recommends \
+    apt-utils \
+    locales \
+    ca-certificates \
+    sudo \
+    curl \
+    rsync \
+    openssh-client \
+    && apt-get upgrade -y \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# UTF-8
+RUN localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
+ENV LANG=en_US.utf8
+ENV LC_ALL=C
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONIOENCODING=utf-8
+
+WORKDIR /apptoo
+
+# Every sudo group user does not need a password
+RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+
+# Create a new group for the hermeswebui and hermeswebuitoo users
+RUN groupadd -g 1024 hermeswebui \ 
+    && groupadd -g 1025 hermeswebuitoo
+
+# The hermeswebui (resp. hermeswebuitoo) user will have UID 1024 (resp. 1025), 
+# be part of the hermeswebui (resp. hermeswebuitoo) and users groups and be sudo capable (passwordless) 
+RUN useradd -u 1024 -d /home/hermeswebui -g hermeswebui -s /bin/bash -m hermeswebui \
+    && usermod -G users hermeswebui \
+    && adduser hermeswebui sudo
+RUN useradd -u 1025 -d /home/hermeswebuitoo -g hermeswebuitoo -s /bin/bash -m hermeswebuitoo \
+    && usermod -G users hermeswebuitoo \
+    && adduser hermeswebuitoo sudo
+RUN chown -R hermeswebuitoo:hermeswebuitoo /apptoo
+
+USER root
+
+COPY --chmod=555 docker_init.bash /hermeswebui_init.bash
+
+RUN touch /.within_container
+
+# Remove APT proxy configuration and clean up APT downloaded files
+RUN rm -rf /var/lib/apt/lists/* /etc/apt/apt.conf.d/01proxy \
+    && apt-get clean
+
+USER root
+
+# Pre-install uv system-wide so the container doesn't need internet access at runtime.
+# Installing as root places uv in /usr/local/bin, available to all users.
+# The init script will skip the download when uv is already on PATH.
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
+
+USER hermeswebuitoo
+
+COPY --chown=hermeswebuitoo:hermeswebuitoo . /apptoo
+
+# Bake the git version tag into the image so the settings badge works even
+# when .git is not present (it is excluded by .dockerignore).
+# CI passes: --build-arg HERMES_VERSION=$(git describe --tags --always)
+# Local builds that omit the arg get "unknown" as the fallback.
+ARG HERMES_VERSION=unknown
+RUN echo "__version__ = '${HERMES_VERSION}'" > /apptoo/api/_version.py
 
 # Default to binding all interfaces (required for container networking)
 ENV HERMES_WEBUI_HOST=0.0.0.0
 ENV HERMES_WEBUI_PORT=8787
 
-# State directory (mount as volume for persistence)
-ENV HERMES_WEBUI_STATE_DIR=/data
-
 EXPOSE 8787
 
-CMD ["python", "server.py"]
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8787/health || exit 1
+
+CMD ["/hermeswebui_init.bash"]
+

HERMES.md

@@ -1,165 +1,176 @@
 # Why Hermes
 
-Hermes is a persistent, autonomous AI agent that lives on your server. It remembers everything,
-schedules work while you sleep, and gets more capable the longer it runs. This document explains
-the mental model, why that matters, and how Hermes compares to every major AI tool available today.
+Hermes is a persistent, autonomous AI agent that runs on your server. It has layered memory that
+accumulates across sessions, a cron scheduler that fires jobs while you're offline, and a
+self-improving skills system that saves reusable procedures automatically. You reach it from a
+terminal, a browser, or a messaging app — and it's the same agent with the same history every time.
+
+This document explains the mental model, how Hermes compares to other tools honestly, and where
+it is and is not the right choice.
 
 ---
 
-## The Core Idea: Assistants Forget. Agents Don't.
+## The real problem: most tools are excellent in the moment and weak over time
 
-Every time you open Claude Code, Codex, or a chat window, the tool starts from zero. It does not
-know who you are, what you worked on yesterday, how your repo is structured, or what bugs you
-already fixed. You re-explain yourself every single session. The tool is powerful in the moment
-and useless the next day.
+Memory is no longer a differentiator on its own. ChatGPT, Claude, Cursor, and GitHub Copilot all
+have some form of memory now. Anthropic, OpenAI, and Microsoft are all shipping scheduling and
+agent features. The category boundaries that existed twelve months ago are blurring fast.
 
-Hermes fills that gap. It runs on your server, retains context across every session, and acts
-on your behalf whether or not you are at a keyboard.
+Hermes is not the only tool with memory or automation. It is the tool that makes those
+capabilities durable, self-hosted, cross-surface, and cumulative on your own server. The
+distinction that matters is not "has memory" vs. "has no memory" — it's whether context persists
+across sessions automatically, whether execution happens on hardware you control, whether you can
+reach the same agent identity from any device, and whether the system gets meaningfully better at
+your specific workflow over time without manual configuration.
 
 ```
-Assistant model:  You -> [Tool] -> Answer -> Done
-                  (tool forgets everything when the window closes)
+Session-scoped:   You -> [Tool] -> Answer -> Done
+                  (some tools now carry memory, but the execution is stateless)
 
-Agent model:      You <-> [Hermes] <-> (memory, skills, schedule, tools)
-                  (persistent, learns your stack, acts on your behalf, runs while you're offline)
+Persistent agent: You <-> [Hermes] <-> (memory, skills, schedule, tools, surfaces)
+                  (runs on your server, accumulates context, acts on your behalf offline)
 ```
 
 ---
 
-## The Three Pillars
+## A note on convergence
 
-### 1. Memory That Compounds
+The market is converging. Chat assistants are adding task scheduling and file connectors. IDE
+tools are launching cloud agent modes. CLI tools are adding skills systems and mobile surfaces.
+The lines between "assistant," "editor," and "agent" are dissolving.
 
-Hermes has layered memory that survives every session, every reboot, every model swap:
+This makes comparisons harder but also makes the question sharper: what actually matters when
+every tool is claiming some version of every feature? For Hermes, the answer is synthesis. Any
+single feature — memory, scheduling, messaging — is available somewhere else. The value is
+having all of them in one self-hosted system, running continuously, with a persistent identity
+that accumulates real knowledge of your stack over time.
 
-- **User profile** -- who you are, your preferences, your communication style, things you've
-  corrected Hermes on
-- **Agent memory** -- facts about your environment, your toolchain, your project conventions
-- **Skills** -- reusable procedures Hermes discovers and saves; it never has to relearn how to
-  deploy your app, run your tests, or review a PR
-- **Session history** -- every past conversation is searchable; Hermes can recall what you
-  worked on last Tuesday
+---
+
+## The three pillars
+
+### 1. Memory that compounds
+
+Hermes has layered memory that survives every session, every reboot, and every model swap:
+
+- User profile — who you are, your preferences, your communication style, things you've corrected Hermes on
+- Agent memory — facts about your environment, your toolchain, your project conventions
+- Skills — reusable procedures Hermes discovers and saves automatically; it never has to relearn how to deploy your app, run your tests, or review a PR
+- Session history — every past conversation is searchable; Hermes can recall what you worked on last Tuesday
 
 When you correct Hermes, it remembers. When it solves a tricky problem, it saves the approach.
-When it learns your stack, that knowledge carries into every future session.
+When it learns your stack, that knowledge carries into every future session. You never configure
+this manually — it happens in the background as a side effect of normal use.
 
-### 2. Autonomous Scheduling
+### 2. Autonomous scheduling
 
-Hermes can run jobs without you present -- every hour, every morning, on any cron schedule.
-It fires up a fresh session, runs the task, and delivers the result to wherever you want it:
-Telegram, Discord, Slack, Signal, WhatsApp, SMS, email, and more.
+Hermes can run jobs without you present — every hour, every morning, on any cron schedule. It
+fires up a fresh session with full access to your memory and skills, runs the task, and delivers
+the result wherever you want it: Telegram, Discord, Slack, Signal, WhatsApp, SMS, email, and more.
 
 Things Hermes can do while you sleep:
 
 - Review new pull requests on your GitHub repo and post a full verdict comment
-- Send you a morning briefing of news, markets, or anything else you care about
+- Send a morning briefing of news, markets, or anything else you track
 - Run your test suite and alert you if something breaks
 - Watch a competitor's blog for new posts and summarize them
 - Monitor a datasource and notify you when a threshold is crossed
 
-### 3. Reach It From Anywhere
+The difference from cloud-scheduled alternatives is that the job runs on your server, with your
+memory and skills, and your data never leaves your hardware.
+
+### 3. Reach it from anywhere
 
 Hermes runs on your server and is reachable from every surface: terminal over SSH, the web UI
 (this project), and messaging apps including Telegram, Discord, Slack, WhatsApp, Signal, and
 Matrix. Start a task from your phone, check it from the browser on your laptop, continue it in
-a terminal on a remote server. The same agent, memory, and history follow you everywhere.
+a terminal on a remote server. The same agent, memory, and history follow you across all of them.
 
 ---
 
-## A Framework for AI Tools
+## How AI tools are layered today
 
-There are four distinct categories of AI tool. Understanding the category tells you what a tool
-can and cannot do.
+The old four-category model — chat, editor, CLI, agent — is too clean. These layers are actively
+collapsing into each other. Here is a more honest picture:
 
-### Category 1: Chat Assistants
-*Claude.ai, ChatGPT, Gemini*
+Chat assistants (Claude.ai, ChatGPT) now have persistent memory, task scheduling, 50+ service
+connectors, and in some cases full agent modes with computer use. They are no longer "just chat."
 
-You open a window, ask something, get an answer. No persistent memory beyond the conversation,
-no ability to run code or touch files, no way to act on your behalf. Excellent for Q&A,
-drafting, and brainstorming. You re-explain your context every session.
+IDE tools (Cursor, Windsurf, Copilot) have shipped or are shipping cross-session memory,
+cloud-based background agents, and in Cursor's case a full Automations platform with Slack
+integration. Cursor v3.0 (April 2026) is explicitly agent-first.
 
-### Category 2: IDE Integrations
-*GitHub Copilot, Cursor, Windsurf, Zed AI*
+CLI tools (Claude Code, Codex, OpenCode) have added hooks, skills, desktop app automations,
+and multi-surface reach. Claude Code now spans terminal, IDE, desktop, and browser. Codex has
+become a product family: CLI, IDE extension, desktop app, and Codex Cloud.
 
-Deep inside your editor. Autocomplete, inline diffs, refactors -- all excellent. Windsurf was
-earliest with workspace-scoped memory (Cascade Memories); Copilot has been shipping repo-level
-memory since late 2025 and is catching up. Cursor has no native memory as of early 2026. None
-have scheduling or messaging access. Tied to one machine and one editor.
+Persistent self-hosted agents (Hermes, OpenClaw) sit at the intersection: they combine the
+tool-use power of CLI agents, the memory of chat assistants, the scheduling of automation
+platforms, and the cross-surface reach of messaging integrations — running continuously on
+hardware you own.
 
-### Category 3: Agentic CLI Tools
-*Claude Code, Codex CLI, OpenCode, Aider*
-
-The current frontier for most developers. Can use real tools -- run shell commands, read and
-write files, search the web, call APIs. Great for deep, multi-step tasks in a single terminal
-session. All are adding memory and scheduling features to varying degrees (see comparisons below),
-but the core model is still session-scoped: you invoke it, it works, it stops.
-
-### Category 4: Persistent Autonomous Agents
-*Hermes, OpenClaw (as of early 2026)*
-
-All the tool use of Category 3, plus memory that accumulates across sessions, plus always-on
-scheduling, plus multi-modal access from any device or messaging app. Gets more useful over time
-rather than resetting to zero. Hermes and OpenClaw are the two primary open-source, self-hosted
-tools in this category. OpenClaw is a gateway-centric automation platform; Hermes is a
-self-improving agent that writes and reuses its own procedures from experience.
+The question is not which category a tool belongs to. The question is which combination of
+capabilities you actually need, where that execution lives, and whether the system gets better
+at your specific context over time.
 
 ---
 
-## How Hermes Compares
+## How Hermes compares
 
 ### vs. OpenClaw
 
-OpenClaw is the most direct comparison to Hermes and the question most people ask first.
-Both are open-source, self-hosted, always-on agents with persistent memory, cron scheduling,
-and messaging app integration. If you're evaluating Hermes, you should evaluate OpenClaw too.
+OpenClaw is the most direct comparison and the question most people ask first. Both are
+open-source, self-hosted, always-on agents with persistent memory, cron scheduling, and messaging
+app integration. If you're evaluating Hermes, evaluate OpenClaw too.
 
-OpenClaw (MIT, ~347k GitHub stars) is built around a **Gateway** control plane written in
-Node.js/TypeScript. It excels at broad personal automation: native Chrome/Chromium control for
-browser automation, the widest messaging platform support in the space (WhatsApp, Telegram,
-Signal, iMessage, LINE, WeChat, Slack, Discord, Teams, Matrix, and more), voice wake words,
-and a ClawHub skill marketplace where users share pre-built automations. The community is large
-and the ecosystem is growing fast.
+OpenClaw (MIT) is built around a Gateway control plane written in Node.js/TypeScript. It has the
+widest messaging coverage in the space — 24+ channels including WhatsApp, Telegram, Signal,
+iMessage, LINE, WeChat, Slack, Discord, Teams, Matrix, Google Chat, Feishu, Mattermost, IRC,
+Nextcloud Talk, and more. It has native Chrome/Chromium control via CDP, voice wake words on
+macOS and iOS, and a ClawHub marketplace with 10,700+ skills. The community is large (350k+
+GitHub stars, 16,900+ commits) and growing.
 
-Hermes takes a different approach. It is built in Python and centers on a **self-improving
-agent loop** rather than a gateway control plane. The core difference is in how skills work:
-OpenClaw skills are primarily human-authored plugins installed from a marketplace; Hermes
-**writes and saves its own skills automatically** as part of every session. When Hermes solves
-a problem a new way, it saves the procedure and reuses it going forward without any user effort.
+Hermes is built in Python and centers on a self-improving agent loop rather than a gateway
+control plane. The core architectural difference is in skills: OpenClaw skills are primarily
+human-authored plugins installed from a marketplace. Hermes writes and saves its own skills
+automatically as part of every session. When Hermes solves a problem a new way, it saves the
+procedure and reuses it without any user effort. That's not a subtle distinction — it's the
+reason Hermes gets meaningfully better at your workflow without you maintaining a plugin library.
 
-Beyond the skills architecture, there are two other practical differences worth knowing:
+Two practical differences worth knowing directly:
 
-**Stability.** OpenClaw's community forums and GitHub issues document a recurring pattern of
-update-breaking regressions -- for example, Telegram integration was broken across multiple
-releases in early 2026. The unofficial WhatsApp Web protocol OpenClaw uses is known to
-disconnect and requires periodic re-pairing (this is documented in OpenClaw's own FAQ).
-Hermes has had no equivalent release breakages.
+Stability. OpenClaw's GitHub issues and community forums document recurring update-breaking
+regressions. Telegram integration was broken across multiple releases from early 2026 through
+at least April 2026. The unofficial WhatsApp Web protocol OpenClaw relies on disconnects and
+requires periodic re-pairing — this is in OpenClaw's own FAQ.
 
-**Security.** ClawHub's open publishing model has been exploited repeatedly. A community audit
-identified over a thousand malicious skills in the marketplace including prompt injections and
-tool-poisoning payloads; the community-maintained awesome-openclaw-skills list tracks confirmed
-removals and flags known bad actors. Hermes has no third-party marketplace and a correspondingly
-smaller attack surface.
+Security. ClawHub's open publishing model has been exploited at scale. Three separate audits in
+early 2026 found serious problems: Koi Security (January 2026) linked 335 skills to a campaign
+called "ClawHavoc" that delivered Atomic Stealer malware on macOS; Bitdefender found roughly
+900 malicious packages representing about 20% of the ecosystem at the time; Snyk's "ToxicSkills"
+report (February 2026) found malicious skills across roughly 4,000 scanned packages. China's
+CNCERT issued a national warning about ClawHub. Hermes has no third-party marketplace and a
+correspondingly smaller attack surface.
 
-**OpenClaw's genuine strengths** are worth stating plainly: it has broader messaging coverage
-(iMessage, LINE, WeChat, Teams -- platforms Hermes does not support), native browser and
-computer control via Chrome CDP, voice wake words on macOS and iOS, a larger community, and
-more third-party integrations than Hermes. If those capabilities matter most to you, OpenClaw
-is worth a serious look.
+OpenClaw's genuine strengths are worth stating plainly: broader messaging coverage (iMessage,
+LINE, WeChat, Teams, Google Chat — platforms Hermes does not support), native browser and
+computer control via Chrome CDP, voice wake words, a larger community, and more third-party
+integrations than Hermes. If those capabilities matter most, OpenClaw is worth a serious look.
 
-Where Hermes is the better fit: you want an agent that self-improves from experience without
-manual plugin authoring, you work in Python and want access to the ML/data science ecosystem,
-you want a stable deployment that does not break between updates, or you want a full web chat
-UI rather than a monitoring dashboard.
+Where Hermes fits better: you want an agent that self-improves from experience without managing
+a plugin library, you work in Python and want the ML/data science ecosystem, you want a stable
+deployment that doesn't break between updates, or you want a full web chat UI rather than a
+control dashboard.
 
 | | OpenClaw | Hermes |
 |---|---|---|
 | Persistent memory | Yes | Yes |
 | Scheduled jobs (cron) | Yes | Yes |
-| Messaging app access | Yes (15+ platforms, incl. iMessage/WeChat) | Yes (10+ platforms) |
-| Web UI | Gateway dashboard (monitoring only) | Full three-panel chat UI |
+| Messaging app access | Yes (24+ platforms, incl. iMessage/WeChat/LINE) | Yes (many platforms) |
+| Web UI | Chat UI + control dashboard | Full three-panel chat UI |
 | Self-hosted | Yes | Yes |
 | Open source | Yes (MIT) | Yes |
-| Self-improving skills | Partial (AI can generate skills; not the default loop) | Yes (automatic, first-class) |
+| Self-improving skills | Partial (AI can generate; not the default loop) | Yes (automatic, first-class) |
 | Browser / computer control | Yes (native Chrome CDP) | Via shell / tools |
 | Voice wake words | Yes (macOS/iOS) | No |
 | Python / ML ecosystem | No (Node.js) | Yes |
@@ -167,209 +178,312 @@ UI rather than a monitoring dashboard.
 | Multi-profile support | Via binding-rule routing | Yes (first-class named profiles) |
 | Provider-agnostic | Yes | Yes |
 | Update reliability | Moderate (documented regressions) | High |
+| Memory inspectability | Limited | Yes (markdown files, editable) |
+| Self-hosted autonomous execution | Yes | Yes |
 
 ### vs. Claude Code (Anthropic)
 
-Claude Code is Anthropic's official agentic CLI and one of the best tools in Category 3.
-In a single focused session it is capable -- deep code understanding, shell access, file
-editing, multi-step reasoning.
+Claude Code is Anthropic's official agentic tool and one of the strongest options for focused
+coding sessions. It has deep code understanding, shell access, file editing, and multi-step
+reasoning. It has been expanding rapidly — it now spans terminal, IDE plugin, desktop app, and
+browser surfaces — and the gap is closing in several areas.
 
-Claude Code has been adding features rapidly and the gap is narrowing:
+What Claude Code has that's worth knowing:
 
-- **Hooks system** -- 13 event types (SessionStart, PreToolUse, PostToolUse, Stop, etc.) with
-  4 handler types (shell command, HTTP endpoint, LLM prompt, sub-agent); deterministic
+- Hooks system — 26 event types (SessionStart, PreToolUse, PostToolUse, Stop, and more) with
+  4 handler types (shell command, HTTP endpoint, LLM prompt, sub-agent); gives deterministic
   non-LLM control over the agent lifecycle
-- **Plugins / Skills** -- installable via `/plugin install`, hot-reloaded from `~/.claude/skills`,
-  with a marketplace; skills and slash commands unified as of v2.1.0
-- **Scheduling** -- `/loop` (session-scoped), cloud-managed cron via `claude.ai/code/scheduled`
-  (Anthropic infrastructure, minimum interval applies), and desktop app automations
-- **Messaging channels** -- Telegram, Discord, iMessage, and webhooks via the Channels feature
-  (research preview, v2.1.80+); deep Slack integration that triggers cloud sessions and creates PRs
-- **Claude Cowork** -- a separate product for knowledge workers; connects to 38+
-  services via MCP including Slack, Gmail, Microsoft Teams, Notion, Jira, Salesforce, and more
-- **Memory** -- CLAUDE.md and MEMORY.md for project-level context; auto-memory rolling out
+- Plugins / Skills — installable via `/plugin install`, hot-reloaded from `~/.claude/skills`,
+  with a marketplace; includes the official ralph-wiggum plugin (`/ralph-loop`) for
+  autonomous iteration toward a completion goal (distinct from `/loop`)
+- `/loop` — a native bundled skill, available in every session without any plugin, that runs
+  a prompt on a repeating schedule within an active CLI session (polling/monitoring use case);
+  session-scoped, dies when the terminal closes
+- Scheduling — cloud-managed cron (Anthropic infrastructure, minimum 1-hour interval) and
+  desktop app scheduled tasks (run locally while the app is open, minimum 1-minute interval,
+  full local file access); no self-hosted cron
+- Messaging channels — Telegram, Discord, and iMessage via the Channels feature (research
+  preview, requires Bun runtime); Slack is the most-requested addition and has not yet shipped
+- Memory — CLAUDE.md and MEMORY.md for project-level context; auto-memory since v2.1.59+
+- Claude Cowork — a separate knowledge-worker product connecting 38+ services via MCP
+  including Gmail, Microsoft Teams, Notion, Jira, Salesforce, and more
 
-These are real features. The key differences that remain:
+Claude Code's source was briefly and accidentally made public in March 2026 before being taken
+down. The CLI ships as minified/bundled TypeScript compiled with Bun — it is not open source.
 
-- Claude Code's scheduling runs on **Anthropic's cloud** (or requires the desktop app open),
-  not a self-hosted server; cloud jobs have a minimum interval and your data leaves your hardware
-- Memory is **project-file-based** (CLAUDE.md / MEMORY.md), not a knowledge graph that
-  accumulates automatically across all your work; auto-memory is still rolling out
-- **Not provider-agnostic** -- routes through Bedrock or Vertex but always hits a Claude model;
-  you cannot switch to GPT, Gemini, or a local model
-- **Not open source** -- proprietary; the CLI ships obfuscated JavaScript
-- Messaging channels are a **research preview** requiring Bun runtime; not yet production-grade
+Key differences that remain:
+
+- Scheduling requires cloud (Anthropic infrastructure, data off your hardware, 1-hour minimum)
+  or the desktop app (runs locally, but the app must stay open — not a headless server process);
+  neither runs as a server daemon the way Hermes cron does
+- Memory is project-file-based (CLAUDE.md / MEMORY.md plus rolling auto-memory); it doesn't
+  automatically accumulate a cross-project knowledge graph the way Hermes does
+- Not provider-agnostic — routes through Anthropic, Bedrock, Vertex, or Foundry, but always
+  a Claude model; you can't switch to GPT, Gemini, or a local model
+- Messaging channels are still a research preview, not production
 
 Hermes can use Claude Code as a sub-agent. For large implementation tasks, Hermes can spawn
 Claude Code to handle the heavy lifting and fold the result back into its own memory and history.
 
 | | Claude Code | Hermes |
 |---|---|---|
-| Persistent memory (automatic) | Partial (CLAUDE.md / MEMORY.md, rolling out) | Yes |
-| Skills / hooks system | Yes (Hooks + Plugin/Skills marketplace) | Yes (auto-generated from experience) |
+| Persistent memory (automatic) | Partial (CLAUDE.md / MEMORY.md + auto-memory v2.1.59+) | Yes |
+| Skills / hooks system | Yes (26-event Hooks + Plugin/Skills marketplace) | Yes (auto-generated from experience) |
 | Scheduled jobs (self-hosted) | No (cloud or desktop-app only) | Yes |
-| Messaging access | Partial (Telegram/Discord/iMessage via research preview; Slack native) | Yes (10+ platforms, production) |
+| Messaging access | Partial (Telegram/Discord/iMessage research preview; Slack not yet) | Yes (many platforms, production) |
 | Cowork connectors (Slack, Gmail, etc.) | Yes (via Claude Cowork, separate product) | Via agent tool use |
 | Web UI | Yes (claude.ai/code, Anthropic-hosted) | Yes (self-hosted) |
-| Provider-agnostic | No (Claude models only, via Bedrock/Vertex) | Yes (any provider) |
+| Provider-agnostic | No (Claude models only) | Yes (any provider) |
 | Self-hosted scheduling | No | Yes |
 | Open source | No | Yes |
+| Background/cloud agent mode | Yes (cloud-scheduled) | Yes (self-hosted cron) |
 | Runs as sub-agent of Hermes | Yes | N/A |
+| Memory inspectability | Partial (CLAUDE.md readable; auto-memory less so) | Yes (markdown files) |
 
 ### vs. Codex CLI (OpenAI)
 
-Codex CLI is OpenAI's open-source agentic terminal tool (Apache 2.0, ~73k GitHub stars). It
-supports 10+ providers including Anthropic, Google, Mistral, Groq, and local models via Ollama.
-It added persistent session memory in v0.100.0 with `codex resume`. The desktop app has an
-Automations feature for scheduled local tasks.
+Codex CLI (Apache 2.0, ~60k GitHub stars) started as a straightforward terminal tool and has
+expanded into a product family. It was rewritten from TypeScript to Rust. It now includes an IDE
+extension, a desktop app with an Automations feature, and Codex Cloud for remote execution. A
+Skills system is shared across surfaces. It supports 12+ built-in providers: OpenAI, Anthropic,
+Google/Gemini, Mistral, Groq, Ollama, OpenRouter, LM Studio, Together AI, DeepSeek, xAI,
+Azure OpenAI, and custom endpoints.
 
-The CLI itself has no native scheduling (open feature request as of early 2026). Memory is
-session-history-based rather than a living knowledge graph. No messaging app access. A strong
-tool for single-session coding; Hermes adds the always-on layer on top.
+The CLI itself has no native scheduling (open feature request). Session continuity is available
+via `codex resume`. Memory is session-history-based plus AGENTS.md project context — not a
+living knowledge graph that accumulates across all your projects. No first-party messaging
+integration. The Automations feature in the desktop app covers scheduled local tasks but doesn't
+reach the cross-session, cross-surface continuity Hermes has.
 
 | | Codex CLI | Hermes |
 |---|---|---|
 | Persistent memory | Partial (session history + AGENTS.md) | Yes (automatic, layered) |
-| Scheduled jobs | Partial (desktop app only; CLI has none) | Yes |
+| Scheduled jobs | Partial (desktop app Automations; CLI has none) | Yes |
 | Messaging app access | No | Yes |
-| Web UI | No | Yes (self-hosted) |
-| Provider-agnostic | Yes (10+ providers) | Yes (10+ providers) |
+| Web UI | No (CLI + desktop app) | Yes (self-hosted) |
+| Provider-agnostic | Yes (12+ providers) | Yes |
 | Self-hosted | Yes | Yes |
 | Open source | Yes (Apache 2.0) | Yes |
+| Background/cloud agent mode | Yes (Codex Cloud) | Yes (self-hosted cron) |
+| Self-improving skills | No | Yes |
 
 ### vs. OpenCode
 
-OpenCode is an open-source TUI agentic coding assistant, provider-agnostic across 75+ providers.
-It has a WebUI embedded in its binary and an official desktop app. It uses SQLite for session
-history and AGENTS.md for project context.
+OpenCode is an open-source TUI agentic coding assistant supporting 75+ providers. It has a WebUI
+embedded in its binary, an official desktop app, SQLite session history, and AGENTS.md project
+context. It supports CLAUDE.md as a fallback for users migrating from Claude Code. There are 30+
+community plugins, and community messaging integrations exist for Telegram, Slack, Discord, and
+Microsoft Teams — though none are first-party and all require manual setup.
 
-No native scheduled jobs (a community background plugin exists), no first-party messaging
-integration (community Telegram bots exist but require manual setup), and no automatic
-cross-session semantic memory. Good for interactive terminal coding sessions.
+OpenCode Go ($10/month) and OpenCode Zen (curated model service) are subscription tiers. The
+GitHub Copilot official integration launched January 2026. There is no native scheduling; a
+community background plugin exists. No automatic cross-session semantic memory.
 
 | | OpenCode | Hermes |
 |---|---|---|
 | Persistent memory | Partial (session history + AGENTS.md) | Yes (automatic, layered) |
 | Scheduled jobs | No (community plugin only) | Yes |
-| Messaging app access | No (community Telegram bot only) | Yes (first-party, 10+ platforms) |
+| Messaging app access | Community integrations only (Telegram/Slack/Discord/Teams) | Yes (first-party, many platforms) |
 | Web UI | Yes (embedded + desktop app) | Yes (self-hosted) |
 | Mobile access | No | Yes |
-| Skills system | No | Yes |
+| Skills / plugins | Yes (30+ community plugins) | Yes (auto-generated, first-party) |
 | Provider-agnostic | Yes (75+ providers) | Yes |
 | Open source | Yes | Yes |
+| Self-hosted autonomous execution | No | Yes |
 
-### vs. Cursor / Windsurf / Copilot
+### vs. Cursor
 
-Category 2 tools -- exceptional at in-editor autocomplete, inline diffs, and code review.
-Not competing for the same job as Hermes, and they work well alongside it.
+Cursor has changed substantially. The "no memory, no scheduling, no messaging" description was
+accurate in 2024 and is wrong now.
 
-Windsurf was earliest with workspace-scoped memory (Cascade Memories); Copilot has been
-shipping repo-level memory since late 2025. Cursor has no native cross-session memory as of
-early 2026. None have scheduling or messaging access.
+Memories (per-project cross-session knowledge base) shipped in beta with v1.0 in June 2025.
+Automations launched March 5, 2026 — time-based, event-based (GitHub/Linear/PagerDuty), and
+communication-based (Slack) triggers that fire background agents on cloud VMs. The web app,
+mobile agent, and Slack bot give it multi-surface reach. Cursor v3.0 (April 2, 2026) is
+explicitly agent-first with Design Mode and 30+ marketplace plugins. Cursor acquired Supermaven
+for autocomplete. As of early 2026 it's valued at $29.3B with $2B ARR. It is not a narrow editor
+tool anymore.
+
+Hermes still has a different profile: it's self-hosted and server-resident, the same persistent
+identity follows you across every surface without cloud intermediation, and it works with any
+model family rather than being cloud-VM-based. For workflows that require data sovereignty,
+self-hosted scheduling, or deep Python/ML tooling on your own hardware, Cursor's cloud-agent
+architecture is a fundamental mismatch. For teams that want editor-native agents with strong
+IDE integration, Cursor's recent evolution is significant.
 
 | | Cursor | Windsurf | Copilot | Hermes |
 |---|---|---|---|---|
-| In-editor autocomplete | Excellent | Excellent | Excellent | No |
+| In-editor autocomplete | Excellent (Supermaven) | Excellent (Cascade) | Excellent | No |
 | Inline diff / refactor | Yes | Yes | Yes | Via shell |
-| Cross-session memory | No | Yes (workspace) | Partial (repo, early access) | Yes |
-| Scheduled background jobs | No | No | No | Yes |
-| Messaging app / mobile | No | No | No | Yes |
+| Cross-session memory | Yes (Memories, per-project) | Yes (Cascade Memories, workspace) | Yes (Agentic Memory, repo-scoped, 28-day expiry) | Yes (automatic, persistent) |
+| Scheduled background jobs | Yes (Automations, cloud VM) | No | Via Coding Agent (issue-driven) | Yes (self-hosted cron) |
+| Messaging app / multi-surface | Yes (Slack bot, web app, mobile) | No | Via Copilot CLI / fleet | Yes (many platforms) |
+| Background/cloud agent mode | Yes (Automations on cloud VMs) | No | Yes (Coding Agent, GA Mar 2026) | Yes (self-hosted) |
 | Terminal tool use | Limited | Limited | Limited | Full |
 | Self-hosted | No | No | No | Yes |
-| Provider-agnostic | Partial | Partial | No | Yes |
+| Self-hosted autonomous execution | No | No | No | Yes |
+| Provider-agnostic | Partial | Partial | No (GitHub models) | Yes |
 | Open source | No | No | No | Yes |
+| Memory inspectability | Partial | Yes (stored locally) | Limited | Yes (markdown files) |
 
-### vs. Claude.ai / ChatGPT
+### vs. Claude.ai and ChatGPT
 
-Category 1. For drafting, Q&A, and brainstorming in the moment, both are excellent.
+These are no longer simple chat tools. The description of "no memory, no scheduling, no
+messaging" is inaccurate for both.
 
-Claude.ai memory has been improving -- it now generates memory from chat history, not just
-user-curated entries. Claude.ai can also execute code and read/write files in a sandboxed
-environment via Artifacts. These are real capabilities, just not the same as direct filesystem
-or shell access on your own server.
+Claude Cowork (in Claude Desktop) launched scheduled tasks on February 25, 2026 — hourly,
+daily, weekly, weekdays, and on-demand. It runs in an isolated VM with file and shell access.
+Claude has 50+ service connectors as of February 2026 including Slack (launched January 26,
+2026), Gmail, Google Calendar, Google Drive, Microsoft 365, Notion, Asana, Linear, and Jira.
+Memory auto-generates from chat history, not just user-curated entries. Code execution and
+file access in Artifacts is sandboxed, not the same as shell access on your own server.
 
-| | Claude.ai / ChatGPT | Hermes |
-|---|---|---|
-| Memory across conversations | Yes (improving; auto-generated from history) | Yes (deep, automatic) |
-| Runs shell commands | No | Yes |
-| Code execution | Sandboxed (Artifacts) | Yes (full shell) |
-| Reads / writes files | Sandboxed (Artifacts) | Yes (full filesystem) |
-| Schedules background jobs | No | Yes |
-| Web UI | Yes | Yes |
-| Messaging apps | No | Yes |
-| Self-hosted | No | Yes |
-| Provider-agnostic | No | Yes |
-| Open source | No | Yes |
+ChatGPT has Agent Mode (launched July 17, 2025), Scheduled Tasks (January 2025, recurring
+automated prompts), a computer-using agent, Projects, 50+ connectors including Gmail, GitHub,
+and Google Drive, dual-mode memory (auto + manual), and ChatGPT Pulse for Pro users (daily
+research briefings). It is not a passive Q&A interface.
+
+Where Claude.ai and ChatGPT differ from Hermes: neither is self-hosted, neither is
+provider-agnostic, and neither gives you execution on your own hardware. Connectors and
+scheduling exist, but they run on Anthropic's or OpenAI's infrastructure. Your memory, session
+history, and agent execution live on their servers, not yours. For many use cases that's fine
+— they are capable and well-supported. For privacy-conscious users, regulated environments, or
+workflows that require persistent server-side execution on controlled hardware, it's a
+disqualifying constraint.
+
+| | Claude.ai | ChatGPT | Hermes |
+|---|---|---|---|
+| Memory across conversations | Yes (auto-generated from history) | Yes (dual-mode: auto + manual) | Yes (deep, automatic) |
+| Scheduled tasks | Yes (Cowork: hourly/daily/weekly) | Yes (since Jan 2025) | Yes (any cron, self-hosted) |
+| Service connectors / messaging | Yes (50+ via Cowork) | Yes (50+ connectors) | Yes (many platforms, direct) |
+| Runs shell commands | Sandboxed (Cowork VM) | Sandboxed | Yes (full shell) |
+| Code execution | Sandboxed | Sandboxed | Yes (full shell) |
+| Reads / writes files | Sandboxed | Sandboxed | Yes (full filesystem) |
+| Web UI | Yes (Anthropic-hosted) | Yes (OpenAI-hosted) | Yes (self-hosted) |
+| Self-hosted | No | No | Yes |
+| Provider-agnostic | No | No | Yes |
+| Open source | No | No | Yes |
+| Self-hosted autonomous execution | No | No | Yes |
+| Memory inspectability | Limited | Limited | Yes (markdown files) |
 
 ---
 
-## The Compounding Advantage
+## The compounding advantage
 
-What matters most about Hermes is that it improves over time. That is the point.
+What distinguishes Hermes from most of the tools above is that it gets meaningfully better at
+your specific workflow over time without manual configuration.
 
 Every time Hermes encounters a new environment, it saves facts to memory. Every time it solves
 a problem a new way, it saves the approach as a skill. Every time you correct it, it updates its
-profile of you. Every session, every scheduled job, every tool call, the agent gets more
-calibrated to you and your workflow.
+profile of you. Every session, every scheduled job, every tool call adds to a body of knowledge
+that is specific to you, stored on your hardware, and available to every future interaction.
 
-A Claude Code session on day one and day one hundred are identical. A Hermes agent on day one
-and day one hundred is smarter about you -- it knows your stack, your conventions, your
-preferences, and the solutions that have worked before.
+A Claude Code session on day one and day one hundred are identical — it starts fresh. A Hermes
+agent on day one and day one hundred knows your stack, your conventions, your preferences, and
+the solutions that have worked before. That's the actual compounding.
 
 ---
 
-## Who Hermes Is For
+## Who Hermes is for
 
-**Solo developers and power users** who don't want to re-explain their stack every session and
-want an AI that actually knows their environment.
+Solo developers and power users who don't want to re-explain their stack every session and want
+an AI that actually knows their environment.
 
-**Teams on a shared server** where multiple people want Claude-quality AI access without each
-paying for a separate subscription or running local tooling.
+Teams on a shared server where multiple people want capable AI access without each paying for
+a separate subscription or running separate local tooling.
 
-**Automation-heavy workflows** where you want an AI running tasks on a schedule, delivering
-results to your phone, without babysitting it.
+Automation-heavy workflows where you want an AI running tasks on a schedule, delivering results
+to your phone, without babysitting it.
 
-**Privacy-conscious users** who want their conversations, memory, and files on their own
-hardware.
+Privacy-conscious users who want their conversations, memory, and files on their own hardware.
 
-**Multi-model users** who want to switch between OpenAI, Anthropic, Google, DeepSeek, and
-others based on cost, capability, or rate limits, without rebuilding their workflow each time.
+Multi-model users who want to switch between OpenAI, Anthropic, Google, DeepSeek, and others
+based on cost, capability, or rate limits, without rebuilding their workflow each time.
 
 ---
 
-## Scope and Limits
+## What Hermes is not
 
-**Hermes lives in the terminal, browser, and messaging apps.** For in-editor autocomplete and
-inline diffs, use Cursor or Windsurf alongside it -- they do that job better.
+Hermes is not the best in-editor autocomplete tool. Cursor and Windsurf do that job better.
+Use one alongside Hermes.
 
-**You run Hermes on your own server.** That means initial setup, but your data stays on your
+It is not zero-setup. You are running a server. That means initial configuration, and it means
+you're responsible for uptime, upgrades, and backups. The tradeoff is data sovereignty and
+control; that only makes sense if you actually want it.
+
+It does not make weaker models magical. Memory and skills help, but the underlying model still
+determines reasoning quality. Hermes with a weak model is a well-organized weak model.
+
+It still needs guardrails, approvals, and observability for high-stakes automations. Autonomous
+execution on a schedule with shell access is powerful and requires judgment about what to
+approve. Terminal commands can require confirmation before running; use that for anything
+consequential.
+
+If you need the absolute lowest-friction path to a one-off answer or a quick edit, a chat
+interface or an in-editor tool is the right call. Hermes is for continuity and autonomy, not
+minimum-friction one-shots.
+
+---
+
+## Scope and limits
+
+Hermes lives in the terminal, browser, and messaging apps. For in-editor autocomplete and inline
+diffs, use Cursor or Windsurf — they do that job better and work well alongside Hermes.
+
+You run Hermes on your own server. That means initial setup, but your data stays on your
 hardware and you control the schedule, the models, and the costs.
 
-**Hermes is an orchestration and memory layer.** It makes whatever model you point it at more
-useful over time. The models do the reasoning; Hermes makes sure that reasoning accumulates into
+Hermes is an orchestration and memory layer. It makes whatever model you point at it more useful
+over time. The models do the reasoning; Hermes makes sure that reasoning accumulates into
 something durable.
 
 ---
 
-## Quick Reference
+## Security and control
 
-| | OpenClaw | Claude Code | Codex CLI | OpenCode | Cursor | Claude.ai | Hermes |
-|---|---|---|---|---|---|---|---|
-| Persistent memory (auto) | Yes | Partial† | Partial | Partial | No | Yes (improving) | **Yes** |
-| Scheduled / background jobs | Yes | Partial‡ | Partial§ | No | No | No | **Yes (self-hosted)** |
-| Messaging app access | Yes (15+ platforms) | Partial (Telegram/Discord preview; Slack native) | No | No | No | No | **Yes (10+ platforms)** |
-| Web UI | Dashboard only | Yes (Anthropic cloud) | No | Yes | No | Yes | **Yes (self-hosted)** |
-| Skills system | Yes (marketplace) | Yes (Hooks + Plugins) | No | No | No | No | **Yes** |
-| Self-improving skills | Partial | No | No | No | No | No | **Yes** |
-| Browser / computer control | Yes (Chrome CDP) | No | No | No | No | No | Via shell |
-| Python / ML ecosystem | No (Node.js) | No | No | No | No | No | **Yes** |
-| In-editor autocomplete | No | No | No | No | Yes | No | No |
-| Orchestrates other agents | No | No | No | No | No | No | **Yes** |
-| Provider-agnostic | Yes | No (Claude only) | Yes | Yes | Partial | No | **Yes** |
-| Self-hosted | Yes | No | Yes | Yes | No | No | **Yes** |
-| Open source | Yes (MIT) | No | Yes | Yes | No | No | **Yes** |
-| Always-on / autonomous | Yes | No | No | No | No | No | **Yes** |
+Memory is stored locally on your server as readable, editable files: user profile, agent memory,
+and skills are all markdown. Session history is in SQLite on your machine. You can inspect,
+edit, or delete any of it directly.
 
-† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall  
-‡ Claude Code scheduling: cloud-managed (Anthropic infrastructure) or desktop-app only; no self-hosted cron  
-§ Codex scheduling: desktop app Automations only; CLI has no native scheduling
+If you want external memory providers, eight are supported: Mem0, Honcho, Hindsight, RetainDB,
+ByteRover, Supermemory, Holographic, and others. These are optional and configurable.
+
+Execution runs in configurable backends: local shell, Docker, SSH, Daytona, Singularity, or
+Modal. You choose what execution environment Hermes operates in and what it can reach.
+
+Terminal commands can require confirmation before running. For any automation that touches
+production systems or makes external calls, enable approval controls.
+
+Secrets stay on your hardware. Hermes does not phone home; it calls whatever model APIs you
+configure directly.
+
+Multiple profiles give isolation between users or projects. A shared server can have separate
+profiles with separate memory, separate skills, and separate history.
+
+---
+
+## Quick reference
+
+| | OpenClaw | Claude Code | Codex | OpenCode | Cursor | Copilot | Claude.ai | ChatGPT | Hermes |
+|---|---|---|---|---|---|---|---|---|---|
+| Persistent memory (auto) | Yes | Partial† | Partial | Partial | Yes (per-project) | Yes (repo-scoped‡) | Yes | Yes | Yes |
+| Scheduled / background jobs | Yes | Partial§ | Partial¶ | No | Yes (Automations) | Via Coding Agent | Yes (Cowork) | Yes | Yes (self-hosted) |
+| Messaging / multi-surface | Yes (24+ platforms) | Partial (preview) | No | Community only | Yes (Slack/web/mobile) | Via CLI/fleet | Yes (50+ connectors) | Yes (50+ connectors) | Yes (many platforms) |
+| Web UI | Chat UI + control dashboard | Anthropic-hosted | No | Yes | Yes + mobile | github.com | Yes (Claude Desktop) | Yes | Yes (self-hosted) |
+| Skills system | Yes (ClawHub marketplace) | Yes (Hooks + Plugins) | Partial (Skills) | Community plugins | Yes (marketplace) | No | No | No | Yes (auto-generated) |
+| Self-improving skills | Partial | No | No | No | No | No | No | No | Yes |
+| Browser / computer control | Yes (Chrome CDP) | No | No | No | No | No | No | Yes (CUA) | Via shell |
+| In-editor autocomplete | No | No | Via extension | No | Excellent | Excellent | No | No | No |
+| Orchestrates other agents | No | No | No | No | No | No | No | No | Yes |
+| Provider-agnostic | Yes | No (Claude only) | Yes | Yes | Partial | No | No | No | Yes |
+| Self-hosted | Yes | No | Yes (CLI) | Yes | No | No | No | No | Yes |
+| Self-hosted autonomous execution | Yes | No | No | No | No | No | No | No | Yes |
+| Background/cloud agent mode | Yes | Yes (cloud) | Yes (Codex Cloud) | No | Yes (cloud VMs) | Yes (Coding Agent) | Yes (Cowork VM) | Yes (Agent Mode) | Yes (self-hosted) |
+| Memory inspectability | Limited | Partial | Partial | Partial | Partial | Limited | Limited | Limited | Yes (markdown files) |
+| Open source | Yes (MIT) | No | Yes (Apache 2.0) | Yes | No | No | No | No | Yes |
+| Always-on autonomous execution | Yes | No | No | No | No | No | No | No | Yes |
+
+† Claude Code: CLAUDE.md / MEMORY.md project context plus auto-memory since v2.1.59+; no automatic cross-project accumulation
+‡ Copilot Agentic Memory: public preview Jan 15, 2026; enabled by default Mar 4, 2026; repo-scoped, auto-expires after 28 days
+§ Claude Code scheduling: cloud-managed (Anthropic infrastructure) or desktop-app only; no self-hosted cron
+¶ Codex scheduling: desktop app Automations only; CLI has no native scheduling

README.md

@@ -1,26 +1,29 @@
 # Hermes Web UI
 
-[Hermes Agent](https://hermes-agent.nousresearch.com/) is a sophisticated autonomous agent that lives on your server, accessed via a terminal or messaging apps, remembers what it learns, and gets more capable the longer it runs.
+[Hermes Agent](https://hermes-agent.nousresearch.com/) is a sophisticated autonomous agent that lives on your server, accessed via a terminal or messaging apps, that remembers what it learns and gets more capable the longer it runs.
 
 Hermes WebUI is a lightweight, dark-themed web app interface in your browser for [Hermes Agent](https://hermes-agent.nousresearch.com/).
 Full parity with the CLI experience - everything you can do from a terminal,
 you can do from this UI. No build step, no framework, no bundler. Just Python
 and vanilla JS.
 
-Layout: three-panel Claude-style. Left sidebar for sessions and tools,
-center for chat, right for workspace file browsing.
+Layout: three-panel. Left sidebar for sessions and navigation, center for chat,
+right for workspace file browsing. Model, profile, and workspace controls live in
+the **composer footer** — always visible while composing. A circular context ring
+shows token usage at a glance. All settings and session tools are in the
+**Hermes Control Center** (launcher at the sidebar bottom).
 
-<img alt="Hermes Web UI — three-panel layout" width="1417" height="867" alt="image" src="https://github.com/user-attachments/assets/51adff98-53ee-4800-8508-78b6c34dd3dc" />
+<img width="2448" height="1748" alt="Hermes Web UI — three-panel layout" src="https://github.com/user-attachments/assets/6bf8af4c-209d-441e-8b92-6515d7a0c369" />
 
 <table>
   <tr>
     <td width="50%" align="center">
-      <img alt="Light mode with full profile support" src="https://github.com/user-attachments/assets/9b68142f-d974-4493-a8d1-fd73e622c7fd" />
-      <br /><sub>Workspace file browser with inline preview</sub>
+      <img width="2940" height="1848" alt="Light mode with full profile support" src="https://github.com/user-attachments/assets/4ef3a59c-7a66-4705-b4e7-cb9148fe4c47" />
+      <br /><sub>Light mode with full profile support</sub>
     </td>
     <td width="50%" align="center">
-      <img alt="Customize your settings, and configure a password" src="https://github.com/user-attachments/assets/941f3156-21e3-41fd-bcc8-f975d5000cb8" />
-      <br /><sub>Session projects, tags, and tool call cards</sub>
+      <img alt="Customize your settings, configure a password" src="https://github.com/user-attachments/assets/941f3156-21e3-41fd-bcc8-f975d5000cb8" />
+      <br /><sub>Customize your settings, configure a password</sub>
     </td>
   </tr>
 </table>
@@ -92,54 +95,116 @@ ecosystem. See [HERMES.md](HERMES.md) for the full side-by-side.
 
 ## Quick start
 
-First, you need to install and configure [Hermes Agent](https://hermes-agent.nousresearch.com/). Once installed:
+Run the repo bootstrap:
 
 ```bash
 git clone https://github.com/nesquena/hermes-webui.git hermes-webui
 cd hermes-webui
+python3 bootstrap.py
+```
+
+Or keep using the shell launcher:
+
+```bash
 ./start.sh
 ```
 
-That is it. The script will:
+The bootstrap will:
 
-1. Locate your Hermes agent checkout automatically.
-2. Find (or create) a Python environment with the required dependencies.
-3. Start the server.
-4. Print the URL (and SSH tunnel command if you are on a remote machine).
+1. Detect Hermes Agent and, if missing, attempt the official installer (`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`).
+2. Find or create a Python environment with the WebUI dependencies.
+3. Start the web server and wait for `/health`.
+4. Open the browser unless you pass `--no-browser`.
+5. Drop you into a first-run onboarding wizard inside the WebUI.
+
+> Native Windows is not supported for this bootstrap yet. Use Linux, macOS, or WSL2.
+
+If provider setup is still incomplete after install, the onboarding wizard will point you to finish it with `hermes model` instead of trying to replicate the full CLI setup in-browser.
 
 ---
 
 ## Docker
 
-**Pre-built images** (amd64 + arm64) are published to GHCR on every release:
+**Pre-built images** (amd64 + arm64) are published to GHCR on every release.
+
+For a comprehensive setup guide covering all 3 compose files, common failure modes, and bind-mount migration, see [`docs/docker.md`](docs/docker.md). The README covers the 5-minute happy path.
+
+### 5-minute quickstart (single container)
+
+The simplest setup: one WebUI container that runs the agent in-process.
+
+```bash
+git clone https://github.com/nesquena/hermes-webui
+cd hermes-webui
+cp .env.docker.example .env
+# Edit .env if your host UID isn't 1000 (e.g. macOS where UIDs start at 501)
+docker compose up -d
+# Open http://localhost:8787
+```
+
+The container auto-detects your UID/GID from the mounted `~/.hermes` volume so files written by the agent stay readable by you on the host.
+
+To enable password protection (required if you expose the port outside `127.0.0.1`):
+
+```bash
+echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong" >> .env
+docker compose up -d --force-recreate
+```
+
+### Manual `docker run` (no compose)
 
 ```bash
 docker pull ghcr.io/nesquena/hermes-webui:latest
-docker run -d -p 8787:8787 -v ~/.hermes:/root/.hermes ghcr.io/nesquena/hermes-webui:latest
+docker run -d \
+  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
+  -v ~/.hermes:/home/hermeswebui/.hermes \
+  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
+  -v ~/workspace:/workspace \
+  -p 127.0.0.1:8787:8787 \
+  ghcr.io/nesquena/hermes-webui:latest
 ```
 
-Or run with Docker Compose (recommended):
-
-```bash
-docker compose up -d
-```
-
-Or build locally:
+### Build locally
 
 ```bash
 docker build -t hermes-webui .
-docker run -d -p 8787:8787 -v ~/.hermes:/root/.hermes hermes-webui
+docker run -d \
+  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
+  -v ~/.hermes:/home/hermeswebui/.hermes \
+  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
+  -v ~/workspace:/workspace \
+  -p 127.0.0.1:8787:8787 \
+  hermes-webui
 ```
 
-Open http://localhost:8787 in your browser.
+### Multi-container setups
 
-To enable password protection:
+If you want the agent and WebUI in separate containers (for isolation, or because you're already running an agent gateway elsewhere):
 
 ```bash
-docker run -d -p 8787:8787 -e HERMES_WEBUI_PASSWORD=your-secret -v ~/.hermes:/root/.hermes ghcr.io/nesquena/hermes-webui:latest
+# Agent + WebUI
+docker compose -f docker-compose.two-container.yml up -d
+
+# Agent + Dashboard + WebUI
+docker compose -f docker-compose.three-container.yml up -d
 ```
 
-Session data persists in a named volume (`hermes-data`) across restarts.
+Both compose files use **named Docker volumes** by default, which solves the UID/GID problem by construction. If you need bind mounts to share an existing host directory, see [`docs/docker.md`](docs/docker.md) for the full migration recipe.
+
+> **Known limitation (#681)**: in the two-container setup, tools triggered from the WebUI run in the **WebUI container**, not the agent container. If you need git/node/etc. on the WebUI's filesystem, either use the single-container setup, extend the WebUI Dockerfile, or use the community [all-in-one image](https://github.com/sunnysktsang/hermes-suite).
+
+### Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `PermissionError` at startup | UID mismatch on bind mount | Set `UID=$(id -u)` in `.env` |
+| `.env: permission denied` (#1389) | `fix_credential_permissions()` enforced 0600 | Set `HERMES_SKIP_CHMOD=1` in `.env` |
+| Workspace appears empty | UID mismatch on `/workspace` mount | Set `UID=$(id -u)` in `.env` |
+| `git: command not found` in chat | Two-container architectural limit (#681) | Use single-container or extend Dockerfile |
+| WebUI can't find agent source | `hermes-agent-src` volume misconfigured | Use the named volumes from compose files as-is |
+| Podman shared `.hermes` fails | Podman 3.4 `keep-id` limitation | Use Podman 4+ or single-container |
+
+For the deep dive on each of these, see [`docs/docker.md`](docs/docker.md).
 
 > **Note:** By default, Docker Compose binds to `127.0.0.1` (localhost only).
 > To expose on a network, change the port to `"8787:8787"` in `docker-compose.yml`
@@ -167,6 +232,7 @@ If discovery finds everything, nothing else is required.
 export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
 export HERMES_WEBUI_PYTHON=/path/to/python
 export HERMES_WEBUI_PORT=9000
+export HERMES_WEBUI_AUTO_INSTALL=1  # enable auto-install of agent deps (disabled by default)
 ./start.sh
 ```
 
@@ -188,6 +254,9 @@ Full list of environment variables:
 | `HERMES_WEBUI_DEFAULT_WORKSPACE` | `~/workspace` | Default workspace |
 | `HERMES_WEBUI_DEFAULT_MODEL` | `openai/gpt-5.4-mini` | Default model |
 | `HERMES_WEBUI_PASSWORD` | *(unset)* | Set to enable password authentication |
+| `HERMES_WEBUI_EXTENSION_DIR` | *(unset)* | Optional local directory served at `/extensions/`; must point to an existing directory before extension injection is enabled |
+| `HERMES_WEBUI_EXTENSION_SCRIPT_URLS` | *(unset)* | Optional comma-separated same-origin script URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
+| `HERMES_WEBUI_EXTENSION_STYLESHEET_URLS` | *(unset)* | Optional comma-separated same-origin stylesheet URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
 | `HERMES_HOME` | `~/.hermes` | Base directory for Hermes state (affects all paths) |
 | `HERMES_CONFIG_PATH` | `~/.hermes/config.yaml` | Path to Hermes config file |
 
@@ -215,6 +284,40 @@ 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.
+
+> **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`.
+
+---
+
 ## Manual launch (without start.sh)
 
 If you prefer to launch the server directly:
@@ -250,8 +353,8 @@ Or using the agent venv explicitly:
 ```
 
 Tests run against an isolated server on port 8788 with a separate state directory.
-Production data and real cron jobs are never touched. Current count: **424 tests**
-across 22 test files.
+Production data and real cron jobs are never touched. Current count: **3309 tests**
+across 100+ test files.
 
 ---
 
@@ -263,7 +366,7 @@ across 22 test files.
 - Send a message while one is processing -- it queues automatically
 - Edit any past user message inline and regenerate from that point
 - Retry the last assistant response with one click
-- Cancel a running task from the activity bar
+- Cancel a running task directly from the composer footer (Stop button next to Send)
 - Tool call cards inline -- each shows the tool name, args, and result snippet; expand/collapse all toggle for multi-tool turns
 - Subagent delegation cards -- child agent activity shown with distinct icon and indented border
 - Mermaid diagram rendering inline (flowcharts, sequence diagrams, gantt charts)
@@ -280,6 +383,7 @@ across 22 test files.
 
 ### Sessions
 - Create, rename, duplicate, delete, search by title and message content
+- Session actions via `⋯` dropdown per session — pin, move to project, archive, duplicate, delete
 - Pin/star sessions to the top of the sidebar (gold indicator)
 - Archive sessions (hide without deleting, toggle to show)
 - Session projects -- named groups with colors for organizing sessions
@@ -311,10 +415,11 @@ across 22 test files.
 - Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)
 
 ### Profiles
-- Profile picker in the topbar -- purple chip with dropdown showing all profiles
+- Profile chip in the **composer footer** -- dropdown showing all profiles with gateway status and model info
 - Gateway status dots (green = running), model info, skill count per profile
 - Profiles management panel -- create, switch, and delete profiles from the sidebar
 - Clone config from active profile on create
+- Optional custom endpoint fields on create -- Base URL and API key written into the profile's `config.yaml` at creation time, so Ollama, LMStudio, and other local endpoints can be configured without editing files manually
 - Seamless switching -- no server restart; reloads config, skills, memory, cron, models
 - Per-session profile tracking (records which profile was active at creation)
 
@@ -328,23 +433,24 @@ across 22 test files.
 - CDN resources pinned with SRI integrity hashes
 
 ### Themes
-- 6 built-in themes: Dark (default), Light, Slate, Solarized Dark, Monokai, Nord
+- 7 built-in themes: Dark (default), Light, Slate, Solarized Dark, Monokai, Nord, OLED
 - Switch via Settings panel dropdown (instant live preview) or `/theme` command
 - Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
 - Custom themes: define a `:root[data-theme="name"]` CSS block and it works — see [THEMES.md](THEMES.md)
 
 ### Settings and configuration
-- Settings panel (gear icon) -- default model, default workspace, send key, theme
+- **Hermes Control Center** (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
 - Send key: Enter (default) or Ctrl/Cmd+Enter
 - Show/hide CLI sessions toggle (enabled by default)
 - Token usage display toggle (off by default, also via `/usage` command)
+- Control Center always opens on the Conversation tab; resets on close
 - Unsaved changes guard -- discard/save prompt when closing with unpersisted changes
 - Cron completion alerts -- toast notifications and unread badge on Tasks tab
 - Background agent error alerts -- banner when a non-active session encounters an error
 
 ### Slash commands
 - Type `/` in the composer for autocomplete dropdown
-- Built-in: `/help`, `/clear`, `/model <name>`, `/workspace <name>`, `/new`, `/usage`, `/theme`, `/compact`
+- Built-in: `/help`, `/clear`, `/compress [focus topic]`, `/compact` (alias), `/model <name>`, `/workspace <name>`, `/new`, `/usage`, `/theme`
 - Arrow keys navigate, Tab/Enter select, Escape closes
 - Unrecognized commands pass through to the agent
 
@@ -359,10 +465,10 @@ across 22 test files.
 
 ### Mobile responsive
 - Hamburger sidebar -- slide-in overlay on mobile (<640px)
-- Bottom navigation bar -- 5-tab iOS-style fixed bar
+- Sidebar top tabs stay available on mobile; no fixed bottom nav stealing chat height
 - Files slide-over panel from right edge
 - Touch targets minimum 44px on all interactive elements
-- Composer positioned above bottom nav
+- Full-height chat/composer on phones without bottom-nav spacing
 - Desktop layout completely unchanged
 
 ---
@@ -370,31 +476,33 @@ across 22 test files.
 ## Architecture
 
 ```
-server.py               HTTP routing shell + auth middleware (~83 lines)
+server.py               HTTP routing shell + auth middleware (~154 lines)
 api/
-  auth.py               Optional password authentication, signed cookies (~149 lines)
-  config.py             Discovery, globals, model detection, reloadable config (~726 lines)
-  helpers.py            HTTP helpers, security headers (~71 lines)
-  models.py             Session model + CRUD + CLI bridge (~338 lines)
-  profiles.py           Profile state management, hermes_cli wrapper (~366 lines)
-  routes.py             All GET + POST route handlers (~1314 lines)
-  streaming.py          SSE engine, run_agent, cancel support (~332 lines)
-  upload.py             Multipart parser, file upload handler (~78 lines)
+  auth.py               Optional password authentication, signed cookies (~201 lines)
+  config.py             Discovery, globals, model detection, reloadable config (~1110 lines)
+  helpers.py            HTTP helpers, security headers (~175 lines)
+  models.py             Session model + CRUD + CLI bridge (~377 lines)
+  onboarding.py         First-run onboarding wizard, OAuth provider support (~507 lines)
+  profiles.py           Profile state management, hermes_cli wrapper (~411 lines)
+  routes.py             All GET + POST route handlers (~2250 lines)
+  state_sync.py         /insights sync — message_count to state.db (~113 lines)
+  streaming.py          SSE engine, run_agent, cancel support (~660 lines)
+  updates.py            Self-update check and release notes (~257 lines)
+  upload.py             Multipart parser, file upload handler (~82 lines)
   workspace.py          File ops, workspace helpers, git detection (~288 lines)
 static/
-  index.html            HTML template (~388 lines)
-  style.css             All CSS incl. mobile responsive (~726 lines)
-  ui.js                 DOM helpers, renderMd, tool cards, context indicator (~1063 lines)
-  workspace.js          File preview, file ops, git badge (~247 lines)
-  sessions.js           Session CRUD, collapsible groups, search (~589 lines)
-  messages.js           send(), SSE handlers, rAF throttle (~352 lines)
-  panels.js             Cron, skills, memory, profiles, settings (~1146 lines)
-  commands.js           Slash command autocomplete (~170 lines)
-  boot.js               Mobile nav, voice input, boot IIFE (~338 lines)
+  index.html            HTML template (~600 lines)
+  style.css             All CSS incl. mobile responsive, themes (~1050 lines)
+  ui.js                 DOM helpers, renderMd, tool cards, context indicator (~1740 lines)
+  workspace.js          File preview, file ops, git badge (~286 lines)
+  sessions.js           Session CRUD, collapsible groups, search, reload recovery (~800 lines)
+  messages.js           send(), SSE handlers, live streaming, session recovery (~655 lines)
+  panels.js             Cron, skills, memory, profiles, settings (~1438 lines)
+  commands.js           Slash command autocomplete (~267 lines)
+  boot.js               Mobile nav, voice input, boot IIFE (~524 lines)
 tests/
   conftest.py           Isolated test server (port 8788)
-  test_sprint{1-23}.py  22 test files, 426 test functions
-  test_regressions.py   Permanent regression gate (23 tests)
+  61 test files          961 test functions
 Dockerfile              python:3.12-slim container image
 docker-compose.yml      Compose with named volume and optional auth
 .github/workflows/      CI: multi-arch Docker build + GitHub Release on tag
@@ -415,6 +523,138 @@ State lives outside the repo at `~/.hermes/webui-mvp/` by default
 - `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets
 - `THEMES.md` -- theme system documentation, custom theme guide
 
+## Contributors
+
+Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly or incorporated via batch release — shapes the project, and we're grateful to everyone who has taken the time to contribute.
+
+**66 contributors have shipped code that landed in a release tag** as of v0.50.245. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights:
+
+### Top contributors (by merged-PR count)
+
+| # | Contributor | PRs | First → latest release |
+|---|---|---:|---|
+| 1 | [@franksong2702](https://github.com/franksong2702) | 22 | `v0.50.49` → `v0.50.245` |
+| 2 | [@bergeouss](https://github.com/bergeouss) | 18 | `v0.50.49` → `v0.50.240` |
+| 3 | [@aronprins](https://github.com/aronprins) | 8 | `v0.47.0` → `v0.50.77` |
+| 4 | [@iRonin](https://github.com/iRonin) | 6 | `v0.41.0` |
+| 5 | [@24601](https://github.com/24601) | 6 | `v0.50.201` |
+| 6 | [@KingBoyAndGirl](https://github.com/KingBoyAndGirl) | 4 | `v0.50.232` → `v0.50.237` |
+| 7 | [@renheqiang](https://github.com/renheqiang) | 4 | `v0.50.93` |
+| 8 | [@ccqqlo](https://github.com/ccqqlo) | 3 | `v0.50.83` → `v0.50.207` |
+| 9 | [@deboste](https://github.com/deboste) | 3 | `v0.16.1` |
+| 10 | [@frap129](https://github.com/frap129) | 3 | `v0.50.157` → `v0.50.166` |
+
+See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full ranked list of all 66 contributors, including everyone with one or two merged PRs and the special-thanks roll for design and architectural contributions.
+
+### Notable contributions
+
+**[@aronprins](https://github.com/aronprins)** — v0.50.0 UI overhaul (PR #242)
+The biggest single contribution to the project: a complete UI redesign that moved model/profile/workspace controls into the composer footer, replaced the gear-icon settings panel with the Hermes Control Center (tabbed modal), removed the activity bar in favor of inline composer status, redesigned the session list with a `⋯` action dropdown, and added the workspace panel state machine. 26 commits, thoroughly designed and iterated through multiple review rounds.
+
+**[@iRonin](https://github.com/iRonin)** — Security hardening sprint (PRs #196–#204)
+Six consecutive security and reliability PRs: session memory leak fix (expired token pruning), Content-Security-Policy + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file browser API. This is the kind of focused, high-quality security work that makes a self-hosted tool trustworthy.
+
+**[@DavidSchuchert](https://github.com/DavidSchuchert)** — German translation (PR #190)
+Complete German locale (`de`) covering all UI strings, settings labels, commands, and system messages — and in doing so, stress-tested the i18n system and exposed several elements that weren't yet translatable, which got fixed as part of the same PR.
+
+**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming, session recovery, workspace fallback (PRs #366, #367)
+Three interlocking improvements: workspace fallback resolution so the server recovers gracefully when the configured workspace is deleted or unavailable; live reasoning cards that upgrade the generic thinking spinner to a real-time reasoning display as the model thinks; and durable session state recovery via `localStorage` so in-flight tool cards, partial assistant output, and the live SSE stream all survive a full page reload or session switch.
+
+### Feature contributions
+
+**[@gabogabucho](https://github.com/gabogabucho)** — Spanish locale + onboarding wizard (PRs #275, #285)
+Full Spanish (`es`) locale covering all 175 UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch — the feature most responsible for new users actually getting started.
+
+**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + gateway sync + Docker hardening (18 PRs, `v0.50.49` → `v0.50.240`)
+Real-time gateway session sync (Telegram/Discord/Slack into the WebUI sidebar via SSE), the provider management UI for adding/editing custom providers from Settings, the two-container Docker setup docs, OAuth provider status detection, profile isolation hardening (per-profile `.env` secrets), and the bulk of what users see when they touch Settings → Providers.
+
+**[@ccqqlo](https://github.com/ccqqlo)** — Terminal approval UX + custom model discovery + mobile close button (PRs #224, #225, #238, #333)
+A run of focused quality-of-life improvements: terminal tool approval prompts that stay visible long enough to actually be read, restored custom model API key discovery, and the redundant mobile close button fix that had been confusing users on narrow screens.
+
+**[@kevin-ho](https://github.com/kevin-ho)** — OLED theme (PR #168)
+Added the 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk. Small diff, big impact for anyone on an OLED display.
+
+**[@Bobby9228](https://github.com/Bobby9228)** — Mobile Profiles button + Android Chrome fixes (PRs #253, #263, #265)
+Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones, plus a set of Android Chrome-specific fixes for the profile dropdown.
+
+**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (22 PRs, `v0.50.49` → `v0.50.245`)
+The session title guard, breadcrumb workspace navigation, mobile workspace panel sliver fix (#1300), composer footer container queries, streaming session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, and a long tail of polish across the session sidebar, mobile responsive layout, and workspace state machine.
+
+**[@betamod](https://github.com/betamod)** — Security hardening (PR #171)
+A comprehensive security audit PR covering CSRF protection, SSRF guards, XSS escaping improvements, and the env race condition between concurrent agent sessions — foundational security work that shipped in v0.39.0.
+
+**[@TaraTheStar](https://github.com/TaraTheStar)** — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
+Made the assistant display name configurable throughout the UI, added thinking/reasoning block display in chat, and refactored the login page to use template variables instead of inline string replacement.
+
+**[@thadreber-web](https://github.com/thadreber-web)** — CLI session bridge (PR #56)
+The original CLI session bridge: reads CLI sessions from the agent's SQLite state store and surfaces them in the WebUI sidebar. This was the first bridge between the CLI and WebUI session worlds.
+
+**[@deboste](https://github.com/deboste)** — Reverse proxy auth + mobile responsive layout + model routing (PRs #3, #4, #5)
+Three of the very first community PRs: fixed EventSource/fetch to use the URL origin for reverse proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.
+
+### Bug fix and security contributions
+
+**[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — Profile .env secret isolation (PR #351)
+Fixed API key leakage between profiles on switch — switching from a profile with `OPENAI_API_KEY` to one without it left the key in the process environment for the duration of the session, effectively leaking credentials. A subtle and important security fix.
+
+**[@lawrencel1ng](https://github.com/lawrencel1ng)** — Bandit security fixes B310/B324/B110 + QuietHTTPServer (PR #354)
+Systematic bandit security scan fixes: URL scheme validation before `urlopen`, MD5 `usedforsecurity=False`, and 40+ bare `except: pass` blocks replaced with proper logging — plus `QuietHTTPServer` to stop client-disconnect log spam from SSE streams.
+
+**[@lx3133584](https://github.com/lx3133584)** — CSRF fix for reverse proxy on non-standard ports (PR #360)
+Fixed CSRF rejection for deployments behind Nginx Proxy Manager or similar on non-standard ports — a real-world blocker for anyone hosting on a port other than 80/443.
+
+**[@DelightRun](https://github.com/DelightRun)** — session_search fix for WebUI sessions (PR #356)
+The `session_search` tool silently returned "Session database not available" in every WebUI session. Tracked down the missing `SessionDB` injection in the streaming path and fixed it.
+
+**[@shaoxianbilly](https://github.com/shaoxianbilly)** — Unicode filename downloads (PR #378)
+Fixed `UnicodeEncodeError` crashes when downloading workspace files with Chinese, Japanese, or other non-ASCII names. Implemented proper `Content-Disposition` header with RFC 5987 `filename*=UTF-8''...` encoding.
+
+**[@huangzt](https://github.com/huangzt)** — Cancel interrupts agent (PR #244)
+Made the Cancel button actually interrupt the running agent and clean up UI state, rather than just hiding the button while the agent kept running.
+
+**[@tgaalman](https://github.com/tgaalman)** — Thinking card fix (PR #169)
+Fixed top-level reasoning fields being missed in the thinking card display — an edge case in how Claude's extended thinking blocks surface in the API response.
+
+**[@smurmann](https://github.com/smurmann)** — Custom provider routing fix (PR #189)
+Fixed model routing for slash-prefixed custom provider models, which were being misrouted in the model selector. A precise fix for a real edge case in multi-provider setups.
+
+**[@jeffscottward](https://github.com/jeffscottward)** — Claude Haiku model ID fix (PR #145)
+Caught and corrected the Claude Haiku model ID (`3-5` → `4-5`) immediately after the Anthropic release — the kind of quick community catch that keeps the model dropdown accurate.
+
+**[@kcclaw001](https://github.com/kcclaw001)** — Credential redaction in API responses (PR #243)
+Added credential redaction to all API response paths so API keys, tokens, and other secrets in session data or error messages are masked before reaching the browser.
+
+**[@mbac](https://github.com/mbac)** — Phantom "Custom" provider group fix (PR #191)
+Removed the phantom "Custom" optgroup that appeared in the model dropdown even when no custom provider was configured — a small but consistently confusing UI noise issue.
+
+**[@andrewy-wizard](https://github.com/andrewy-wizard)** — Chinese localization (PR #177)
+Added Simplified Chinese (`zh`) locale to the WebUI. One of the first non-English locales and the most-used non-English locale in the codebase.
+
+**[@mmartial](https://github.com/mmartial)** — Docker UID/GID matching (PR #237)
+Added Docker support for running as an arbitrary UID/GID matching the host user, eliminating permission issues with bind-mounted volumes — essential for Docker deployments where the host user isn't UID 1000.
+
+**[@vCillusion](https://github.com/vCillusion)** — pip package resolution fix (PR #76)
+Fixed agent dependency resolution to prefer packages from the venv's site-packages over the agent directory itself, preventing shadowing bugs when developing locally.
+
+**[@carlytwozero](https://github.com/carlytwozero)** — API key pass-through for non-Anthropic providers (PR #78)
+Fixed `api_key` not being passed to `AIAgent` for non-Anthropic `/anthropic` providers — a quiet regression that silently broke any non-default provider.
+
+**[@mangodxd](https://github.com/mangodxd)** — Type hints cleanup (PR #115)
+Added missing type hints across 10 files and corrected 9 inaccurate existing ones — the kind of maintenance work that makes the codebase easier to reason about.
+
+**[@Argonaut790](https://github.com/Argonaut790)** — HTML entity decode + Traditional Chinese locale (PR #239)
+Fixed double-escaping of HTML entities in `renderMd()` — LLM output containing `&lt;code&gt;` was being escaped a second time, rendering as literal text instead of the intended markdown. The same PR also completed the Simplified Chinese translation (40+ missing keys) and added a full Traditional Chinese (`zh-Hant`) locale.
+
+**[@indigokarasu](https://github.com/indigokarasu)** — Visual redesign proposal: icon rail + design token system + 7 themes (PR #213)
+A CSS-only redesign of the full UI — proper design tokens (`--bg-primary`, `--text-info`, spacing scale), an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but directly shaped the design language and theme architecture that shipped in v0.50.0.
+
+**[@zenc-cp](https://github.com/zenc-cp)** — Anti-hallucination guard for ReAct loop (PR #133)
+Added a streaming token buffer and post-run message scrub to `streaming.py` to detect and strip fake tool execution JSON that weaker models write inline instead of calling tools properly. A three-layer approach: ephemeral anti-hallucination prompt, live token filtering, and session history cleanup. The pattern influenced later streaming.py improvements.
+
+---
+
+Want to contribute? See [ARCHITECTURE.md](ARCHITECTURE.md) for the codebase layout and [TESTING.md](TESTING.md) for how to run the test suite. The best contributions are focused, well-tested, and solve a real problem — exactly what every person on this list did.
+
 ## Repo
 
 ```

ROADMAP.md

@@ -1,321 +1,349 @@
-# Hermes Web UI: Full Parity Roadmap
+# Hermes Web UI — Roadmap
 
-> Goal: Full 1:1 parity with the Hermes CLI experience via a clean dark web UI.
-> Everything you can do from the CLI terminal, you can do from this UI.
+> Web companion to the Hermes Agent CLI. Same workflows, browser-native.
 >
-> Last updated: v0.35 (April 5, 2026)
-> Tests: 433 total (433 passing, 0 failures)
-> Source: <repo>/
+> Last updated: v0.50.282 (May 03, 2026) — 4018 tests collected
+> Test source: `pytest tests/ --collect-only -q`
+> Per-version detail: see [CHANGELOG.md](./CHANGELOG.md)
 
 ---
 
-## Sprint History (Completed)
+## Status snapshot
 
-| Sprint | Theme | Highlights | Tests |
-|--------|-------|-----------|-------|
-| Sprint 1 | Bug fixes + foundations | B1-B11 fixed, LOCK on SESSIONS, section headers, request logging | 19 |
-| Sprint 2 | Rich file preview | Image preview, rendered markdown, table support, smart icons | 27 |
-| Sprint 3 | Panel nav + viewers | Sidebar tabs, cron/skills/memory panels, B6/B10/B14, Phase D start | 48 |
-| Sprint 4 | Relocation + power features | Source to <repo>/, CSS extracted, session rename/search, file ops | 68 |
-| Sprint 5 | Phase A complete + workspace | JS extracted (server.py 1778->1042 lines), workspace management, copy message, file editor, session index | 86 |
-| Test hardening | Isolated test environment | Port 8788 test server, conftest autouse, cleanup_zero_message, 5 test files rewritten | 90 |
-| Sprint 6 | Polish + Phase E complete | HTML to static/, resizable panels, cron create, session JSON export, Escape from editor | 106 |
-| Sprint 7 | Wave 2 Core: CRUD + Search | Cron edit/delete, skill create/edit/delete, memory write, session content search, health improvements, git init | 125 |
-| Sprint 8 | Daily Driver Finish Line | Edit+regenerate user messages, regenerate last response, clear conversation, Prism.js syntax highlighting, reconnect banner fix, session list scroll fix | 139 |
-| Sprint 8 hotfix | Message queue + INFLIGHT fix | Queue messages while busy (toast + badge + auto-drain), INFLIGHT-first loadSession (message stays on switch-away/back) | 139 |
-| Sprint 9 | Codebase health + daily driver gaps | app.js deleted and replaced by 6 modules, tool call cards inline, attachment persistence on reload, todo list panel | 149 |
-| Sprint 10 | Server health + operational polish | server.py split into api/ modules, background task cancel, cron run history viewer, tool card UX polish | 167 |
-| Sprint 10 fixes | Import regressions + regression tests | uuid, AIAgent, has_pending, SSE cancel loop, Session.__init__ tool_calls; test_regressions.py | 177 |
-| Concurrency sweeps | Multi-session correctness | Approval cross-session (R10), activity bar per-session (R11), live cards on switch-back (R12), tool cards after done (R13), session model authoritative (R14), newSession cards (R15) | 190 |
-| Sprint 11 | Multi-provider models + streaming | Dynamic model dropdown (any Hermes provider), smooth scroll pinning, routes extracted to api/routes.py (server.py 704→76 lines) | 201 |
-| Sprint 12 | Settings + reliability + session QoL | Settings panel (gear icon, settings.json), SSE auto-reconnect, pin sessions, import session from JSON | 211 |
-| Sprint 13 | Alerts + polish | Cron completion alerts (polling + badge), background error banner, session duplicate, browser tab title | 221 |
-| Sprint 14 | Visual polish + workspace ops | Mermaid diagrams, message timestamps, file rename, folder create, session tags, session archive | 233 |
-| Sprint 15 | Session projects + code copy | Session projects/folders, code block copy button, tool card expand/collapse toggle | 237 |
-| Sprint 16 | Session sidebar visual polish | SVG action icons, overlay hover actions, pin indicator, project border, safe HTML rendering | 289 |
-| Sprint 17 | Workspace polish + slash commands + settings | Breadcrumb navigation, slash command autocomplete, send key setting (#26) | 318 |
-| Sprint 18 | Thinking display + workspace tree | File preview auto-close, thinking/reasoning cards, expandable directory tree (#22) | 318 |
-| Sprint 19 | Auth + security hardening | Password auth (off by default), login page, security headers, 20MB body limit (#23) | 328 |
-| Sprint 20 | Voice input + send button | Voice input (Web Speech API), send button icon-circle with pop-in animation | 415 |
-| Sprint 21 | Mobile responsive + Docker | Hamburger sidebar, bottom nav, files slide-over, Docker support (#21, #7) | 415 |
-| Sprint 22 | Multi-profile support | Profile picker, management panel, seamless switching, per-session tracking (#28) | 415 |
-| Sprint 23 | Agentic transparency | Token/cost display, subagent cards, skill picker in cron, skill linked files, workspace tree persistence, timestamp fixes | 424 |
-| v0.32 | Auto-compaction handling | Compression detection, /compact command, real context window indicator | 424 |
-| v0.33 | /insights sync | Opt-in state.db sync so `hermes /insights` includes WebUI sessions | 424 |
-| v0.34 | Sprint 26 — Pluggable themes | Dark, Light, Slate, Solarized, Monokai, Nord; settings unsaved-changes guard; /theme command | 433 |
-| v0.34.1 | Theme variable polish | 30+ hardcoded dark-navy colors replaced with theme-aware CSS variables | 433 |
-| v0.34.2 | Theme text colors | 5 new per-theme typography variables (--strong, --em, --code-text, --code-inline-bg, --pre-text) | 433 |
-| v0.34.3 | Light theme final polish | 46 light-scoped selector overrides for sidebar, roles, chips, interactive elements | 433 |
-| v0.35 | Security hardening | Env race fix, random signing key, upload path traversal, PBKDF2 password hash | 433 |
+| Surface | Status |
+|---|---|
+| **Hermes CLI parity** | ✅ Complete — every CLI workflow has a web equivalent |
+| **Streaming + tool transparency** | ✅ Live tool cards, reasoning cards, approval prompts, cancel |
+| **Multi-provider model support** | ✅ Any provider configured in `config.yaml` shows in the picker |
+| **Sessions + projects + search** | ✅ CRUD, content search, projects, tags, archive, fork, import |
+| **Mobile + Docker + auth** | ✅ Hamburger nav, slide-overs, password auth, GHCR images |
+| **Auxiliary surfaces** | ✅ Workspace tree + edit, cron CRUD, skills CRUD, memory write, MCP server UI |
+| **Visual polish** | ✅ 8 themes (incl. light/system/OLED/Sienna), Mermaid, KaTeX, syntax highlighting |
+| **Native distribution** | ✅ macOS desktop app (universal arm64+x86_64 DMG, signed) — separate repo |
+
+Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 
 ---
 
-## Current Architecture Status
+## Architecture
 
-| Layer | Location | Status |
-|-------|----------|--------|
-| Python server | <repo>/server.py (~81 lines) + api/ modules (~3210 lines) | Thin shell + auth middleware + business logic in api/ |
-| HTML template | <repo>/static/index.html (~364 lines) | Served from disk |
-| CSS | <repo>/static/style.css (~670 lines) | Served from disk, incl. mobile responsive |
-| JavaScript | <repo>/static/{ui,workspace,sessions,messages,panels,boot,commands}.js | 7 modules, ~3610 lines total |
-| Docker | Dockerfile, docker-compose.yml, .dockerignore | python:3.12-slim, multi-arch (amd64+arm64) |
-| CI/CD | .github/workflows/release.yml | Auto-release + GHCR publish on tag push |
-| Runtime state | ~/.hermes/webui-mvp/sessions/ | Session JSON files |
-| Test server | Port 8788, state dir ~/.hermes/webui-mvp-test/ | Isolated, wiped per run |
-| Production server | Port 8787 | SSH tunnel from Mac |
+| Layer | Files | Status |
+|---|---|---|
+| Python server | `server.py` (~165 lines) + `api/` modules (~20k lines) | Thin shell + auth middleware + business logic |
+| HTML template | `static/index.html` (~600 lines) | Served from disk |
+| CSS | `static/style.css` (~3k lines) | Themes, mobile responsive, KaTeX, table styles |
+| JavaScript | `static/{ui,sessions,messages,workspace,panels,boot,commands,icons,i18n,login,onboarding}.js` (~26k lines) | 11 modules served as static files |
+| Service worker | `static/sw.js` | Offline shell cache, version-pinned assets |
+| Docker | `Dockerfile`, `docker-compose.yml` | `python:3.12-slim`, multi-arch (amd64+arm64), HEALTHCHECK |
+| CI/CD | `.github/workflows/release.yml` | Auto-release + GHCR publish on tag push |
+| Test isolation | `tests/_pytest_port.py` | Per-worktree port + state-dir derivation, no collisions |
 
 ---
 
-## Feature Parity Checklist
+## Feature parity checklist
 
-### Chat and Agent
+### Chat and streaming
 - [x] Send messages, get SSE-streaming responses
-- [x] Switch models per session (10 models, grouped by provider)
-- [x] Multi-provider API support: use any Hermes agent API provider (OpenAI, Anthropic, Google, etc.) directly, not just OpenRouter (Sprint 11)
-- [x] Custom endpoint model discovery: auto-detect models from Ollama, LM Studio, and other local LLM servers via base_url (PR #18)
-- [x] Upload files to workspace (drag-drop, click, clipboard paste)
-- [x] File tray with remove button
-- [x] Tool progress shown in activity bar above composer
-- [x] Approval card for dangerous commands (Allow once/session/always, Deny)
+- [x] Composer-scoped model picker (per-conversation model selection)
+- [x] Multi-provider API support — OpenAI, Anthropic, Google, OpenRouter, xAI, GLM, DeepSeek, Mistral, MiniMax, Kimi, OpenCode, Nous Portal, custom OpenAI-compatible endpoints
+- [x] Live custom-endpoint model discovery (Ollama, LM Studio, vLLM via `/v1/models`)
+- [x] Free-form OpenRouter model name (autocomplete + custom input)
+- [x] Tool progress shown inline via live tool cards
+- [x] Approval card for dangerous commands (Allow once / session / always, Deny)
 - [x] Approval polling + SSE-pushed approval events
+- [x] Clarify dialog — agent can ask blocking clarifying questions
+- [x] Subagent delegation cards in tool view
 - [x] INFLIGHT guard: switch sessions mid-request without losing response
 - [x] Session restores from localStorage on page load
 - [x] Reconnect banner if page reloaded mid-stream
+- [x] SSE auto-reconnect with stream replay
+- [x] Token / cost estimate per message and per session
+- [x] Context usage indicator (compact ring badge in composer footer)
+- [x] Auto-compaction handling + `/compact` command
+- [x] rAF-throttled token rendering (smooth, no DOM thrash)
+- [x] Cancel / stop button in composer footer
+- [x] Reasoning effort selector (low / medium / high / xhigh) + `/reasoning`
+- [x] Pure-text streaming with crash-recovery — partial messages restored from localStorage on reload
+
+### Conversation controls
 - [x] Copy message to clipboard (hover icon on each bubble)
 - [x] Edit last user message and regenerate
-- [ ] Branch/fork conversation (Wave 3)
-- [x] Token/cost estimate per message (Sprint 23)
-
-### Tool Visibility
-- [x] Tool progress in activity bar (moved out of composer footer)
-- [x] Approval card with all 4 choices
-- [x] Tool call cards inline (collapsed, show name/args/result)
-
-### Workspace / Files
-- [x] Browse workspace directory tree with type icons
-- [x] Preview text/code files (read-only)
-- [x] Preview markdown files (rendered, tables supported)
-- [x] Preview image files (PNG, JPG, GIF, SVG, WEBP inline)
-- [x] Edit files inline (Edit button, Enter to save, Escape to cancel)
-- [x] Create new file (+ button in panel header)
-- [x] Delete file (hover trash, confirm dialog)
-- [x] File name truncation with tooltip for long names
-- [x] Right panel resizable (drag inner edge)
-- [x] Syntax highlighted code preview (Prism.js)
-- [x] Rename file (Sprint 14)
-- [x] Create folder (Sprint 14)
+- [x] Regenerate last response
+- [x] Clear conversation (wipe messages, keep session)
+- [x] Branch / fork conversation from any message point (#465)
+- [x] Pure-text + tool-call streams both recover
 
 ### Sessions
 - [x] Create session (+ button or Cmd/Ctrl+K)
 - [x] Load session (click in sidebar)
-- [x] Delete session (hover trash, toast, correct fallback)
-- [x] Auto-title from first user message
-- [x] Rename session title (double-click in sidebar, Enter saves, Escape cancels)
-- [x] Filter/search sessions by title (live filter box)
-- [x] Date group headers (Today / Yesterday / Earlier)
-- [x] Download session as Markdown transcript
-- [x] Export session as JSON (full messages + metadata)
-- [x] Session inherits last-used workspace on creation
-- [x] Session content search (search message text across sessions)
-- [x] Session tags / labels (Sprint 14)
-- [x] Archive sessions (Sprint 14)
-- [x] Clear conversation (wipe messages, keep session) (Wave 3)
-- [x] Import session from JSON (Sprint 12)
-- [x] Pin/star sessions to top of list (Sprint 12)
-- [x] Duplicate session (Sprint 13)
-- [x] Session projects / folders (Sprint 15)
+- [x] Delete session (hover trash, toast undo, fallback)
+- [x] Auto-title from first user message + adaptive title refresh (configurable cadence)
+- [x] LLM-generated titles via auxiliary route (configurable model)
+- [x] Rename session inline (double-click, Enter saves, Escape cancels)
+- [x] Title search (live filter)
+- [x] Content search (full-text across all sessions)
+- [x] Date group headers (Today / Yesterday / Earlier) with collapsible groups
+- [x] Pin / star sessions to top
+- [x] Duplicate session
+- [x] Import / Export session as JSON (full messages + metadata)
+- [x] Download as Markdown transcript
+- [x] Tags (`#tag` extraction + filter chips)
+- [x] Archive sessions (hidden by default, "Show N archived" toggle)
+- [x] Projects / folders (chip filter bar, "Unassigned" filter)
+- [x] Per-session profile tracking
+- [x] Per-session toolset override (`/toolsets`)
+- [x] Batch select mode (multi-select, bulk delete / move / archive)
+- [x] CLI session bridge — read CLI sessions from state.db, import as WebUI sessions
 
-### Workspace Management
-- [x] Add workspace with path validation (must be existing directory)
-- [x] Remove workspace
-- [x] Rename workspace display name
-- [x] Quick-switch workspace from topbar dropdown
-- [x] Sidebar live workspace display (name + path, updates in real time)
-- [x] New sessions inherit last used workspace
-- [x] Workspace list persists to workspaces.json
-- [ ] Workspace reorder (drag) (Wave 2)
+### Workspace and files
+- [x] Add workspace with path validation (existing directory, follows symlinks)
+- [x] Remove / rename workspace
+- [x] Quick-switch from topbar dropdown
+- [x] Sidebar live workspace display (name + path)
+- [x] New sessions inherit last-used workspace
+- [x] Browse workspace directory tree with type icons
+- [x] Tree view with expand / collapse + lazy load (#22)
+- [x] Breadcrumb navigation in subdirectories
+- [x] Preview text / code (read-only)
+- [x] Preview markdown (rendered + tables + Mermaid + KaTeX)
+- [x] Preview images (PNG, JPG, GIF, SVG, WEBP, AVIF inline)
+- [x] Preview PDF / SVG / audio / video / Excalidraw / CSV / JSON / YAML
+- [x] Edit files inline (Edit button, Enter saves, Escape cancels)
+- [x] Create / rename / delete files and folders (in current directory)
+- [x] Drag-drop / click / clipboard paste upload
+- [x] Archive upload (zip / tar) with extraction
+- [x] Syntax highlighted code preview (Prism.js, language-aware)
+- [x] File preview auto-close on directory navigation
+- [x] Right panel resizable (drag inner edge)
+- [x] Embedded workspace terminal (`/api/terminal/{start,input,output}`)
+- [x] Git branch + dirty status badge in workspace header
 
-### Scheduled Tasks (Cron)
-- [x] View all cron jobs (Tasks sidebar tab)
-- [x] View last run output per job (auto-loaded on expand)
-- [x] Expand job to see prompt, schedule, last output
-- [x] Run job manually (Run now button)
-- [x] Pause / Resume job
-- [x] Create cron job from UI (+ New job form with name, schedule, prompt, delivery)
-- [x] Edit existing cron job
-- [x] Delete cron job
-- [x] View full cron run history (expandable per job)
-- [x] Skill picker in cron create form (Sprint 23)
+### Cron jobs
+- [x] List all cron jobs (Tasks sidebar tab)
+- [x] View job details (prompt, schedule, last run, output)
+- [x] Run / pause / resume / delete
+- [x] Create job from UI (name, schedule, prompt, delivery target)
+- [x] Edit job inline (full create-form parity, including skills)
+- [x] Skill picker in create + edit forms
+- [x] Cron run history viewer (expandable per job)
+- [x] Cron completion alerts (toast + badge)
+- [x] Run-status tracking with live watch mode
 
 ### Skills
-- [x] List all skills grouped by category (Skills sidebar tab)
-- [x] Search/filter skills by name, description, category
-- [x] View full SKILL.md content in right preview panel
-- [x] Create skill
-- [x] Edit skill
-- [x] Delete skill
-- [x] View skill linked files (Sprint 23)
+- [x] List all skills grouped by category
+- [x] Search / filter by name, description, category
+- [x] View full SKILL.md content
+- [x] View skill linked files
+- [x] Create / edit / delete skill
+- [x] `/skills` slash command
 
 ### Memory
-- [x] View personal notes (MEMORY.md) rendered as markdown (Memory tab)
-- [x] View user profile (USER.md) rendered as markdown (Memory tab)
-- [x] Last-modified timestamp on each section
-- [x] Add/edit memory entry inline
-
-### Configuration
-- [x] Settings panel (default model, default workspace) (Sprint 12)
-- [x] Send key preference (Enter or Ctrl+Enter) (Sprint 17)
-- [x] Password authentication (Sprint 19)
-- [ ] Enable/disable toolsets per session (deferred)
-
-### Notifications
-- [x] Cron job completion alerts (Sprint 13)
-- [x] Background agent error alerts (Sprint 13)
-
-### Workspace
-- [x] Breadcrumb navigation in subdirectories (Sprint 17)
-- [x] Workspace tree view with expand/collapse (Sprint 18, Issue #22)
-- [x] File preview auto-close on directory navigation (Sprint 18)
-
-### Slash Commands
-- [x] Command registry + autocomplete dropdown (Sprint 17)
-- [x] Built-in: /help, /clear, /model, /workspace, /new (Sprint 17)
-
-### Security
-- [x] Password auth with signed cookies (Sprint 19, Issue #23)
-- [x] Security headers (X-Content-Type-Options, X-Frame-Options) (Sprint 19)
-- [x] POST body size limit (20MB) (Sprint 19)
-
-### Thinking / Reasoning
-- [x] Collapsible thinking cards for extended-thinking models (Sprint 18)
-
-### Voice
-- [x] Voice input via Web Speech API (Sprint 20)
-
-### Mobile
-- [x] Mobile responsive layout — hamburger sidebar, bottom nav, files slide-over (Sprint 21)
+- [x] View personal notes (MEMORY.md) rendered as markdown
+- [x] View user profile (USER.md) rendered as markdown
+- [x] Last-modified timestamp per section
+- [x] Add / edit memory entries inline
 
 ### Profiles
-- [x] Multi-profile support — create, switch, delete profiles (Sprint 22, Issue #28)
+- [x] Multi-profile support — create, switch, delete (#28)
+- [x] Topbar profile picker with gateway-status dots
+- [x] Profile management panel (full CRUD)
+- [x] Seamless switching (no server restart, refreshes models / skills / memory / cron / workspace)
+- [x] Profile-local workspace storage
+- [x] First-run onboarding wizard with provider config (OpenRouter / Anthropic / OpenAI / Custom)
+- [x] In-app OAuth for Codex and Claude
 
-### Advanced / Future
-- [ ] Subagent session tree -- show subagent hierarchy in sidebar with expand/collapse (PR #75)
-- [ ] Specialized tool card renderers -- diff viewer, terminal output, todo checklist views (PR #75)
-- [x] Streaming performance -- rAF-throttled token rendering (Sprint 24, PR #81)
-- [x] Workspace git detection -- branch name and dirty status badge (Sprint 24, PR #82)
-- [x] Collapsible date groups -- click group headers to collapse (Sprint 24, PR #80)
-- [x] Context usage indicator -- token count and cost in composer footer (Sprint 24, PR #83)
-- [ ] LLM-generated session titles -- auto-title via small model instead of first-message substring (PR #75)
-- [ ] Workspace git detection -- show branch name, dirty status in workspace header (PR #75)
-- [ ] Clarify dialog -- agent can ask clarifying questions that block until user responds (PR #75)
-- [ ] Gateway approval polling -- support blocking approvals from messaging gateway (PR #75)
-- [ ] Unified session storage -- SessionDB shared between webui and CLI (PR #75)
-- [ ] TTS playback of responses (deferred)
-- [x] Background task cancel (activity bar Cancel button)
-- [ ] Code execution cell (deferred)
-- [ ] Desktop application (Sprint 25, PLANNED)
-- [x] Pluggable UI themes -- Dark, Light, Slate, Solarized, Monokai, Nord (Sprint 26, v0.34)
-- [ ] Extended slash command / skill integration (deferred)
-- [ ] Virtual scroll for large lists (deferred)
+### Configuration
+- [x] Settings panel (default model, default workspace, send key, theme, voice, font size)
+- [x] Send key preference (Enter or Ctrl+Enter)
+- [x] Password authentication (off by default)
+- [x] Per-session toolset override
+- [x] Personality config via `config.yaml`
+- [x] Reasoning effort persistence
+
+### Notifications
+- [x] Cron job completion alerts
+- [x] Background agent error banner
+- [x] Approval pending badge
+- [x] Provider / model mismatch toast warning
+
+### Slash commands
+- [x] Command registry + autocomplete dropdown
+- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/btw`, `/reasoning`, `/skills`, `/toolsets`
+- [x] Transparent pass-through for unrecognized commands
+
+### Security
+- [x] Password auth with signed HMAC HTTP-only cookies (24h TTL)
+- [x] Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
+- [x] CSRF protection (scheme-aware, port-normalized for reverse proxies)
+- [x] PBKDF2 password hashing
+- [x] Rate limiting on auth endpoints
+- [x] Session ID validation
+- [x] SSRF guard on `/api/models/live`, `cfg_base_url`, `custom_providers[]`
+- [x] ENV_LOCK around env mutations
+- [x] XSS sanitization on all rendered HTML
+- [x] HMAC-signed signing keys (random per install)
+- [x] Skills path-traversal guard
+- [x] Secure cookie flags (HttpOnly, SameSite, Secure when HTTPS)
+- [x] Error message sanitization (no stack traces in responses)
+- [x] POST body size limit (20MB)
+- [x] Upload path-traversal guard
+- [x] Credential redaction in API responses
+- [x] Profile `.env` secret isolation on switch
+- [x] Auto-install gate (opt-in via `HERMES_WEBUI_AUTO_INSTALL=1`)
+
+### Visual / UX
+- [x] 8 themes — Dark, Light, System (auto-sync), Slate, Solarized, Monokai, Nord, OLED, Sienna
+- [x] 2-axis appearance model (theme + skin) for community theme contributions
+- [x] Mermaid diagram rendering
+- [x] KaTeX math rendering with fence-before-math fix
+- [x] Syntax highlighting (Prism.js, language-aware, YAML newline preservation)
+- [x] Markdown image syntax `![alt](url)` and inline MEDIA: tokens render as `<img>`
+- [x] Plain URL auto-linking
+- [x] Inline markdown in table cells (bold, italic, code, links)
+- [x] Code block copy button
+- [x] Tool card expand / collapse toggle
+- [x] Collapsible thinking / reasoning cards (Claude extended thinking, o3 reasoning tokens)
+- [x] Message timestamps (subtle, full date on hover)
+- [x] Empty composer hides send button (icon-circle with pop-in animation)
+- [x] Pluggable Lucide SVG icons (no emoji rendering inconsistencies)
+- [x] Composer-centric controls (v0.50.0 UI overhaul)
+- [x] Hermes Control Center modal (centralized actions)
+- [x] Workspace panel state machine (defaults closed, opens for browsing / preview)
+- [x] PWA manifest + service worker (offline shell)
+- [x] Favicon (SVG + PNG + ICO)
+- [x] Branded onboarding wizard
+
+### Voice
+- [x] Voice input via Web Speech API (push-to-talk dictation)
+- [x] Hands-free voice mode (turn-based conversation, opt-in via Settings → Preferences)
+- [x] TTS playback of responses (configurable voice, rate, pitch)
+
+### Mobile
+- [x] Hamburger sidebar (slide-in overlay)
+- [x] Bottom navigation bar (5-tab iOS-style)
+- [x] Files slide-over (right panel as slide-over)
+- [x] 44px minimum touch targets
+- [x] Container queries on composer
+- [x] Android Chrome compatibility fixes
+- [x] PWA installation (manifest + icons + Android support)
+
+### Internationalization
+- [x] 9 locales — English, Japanese, Russian, Spanish, German, Chinese (zh + zh-Hant), Portuguese, Korean, French
+- [x] Key-parity test ensures every locale has every key
+- [x] Right-to-left and CJK input (IME composition fixes)
+
+### Gateway integration
+- [x] Real-time gateway sessions in sidebar (Telegram, Discord, Slack, Weixin) via SSE + DB polling
+- [x] Cross-channel handoff dock — composer-docked flyout summarizing the live external session
+- [x] Transcript-summary card at 10+ rounds
+- [x] Sidebar dedup keying on per-conversation identity (distinct chats from same platform stay separate)
+- [x] Gateway session sync skips dup / delete options for external sessions
+
+### MCP integration
+- [x] MCP server management UI (System Settings → MCP Servers)
+- [x] Add / edit / delete MCP server entries
+
+### Distribution
+- [x] Docker support (multi-arch amd64 + arm64, HEALTHCHECK, UID/GID auto-detect)
+- [x] Two-container Docker compose (webui + agent)
+- [x] GHCR auto-publish on tag push
+- [x] Subpath mount support (reverse proxy at `/hermes/`)
+- [x] PWA installable from any browser
+- [x] Native macOS app — universal Intel + Apple Silicon, signed + notarized DMG, Sparkle 2 auto-update — see `hermes-webui/hermes-swift-mac` repo
 
 ---
 
-## Sprint 7: Wave 2 Core -- Cron/Skill/Memory CRUD + Session Content Search (COMPLETED)
+## Forward work
 
-**Theme:** "Wave 2 Core -- Cron/Skill/Memory CRUD + Session Content Search"
+### Confirmed candidates (open feature requests with sprint-candidate or active interest)
 
-### Track A: Bug Fixes
-| Item | Description |
-|------|-------------|
-| Activity bar sizing | Activity bar sometimes overlaps first message on short viewports |
-| Model dropdown sync | Model chip in topbar sometimes shows stale model after session switch |
-| Cron output truncation | Long cron output in the tasks panel overflows its container |
+| Theme | Tracking | Why |
+|---|---|---|
+| Persistent-host stability | #1458 | Bootstrap fork pattern crashes under launchd / systemd — partial fix shipped (foreground mode); state.db FD leak and HTTP-unhealthy wedge remain |
+| Free-tier OpenRouter variants visible | #1426 | `:free` tool-support filter currently hides them from the picker |
+| macOS scroll override regression | #1360 | Auto-scroll sometimes overrides user scroll on the desktop app |
+| GLM dual-use (main + auxiliary) | #1291 | Currently mutually exclusive; same provider can't serve both surfaces |
+| Auto-assign session to filtered project | #1468 | When user is filtering by project X, new session should default to project X |
+| Update banner "What's new?" link | #1512 | Surface release highlights from the update banner |
+| Sunset legacy `LMSTUDIO_API_KEY` env var | #1502 | Tracking issue — alias stays for one minor cycle, then removed |
+| Hermes Agent dashboard cross-link | #1459 | Detect a running Hermes Agent and surface link in nav |
+| Gateway status card in Settings | #1457 | Current gateway-status dots only on profile picker |
+| Insights — daily token chart + per-model breakdown | #1456 | Existing usage badge is per-message; need rollup view |
+| Logs tab — view agent / errors / gateway logs | #1455 | Currently requires terminal access to log files |
+| Model picker collision handling | #1425 | Same-name models from different providers aren't disambiguated in dropdown |
+| "Reveal in Finder" right-click on workspace | #1424 | macOS desktop app convenience |
+| Configurable session persistence timing | #1406 | Currently every checkpoint, want operator control |
+| Silent credential self-heal on 401 | #1401 | Gateway auth.json drift should resolve without user re-auth |
+| LLM Wiki status panel | #1257 | On / off toggle for Wiki integration |
+| Lightweight in-app Canvas editing | #1255 | Text canvas for prompt drafting / shared notes |
+| Provider / Model source-of-truth alignment | #1240 | Reconcile WebUI vs CLI vs Gateway provider resolution |
+| Built-in SearXNG web search | #1037 | Lightweight search tool with on / off toggle |
+| Subagent session relationship view | #1004 | Show subagent hierarchy in sidebar with expand / collapse |
 
-### Track B: Features
-| Feature | What | Value |
-|---------|------|-------|
-| Session content search | Search message text across all sessions, not just titles. GET /api/sessions/search already does title search; extend to message content with a configurable depth limit | High: the single most-requested nav feature after rename |
-| Cron edit + delete | Edit an existing cron job (name, schedule, prompt, delivery) inline in the tasks panel. Delete with confirm. POST /api/crons/update and /api/crons/delete | High: closes the cron CRUD gap (create was Sprint 6) |
-| Skill create + edit | A "New skill" form in the Skills panel. Name, category, SKILL.md content in a textarea editor. Save calls POST /api/skills/save (writes to ~/.hermes/skills/). Edit opens existing skill in the same editor | High: biggest remaining CLI gap after cron |
+### Backlog (deferred, listed for visibility)
 
-### Track C: Architecture
-| Item | What |
-|------|------|
-| Phase E: app.js module split (start) | Split app.js (1332 lines) into logical modules: sessions.js, chat.js, workspace.js, panels.js, ui.js. Serve via ES module imports in index.html. This is Phase E completion. |
-| Health endpoint improvement | Add active_streams, uptime_seconds to /health response (Phase G) |
-| Git init | git init <repo>, first commit, push to private GitHub repo |
+- **Insights / monitoring suite** — agent heartbeat + alerts (#716), quota / rate-limit display (#706), data tabs (#722), monitor dashboard concepts (#766, #721)
+- **Native MCP server expose** — Hermes WebUI as an MCP server for direct agent integration (#733)
+- **Provider failover status** — show active provider per model + LLM Gateway failover state (#732)
+- **Teams / agents management panel** — editable names, roles, assignments (#719)
+- **Web UI profile model alignment with Hermes runtime** — design parity (#749)
+- **DOM windowing / message virtualization** — for sessions with hundreds of messages (#734)
+- **Searchable global tool list** (#697)
+- **Add agent / replace model modals** (#698)
+- **Code execution inline cells** — Jupyter-style cell rendering inside chat
+- **Sharing / public conversation URLs** — requires hosted backend with access control (out of scope for self-host)
 
-### Tests
-- ~20 new pytest tests (cron update/delete, skill save, session content search)
-- TESTING.md: Sections 29-31 (cron edit, skill edit, session search)
-- Estimated total after Sprint 7: ~126
+### Intentionally not planned
+- Full SwiftUI rewrite of the frontend — the WKWebView shell already gets 95% of native benefit
+- App Store distribution — sandboxing breaks the local server model
+- Real-time multi-user collaboration — single-user assumption throughout
+- Plugin marketplace — Hermes skills cover this surface
+- Anthropic / Claude proprietary features — Projects AI memory, Claude artifacts sync (not reproducible)
 
 ---
 
-## Wave 2: Full CRUD and Interaction Parity
+## Sprint history
 
-**Status:** In progress. Sprint 6 completed cron create and workspace management.
-Remaining Wave 2 items targeted for Sprints 7-8.
+Per-version detail lives in [CHANGELOG.md](./CHANGELOG.md). The table below is a high-level chronology of major sprint themes; individual PR / fix detail moved to CHANGELOG to keep this file readable.
 
-### Sprint 2.0: Workspace Management (COMPLETE Sprint 5+6)
-All workspace features delivered: add/validate/remove/rename workspaces, topbar quick-switch,
-sidebar live display, new sessions inherit last workspace. See Sprint 5 completed section.
-
-### Sprint 2.1: Cron Job Management (Partial -- Sprint 7 for remaining)
-- [x] View all jobs (Sprint 3)
-- [x] Run / pause / resume (Sprint 3)
-- [x] Create job from UI (Sprint 6)
-- [x] Edit job
-- [x] Delete job
-- [x] Full cron run history
-
-### Sprint 2.2: Skill Management (Partial -- Sprint 7 for remaining)
-- [x] List all skills with categories (Sprint 3)
-- [x] View SKILL.md content (Sprint 3)
-- [x] Create skill
-- [x] Edit skill
-- [x] Delete skill
-
-### Sprint 2.3: Memory Write (Sprint 7)
-- [x] View notes + profile (Sprint 3)
-- [x] Edit notes inline
-
-### Sprint 2.4: Todo Management (Wave 2)
-- [x] View current todo list (sidebar Todo panel, parsed from session history)
-
-### Sprint 2.5: Session Content Search (Sprint 7)
-- [x] Session title search (Sprint 4)
-- [x] Message content search across sessions
-
-### Sprint 2.6: Session Rename (COMPLETE Sprint 4)
-Double-click any session title in the left sidebar to edit inline.
-Enter saves, Escape cancels. Topbar updates immediately.
+| Range | Theme | Highlights |
+|---|---|---|
+| Sprints 1–6 | Foundations + workspace | server / static split, JS module split, workspace CRUD, file editor, message queue + INFLIGHT, isolated test environment |
+| Sprint 7 | Wave 2 core | Cron / skill / memory CRUD, session content search, health endpoint, git init |
+| Sprint 8 | Daily-driver finish line | Edit + regenerate, regenerate last response, clear conversation, Prism.js, queue + INFLIGHT polish |
+| Sprints 9–10 | Codebase health + operational polish | `app.js` → 6 modules, server.py → `api/` modules, tool card UX, background task cancel, regression tests |
+| Sprint 11 | Multi-provider models + streaming | Dynamic model dropdown, smooth scroll pinning, routes extracted to `api/routes.py` |
+| Sprint 12 | Settings + reliability + session QoL | Settings panel, SSE auto-reconnect, pin sessions, JSON import |
+| Sprint 13 | Alerts + polish | Cron alerts, background error banner, session duplicate, browser tab title |
+| Sprint 14 | Visual polish + workspace ops | Mermaid, message timestamps, file rename, folder create, session tags, archive |
+| Sprint 15 | Session projects + code copy | Projects / folders, code copy button, tool card expand / collapse |
+| Sprint 16 | Sidebar visual polish | SVG icons, action dropdown, pin indicator, project border, safe HTML rendering |
+| Sprint 17 | Workspace polish + slash commands | Breadcrumb nav, slash command autocomplete, send key setting (#26) |
+| Sprint 18 | Thinking display + workspace tree | File preview auto-close, thinking / reasoning cards, expandable directory tree (#22) |
+| Sprint 19 | Auth + security hardening | Password auth, login page, security headers, body limit (#23) |
+| Sprint 20 | Voice input + send button | Web Speech API voice, send button polish |
+| Sprint 21 | Mobile responsive + Docker | Hamburger sidebar, mobile nav, slide-over files, Docker support (#21, #7) |
+| Sprint 22 | Multi-profile support | Profile picker, management panel, seamless switching, per-session tracking (#28) |
+| Sprint 23 | Agentic transparency | Token / cost display, subagent cards, skill picker in cron, profile-local storage |
+| Sprint 24 | Web polish | rAF streaming, git detection, collapsible date groups, context ring (#80, #81, #82, #83) |
+| Sprint 25 | macOS desktop application | Native Swift + WKWebView shell, universal DMG, Sparkle 2 auto-update — separate repo |
+| Sprint 26 | Pluggable themes | Light / Slate / Solarized / Monokai / Nord, settings unsaved-changes guard, `/theme` |
+| Sprint 27 | Theme polish | 30+ hardcoded colors → CSS variables, light theme final polish |
+| Sprint 28 | Security hardening | Env race fix, random signing key, upload traversal, PBKDF2 |
+| Sprints 29–32 | Model routing + custom endpoints + reasoning | Model routing by provider prefix, custom endpoint URL fix, OLED theme, top-level reasoning, message_count sync |
+| Sprint 33 | Approval card + Lucide icons | Approval prompt surfaced, emoji → SVG, login CSP fix, update diagnostics |
+| Sprint 34 | v0.50.0 UI overhaul | Composer-centric controls, Control Center modal, workspace state machine, collapsible date groups, rAF throttle, context ring |
+| Sprints 35–37 | Onboarding + i18n + Spanish | First-run wizard, OpenRouter / Anthropic / OpenAI / Custom config, Spanish locale, Docker two-container, mobile Profiles button |
+| Sprints 38–40 | Session + UI polish + Sprint 40 | Five-bug clean-up + sidebar timestamp + test port isolation |
+| Sprints 41–42 | Renderer hardening + KaTeX + handoff | Context ring live usage, renderMd link / image / code stash chain, MEDIA: image rendering, gateway handoff foundation |
+| Sprints 43+ | Continuous contributor sprints | Custom providers, Russian locale, IME fixes, model-switch toast, approval queue multi-slot, profile polish, font-size CSS, contributor wave |
 
 ---
 
-## Completed Waves (Summary)
+## Versioning conventions
 
-| Wave | Theme | Key Deliverables |
-|------|-------|-----------------|
-| Wave 2 | Full CRUD + Interaction | Cron/skill/memory CRUD, session search, workspace management, session rename |
-| Wave 3 | Power Features | Tool call cards, multi-model dropdown, resizable panels, file actions, conversation controls |
-| Wave 4 | Settings + Notifications | Settings panel, cron alerts, background error banner |
-| Wave 5 | Session Continuity | Session tags, archive, projects/folders |
-| Wave 6 | Agentic Features | Background task cancel, voice input (Web Speech API) |
-| Wave 7 | Production Hardening | Password auth, security headers, mobile responsive, Docker + GHCR CI |
+- **Patch** (`v0.50.X`) — small batches, contributor PR releases, hotfixes
+- **Minor** (`v0.X.0`) — sprint completion, new feature surface, architecture milestone
+- **Major** (`v1.0.0`) — declared when CLI parity + Claude parity reach steady state and the feature surface stabilizes
 
----
-
-## User Requested Features
-
-Community-requested enhancements tracked from GitHub issues. All shipped.
-
-| Feature | Issue | Shipped | Sprint |
-|---------|-------|---------|--------|
-| Workspace tree view | #22 | Done | Sprint 18 |
-| Docker container + GHCR images | #7 | Done | Sprint 21 + v0.28.1 CI |
-| Authentication | #23 | Done | Sprint 19 |
-| Send key / personalization | #26 | Done | Sprint 17 |
-| Multi-profile support | #28 | Done | Sprint 22 |
-| Mobile responsive UI | #21 | Done | Sprint 21 |
-| Profile creation in Docker | #44 | Done | v0.27 |
+Per-version detail and contributor attribution live in [CHANGELOG.md](./CHANGELOG.md).

TESTING.md

@@ -1,15 +1,17 @@
 # Hermes Web UI: Browser Testing Plan
 
 > This document is for manual browser testing by you or by a Claude browser agent.
-> It covers user-facing features of the UI through Sprint 26 (v0.34.3).
+> It covers user-facing features of the UI through v0.50.21 and later releases.
 > Each section is written as a step-by-step test procedure with expected outcomes.
 > A browser agent (e.g. Claude with Chrome access) can execute this plan directly.
 >
-> Prerequisites: SSH tunnel is active on port 8786. Open http://localhost:8786 in browser.
-> Server health check: curl http://127.0.0.1:8786/health should return {"status":"ok"}.
+> Prerequisites: SSH tunnel is active on port 8787. Open http://localhost:8787 in browser.
+> Server health check: curl http://127.0.0.1:8787/health should return {"status":"ok"}.
 >
-> Automated tests: 433 total (433 passing, 0 failures)
+> Automated coverage: 3648 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 9 languages, and ~700 issue/PR-pinned regression tests.
 > Run: `pytest tests/ -v --timeout=60`
+>
+> Local regression focus: verify that a previously closed workspace panel stays visually closed from first paint through boot completion on desktop refresh; there should be no brief open-then-close flash.
 
 ---
 
@@ -32,9 +34,11 @@ SETUP: Clear localStorage (DevTools > Application > Local Storage > delete herme
 STEPS:
   1. Navigate to http://localhost:8787
 EXPECT:
-  - Dark background, Hermes logo in sidebar header
+  - Dark background
+  - Sidebar begins directly with the icon tab row; there is no dedicated branding header
   - Center area shows "What can I help with?" heading with suggestion buttons
   - Session list in sidebar is empty or shows existing sessions
+  - Sidebar footer shows a single "Hermes WebUI" control-center button
   - No session is highlighted active
   - Send button is present but there is no input focus by default
 FAIL: Page shows error, blank white screen, or auto-creates a new session without user action.
@@ -73,11 +77,11 @@ STEPS:
 EXPECT:
   - User message appears immediately in chat
   - Thinking dots (three animated dots) appear below
-  - Status bar shows "Hermes is thinking..."
   - Send button becomes disabled (grayed out)
+  - A red stop button appears in the composer footer while the turn is running
   - Within 10-30 seconds, Hermes responds with a three-word greeting
   - Thinking dots disappear
-  - Send button re-enables
+  - Send button re-enables and the stop button disappears
   - Session title in sidebar updates to reflect the first message
 FAIL: Message never appears, thinking dots never go away, Send button stays disabled forever.
 
@@ -144,7 +148,7 @@ FAIL: New session created, error thrown, or UI breaks.
 ### T3.1: Model Dropdown Shows All Options
 SETUP: Any active session.
 STEPS:
-  1. Look at the sidebar bottom: "Model" label and a dropdown
+  1. Look at the composer footer: to the right of the attach/mic controls there is a model dropdown
   2. Click the dropdown to expand it
 EXPECT:
   - Provider groups visible: OpenAI, Anthropic, Other
@@ -153,18 +157,30 @@ EXPECT:
   - Other group: Gemini 2.5 Pro, DeepSeek V3, Llama 4 Scout
 FAIL: Only 2 options visible, no groups, or missing models.
 
-### T3.2: Model Chip Reflects Selection
+### T3.2: Model Dropdown Reflects Active Conversation
 SETUP: Active session.
 STEPS:
   1. Change model dropdown to "Claude Sonnet 4.6"
 EXPECT:
-  - The blue chip in the topbar right updates to "Sonnet 4.6" immediately
-  - NOT "GPT-5.4 Mini" (this was Bug B3, now fixed)
+  - The composer footer dropdown stays on "Claude Sonnet 4.6"
+  - Sending the next message uses that session model rather than an older one from another conversation
 STEPS (continued):
   2. Change model to "Gemini 2.5 Pro"
 EXPECT:
-  - Chip updates to "Gemini 2.5 Pro" (not "GPT-5.4 Mini")
-FAIL: Chip shows wrong model name for any non-Sonnet selection.
+  - The dropdown updates to "Gemini 2.5 Pro"
+  - Switching away and back to the conversation restores the same model in the footer selector
+FAIL: Dropdown shows the wrong active model after a session switch, or sending uses a stale model.
+
+### T3.3: Context Badge Shares Footer Space Cleanly
+SETUP: Active session with at least one completed response.
+STEPS:
+  1. Look at the right side of the composer footer
+EXPECT:
+  - A compact circular context badge appears next to the send button when usage data is available
+  - The number in the center shows the used percentage
+  - Hovering or focusing the badge shows a tooltip with percent used, token count, auto-compress threshold, and estimated cost when available
+  - The model dropdown remains usable without overlapping the send button or pushing controls out of view
+FAIL: Linear meter still shown, tooltip missing/incomplete, controls overlap, or footer wraps in a broken way.
 
 ---
 
@@ -224,12 +240,48 @@ EXPECT:
   - If it was the only file, tray collapses
 FAIL: File not removed, error.
 
+### T4.6: Inline Audio Attachment Editor with Variable Speed
+SETUP: Active session, an audio file ready locally (`.mp3`, `.wav`, `.m4a`, `.ogg`, or `.flac`).
+STEPS:
+  1. Attach the audio file with the paperclip or drag/drop
+  2. Confirm the tray shows an audio media chip, then send the message
+  3. In the sent user message, press Play on the inline audio player
+  4. Click 0.5×, 1.25×, 1.5×, and 2× speed buttons
+EXPECT:
+  - The audio renders inline in the chat instead of only as a download/file badge
+  - Native audio controls are visible and usable
+  - The clicked speed button becomes active and playback speed changes immediately
+  - Download/open behavior for non-media files is unchanged
+FAIL: Audio only downloads, no speed buttons appear, or speed buttons do not affect playback.
+
+### T4.7: Inline Video Attachment Editor with Variable Speed
+SETUP: Active session, a video file ready locally (`.mp4`, `.mov`, `.webm`, or `.m4v`).
+STEPS:
+  1. Attach and send the video file
+  2. In the sent user message, play the inline video
+  3. Switch among 0.75×, 1×, 1.5×, and 2× speed controls
+EXPECT:
+  - The video renders inline, contained within the message width
+  - Native video controls are visible and usable
+  - Speed selection updates the video `playbackRate` without reloading the media
+FAIL: Video only shows a generic badge, overflows the chat column, or speed controls fail.
+
 ---
 
 ## Section 5: Workspace File Browser
 
-### T5.1: File Tree Loads on Session Start
+### T5.0: Panel Is Closed By Default
 SETUP: Active session with workspace set.
+EXPECT:
+  - Right workspace panel is hidden on initial load
+  - Center chat column uses the freed width
+  - "Files" toggle is visible in the topbar
+FAIL: Right panel starts open without any browsing or preview action.
+
+### T5.1: File Tree Loads When Files Panel Is Opened
+SETUP: Active session with workspace set.
+STEPS:
+  1. Click the "Files" toggle in the topbar
 EXPECT:
   - Right panel shows "WORKSPACE" header
   - File tree lists files and directories in the workspace
@@ -263,10 +315,11 @@ STEPS:
   1. Click the X button in the panel header
 EXPECT:
   - Preview closes
-  - File tree is visible again
+  - If the panel auto-opened for that preview, the entire right panel closes again
+  - If the panel was manually opened for browsing first, the file tree is visible again
   - Preview area is hidden
   - Reopening the same file shows fresh content (no stale cached text)
-FAIL: X button does nothing, tree does not reappear.
+FAIL: X button does nothing, panel stays stuck open, or the file tree does not reappear after manual browse mode.
 
 ### T5.5: Preview an Image File (Sprint 2)
 SETUP: Upload a PNG, JPG, or any image file to the workspace, OR the workspace already contains one.
@@ -279,6 +332,33 @@ EXPECT:
   - Image maintains aspect ratio
 FAIL: Raw binary text displayed, broken image icon, error message, or nothing happens.
 
+### T5.5b: Preview Audio/Video Files Inline
+SETUP: Workspace contains at least one audio file (`.mp3`, `.wav`, `.m4a`) and one video file (`.mp4`, `.mov`, `.webm`).
+STEPS:
+  1. Click the audio file in the workspace file tree
+  2. Play it and select 1.5× or 2× speed
+  3. Close preview, then click the video file
+  4. Play it and select 0.75× or 1.25× speed
+EXPECT:
+  - Audio/video open in the workspace preview panel instead of downloading immediately
+  - Path badge shows `audio` or `video`
+  - Native media controls and the variable-speed buttons are visible
+  - Video scales to the preview panel without overflowing
+FAIL: Browser downloads the media immediately, raw binary appears, or speed controls are missing/broken.
+
+### T5.5c: Preview PDF Files Inline
+SETUP: Workspace contains at least one `.pdf` file.
+STEPS:
+  1. Click the PDF file in the workspace file tree
+  2. Use the browser/PDF viewer scroll and zoom controls if available
+  3. Click "Open in browser" as a fallback
+EXPECT:
+  - PDF opens in the workspace preview panel instead of downloading immediately
+  - Path badge shows `pdf`
+  - PDF iframe fills the preview area
+  - "Open in browser" opens the same raw file endpoint in a new tab
+FAIL: Browser downloads the PDF immediately, raw binary appears, or the preview panel is blank without an open fallback.
+
 ### T5.6: Preview a Markdown File (Sprint 2)
 SETUP: Workspace has a .md file (or create one: upload a file named README.md with some markdown content).
 STEPS:
@@ -377,7 +457,8 @@ FAIL: Command blocked after Allow once, card stays, error.
 ### T8.1: Download Conversation as Markdown
 SETUP: A session with at least 2 messages (1 user + 1 assistant).
 STEPS:
-  1. Click the "Transcript" download button in the sidebar bottom
+  1. Click the "Hermes" button in the sidebar footer
+  2. In the Control Center modal, click "Transcript"
 EXPECT:
   - Browser downloads a .md file named hermes-{session_id}.md
   - Opening the file shows the conversation in markdown format:
@@ -468,6 +549,7 @@ FAIL: No log output, log shows Apache-style text instead of JSON, log file not c
 SETUP: Message is sending (thinking dots visible).
 EXPECT:
   - Send button is visually grayed out
+  - Stop button is visible in the composer footer
   - Pressing Enter does NOT send another message
   - Clicking Send button does nothing
 FAIL: Multiple messages sent while one is in flight.
@@ -831,7 +913,7 @@ FAIL: No icon ever appears, icon always visible (not hover-only).
 ### T21.2: Delete a File with Confirmation
 STEPS:
   1. Hover over a file and click its trash icon
-  2. A browser confirm dialog appears: "Delete [filename]?"
+  2. An in-app confirmation modal appears: "Delete [filename]?"
   3. Click OK
 EXPECT:
   - Toast: "Deleted [filename]"
@@ -842,7 +924,7 @@ FAIL: File not deleted, no confirmation dialog, error.
 ### T21.3: Cancel Delete Does Nothing
 STEPS:
   1. Hover over a file and click its trash icon
-  2. Click Cancel on the confirm dialog
+  2. Click Cancel on the confirmation modal
 EXPECT:
   - File remains in the tree
   - No toast, no error
@@ -851,7 +933,7 @@ FAIL: File deleted despite cancel.
 ### T21.4: Create a New File
 STEPS:
   1. Click the + button in the workspace panel header
-  2. A prompt dialog appears: "New file name (e.g. notes.md):"
+  2. An in-app input modal appears: "New file name (e.g. notes.md):"
   3. Type "test-sprint4.md" and click OK
 EXPECT:
   - Toast: "Created test-sprint4.md"
@@ -925,7 +1007,7 @@ FAIL: Invalid path added, no error.
 ### T22.4: Remove a Workspace
 STEPS:
   1. Click the X button next to any non-default workspace
-  2. Confirm the dialog
+  2. Confirm the modal
 EXPECT:
   - Workspace disappears from the list
   - Toast: "Workspace removed"
@@ -981,7 +1063,7 @@ STEPS:
   1. Hover over an assistant message
   2. Click the clipboard icon
 EXPECT:
-  - Icon briefly shows a checkmark (✓) then reverts to clipboard
+  - Icon briefly shows a check icon, then reverts to the copy icon
   - Paste (Cmd+V) elsewhere shows the full text of that message
 FAIL: No visual feedback, clipboard empty or wrong content.
 
@@ -994,23 +1076,23 @@ STEPS:
   1. Click any .py, .js, or .txt file in the workspace file tree
 EXPECT:
   - File content shows in read-only monospace view
-  - An "✎ Edit" button is visible in the preview path bar
+  - An Edit button with a pencil icon is visible in the preview path bar
   - Content is NOT editable (clicking in it does nothing)
 FAIL: Content immediately editable, no Edit button.
 
 ### T24.2: Edit Button Enters Edit Mode
 STEPS:
-  1. Click "✎ Edit" on a code file preview
+  1. Click the Edit button on a code file preview
 EXPECT:
   - Read-only view replaced by an editable textarea
   - Content of the file is pre-populated in the textarea
-  - Button changes to "💾 Save"
+  - Button changes to "Save" with a disk icon
 FAIL: Nothing changes, button doesn't change.
 
 ### T24.3: Save Writes Changes to Disk
 STEPS:
   1. In edit mode, change some text
-  2. Click "💾 Save"
+  2. Click the Save button
 EXPECT:
   - Read-only view returns, showing the updated content
   - Toast: "Saved"
@@ -1022,8 +1104,8 @@ STEPS:
   1. Enter edit mode on a file
   2. Make any change (type a character)
 EXPECT:
-  - Button shows "💾 Save*" (asterisk indicates unsaved changes)
-FAIL: No asterisk, button stays as "💾 Save".
+  - Button shows "Save*" with the disk icon still visible (asterisk indicates unsaved changes)
+FAIL: No asterisk, button stays as "Save".
 
 ### T24.5: Markdown File Edit-Save Roundtrip
 STEPS:
@@ -1070,7 +1152,7 @@ against each criterion below. A Claude browser agent can verify these with brows
 
 ### T25.1: Sidebar Nav Tabs are Icon-Only
 EXPECT:
-  - Five icon-only tabs in the sidebar nav row: 💬 ⏱️ 📚 🧠 📁
+  - Five icon-only tabs in the sidebar nav row: message, clock, book, brain, folder
   - No text labels visible by default (text removed to prevent overflow)
   - Hovering a tab shows a tooltip with the label (Chat/Tasks/Skills/Memory/Spaces)
   - Active tab has a blue underline, icon brighter blue
@@ -1194,7 +1276,7 @@ STEPS:
   3. Click Create job
 EXPECT:
   - Form closes
-  - Toast: "Job created ✓"
+  - Toast: "Job created"
   - New job appears in the cron list with status "active"
 FAIL: Error shown, job not created, form stays open.
 
@@ -1225,7 +1307,8 @@ FAIL: Job created, form doesn't close.
 ### T28.1: JSON Export Button Downloads File
 SETUP: Active session with at least a few messages.
 STEPS:
-  1. Click the "JSON" button in the sidebar footer (next to Transcript)
+  1. Click the "Hermes" button in the sidebar footer
+  2. In the Control Center modal, click "JSON"
 EXPECT:
   - Browser downloads a file named hermes-{session_id}.json
   - Opening the file shows valid JSON with: session_id, title, messages array,
@@ -1289,7 +1372,7 @@ STEPS (continued from T29.1):
   1. Change the name field to "Renamed Job"
   2. Click Save
 EXPECT:
-  - Form closes, toast "Job updated ✓"
+  - Form closes, toast "Job updated"
   - Job header shows new name
 FAIL: Save fails, name unchanged.
 
@@ -1297,7 +1380,7 @@ FAIL: Save fails, name unchanged.
 SETUP: A cron job you can safely delete (or a test job created for this).
 STEPS:
   1. Expand the job, click "Delete"
-  2. Confirm the dialog
+  2. Confirm the modal
 EXPECT:
   - Toast: "Job deleted"
   - Job disappears from the list
@@ -1326,7 +1409,7 @@ tags: [test]
 # Test"
   2. Click Save skill
 EXPECT:
-  - Toast "Skill created ✓", form closes
+  - Toast "Skill created", form closes
   - Skill appears in the skills list
 FAIL: Error, skill not in list.
 
@@ -1354,7 +1437,7 @@ STEPS:
   1. In edit mode, add a line to the textarea
   2. Click Save
 EXPECT:
-  - Toast "Memory saved ✓", form closes
+  - Toast "Memory saved", form closes
   - Memory panel reloads showing the updated content
 FAIL: Save fails, content unchanged.
 
@@ -1467,14 +1550,16 @@ FAIL: Both messages removed, wrong message sent, crash.
 ### T34.1: Clear Button Appears When Session Has Messages
 SETUP: Session with at least one message.
 EXPECT:
-  - A "🗑 Clear" chip appears in the topbar right side (next to the workspace chip)
-  - Button NOT visible when session has no messages / empty state
+  - The "Hermes" button is visible in the sidebar footer
+  - Opening the Control Center shows a "Clear" action in the Conversation section
+  - The Clear action is disabled when there is no active session or no messages
 FAIL: Button always visible, never visible.
 
 ### T34.2: Clear Wipes Messages and Resets Title
 STEPS:
-  1. Click the Clear button in the topbar
-  2. Confirm the dialog
+  1. Click the "Hermes" button in the sidebar footer
+  2. Click "Clear" in the Conversation section
+  3. Confirm the modal
 EXPECT:
   - All messages disappear from the chat area
   - Empty state ("What can I help with?") reappears
@@ -1485,7 +1570,7 @@ FAIL: Session deleted, messages remain, title not reset.
 
 ### T34.3: Cancel Clear Does Nothing
 STEPS:
-  1. Click Clear, then click Cancel in the confirm dialog
+  1. Click Clear, then click Cancel in the confirmation modal
 EXPECT:
   - All messages still present
   - No toast, no change
@@ -1609,7 +1694,7 @@ Each has automated API-level tests in `tests/test_sprint{N}.py`.
 - Switch model. Send a message. Verify response uses selected model.
 
 ### Sprint 12: Settings + Pin + Import
-- Click gear icon. Settings overlay opens.
+- Click the "Hermes WebUI" button in the sidebar footer. Control Center overlay opens with vertical section tabs on the left.
 - Change default model, save. Restart server. Verify setting persisted.
 - Pin a session (star icon in hover overlay). Verify it floats to top of list.
 - Export session as JSON. Import it back. Verify messages restored.
@@ -1637,11 +1722,12 @@ Each has automated API-level tests in `tests/test_sprint{N}.py`.
 
 ### Sprint 16: Sidebar Visual Polish
 - Session titles use full sidebar width (no truncated space for hidden icons).
-- Hover a session → action buttons appear from right with gradient fade.
+- Hover a session → a dotted actions trigger appears on the right.
+- Click the dotted trigger → a dropdown opens with pin, project, archive, duplicate, and delete actions.
 - All icons are monochrome SVGs (not emoji). Consistent across platforms.
 - Pinned sessions show small gold star inline. Unpinned = no star, full title width.
-- Active session has gold highlight (not blue). Overlay gradient matches.
-- Double-click to rename → overlay hides during rename.
+- Active session has gold highlight (not blue).
+- Double-click to rename → session actions hide during rename.
 
 ### Sprint 17: Workspace + Slash Commands + Send Key
 - Navigate into a subdirectory. Breadcrumb bar appears with clickable segments.
@@ -1655,6 +1741,13 @@ Each has automated API-level tests in `tests/test_sprint{N}.py`.
 - Click a directory toggle arrow (▸) → expands in-place showing children.
 - Click again (▾) → collapses. Double-click navigates into it (breadcrumb view).
 - If model returns thinking blocks (Claude extended thinking), verify collapsible gold card appears above response.
+- Verify the thinking card has a tinted background, visible border, and rounded corners like a tool card, but in the gold thinking palette.
+- Open and close a thinking card. Verify the caret rotation and the content reveal both animate smoothly instead of snapping open.
+
+### UI Polish: Tool Card Disclosure Animation
+- Trigger a response with at least one completed tool call card.
+- Open and close the tool call card. Verify the caret rotates smoothly and the args/result section animates open and closed instead of appearing instantly.
+- If a turn has 2+ tool cards, use "Expand all / Collapse all" and verify the same smooth animation applies to every card in the group.
 
 ### Sprint 19: Auth + Security
 - No password set: everything works as normal. No login page.
@@ -1684,12 +1777,13 @@ Each has automated API-level tests in `tests/test_sprint{N}.py`.
 - Open on mobile viewport (<640px): hamburger icon visible in topbar.
 - Tap hamburger → sidebar slides in from left with backdrop overlay.
 - Tap outside sidebar → closes. Tap a session → closes and loads session.
-- Bottom navigation bar: 5 tabs (Chat, Tasks, Skills, Memory, Spaces).
-- Tap "Tasks" in bottom nav → sidebar opens showing Tasks panel.
-- Tap "Chat" in bottom nav → sidebar closes (chat is in main area).
+- Sidebar top nav remains visible inside the mobile drawer; includes Chat/Tasks/Skills/Memory/Spaces/Profile tabs.
+- Tap "Tasks" in the drawer nav → Tasks panel opens in the sidebar drawer.
+- Tap "Chat" in the drawer nav → sidebar closes and chat is unobstructed in the main area.
 - Files button in topbar → right panel slides in from right.
+- No fixed mobile bottom nav; chat transcript and composer use the reclaimed vertical space.
 - All touch targets are at least 44px (session items, buttons, icons).
-- Desktop viewport (>640px): no hamburger, no bottom nav, no mobile elements.
+- Desktop viewport (>640px): no hamburger or mobile overlay; desktop layout unchanged.
 - Docker: `docker compose up -d` starts server on port 8787.
 - Docker: session data persists across container restarts (named volume).
 
@@ -1702,14 +1796,47 @@ Each has automated API-level tests in `tests/test_sprint{N}.py`.
 - "Use" button switches profile. Delete button removes non-default profiles.
 - "+ New profile" form: name validation (lowercase + hyphens), clone config checkbox.
 - Create profile → appears in list and dropdown.
-- Delete profile → confirm dialog. Auto-switches to default if deleting active.
+- Delete profile → confirmation modal. Auto-switches to default if deleting active.
 - Attempt switch while agent busy → blocked with toast message.
 - With hermes-agent not installed → only default profile shown, graceful fallback.
 
 ---
 
-*Last updated: Sprint 26 / v0.34.3, April 5, 2026*
-*Total automated tests: 433 (433 passing, 0 failures)*
+## Slash command parity (manual checklist)
+
+For each batch-1 command, run via webui slash menu AND via `hermes` CLI in the
+same `HERMES_HOME` (when applicable) and verify identical effect.
+
+- [ ] `/help` — dropdown lists 25+ commands; selecting `/help` posts an assistant message listing them.
+- [ ] `/new` (and alias `/reset`) — starts fresh session.
+- [ ] `/clear` — clears current transcript display (webui-only meaning, distinct from CLI's "clear screen").
+- [ ] `/title <name>` — renames active session, topbar + sidebar update; `/title` alone shows current title.
+- [ ] `/status` — assistant message shows session_id, model, workspace, message count.
+- [ ] `/usage` — assistant message shows token counts; the "show token usage" setting is unchanged (toggle still in Settings panel).
+- [ ] `/stop` — interrupts a running stream; with no active stream toasts "No active task to stop."
+- [ ] `/retry` — removes last user+assistant exchange, refills composer with last user text, resends. Final transcript has only ONE copy of the resent message.
+- [ ] `/undo` — removes last user+assistant exchange; toast confirms; repeated until empty toasts "Nothing to undo."
+- [ ] `/model <name>` — switches model dropdown.
+- [ ] `/personality` — lists personalities; `/personality <name>` switches.
+- [ ] `/skills [query]` — lists matching skills.
+- [ ] `/theme <name>` — switches webui theme.
+- [ ] `/workspace <name>` — switches workspace.
+
+Unknown / deferred:
+
+- [ ] `/yolo`, `/reasoning`, `/voice`, `/branch`, `/insights`, `/debug`, `/reload`, etc. — toast "Web UI 暂未实现该命令: /<name>". MUST NOT be sent as plain text to the LLM.
+- [ ] `/compact` — toast "/compress is not available in the web UI yet — use the CLI for now." (was sending free text to LLM before this batch.)
+- [ ] Made-up command (e.g. `/fhfajl`) — fall through to send as text (existing behavior preserved for typos vs. real commands).
+
+Bridged CLI sessions:
+
+- [ ] Open a CLI-bridged session in webui sidebar (if `show_cli_sessions` setting enabled).
+- [ ] `/retry`, `/undo` toast "该命令仅支持 Web UI 原生会话…" and do nothing.
+
+---
+
+*Last updated: v0.50.282, May 03, 2026*
+*Total automated tests collected: 4018*
 *Regression gate: tests/test_regressions.py*
 *Run: pytest tests/ -v --timeout=60*
 *Source: <repo>/*

THEMES.md

@@ -1,6 +1,6 @@
 # Hermes Web UI — Themes
 
-Hermes Web UI supports pluggable color themes. Five themes ship built-in, and
+Hermes Web UI supports pluggable color themes. Seven themes ship built-in, and
 you can create your own with pure CSS — no Python changes needed.
 
 ---
@@ -27,6 +27,7 @@ preview is instant — the UI updates as you click through options.
 | **Solarized Dark** | Ethan Schoonover's classic dark palette. Teal background, warm accents. |
 | **Monokai** | Warm dark theme inspired by the Monokai editor scheme. Green/pink accents. |
 | **Nord** | Arctic blue-gray palette from the Nord color system. Calm and minimal. |
+| **OLED** | True black (#000) backgrounds for OLED displays. Minimizes glow and burn-in risk. |
 | **Custom themes** | Any string accepted by `settings.json`, `POST /api/settings`, and `/theme` if added to the picker/command list. Pure CSS variables only. |
 
 ---

api/agent_sessions.py

@@ -0,0 +1,424 @@
+"""Shared helpers for reading Hermes Agent sessions from state.db."""
+import logging
+import sqlite3
+from contextlib import closing
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+MESSAGING_SOURCES = {
+    'discord',
+    'slack',
+    'telegram',
+    'weixin',
+}
+
+SOURCE_LABELS = {
+    'api_server': 'API',
+    'cli': 'CLI',
+    'cron': 'Cron',
+    'discord': 'Discord',
+    'slack': 'Slack',
+    'telegram': 'Telegram',
+    'tool': 'Tool',
+    'webui': 'WebUI',
+    'weixin': 'Weixin',
+}
+
+
+def normalize_agent_session_source(raw_source: str | None) -> dict:
+    """Return stable source metadata for Hermes Agent session rows.
+
+    ``sessions.source`` is an Agent-level raw value. WebUI needs a smaller,
+    durable contract so routes, SSE snapshots, and future sidebar policies do
+    not each reimplement raw-source checks.
+    """
+    raw = str(raw_source or '').strip().lower() or 'unknown'
+
+    if raw == 'webui':
+        session_source = 'webui'
+    elif raw == 'cli':
+        session_source = 'cli'
+    elif raw in MESSAGING_SOURCES:
+        session_source = 'messaging'
+    elif raw == 'cron':
+        session_source = 'cron'
+    elif raw == 'tool':
+        session_source = 'tool'
+    elif raw == 'api_server':
+        session_source = 'api'
+    else:
+        session_source = 'other'
+
+    label = SOURCE_LABELS.get(raw)
+    if not label:
+        label = raw.replace('_', ' ').title() if raw != 'unknown' else 'Agent'
+
+    return {
+        'raw_source': None if raw == 'unknown' else raw,
+        'session_source': session_source,
+        'source_label': label,
+    }
+
+
+def _with_normalized_source(row: dict) -> dict:
+    normalized = normalize_agent_session_source(row.get('source'))
+    return {**row, **normalized}
+
+
+def _optional_col(name: str, columns: set[str], fallback: str = "NULL") -> str:
+    return f"s.{name}" if name in columns else f"{fallback} AS {name}"
+
+
+def _is_continuation_session(parent: dict | None, child: dict | None) -> bool:
+    """Return True when ``child`` is the next segment of the same conversation.
+
+    Compression rotates session ids automatically. A manual CLI close followed
+    by ``hermes -c`` also records a new child session; for sidebar projection it
+    should continue the same visible conversation rather than becoming a
+    separate child-session row. Plain parent/child links that started before the
+    parent's ended boundary remain child sessions.
+    """
+    if not parent or not child:
+        return False
+    if parent.get('end_reason') not in {'compression', 'cli_close'}:
+        return False
+    ended_at = parent.get('ended_at')
+    if ended_at is None:
+        # Older state.db rows/tests may not have ended_at populated. Preserve
+        # the historical contract that compression/cli_close parent links are
+        # continuations when no boundary timestamp is available.
+        return True
+    try:
+        return float(child.get('started_at') or 0) >= float(ended_at)
+    except (TypeError, ValueError):
+        return False
+
+
+def _continuation_root_id(rows_by_id: dict[str, dict], session_id: str | None) -> str | None:
+    """Return the visible lineage root for ``session_id`` by walking continuations."""
+    if not session_id:
+        return None
+    root_id = str(session_id)
+    current_id = root_id
+    seen = {current_id}
+    for _ in range(len(rows_by_id) + 1):
+        current = rows_by_id.get(current_id)
+        parent_id = current.get('parent_session_id') if current else None
+        parent = rows_by_id.get(parent_id) if parent_id else None
+        if not parent or not _is_continuation_session(parent, current):
+            return root_id
+        if parent_id in seen:
+            return root_id
+        root_id = str(parent_id)
+        current_id = str(parent_id)
+        seen.add(current_id)
+    return root_id
+
+
+def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
+    """Collapse compression chains into one logical sidebar row.
+
+    The visible conversation should still look like the original chain head
+    (title and timestamps), while importing should use the latest importable
+    segment so the user continues from the current compressed state.
+    """
+    rows_by_id = {row['id']: row for row in rows}
+    children_by_parent: dict[str, list[dict]] = {}
+    continuation_child_ids = set()
+
+    for row in rows:
+        parent_id = row.get('parent_session_id')
+        if not parent_id:
+            continue
+        children_by_parent.setdefault(parent_id, []).append(row)
+        if _is_continuation_session(rows_by_id.get(parent_id), row):
+            continuation_child_ids.add(row['id'])
+        else:
+            row['relationship_type'] = 'child_session'
+            parent_root = _continuation_root_id(rows_by_id, parent_id)
+            if parent_root:
+                row['_parent_lineage_root_id'] = parent_root
+
+    for children in children_by_parent.values():
+        children.sort(key=lambda row: row.get('started_at') or 0, reverse=True)
+
+    def compression_tip(row: dict) -> tuple[dict | None, int]:
+        current = row
+        seen = {row['id']}
+        latest_importable = row if (row.get('actual_message_count') or 0) > 0 else None
+        segment_count = 1
+        for _ in range(len(rows_by_id) + 1):
+            candidates = [
+                child for child in children_by_parent.get(current['id'], [])
+                if child['id'] not in seen and _is_continuation_session(current, child)
+            ]
+            if not candidates:
+                return latest_importable, segment_count
+            current = candidates[0]
+            seen.add(current['id'])
+            segment_count += 1
+            if (current.get('actual_message_count') or 0) > 0:
+                latest_importable = current
+        return latest_importable, segment_count
+
+    projected = []
+    for row in rows:
+        if row['id'] in continuation_child_ids:
+            continue
+
+        segment_count = 1
+        tip = row
+        if row.get('end_reason') in {'compression', 'cli_close'}:
+            tip, segment_count = compression_tip(row)
+        if not tip or (tip.get('actual_message_count') or 0) <= 0:
+            continue
+
+        if tip is row:
+            projected.append(dict(row))
+            continue
+
+        merged = dict(row)
+        # Keep the chain head's visible identity (title, started_at), but
+        # point the row at the latest importable segment for navigation AND
+        # surface the tip's recency so an actively-used chain bubbles to the
+        # top of the sidebar by its true last activity. Without overriding
+        # last_activity, a long-lived chain whose tip is being edited NOW
+        # would sort by the root's old timestamp and fall below recently
+        # touched standalone sessions — exactly the inverse of what a user
+        # expects from "Show agent sessions" sorted by activity.
+        for key in (
+            'id', 'model', 'message_count', 'actual_message_count',
+            'ended_at', 'end_reason', 'last_activity',
+        ):
+            if key in tip:
+                merged[key] = tip[key]
+        if not merged.get('title'):
+            merged['title'] = tip.get('title')
+        if not merged.get('source'):
+            merged['source'] = tip.get('source')
+        merged['_lineage_root_id'] = row['id']
+        merged['_lineage_tip_id'] = tip['id']
+        merged['_compression_segment_count'] = segment_count
+        projected.append(merged)
+
+    projected.sort(
+        key=lambda row: row.get('last_activity') or row.get('started_at') or 0,
+        reverse=True,
+    )
+    return projected
+
+
+def read_importable_agent_session_rows(
+    db_path: Path,
+    limit: int = 200,
+    log=None,
+    exclude_sources: tuple[str, ...] | None = ("cron", "webui"),
+) -> list[dict]:
+    """Return agent sessions projected as importable conversations.
+
+    Hermes Agent can create rows in ``state.db.sessions`` before a session has
+    any messages, and long conversations can be split into compression-linked
+    rows. WebUI cannot import empty rows and should not show compression
+    segments as separate conversations, so both the regular ``/api/sessions``
+    path and the gateway SSE watcher use this shared projection.
+
+    By default, omit background/internal sources such as ``cron`` from the WebUI
+    sidebar. This mirrors Hermes Agent CLI's session-list behaviour: interactive
+    views should stay focused on user-facing conversations, while callers that
+    need a source-specific diagnostic view can opt out by passing
+    ``exclude_sources=None``.
+    """
+    db_path = Path(db_path)
+    if not db_path.exists():
+        return []
+
+    log = log or logger
+    with closing(sqlite3.connect(str(db_path))) as conn:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+
+        # Older Hermes Agent versions may not have source tracking. Without a
+        # source column we cannot safely distinguish WebUI rows from agent rows.
+        cur.execute("PRAGMA table_info(sessions)")
+        session_cols = {row[1] for row in cur.fetchall()}
+        if 'source' not in session_cols:
+            log.warning(
+                "agent session listing skipped: state.db at %s has no 'source' column "
+                "(older hermes-agent?). Agent sessions unavailable. "
+                "Upgrade hermes-agent to fix this.",
+                db_path,
+            )
+            return []
+
+        parent_expr = _optional_col('parent_session_id', session_cols)
+        ended_expr = _optional_col('ended_at', session_cols)
+        end_reason_expr = _optional_col('end_reason', session_cols)
+        user_id_expr = _optional_col('user_id', session_cols)
+        chat_id_expr = _optional_col('chat_id', session_cols)
+        chat_type_expr = _optional_col('chat_type', session_cols)
+        thread_id_expr = _optional_col('thread_id', session_cols)
+        session_key_expr = _optional_col('session_key', session_cols)
+        origin_chat_id_expr = _optional_col('origin_chat_id', session_cols)
+        origin_user_id_expr = _optional_col('origin_user_id', session_cols)
+        platform_expr = _optional_col('platform', session_cols)
+
+        where_clauses = ["s.source IS NOT NULL"]
+        params: list[str] = []
+        if exclude_sources:
+            excluded = tuple(str(source) for source in exclude_sources if source)
+            if excluded:
+                placeholders = ", ".join("?" for _ in excluded)
+                where_clauses.append(f"s.source NOT IN ({placeholders})")
+                params.extend(excluded)
+
+        cur.execute(
+            f"""
+            SELECT s.id, s.title, s.model, s.message_count,
+                   s.started_at, s.source,
+                   {user_id_expr},
+                   {chat_id_expr},
+                   {chat_type_expr},
+                   {thread_id_expr},
+                   {session_key_expr},
+                   {origin_chat_id_expr},
+                   {origin_user_id_expr},
+                   {platform_expr},
+                   {parent_expr},
+                   {ended_expr},
+                   {end_reason_expr},
+                   COUNT(m.id) AS actual_message_count,
+                   MAX(m.timestamp) AS last_activity
+            FROM sessions s
+            LEFT JOIN messages m ON m.session_id = s.id
+            WHERE {' AND '.join(where_clauses)}
+            GROUP BY s.id
+            ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC
+            """,
+            params,
+        )
+        projected = _project_agent_session_rows([dict(row) for row in cur.fetchall()])
+        projected = [_with_normalized_source(row) for row in projected]
+        if limit is None:
+            return projected
+        return projected[:max(0, int(limit))]
+
+
+
+def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[str]) -> dict[str, dict]:
+    """Return compression-lineage metadata for known WebUI sidebar sessions.
+
+    WebUI sessions are persisted as JSON files, but Hermes Agent also mirrors
+    them into ``state.db.sessions`` for insights/session history. Compression
+    and cross-surface continuation create parent chains there. ``/api/sessions``
+    needs to surface that lineage to the sidebar so client-side collapse can
+    group logical continuations without mutating or deleting any session files.
+
+    Missing DBs, old schemas, or incomplete rows degrade to an empty mapping.
+    """
+    wanted = {str(sid) for sid in (session_ids or []) if sid}
+    db_path = Path(db_path)
+    if not wanted or not db_path.exists():
+        return {}
+
+    try:
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            conn.row_factory = sqlite3.Row
+            cur = conn.cursor()
+            cur.execute("PRAGMA table_info(sessions)")
+            session_cols = {row[1] for row in cur.fetchall()}
+            if 'parent_session_id' not in session_cols or 'end_reason' not in session_cols:
+                return {}
+            # Scoped fetch via PRIMARY KEY + idx_sessions_parent rather than a
+            # full table scan. The sessions table grows unbounded over time
+            # (1000+ rows is normal, 10000+ for power users), and this function
+            # runs on every sidebar refresh — a full SELECT was ~50x slower
+            # than the indexed lookup at 1000 rows and scales linearly.
+            #
+            # Fetch the wanted ids first, then chase parent_session_id chains
+            # in batches until no new ids appear. Each batch hits PRIMARY KEY
+            # so it's effectively O(N) lookups.
+            #
+            # IN-clause is chunked to 500 to stay under SQLITE_MAX_VARIABLE_NUMBER
+            # on older sqlite (Python 3.9 ships sqlite 3.31 which defaults to 999;
+            # newer Python ships sqlite 3.32+ at 32766). On a power user with
+            # 2000+ sessions in the sidebar, an unchunked first hop would raise
+            # `OperationalError: too many SQL variables`, get swallowed by the
+            # except below, and silently disable lineage collapse forever.
+            # (Opus pre-release review of v0.50.251, SHOULD-FIX 2.)
+            IN_CHUNK = 500
+            rows: dict[str, dict] = {}
+            to_fetch = set(wanted)
+            # Cap walk depth to bound worst-case query count. Real lineage
+            # chains seen in production are <10 segments; anything longer is
+            # almost certainly pathological data and not worth chasing.
+            for _hop in range(20):
+                if not to_fetch:
+                    break
+                fetch_list = list(to_fetch)
+                to_fetch = set()
+                for i in range(0, len(fetch_list), IN_CHUNK):
+                    chunk = fetch_list[i:i + IN_CHUNK]
+                    placeholders = ','.join('?' * len(chunk))
+                    cur.execute(
+                        f"""
+                        SELECT id, source, title, started_at, parent_session_id, ended_at, end_reason
+                        FROM sessions
+                        WHERE id IN ({placeholders})
+                        """,
+                        chunk,
+                    )
+                    for row in cur.fetchall():
+                        rows[row['id']] = dict(row)
+                # Queue up parents we haven't fetched yet.
+                for sid in fetch_list:
+                    parent_id = rows.get(sid, {}).get('parent_session_id')
+                    if parent_id and parent_id not in rows and parent_id not in to_fetch:
+                        to_fetch.add(parent_id)
+    except Exception:
+        return {}
+
+    metadata: dict[str, dict] = {}
+    for sid in wanted:
+        row = rows.get(sid)
+        if not row:
+            continue
+
+        parent_id = row.get('parent_session_id')
+        parent_row = rows.get(parent_id) if parent_id else None
+        if parent_id and parent_row:
+            entry = metadata.setdefault(sid, {})
+            entry['parent_session_id'] = parent_id
+            if not _is_continuation_session(parent_row, row):
+                entry['relationship_type'] = 'child_session'
+                entry['parent_title'] = parent_row.get('title')
+                entry['parent_source'] = parent_row.get('source')
+                parent_root = _continuation_root_id(rows, parent_id)
+                if parent_root:
+                    entry['_parent_lineage_root_id'] = parent_root
+                continue
+
+        root_id = sid
+        current_id = sid
+        segment_count = 1
+        seen = {sid}
+        while True:
+            current = rows.get(current_id)
+            parent_id = current.get('parent_session_id') if current else None
+            parent = rows.get(parent_id) if parent_id else None
+            if not parent or parent_id in seen:
+                break
+            if not _is_continuation_session(parent, current):
+                break
+            root_id = parent_id
+            current_id = parent_id
+            seen.add(parent_id)
+            segment_count += 1
+
+        if root_id != sid:
+            entry = metadata.setdefault(sid, {})
+            entry['_lineage_root_id'] = root_id
+            entry['_compression_segment_count'] = segment_count
+
+    return metadata

api/auth.py

@@ -6,35 +6,108 @@ or configuring a password in the Settings panel.
 import hashlib
 import hmac
 import http.cookies
+import json
+import logging
 import os
 import secrets
+import tempfile
 import time
 
 from api.config import STATE_DIR, load_settings
 
+logger = logging.getLogger(__name__)
+
 # ── Public paths (no auth required) ─────────────────────────────────────────
 PUBLIC_PATHS = frozenset({
     '/login', '/health', '/favicon.ico',
     '/api/auth/login', '/api/auth/status',
+    '/manifest.json', '/manifest.webmanifest',
+    '/sw.js',
 })
 
 COOKIE_NAME = 'hermes_session'
-SESSION_TTL = 86400  # 24 hours
+SESSION_TTL = 86400 * 30  # 30 days
 
-# Active sessions: token -> expiry timestamp
-_sessions = {}
+_SESSIONS_FILE = STATE_DIR / '.sessions.json'
+
+
+def _load_sessions() -> dict[str, float]:
+    """Load persisted sessions from STATE_DIR, pruning expired entries.
+
+    Returns an empty dict on any read or parse error so startup is never
+    blocked by a corrupt or missing sessions file.
+    """
+    try:
+        if _SESSIONS_FILE.exists():
+            data = json.loads(_SESSIONS_FILE.read_text(encoding='utf-8'))
+            if not isinstance(data, dict):
+                raise ValueError('malformed sessions file — expected dict')
+            now = time.time()
+            return {t: exp for t, exp in data.items()
+                    if isinstance(t, str) and isinstance(exp, (int, float)) and exp > now}
+    except Exception as e:
+        logger.debug("Failed to load sessions file, starting fresh: %s", e)
+    return {}
+
+
+def _save_sessions(sessions: dict[str, float]) -> None:
+    """Atomically persist sessions to STATE_DIR/.sessions.json (0600).
+
+    Uses a temp file + os.replace() so a crash mid-write never leaves a
+    truncated file.  Mirrors the same pattern as .signing_key persistence.
+    """
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=STATE_DIR, suffix='.sessions.tmp')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(sessions, f)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, _SESSIONS_FILE)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception as e:
+        logger.debug("Failed to persist sessions: %s", e)
+
+
+# Active sessions: token -> expiry timestamp (persisted across restarts via STATE_DIR)
+_sessions = _load_sessions()
+
+# ── Login rate limiter ──────────────────────────────────────────────────────
+_login_attempts = {}  # ip -> [timestamp, ...]
+_LOGIN_MAX_ATTEMPTS = 5
+_LOGIN_WINDOW = 60  # seconds
+
+def _check_login_rate(ip: str) -> bool:
+    """Return True if the IP is allowed to attempt login."""
+    now = time.time()
+    attempts = _login_attempts.get(ip, [])
+    # Prune old attempts
+    attempts = [t for t in attempts if now - t < _LOGIN_WINDOW]
+    _login_attempts[ip] = attempts
+    return len(attempts) < _LOGIN_MAX_ATTEMPTS
+
+def _record_login_attempt(ip: str) -> None:
+    now = time.time()
+    attempts = _login_attempts.get(ip, [])
+    attempts.append(now)
+    _login_attempts[ip] = attempts
 
 
 def _signing_key():
     """Return a random signing key, generating and persisting one on first call."""
     key_file = STATE_DIR / '.signing_key'
-    if key_file.exists():
-        try:
+    try:
+        if key_file.exists():
             raw = key_file.read_bytes()
             if len(raw) >= 32:
                 return raw[:32]
-        except Exception:
-            pass
+    except Exception:
+        logger.debug("Failed to read or access signing key file, using in-memory key")
     # Generate a new random key
     key = secrets.token_bytes(32)
     try:
@@ -42,7 +115,7 @@ def _signing_key():
         key_file.write_bytes(key)
         key_file.chmod(0o600)
     except Exception:
-        pass  # key works for this process even if persist fails
+        logger.debug("Failed to persist signing key, using in-memory key only")
     return key
 
 
@@ -57,7 +130,7 @@ def _hash_password(password):
     return dk.hex()
 
 
-def get_password_hash():
+def get_password_hash() -> str | None:
     """Return the active password hash, or None if auth is disabled.
     Priority: env var > settings.json."""
     env_pw = os.getenv('HERMES_WEBUI_PASSWORD', '').strip()
@@ -67,12 +140,12 @@ def get_password_hash():
     return settings.get('password_hash') or None
 
 
-def is_auth_enabled():
+def is_auth_enabled() -> bool:
     """True if a password is configured (env var or settings)."""
     return get_password_hash() is not None
 
 
-def verify_password(plain):
+def verify_password(plain) -> bool:
     """Verify a plaintext password against the stored hash."""
     expected = get_password_hash()
     if not expected:
@@ -80,20 +153,32 @@ def verify_password(plain):
     return hmac.compare_digest(_hash_password(plain), expected)
 
 
-def create_session():
+def create_session() -> str:
     """Create a new auth session. Returns signed cookie value."""
     token = secrets.token_hex(32)
     _sessions[token] = time.time() + SESSION_TTL
-    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:16]
+    _save_sessions(_sessions)
+    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
     return f"{token}.{sig}"
 
 
-def verify_session(cookie_value):
+def _prune_expired_sessions():
+    """Remove all expired session entries to prevent unbounded memory growth."""
+    now = time.time()
+    expired = [t for t, exp in _sessions.items() if now > exp]
+    if expired:
+        for token in expired:
+            _sessions.pop(token, None)
+        _save_sessions(_sessions)
+
+
+def verify_session(cookie_value) -> bool:
     """Verify a signed session cookie. Returns True if valid and not expired."""
     if not cookie_value or '.' not in cookie_value:
         return False
+    _prune_expired_sessions()  # lazy cleanup on every verification attempt
     token, sig = cookie_value.rsplit('.', 1)
-    expected_sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:16]
+    expected_sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
     if not hmac.compare_digest(sig, expected_sig):
         return False
     expiry = _sessions.get(token)
@@ -103,14 +188,16 @@ def verify_session(cookie_value):
     return True
 
 
-def invalidate_session(cookie_value):
+def invalidate_session(cookie_value) -> None:
     """Remove a session token."""
     if cookie_value and '.' in cookie_value:
         token = cookie_value.rsplit('.', 1)[0]
-        _sessions.pop(token, None)
+        if token in _sessions:
+            _sessions.pop(token, None)
+            _save_sessions(_sessions)
 
 
-def parse_cookie(handler):
+def parse_cookie(handler) -> str | None:
     """Extract the auth cookie from the request headers."""
     cookie_header = handler.headers.get('Cookie', '')
     if not cookie_header:
@@ -124,13 +211,13 @@ def parse_cookie(handler):
     return morsel.value if morsel else None
 
 
-def check_auth(handler, parsed):
+def check_auth(handler, parsed) -> bool:
     """Check if request is authorized. Returns True if OK.
     If not authorized, sends 401 (API) or 302 redirect (page) and returns False."""
     if not is_auth_enabled():
         return True
     # Public paths don't require auth
-    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/'):
+    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/') or parsed.path.startswith('/session/static/'):
         return True
     # Check session cookie
     cookie_val = parse_cookie(handler)
@@ -144,12 +231,38 @@ def check_auth(handler, parsed):
         handler.wfile.write(b'{"error":"Authentication required"}')
     else:
         handler.send_response(302)
-        handler.send_header('Location', '/login')
+        # Pass the original path as ?next= so login.js redirects back after auth.
+        # SECURITY/CORRECTNESS: the inner `?` and `&` MUST be percent-encoded
+        # when stuffed into the outer `?next=` parameter, otherwise:
+        #   (a) multi-param query strings get truncated at the first inner `&`
+        #       (e.g. `/api/sessions?limit=50&offset=0` would round-trip as
+        #       just `/api/sessions?limit=50` after the browser parses the
+        #       outer URL — `offset=0` becomes a separate top-level query
+        #       parameter that the login page ignores).
+        #   (b) attacker-controlled paths could inject a second `next=`
+        #       parameter; per RFC 3986 the duplicate behaviour is undefined
+        #       and parsers diverge (Python's parse_qs returns last-match,
+        #       URLSearchParams returns first-match), opening a query-pollution
+        #       footgun even though _safeNextPath() rejects most malicious
+        #       shapes downstream.
+        # Encoding the entire `path?query` blob with quote(safe='/') turns
+        # `?` → `%3F` and `&` → `%26`, so the outer parameter holds exactly
+        # one path-with-query string and `searchParams.get('next')` returns
+        # the full original URL (the browser auto-decodes once).
+        # (Opus pre-release advisor finding for v0.50.258.)
+        import urllib.parse as _urlparse
+        _path_with_query = parsed.path or '/'
+        if parsed.query:
+            _path_with_query += '?' + parsed.query
+        # safe='/' keeps path separators readable; everything else (including
+        # `?`, `&`, `=`) gets percent-encoded.
+        _next = _urlparse.quote(_path_with_query, safe='/')
+        handler.send_header('Location', '/login?next=' + _next)
         handler.end_headers()
     return False
 
 
-def set_auth_cookie(handler, cookie_value):
+def set_auth_cookie(handler, cookie_value) -> None:
     """Set the auth cookie on the response."""
     cookie = http.cookies.SimpleCookie()
     cookie[COOKIE_NAME] = cookie_value
@@ -157,10 +270,13 @@ def set_auth_cookie(handler, cookie_value):
     cookie[COOKIE_NAME]['samesite'] = 'Lax'
     cookie[COOKIE_NAME]['path'] = '/'
     cookie[COOKIE_NAME]['max-age'] = str(SESSION_TTL)
+    # Set Secure flag when connection is HTTPS
+    if getattr(handler.request, 'getpeercert', None) is not None or handler.headers.get('X-Forwarded-Proto', '') == 'https':
+        cookie[COOKIE_NAME]['secure'] = True
     handler.send_header('Set-Cookie', cookie[COOKIE_NAME].OutputString())
 
 
-def clear_auth_cookie(handler):
+def clear_auth_cookie(handler) -> None:
     """Clear the auth cookie on the response."""
     cookie = http.cookies.SimpleCookie()
     cookie[COOKIE_NAME] = ''

api/background.py

@@ -0,0 +1,87 @@
+"""Background and ephemeral task tracking for /background and /btw commands."""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+
+# parent_session_id -> list of task dicts
+_BACKGROUND_TASKS: dict[str, list[dict[str, Any]]] = {}
+
+# btw ephemeral session tracking: parent_sid -> {ephemeral_sid, stream_id, question}
+_BTW_TRACKING: dict[str, dict[str, Any]] = {}
+
+
+def track_background(parent_sid: str, bg_sid: str, stream_id: str,
+                     task_id: str, prompt: str) -> None:
+    with _lock:
+        _BACKGROUND_TASKS.setdefault(parent_sid, []).append({
+            "task_id": task_id,
+            "bg_session_id": bg_sid,
+            "stream_id": stream_id,
+            "prompt": prompt,
+            "status": "running",
+            "started_at": time.time(),
+            "answer": None,
+            "completed_at": None,
+        })
+
+
+def track_btw(parent_sid: str, ephemeral_sid: str, stream_id: str,
+              question: str) -> None:
+    with _lock:
+        _BTW_TRACKING[parent_sid] = {
+            "ephemeral_session_id": ephemeral_sid,
+            "stream_id": stream_id,
+            "question": question,
+        }
+
+
+def complete_background(parent_sid: str, task_id: str, answer: str) -> None:
+    with _lock:
+        for t in _BACKGROUND_TASKS.get(parent_sid, []):
+            if t["task_id"] == task_id and t["status"] == "running":
+                t["status"] = "done"
+                t["answer"] = answer
+                t["completed_at"] = time.time()
+                break
+
+
+def get_results(parent_sid: str) -> list[dict[str, Any]]:
+    """Return completed background task results and remove only the done ones
+    from tracking.  Tasks still in ``status="running"`` MUST stay in the list
+    so that ``complete_background()`` can still find them when the worker
+    thread finishes — otherwise the first poll during a long-running task
+    silently drops it and the result is lost forever.
+    """
+    with _lock:
+        tasks = _BACKGROUND_TASKS.get(parent_sid, [])
+        done = [t for t in tasks if t["status"] == "done"]
+        still_running = [t for t in tasks if t["status"] != "done"]
+        if still_running:
+            _BACKGROUND_TASKS[parent_sid] = still_running
+        else:
+            _BACKGROUND_TASKS.pop(parent_sid, None)
+        return [{
+            "task_id": t["task_id"],
+            "prompt": t["prompt"],
+            "answer": t["answer"],
+            "completed_at": t["completed_at"],
+        } for t in done]
+
+
+def get_background_tasks(parent_sid: str) -> list[dict[str, Any]]:
+    """Return all background tasks (running and done) for a parent session."""
+    with _lock:
+        return list(_BACKGROUND_TASKS.get(parent_sid, []))
+
+
+def cleanup_btw(parent_sid: str) -> dict[str, Any] | None:
+    """Remove and return btw tracking for a parent session."""
+    with _lock:
+        return _BTW_TRACKING.pop(parent_sid, None)

api/clarify.py

@@ -0,0 +1,181 @@
+"""Clarify prompt state for the WebUI.
+
+This mirrors the approval flow structure, but the response is a free-form
+clarification string instead of an approval decision.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from typing import Optional
+
+
+DEFAULT_TIMEOUT_SECONDS = 120
+_lock = threading.Lock()
+_pending: dict[str, dict] = {}
+_gateway_queues: dict[str, list] = {}
+_gateway_notify_cbs: dict[str, object] = {}
+
+# ── SSE subscriber registry ─────────────────────────────────────────────
+_clarify_sse_subscribers: dict[str, list[queue.Queue]] = {}
+
+
+class _ClarifyEntry:
+    """One pending clarify request inside a session."""
+
+    __slots__ = ("event", "data", "result")
+
+    def __init__(self, data: dict):
+        self.event = threading.Event()
+        self.data = data
+        self.result: Optional[str] = None
+
+
+def register_gateway_notify(session_key: str, cb) -> None:
+    """Register a per-session callback for sending clarify requests to the UI."""
+    with _lock:
+        _gateway_notify_cbs[session_key] = cb
+
+
+def _clear_queue_locked(session_key: str) -> list[_ClarifyEntry]:
+    entries = _gateway_queues.pop(session_key, [])
+    _pending.pop(session_key, None)
+    return entries
+
+
+def unregister_gateway_notify(session_key: str) -> None:
+    """Unregister the per-session callback and unblock any waiting clarify prompt."""
+    with _lock:
+        _gateway_notify_cbs.pop(session_key, None)
+        entries = _clear_queue_locked(session_key)
+    for entry in entries:
+        entry.event.set()
+
+
+def clear_pending(session_key: str) -> int:
+    """Clear any pending clarify prompts for the session without removing the callback."""
+    with _lock:
+        entries = _clear_queue_locked(session_key)
+    for entry in entries:
+        entry.event.set()
+    return len(entries)
+
+
+def _with_timeout_metadata(data: dict) -> dict:
+    item = dict(data or {})
+    requested_at = float(item.get("requested_at") or time.time())
+    timeout_seconds = int(item.get("timeout_seconds") or DEFAULT_TIMEOUT_SECONDS)
+    expires_at = float(item.get("expires_at") or requested_at + timeout_seconds)
+    item["requested_at"] = requested_at
+    item["timeout_seconds"] = timeout_seconds
+    item["expires_at"] = expires_at
+    return item
+
+
+def _clarify_sse_notify(session_id: str, head: dict | None, total: int) -> None:
+    """Push a clarify event to all SSE subscribers for a session."""
+    payload = {"pending": dict(head) if head else None, "pending_count": total}
+    for q in _clarify_sse_subscribers.get(session_id, ()):
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            pass  # drop if subscriber is slow
+
+
+def sse_subscribe(session_id: str) -> queue.Queue:
+    """Register a bounded Queue for SSE push to a given session."""
+    q: queue.Queue = queue.Queue(maxsize=16)
+    with _lock:
+        _clarify_sse_subscribers.setdefault(session_id, []).append(q)
+    return q
+
+
+def sse_unsubscribe(session_id: str, q: queue.Queue) -> None:
+    """Remove a subscriber Queue; clean up empty session entries."""
+    with _lock:
+        subs = _clarify_sse_subscribers.get(session_id)
+        if subs:
+            try:
+                subs.remove(q)
+            except ValueError:
+                pass
+            if not subs:
+                _clarify_sse_subscribers.pop(session_id, None)
+
+
+def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
+    """Queue a pending clarify request and notify the UI callback if registered."""
+    data = _with_timeout_metadata(data)
+    with _lock:
+        gw_queue = _gateway_queues.setdefault(session_key, [])
+        # De-duplicate while unresolved: if the most recent pending clarify is
+        # semantically identical, reuse it instead of stacking duplicates.
+        if gw_queue:
+            last = gw_queue[-1]
+            if (
+                str(last.data.get("question", "")) == str(data.get("question", ""))
+                and list(last.data.get("choices_offered") or [])
+                == list(data.get("choices_offered") or [])
+            ):
+                entry = last
+                cb = _gateway_notify_cbs.get(session_key)
+                # Keep _pending aligned to the oldest unresolved entry.
+                _pending[session_key] = gw_queue[0].data
+                if cb:
+                    try:
+                        cb(dict(entry.data))
+                    except Exception:
+                        pass
+                return entry
+
+        entry = _ClarifyEntry(data)
+        gw_queue.append(entry)
+        _pending[session_key] = gw_queue[0].data
+        cb = _gateway_notify_cbs.get(session_key)
+        # Notify SSE subscribers from inside _lock for ordering guarantees.
+        _clarify_sse_notify(session_key, dict(gw_queue[0].data), len(gw_queue))
+    if cb:
+        try:
+            cb(data)
+        except Exception:
+            pass
+    return entry
+
+
+def get_pending(session_key: str) -> dict | None:
+    """Return the oldest pending clarify request for this session, if any."""
+    with _lock:
+        queue = _gateway_queues.get(session_key) or []
+        if queue:
+            return dict(queue[0].data)
+        pending = _pending.get(session_key)
+        return dict(pending) if pending else None
+
+
+def has_pending(session_key: str) -> bool:
+    with _lock:
+        return bool(_gateway_queues.get(session_key))
+
+
+def resolve_clarify(session_key: str, response: str, resolve_all: bool = False) -> int:
+    """Resolve the oldest pending clarify request for a session."""
+    with _lock:
+        q = _gateway_queues.get(session_key)
+        if not q:
+            _pending.pop(session_key, None)
+            return 0
+        entries = list(q) if resolve_all else [q.pop(0)]
+        if q:
+            _pending[session_key] = q[0].data
+            _clarify_sse_notify(session_key, dict(q[0].data), len(q))
+        else:
+            _clear_queue_locked(session_key)
+            _clarify_sse_notify(session_key, None, 0)
+    count = 0
+    for entry in entries:
+        entry.result = response
+        entry.event.set()
+        count += 1
+    return count

api/commands.py

@@ -0,0 +1,56 @@
+"""Expose hermes-agent's COMMAND_REGISTRY to the webui frontend.
+
+This module is the single integration point with hermes_cli.commands.
+If hermes-agent is unavailable the endpoint degrades to an empty list
+so the frontend can still load with WEBUI_ONLY commands.
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Commands that are gateway_only in the agent registry -- webui never
+# wants to expose them (sethome, restart, update etc.) even if a future
+# agent version drops the gateway_only flag. /commands is the agent's
+# own command-listing command; webui has its own /help that calls
+# cmdHelp() locally, so /commands would be redundant and confusing.
+_NEVER_EXPOSE: frozenset[str] = frozenset({
+    'sethome', 'restart', 'update', 'commands',
+})
+
+
+def list_commands(_registry=None) -> list[dict[str, Any]]:
+    """Return COMMAND_REGISTRY entries as JSON-friendly dicts.
+
+    Returns empty list if hermes_cli is not installed (graceful
+    degradation -- the frontend has its own fallback minimum set).
+
+    Args:
+        _registry: Optional injected registry for testing. When None
+            (production), imports COMMAND_REGISTRY from hermes_cli.
+    """
+    if _registry is None:
+        try:
+            from hermes_cli.commands import COMMAND_REGISTRY as _registry
+        except ImportError:
+            logger.warning("hermes_cli.commands not importable -- /api/commands returns []")
+            return []
+
+    out: list[dict[str, Any]] = []
+    for cmd in _registry:
+        if cmd.gateway_only:
+            continue
+        if cmd.name in _NEVER_EXPOSE:
+            continue
+        out.append({
+            'name': cmd.name,
+            'description': cmd.description,
+            'category': cmd.category,
+            'aliases': list(cmd.aliases),
+            'args_hint': cmd.args_hint,
+            'subcommands': list(cmd.subcommands),
+            'cli_only': bool(cmd.cli_only),
+            'gateway_only': bool(cmd.gateway_only),
+        })
+    return out

api/extensions.py

@@ -0,0 +1,246 @@
+"""Opt-in WebUI extension hooks.
+
+This module intentionally provides a small, self-hosted extension surface:
+configured same-origin script/style injection plus sandboxed static file serving.
+It is disabled by default and never executes or fetches third-party URLs.
+"""
+
+import html
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+from urllib.parse import unquote, urlsplit
+
+from api.helpers import _security_headers, j
+
+_log = logging.getLogger(__name__)
+
+# Sane bound on configured URLs — real extensions ship 1-3 files. Higher values
+# typically indicate a misconfiguration (one giant unsplit string, or a runaway
+# generator script that wrote an env-var template without filtering). Capping
+# avoids rendering tens of thousands of <script> tags into every page load.
+_MAX_URL_LIST = 32
+
+# Tracks rejected URL strings we've already warned about so a misconfigured env
+# var doesn't spam the log on every request that re-reads it.
+_warned_urls: set = set()
+
+EXTENSION_ROUTE_PREFIX = "/extensions/"
+_EXTENSION_DIR_ENV = "HERMES_WEBUI_EXTENSION_DIR"
+_EXTENSION_SCRIPT_URLS_ENV = "HERMES_WEBUI_EXTENSION_SCRIPT_URLS"
+_EXTENSION_STYLESHEET_URLS_ENV = "HERMES_WEBUI_EXTENSION_STYLESHEET_URLS"
+_ALLOWED_ASSET_PREFIXES = ("/extensions/", "/static/")
+
+_EXTENSION_MIME = {
+    "css": "text/css",
+    "js": "application/javascript",
+    "html": "text/html",
+    "svg": "image/svg+xml",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "ico": "image/x-icon",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "woff": "font/woff",
+    "woff2": "font/woff2",
+    "ttf": "font/ttf",
+    "otf": "font/otf",
+    "wasm": "application/wasm",
+}
+_TEXT_MIME_TYPES = {"text/css", "application/javascript", "text/html", "image/svg+xml", "text/plain"}
+
+
+def _extension_root() -> Optional[Path]:
+    """Return the configured extension directory, or None when disabled.
+
+    A missing or non-directory path disables extensions instead of failing open.
+    The startup docs encourage users to point this at a directory they control.
+    """
+    raw = os.getenv(_EXTENSION_DIR_ENV, "").strip()
+    if not raw:
+        return None
+    root = Path(raw).expanduser().resolve()
+    if not root.exists() or not root.is_dir():
+        return None
+    return root
+
+
+def _fully_unquote_path(path: str) -> str:
+    """Decode percent-encoding until stable so encoded dot-segments cannot hide.
+
+    Iterates up to 10 times so even quadruple-encoded inputs like
+    ``%2525252e%2525252e`` collapse to literal ``..`` and are rejected by
+    the segment-level safety check downstream. URL strings stabilize in
+    fewer than 5 iterations in practice; the cap is defensive.
+    """
+    previous = path
+    for _ in range(10):
+        current = unquote(previous)
+        if current == previous:
+            return current
+        previous = current
+    return previous
+
+
+def _is_safe_asset_url(value: str) -> bool:
+    """Allow only same-origin extension/static asset URLs.
+
+    External schemes, protocol-relative URLs, fragments, arbitrary API paths, and
+    encoded traversal are rejected so enabling extensions does not require
+    loosening the CSP.
+    """
+    if not value or any(ch in value for ch in ('\x00', '\r', '\n', '"', "'", "<", ">", "\\")):
+        return False
+    parsed = urlsplit(value)
+    if parsed.scheme or parsed.netloc or parsed.fragment:
+        return False
+
+    decoded_path = _fully_unquote_path(parsed.path)
+    if not any(decoded_path.startswith(prefix) for prefix in _ALLOWED_ASSET_PREFIXES):
+        return False
+
+    for prefix in _ALLOWED_ASSET_PREFIXES:
+        if decoded_path.startswith(prefix):
+            return _is_safe_relative_path(decoded_path[len(prefix) :])
+    return False
+
+
+def _read_url_list(env_name: str) -> List[str]:
+    raw = os.getenv(env_name, "")
+    urls = []
+    for item in raw.split(","):
+        value = item.strip()
+        if not value:
+            continue
+        if _is_safe_asset_url(value):
+            urls.append(value)
+            if len(urls) >= _MAX_URL_LIST:
+                # Stop accumulating after the cap. Anything past this point
+                # would be silently dropped anyway; logging once makes the
+                # truncation visible to a confused operator.
+                if env_name not in _warned_urls:
+                    _warned_urls.add(env_name)
+                    _log.warning(
+                        "Extension URL list %s truncated at %d entries",
+                        env_name, _MAX_URL_LIST,
+                    )
+                break
+        elif value not in _warned_urls:
+            # First-time-seen invalid URL: log once per process so a typo
+            # in HERMES_WEBUI_EXTENSION_*_URLS doesn't disappear silently.
+            _warned_urls.add(value)
+            _log.warning(
+                "Rejected extension URL %r from %s (not a same-origin "
+                "/extensions/ or /static/ path, or contains unsafe chars)",
+                value, env_name,
+            )
+    return urls
+
+
+def get_extension_config() -> Dict[str, object]:
+    """Return public extension config without exposing filesystem paths."""
+    enabled = _extension_root() is not None
+    if not enabled:
+        return {"enabled": False, "script_urls": [], "stylesheet_urls": []}
+    return {
+        "enabled": True,
+        "script_urls": _read_url_list(_EXTENSION_SCRIPT_URLS_ENV),
+        "stylesheet_urls": _read_url_list(_EXTENSION_STYLESHEET_URLS_ENV),
+    }
+
+
+def inject_extension_tags(index_html: str) -> str:
+    """Inject configured extension tags into the app shell.
+
+    Tags are inserted only when the extension directory is enabled. URLs are
+    escaped even though they are already validated, keeping the renderer robust
+    if validation rules evolve later.
+    """
+    config = get_extension_config()
+    if not config["enabled"]:
+        return index_html
+
+    result = index_html
+    stylesheet_tags = [
+        '<link rel="stylesheet" href="{}">'.format(html.escape(url, quote=True))
+        for url in config["stylesheet_urls"]
+    ]
+    script_tags = [
+        '<script src="{}" defer></script>'.format(html.escape(url, quote=True))
+        for url in config["script_urls"]
+    ]
+
+    if stylesheet_tags:
+        head_marker = "</head>"
+        block = "\n".join(stylesheet_tags) + "\n"
+        if head_marker in result:
+            result = result.replace(head_marker, block + head_marker, 1)
+        else:
+            result = block + result
+
+    if script_tags:
+        body_marker = "</body>"
+        block = "\n".join(script_tags) + "\n"
+        if body_marker in result:
+            result = result.replace(body_marker, block + body_marker, 1)
+        else:
+            result = result + "\n" + block
+
+    return result
+
+
+def _is_safe_relative_path(rel: str) -> bool:
+    if not rel or "\x00" in rel or "\\" in rel:
+        return False
+    for segment in rel.split("/"):
+        if not segment or segment in (".", "..") or segment.startswith("."):
+            return False
+    return True
+
+
+def _not_found(handler) -> bool:
+    j(handler, {"error": "not found"}, status=404)
+    return True
+
+
+def serve_extension_static(handler, parsed) -> bool:
+    """Serve a file from the configured extension directory.
+
+    The function always returns True for /extensions/* requests: either a file
+    response or a 404. It never reveals why a request failed, which avoids
+    leaking local paths or extension configuration details.
+    """
+    root = _extension_root()
+    if root is None:
+        return _not_found(handler)
+
+    rel = unquote(parsed.path[len(EXTENSION_ROUTE_PREFIX) :])
+    if not _is_safe_relative_path(rel):
+        return _not_found(handler)
+
+    static_file = (root / rel).resolve()
+    try:
+        static_file.relative_to(root)
+    except ValueError:
+        return _not_found(handler)
+
+    if not static_file.exists() or not static_file.is_file():
+        return _not_found(handler)
+
+    ct = _EXTENSION_MIME.get(static_file.suffix.lower().lstrip("."), "text/plain")
+    ct_header = "{}; charset=utf-8".format(ct) if ct in _TEXT_MIME_TYPES else ct
+    try:
+        raw = static_file.read_bytes()
+    except OSError:
+        return _not_found(handler)
+
+    handler.send_response(200)
+    handler.send_header("Content-Type", ct_header)
+    handler.send_header("Cache-Control", "no-store")
+    handler.send_header("Content-Length", str(len(raw)))
+    _security_headers(handler)
+    handler.end_headers()
+    handler.wfile.write(raw)
+    return True

api/gateway_watcher.py

@@ -0,0 +1,230 @@
+"""
+Hermes Web UI -- Gateway session watcher.
+
+Background daemon thread that polls state.db every 5 seconds for changes
+to gateway sessions (telegram, discord, slack, etc.). When changes are
+detected, it pushes notifications to all subscribed SSE clients.
+
+This enables real-time session list updates in the sidebar without
+requiring any changes to hermes-agent.
+"""
+import hashlib
+import json
+import logging
+import os
+import queue
+import threading
+import time
+from pathlib import Path
+
+from api.config import HOME
+from api.agent_sessions import read_importable_agent_session_rows
+
+logger = logging.getLogger(__name__)
+
+
+# ── State hash tracking ─────────────────────────────────────────────────────
+
+def _snapshot_hash(sessions: list) -> str:
+    """Create a lightweight hash of session IDs and timestamps for change detection."""
+    key = '|'.join(
+        f"{s['session_id']}:{s.get('updated_at', 0)}:{s.get('message_count', 0)}"
+        for s in sorted(sessions, key=lambda x: x['session_id'])
+    )
+    return hashlib.md5(key.encode(), usedforsecurity=False).hexdigest()
+
+
+# ── DB resolution (shared pattern with state_sync.py) ──────────────────────
+
+def _get_state_db_path() -> Path:
+    """Resolve state.db path for the active profile."""
+    try:
+        from api.profiles import get_active_hermes_home
+        hermes_home = Path(get_active_hermes_home()).expanduser().resolve()
+    except Exception:
+        hermes_home = Path(os.getenv('HERMES_HOME', str(HOME / '.hermes'))).expanduser().resolve()
+    return hermes_home / 'state.db'
+
+
+def _get_agent_sessions_from_db() -> list:
+    """Read all non-webui sessions from state.db.
+    Returns list of session dicts, or empty list on any error.
+    """
+    db_path = _get_state_db_path()
+    if not db_path.exists():
+        return []
+
+    try:
+        sessions = []
+        for row in read_importable_agent_session_rows(db_path, limit=200, log=logger):
+            sessions.append({
+                'session_id': row['id'],
+                'title': row['title'] or 'Agent Session',
+                'model': row['model'] or None,
+                'message_count': row['message_count'] or row['actual_message_count'] or 0,
+                'created_at': row['started_at'],
+                'updated_at': row['last_activity'] or row['started_at'],
+                'source': row['source'] or 'cli',
+                'raw_source': row.get('raw_source'),
+                'session_source': row.get('session_source'),
+                'source_label': row.get('source_label'),
+            })
+        return sessions
+    except Exception:
+        return []
+
+
+# ── GatewayWatcher ──────────────────────────────────────────────────────────
+
+class GatewayWatcher:
+    """Background thread that polls state.db for agent session changes.
+
+    Usage:
+        watcher = GatewayWatcher()
+        watcher.start()
+        q = watcher.subscribe()
+        # ... receive change events via q.get() ...
+        watcher.unsubscribe(q)
+        watcher.stop()
+    """
+
+    POLL_INTERVAL = 5  # seconds between polls
+    SUBSCRIBER_TIMEOUT = 30  # seconds before sending keepalive comment
+
+    def __init__(self):
+        self._subscribers: list[queue.Queue] = []
+        self._sub_lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._last_hash: str = ''
+        self._last_sessions: list = []
+
+    def start(self):
+        """Start the watcher daemon thread."""
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._poll_loop, daemon=True, name='gateway-watcher')
+        self._thread.start()
+
+    def is_alive(self) -> bool:
+        """Return True when the poll thread is running.
+
+        Public accessor used by ``/api/sessions/gateway/stream`` probe mode and
+        the live SSE handler to detect a watcher instance whose poll thread
+        died silently (e.g. uncaught exception in ``_poll_loop``).  Callers
+        use this to decide whether to return 503 and trigger the client-side
+        polling fallback, instead of handing out an SSE connection that would
+        never emit events.
+        """
+        t = self._thread
+        return t is not None and t.is_alive()
+
+    def stop(self):
+        """Stop the watcher thread."""
+        self._stop_event.set()
+        # Wake up any subscribers
+        with self._sub_lock:
+            for q in self._subscribers:
+                try:
+                    q.put(None)  # sentinel
+                except Exception:
+                    logger.debug("Failed to send sentinel to subscriber")
+        if self._thread:
+            self._thread.join(timeout=3)
+            self._thread = None
+
+    def subscribe(self) -> queue.Queue:
+        """Subscribe to change events. Returns a queue.Queue.
+        Events are dicts: {'type': 'sessions_changed', 'sessions': [...]}
+        A None sentinel means the watcher is stopping.
+        """
+        q = queue.Queue(maxsize=10)
+        with self._sub_lock:
+            self._subscribers.append(q)
+        return q
+
+    def unsubscribe(self, q: queue.Queue):
+        """Remove a subscriber queue."""
+        with self._sub_lock:
+            try:
+                self._subscribers.remove(q)
+            except ValueError:
+                pass
+
+    def _notify_subscribers(self, sessions: list):
+        """Push change event to all subscribers."""
+        event = {
+            'type': 'sessions_changed',
+            'sessions': sessions,
+        }
+        with self._sub_lock:
+            dead = []
+            for q in self._subscribers:
+                try:
+                    q.put_nowait(event)
+                except queue.Full:
+                    dead.append(q)  # remove slow consumers
+                except Exception:
+                    dead.append(q)
+            for q in dead:
+                try:
+                    self._subscribers.remove(q)
+                except ValueError:
+                    pass
+                # Send a None sentinel so the SSE handler unblocks, closes,
+                # and lets the browser's EventSource auto-reconnect.
+                try:
+                    q.put_nowait(None)
+                except Exception:
+                    logger.debug("Failed to send sentinel to dead subscriber")
+
+    def _poll_loop(self):
+        """Main polling loop. Runs in a daemon thread."""
+        while not self._stop_event.is_set():
+            try:
+                sessions = _get_agent_sessions_from_db()
+                current_hash = _snapshot_hash(sessions)
+
+                if current_hash != self._last_hash:
+                    self._last_hash = current_hash
+                    self._last_sessions = sessions
+                    self._notify_subscribers(sessions)
+            except Exception:
+                logger.debug("Error in gateway watcher poll loop", exc_info=True)
+
+            # Sleep in small increments so we can stop promptly
+            for _ in range(self.POLL_INTERVAL * 10):
+                if self._stop_event.is_set():
+                    return
+                time.sleep(0.1)
+
+
+# ── Module-level singleton ─────────────────────────────────────────────────
+
+_watcher: GatewayWatcher | None = None
+_watcher_lock = threading.Lock()
+
+
+def start_watcher():
+    """Start the global gateway watcher (idempotent)."""
+    global _watcher
+    with _watcher_lock:
+        if _watcher is None:
+            _watcher = GatewayWatcher()
+            _watcher.start()
+
+
+def stop_watcher():
+    """Stop the global gateway watcher."""
+    global _watcher
+    with _watcher_lock:
+        if _watcher is not None:
+            _watcher.stop()
+            _watcher = None
+
+
+def get_watcher() -> GatewayWatcher | None:
+    """Get the global watcher instance (or None if not started)."""
+    with _watcher_lock:
+        return _watcher

api/helpers.py

@@ -2,22 +2,32 @@
 Hermes Web UI -- HTTP helper functions.
 """
 import json as _json
+import re as _re
 from pathlib import Path
 from api.config import IMAGE_EXTS, MD_EXTS
 
 
-def require(body: dict, *fields):
+def require(body: dict, *fields) -> None:
     """Phase D: Validate required fields. Raises ValueError with clean message."""
     missing = [f for f in fields if not body.get(f) and body.get(f) != 0]
     if missing:
         raise ValueError(f"Missing required field(s): {', '.join(missing)}")
 
 
-def bad(handler, msg, status=400):
+def bad(handler, msg, status: int=400):
     """Return a clean JSON error response."""
     return j(handler, {'error': msg}, status=status)
 
 
+def _sanitize_error(e: Exception) -> str:
+    """Strip filesystem paths from exception messages before returning to client."""
+    import re
+    msg = str(e)
+    # Remove absolute paths (Unix and Windows)
+    msg = re.sub(r'(?:(?:/[a-zA-Z0-9_.-]+)+|(?:[A-Z]:\\[^\s]+))', '<path>', msg)
+    return msg
+
+
 def safe_resolve(root: Path, requested: str) -> Path:
     """Resolve a relative path inside root, raising ValueError on traversal."""
     resolved = (root / requested).resolve()
@@ -30,21 +40,59 @@ def _security_headers(handler):
     handler.send_header('X-Content-Type-Options', 'nosniff')
     handler.send_header('X-Frame-Options', 'DENY')
     handler.send_header('Referrer-Policy', 'same-origin')
+    handler.send_header(
+        'Content-Security-Policy',
+        "default-src 'self' https://*.cloudflareaccess.com; "
+        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://static.cloudflareinsights.com; "
+        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; "
+        "img-src 'self' data: https: blob:; font-src 'self' data: https://cdn.jsdelivr.net https://fonts.gstatic.com; connect-src 'self'; "
+        "manifest-src 'self' https://*.cloudflareaccess.com; "
+        "base-uri 'self'; form-action 'self'"
+    )
+    handler.send_header(
+        'Permissions-Policy',
+        'camera=(), microphone=(self), geolocation=(), clipboard-write=(self)'
+    )
 
 
-def j(handler, payload, status=200):
-    """Send a JSON response."""
+def _accepts_gzip(handler) -> bool:
+    """Check if the client accepts gzip encoding."""
+    headers = getattr(handler, 'headers', None)
+    if not headers:
+        return False
+    ae = headers.get('Accept-Encoding', '')
+    return 'gzip' in ae
+
+
+def j(handler, payload, status: int=200, extra_headers: dict=None) -> None:
+    """Send a JSON response.
+
+    *extra_headers*: optional dict of additional headers to include
+    (e.g., {'Set-Cookie': '...'}).  Headers are sent before end_headers().
+    """
     body = _json.dumps(payload, ensure_ascii=False, indent=2).encode('utf-8')
     handler.send_response(status)
     handler.send_header('Content-Type', 'application/json; charset=utf-8')
+
+    # Gzip-compress responses over 1KB when the client accepts it.
+    # Typical JSON API responses compress 70-80%, giving a big speedup
+    # for large payloads (session history, message lists).
+    if _accepts_gzip(handler) and len(body) > 1024:
+        import gzip
+        body = gzip.compress(body, compresslevel=4)
+        handler.send_header('Content-Encoding', 'gzip')
+
     handler.send_header('Content-Length', str(len(body)))
     handler.send_header('Cache-Control', 'no-store')
     _security_headers(handler)
+    if extra_headers:
+        for k, v in extra_headers.items():
+            handler.send_header(k, v)
     handler.end_headers()
     handler.wfile.write(body)
 
 
-def t(handler, payload, status=200, content_type='text/plain; charset=utf-8'):
+def t(handler, payload, status: int=200, content_type: str='text/plain; charset=utf-8') -> None:
     """Send a plain text or HTML response."""
     body = payload if isinstance(payload, bytes) else str(payload).encode('utf-8')
     handler.send_response(status)
@@ -59,7 +107,135 @@ def t(handler, payload, status=200, content_type='text/plain; charset=utf-8'):
 MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
 
 
-def read_body(handler):
+# ── Credential redaction ──────────────────────────────────────────────────────
+
+def _build_redact_fn():
+    """Return a redactor backed by hermes-agent plus local fallback patterns."""
+    # Minimal fallback covering the most common credential prefixes.
+    # Keep this active even when hermes-agent is importable so API responses do
+    # not regress if the agent redactor misses a token shape.
+    _CRED_RE = _re.compile(
+        r"(?<![A-Za-z0-9_-])("
+        r"sk-[A-Za-z0-9_-]{10,}"          # OpenAI / Anthropic / OpenRouter
+        r"|ghp_[A-Za-z0-9]{10,}"          # GitHub PAT (classic)
+        r"|github_pat_[A-Za-z0-9_]{10,}"  # GitHub PAT (fine-grained)
+        r"|gho_[A-Za-z0-9]{10,}"          # GitHub OAuth token
+        r"|ghu_[A-Za-z0-9]{10,}"          # GitHub user-to-server token
+        r"|ghs_[A-Za-z0-9]{10,}"          # GitHub server-to-server token
+        r"|ghr_[A-Za-z0-9]{10,}"          # GitHub refresh token
+        r"|AKIA[A-Z0-9]{16}"              # AWS Access Key ID
+        r"|xox[baprs]-[A-Za-z0-9-]{10,}" # Slack tokens
+        r"|hf_[A-Za-z0-9]{10,}"          # HuggingFace token
+        r"|SG\.[A-Za-z0-9_-]{10,}"       # SendGrid API key
+        r")(?![A-Za-z0-9_-])"
+    )
+    _AUTH_HDR_RE = _re.compile(r"(Authorization:\s*Bearer\s+)(\S+)", _re.IGNORECASE)
+    _ENV_RE = _re.compile(
+        r"([A-Z0-9_]{0,50}(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)[A-Z0-9_]{0,50})"
+        r"\s*=\s*(['\"]?)(\S+)\2"
+    )
+    _PRIVKEY_RE = _re.compile(
+        r"-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----"
+    )
+
+    def _mask(token: str) -> str:
+        return f"{token[:6]}...{token[-4:]}" if len(token) >= 18 else "***"
+
+    def _fallback_redact(text: str) -> str:
+        if not isinstance(text, str) or not text:
+            return text
+        text = _CRED_RE.sub(lambda m: _mask(m.group(1)), text)
+        text = _AUTH_HDR_RE.sub(lambda m: m.group(1) + _mask(m.group(2)), text)
+        text = _ENV_RE.sub(
+            lambda m: f"{m.group(1)}={m.group(2)}{_mask(m.group(3))}{m.group(2)}", text
+        )
+        text = _PRIVKEY_RE.sub("[REDACTED PRIVATE KEY]", text)
+        return text
+
+    try:
+        from agent.redact import redact_sensitive_text
+    except ImportError:
+        return _fallback_redact
+
+    def _combined_redact(text: str) -> str:
+        if not isinstance(text, str) or not text:
+            return text
+        # WebUI API responses are a hard safety boundary — pass force=True so the
+        # agent's broader patterns (Stripe sk_live_, Google AIza…, JWT eyJ…, DB
+        # connection strings, Telegram bot tokens) run regardless of the user's
+        # HERMES_REDACT_SECRETS opt-in. The local fallback then handles the
+        # common short-prefix shapes the agent omits (ghp_, sk-, hf_, AKIA).
+        try:
+            agent_redacted = redact_sensitive_text(text, force=True)
+        except TypeError:
+            # Older hermes-agent builds that predate the force kwarg.
+            agent_redacted = redact_sensitive_text(text)
+        return _fallback_redact(agent_redacted)
+
+    return _combined_redact
+
+
+_redact_fn_cached = _build_redact_fn()
+
+
+def _redact_text(text: str, *, _enabled: bool | None = None) -> str:
+    """Redact sensitive text from API responses. Respects api_redact_enabled setting.
+
+    The ``_enabled`` parameter is an internal optimization for callers that
+    redact many strings in a single response — `redact_session_data()` reads
+    the setting once and threads it through ``_redact_value`` so we avoid
+    re-loading settings.json from disk per string. (Opus pre-release perf fix.)
+    """
+    if not isinstance(text, str) or not text:
+        return text
+    if _enabled is None:
+        from api.config import load_settings
+        _enabled = bool(load_settings().get("api_redact_enabled", True))
+    if not _enabled:
+        return text
+    return _redact_fn_cached(text)
+
+
+def _redact_value(v, *, _enabled: bool | None = None):
+    """Recursively redact credentials from strings, dicts, and lists.
+
+    ``_enabled`` is threaded through so a single response-level redact pass
+    only reads settings.json once. (Opus pre-release perf fix.)
+    """
+    if isinstance(v, str):
+        return _redact_text(v, _enabled=_enabled)
+    if isinstance(v, dict):
+        return {k: _redact_value(val, _enabled=_enabled) for k, val in v.items()}
+    if isinstance(v, list):
+        return [_redact_value(item, _enabled=_enabled) for item in v]
+    return v
+
+
+def redact_session_data(session_dict: dict) -> dict:
+    """Redact credentials from message content and tool_call data before API response.
+
+    Applies to: messages[], tool_calls[], and title.
+    The underlying session file is not modified; redaction is response-layer only.
+
+    Reads the ``api_redact_enabled`` setting ONCE for the entire response and
+    threads it through to avoid hundreds of settings.json reads per session
+    payload (a 50-message session has hundreds of nested strings). When the
+    setting is disabled this is also a fast path: the recursion still walks
+    but every string returns early.
+    """
+    from api.config import load_settings
+    _enabled = bool(load_settings().get("api_redact_enabled", True))
+    result = dict(session_dict)
+    if isinstance(result.get('title'), str):
+        result['title'] = _redact_text(result['title'], _enabled=_enabled)
+    if 'messages' in result:
+        result['messages'] = _redact_value(result['messages'], _enabled=_enabled)
+    if 'tool_calls' in result:
+        result['tool_calls'] = _redact_value(result['tool_calls'], _enabled=_enabled)
+    return result
+
+
+def read_body(handler) -> dict:
     """Read and JSON-parse a POST request body (capped at 20MB)."""
     length = int(handler.headers.get('Content-Length', 0))
     if length > MAX_BODY_BYTES:
@@ -69,3 +245,50 @@ def read_body(handler):
         return _json.loads(raw)
     except Exception:
         return {}
+
+
+# ── Profile cookie helpers (issue #798) ─────────────────────────────────────
+
+PROFILE_COOKIE_NAME = 'hermes_profile'
+
+
+def get_profile_cookie(handler) -> str | None:
+    """Extract the hermes_profile cookie value from the request, or None."""
+    cookie_header = handler.headers.get('Cookie', '')
+    if not cookie_header:
+        return None
+    import http.cookies as _hc
+    cookie = _hc.SimpleCookie()
+    try:
+        cookie.load(cookie_header)
+    except _hc.CookieError:
+        return None
+    morsel = cookie.get(PROFILE_COOKIE_NAME)
+    if morsel and morsel.value:
+        # Validate against profile-name pattern before trusting
+        from api.profiles import _PROFILE_ID_RE
+        val = morsel.value
+        if val == 'default' or _PROFILE_ID_RE.fullmatch(val):
+            return val
+    return None
+
+
+def build_profile_cookie(name: str) -> str:
+    """Build a Set-Cookie header value for the hermes_profile cookie.
+
+    Always persist the selected profile in the cookie, including 'default'.
+    Clearing the cookie causes the backend to fall back to process-global
+    _active_profile, which can unexpectedly switch clients back to another
+    profile.
+
+    Set HttpOnly because the UI reads the active profile from
+    /api/profile/active JSON and does not need to access this cookie via
+    document.cookie.
+    """
+    import http.cookies as _hc
+    cookie = _hc.SimpleCookie()
+    cookie[PROFILE_COOKIE_NAME] = name
+    cookie[PROFILE_COOKIE_NAME]['path'] = '/'
+    cookie[PROFILE_COOKIE_NAME]['httponly'] = True
+    cookie[PROFILE_COOKIE_NAME]['samesite'] = 'Lax'
+    return cookie[PROFILE_COOKIE_NAME].OutputString()

api/metering.py

@@ -0,0 +1,187 @@
+"""
+Hermes Web UI -- Streaming performance metering.
+
+Tracks Tokens Per Second (TPS) across all active WebUI sessions, and the
+HIGH/LOW TPS values observed over the past 60 minutes.  Metering data is
+emitted via SSE events so the header label can update live during a stream.
+
+Architecture
+────────────
+Each streaming session is tracked independently.  TPS per session is:
+
+    session_tps = total_tokens / (last_token_ts - first_token_ts)
+
+The global tps is the average of all currently active sessions' TPS values.
+This correctly represents the system's real-time capacity regardless of how
+many sessions are running or how long each has been streaming.
+
+For HIGH/LOW tracking, every stats snapshot records the current global tps
+(only when > 0 — idle periods are skipped) into a rolling 60-minute history.
+The max/min of that history gives the peak throughput observed over the past hour.
+
+The ticker in streaming.py calls get_interval() — it returns 1.0 when sessions
+are actively receiving tokens so the header updates at 1 Hz, and 10.0 when idle
+so the ticker exits and no idle readings are emitted.
+
+Usage from api/streaming.py
+─────────────────────────────
+  from api.metering import meter
+
+  meter().begin_session(stream_id)                     # stream starts
+  meter().record_token(stream_id, running_output)     # per output token
+  meter().record_reasoning(stream_id, running_reasoning_len)  # per reasoning token
+
+The SSE `metering` event payload:
+  {
+    "tps": 47.3,    # average TPS across active sessions (real-time)
+    "high": 52.1,   # highest average TPS observed in the past 60 minutes
+    "low":  31.4,   # lowest average TPS (excl. readings < 1 tps, to ignore idle)
+    "active": 1,    # sessions currently streaming
+  }
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+
+_HOUR_SECS = 3600.0   # rolling window for HIGH/LOW tracking
+_STALE_SECS = 60.0    # consider a session inactive after this
+
+
+@dataclass
+class _SessionMeter:
+    output_tokens: int = 0
+    reasoning_tokens: int = 0
+    first_token_ts: float = 0.0   # time.monotonic() of first token received
+    last_token_ts: float = 0.0    # time.monotonic() of last token received
+
+    def total_tokens(self) -> int:
+        return self.output_tokens + self.reasoning_tokens
+
+    def tps(self) -> float:
+        if self.first_token_ts == 0.0 or self.last_token_ts <= self.first_token_ts:
+            return 0.0
+        return self.total_tokens() / (self.last_token_ts - self.first_token_ts)
+
+
+class GlobalMeter:
+    """Thread-safe global streaming meter.
+
+    Tracks per-session TPS, averages them for a global tps, and maintains a
+    60-minute rolling history of global tps snapshots for HIGH/LOW reporting.
+    """
+
+    __slots__ = (
+        '_lock',
+        '_sessions',        # stream_id -> _SessionMeter
+        '_readings',        # [(monotonic_ts, tps), ...] rolling 60-minute history
+        '_window_start',    # monotonic ts of current window
+    )
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._sessions: dict[str, _SessionMeter] = {}
+        self._readings: list[tuple[float, float]] = []
+        self._window_start: float = time.monotonic()
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def begin_session(self, stream_id: str) -> None:
+        with self._lock:
+            self._sessions[stream_id] = _SessionMeter()
+
+    def get_interval(self) -> float:
+        """Return 1.0 when sessions are actively receiving tokens, 10.0 when idle.
+
+        Used by the streaming ticker to run at 1 Hz during work and exit when
+        there is nothing to measure.
+        """
+        now = time.monotonic()
+        with self._lock:
+            # Only count sessions that have received at least one token recently.
+            active_sids = {
+                sid for sid, s in self._sessions.items()
+                if s.first_token_ts > 0 and (now - s.last_token_ts) <= _STALE_SECS
+            }
+            return 1.0 if active_sids else 10.0
+
+    def record_token(self, stream_id: str, running_output_tokens: int) -> None:
+        now = time.monotonic()
+        with self._lock:
+            s = self._sessions.get(stream_id)
+            if s is None:
+                return
+            if s.first_token_ts == 0.0:
+                s.first_token_ts = now
+            s.last_token_ts = now
+            s.output_tokens = running_output_tokens
+
+    def record_reasoning(self, stream_id: str, running_reasoning_tokens: int) -> None:
+        now = time.monotonic()
+        with self._lock:
+            s = self._sessions.get(stream_id)
+            if s is None:
+                return
+            if s.first_token_ts == 0.0:
+                s.first_token_ts = now
+            s.last_token_ts = now
+            s.reasoning_tokens = running_reasoning_tokens
+
+    def end_session(self, stream_id: str, final_output_tokens: int, input_tokens: int = 0) -> None:
+        with self._lock:
+            self._sessions.pop(stream_id, None)
+
+    def get_stats(self) -> dict:
+        now = time.monotonic()
+        with self._lock:
+            # Prune stale sessions
+            stale = [
+                sid for sid, s in self._sessions.items()
+                if s.first_token_ts > 0 and (now - s.last_token_ts) > _STALE_SECS
+            ]
+            for sid in stale:
+                self._sessions.pop(sid, None)
+
+            # Reset window if everything went stale
+            if not self._sessions:
+                self._window_start = now
+
+            # Compute global tps: average of per-session TPS values
+            active = [s for s in self._sessions.values() if s.first_token_ts > 0]
+            if active:
+                global_tps = sum(s.tps() for s in active) / len(active)
+            else:
+                global_tps = 0.0
+
+            # Prune readings older than 1 hour
+            cutoff = now - _HOUR_SECS
+            self._readings = [(ts, v) for ts, v in self._readings if ts > cutoff]
+
+            # Only record this snapshot for HIGH/LOW if there is active work.
+            # This prevents idle periods from flooding the history and keeps
+            # HIGH/LOW meaningful for the past hour of actual throughput.
+            if global_tps > 0:
+                self._readings.append((now, global_tps))
+
+            # HIGH/LOW from the past hour (skip near-zero idle readings)
+            active_readings = [v for _, v in self._readings if v >= 1.0]
+            high = max(active_readings) if active_readings else 0.0
+            low = min(active_readings) if active_readings else 0.0
+
+            return {
+                'tps': round(global_tps, 1),
+                'high': round(high, 1),
+                'low': round(low, 1),
+                'active': len(self._sessions),
+            }
+
+
+# ── Module-level singleton ─────────────────────────────────────────────────────
+
+_meter = GlobalMeter()
+
+
+def meter() -> GlobalMeter:
+    return _meter

api/oauth.py

@@ -0,0 +1,187 @@
+"""In-app OAuth flow implementations for providers like OpenAI Codex.
+
+Uses only stdlib (urllib.request, json, time) — no external dependencies.
+Credentials are stored in ~/.hermes/auth.json under the credential_pool.
+"""
+
+import json
+import logging
+import time
+import uuid
+import urllib.request
+import urllib.parse
+import urllib.error
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+AUTH_JSON_PATH = Path.home() / ".hermes" / "auth.json"
+
+# ── Codex OAuth constants (from hermes_cli/auth.py) ──
+CODEX_CLIENT_ID = "pdlLIX2Y72MIl2rhLhTE9VV9bN905kBh"
+CODEX_AUTH_URL = "https://auth.openai.com/oauth/device/authorize"
+CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token"
+CODEX_SCOPE = "openid profile email offline_access"
+CODEX_GRANT_TYPE_DEVICE = "urn:ietf:params:oauth:grant-type:device_code"
+
+
+# ── auth.json helpers ──
+
+def _read_auth_json():
+    """Read auth.json and return parsed dict, or empty dict."""
+    if AUTH_JSON_PATH.exists():
+        try:
+            return json.loads(AUTH_JSON_PATH.read_text())
+        except json.JSONDecodeError as exc:
+            logger.warning("Failed to parse %s: %s", AUTH_JSON_PATH, exc)
+            return {}
+    return {}
+
+
+def _write_auth_json(data):
+    """Atomically write auth.json via temp-file rename.
+
+    SECURITY: auth.json contains OAuth access/refresh tokens. ``tmp.replace()``
+    preserves the temp file's mode (created with the process umask, typically
+    0644 or 0664), NOT the prior auth.json mode. Without an explicit chmod,
+    tokens land world-readable on shared systems. Set 0600 BEFORE the rename
+    so there is no window where the final file is world-readable.
+    (Opus pre-release advisor finding.)
+    """
+    import os, stat
+    AUTH_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
+    tmp = AUTH_JSON_PATH.with_suffix('.tmp')
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False))
+    try:
+        tmp.chmod(0o600)
+    except OSError as e:
+        # Best-effort: if chmod fails (e.g. on a filesystem that doesn't
+        # support POSIX modes), don't abort. The startup permission fixer
+        # in api.startup will sweep auth.json on the next process start.
+        logger.warning("Failed to chmod 0600 on %s: %s", tmp, e)
+    tmp.replace(AUTH_JSON_PATH)
+
+
+# ── Codex device-code flow ──
+
+def start_codex_device_code():
+    """Start Codex OAuth device-code flow.
+
+    Returns dict: { device_code, user_code, verification_uri, expires_in, interval }
+    Raises RuntimeError on network error.
+    """
+    params = {
+        "client_id": CODEX_CLIENT_ID,
+        "scope": CODEX_SCOPE,
+    }
+    data = urllib.parse.urlencode(params).encode()
+    req = urllib.request.Request(CODEX_AUTH_URL, data=data, method="POST")
+    req.add_header("Content-Type", "application/x-www-form-urlencoded")
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return json.loads(resp.read().decode())
+    except Exception as e:
+        raise RuntimeError(f"Failed to start Codex OAuth: {e}") from e
+
+
+def poll_codex_token(device_code, interval=5):
+    """Poll for Codex OAuth token. Generator that yields status dicts.
+
+    Yields:
+      {"status": "polling", "attempt": N, "max_attempts": 40}
+      {"status": "success", "credentials": {...}}
+      {"status": "error", "error": "..."}
+    """
+    params = {
+        "grant_type": CODEX_GRANT_TYPE_DEVICE,
+        "device_code": device_code,
+        "client_id": CODEX_CLIENT_ID,
+    }
+    data = urllib.parse.urlencode(params).encode()
+    max_attempts = 40  # 40 * 5 = 200s max
+
+    for attempt in range(max_attempts):
+        yield {"status": "polling", "attempt": attempt + 1, "max_attempts": max_attempts}
+
+        req = urllib.request.Request(CODEX_TOKEN_URL, data=data, method="POST")
+        req.add_header("Content-Type", "application/x-www-form-urlencoded")
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                token_data = json.loads(resp.read().decode())
+                # Save to auth.json credential_pool
+                _save_codex_credentials(token_data)
+                yield {"status": "success", "credentials": {
+                    "access_token": "***",
+                    "refresh_token": "***",
+                    "token_type": token_data.get("token_type"),
+                    "expires_in": token_data.get("expires_in"),
+                }}
+                return
+        except urllib.error.HTTPError as e:
+            body = e.read().decode()
+            try:
+                err_data = json.loads(body)
+                error = err_data.get("error", "")
+                if error == "authorization_pending":
+                    time.sleep(interval)
+                    continue
+                elif error == "slow_down":
+                    time.sleep(interval + 5)
+                    continue
+                elif error == "expired_token":
+                    yield {"status": "error", "error": "Device code expired. Please try again."}
+                    return
+                else:
+                    yield {"status": "error", "error": err_data.get("error_description", error)}
+                    return
+            except Exception:
+                yield {"status": "error", "error": body[:200]}
+                return
+        except Exception as e:
+            yield {"status": "error", "error": str(e)}
+            return
+
+    yield {"status": "error", "error": "OAuth flow timed out. Please try again."}
+
+
+def _save_codex_credentials(token_data):
+    """Save Codex OAuth credentials to auth.json credential_pool."""
+    auth = _read_auth_json()
+    if "credential_pool" not in auth:
+        auth["credential_pool"] = {}
+    pool = auth["credential_pool"]
+
+    if "openai-codex" not in pool:
+        pool["openai-codex"] = []
+
+    # Check if an oauth_device entry already exists (update in place)
+    updated = False
+    _now_iso = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    for entry in pool["openai-codex"]:
+        if entry.get("source") == "oauth_device":
+            entry["access_token"] = token_data.get("access_token", "")
+            entry["refresh_token"] = token_data.get("refresh_token", "")
+            entry["auth_type"] = "oauth"
+            entry["updated_at"] = _now_iso
+            updated = True
+            break
+
+    if not updated:
+        existing_ids = {e["id"] for e in pool.get("openai-codex", [])}
+        for _ in range(3):  # retry on collision
+            cred_id = "codex-oauth-" + uuid.uuid4().hex[:8]
+            if cred_id not in existing_ids:
+                break
+        pool["openai-codex"].append({
+            "id": cred_id,
+            "label": "Codex OAuth",
+            "auth_type": "oauth",
+            "source": "oauth_device",
+            "access_token": token_data.get("access_token", ""),
+            "refresh_token": token_data.get("refresh_token", ""),
+            "priority": 1,
+            "created_at": _now_iso,
+        })
+
+    auth["updated_at"] = _now_iso
+    _write_auth_json(auth)

api/onboarding.py

@@ -0,0 +1,972 @@
+"""Hermes Web UI -- first-run onboarding helpers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import urllib.error
+import urllib.request
+from pathlib import Path
+from urllib.parse import urlparse
+
+from api.auth import is_auth_enabled
+from api.config import (
+    DEFAULT_MODEL,
+    DEFAULT_WORKSPACE,
+    _FALLBACK_MODELS,
+    _HERMES_FOUND,
+    _PROVIDER_DISPLAY,
+    _PROVIDER_MODELS,
+    _get_config_path,
+    get_available_models,
+    get_config,
+    load_settings,
+    reload_config,
+    save_settings,
+    verify_hermes_imports,
+)
+from api.providers import _write_env_file  # shared impl with _ENV_LOCK (#1164)
+from api.workspace import get_last_workspace, load_workspaces
+
+logger = logging.getLogger(__name__)
+
+
+_SUPPORTED_PROVIDER_SETUPS = {
+    # ── Easy start ──────────────────────────────────────────────────────
+    "openrouter": {
+        "label": "OpenRouter",
+        "env_var": "OPENROUTER_API_KEY",
+        "default_model": "anthropic/claude-sonnet-4.6",
+        "requires_base_url": False,
+        "models": [
+            {"id": model["id"], "label": model["label"]} for model in _FALLBACK_MODELS
+        ],
+        "category": "easy_start",
+        "quick": True,
+    },
+    "anthropic": {
+        "label": "Anthropic",
+        "env_var": "ANTHROPIC_API_KEY",
+        "default_model": "claude-sonnet-4.6",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("anthropic", [])),
+        "category": "easy_start",
+    },
+    "openai": {
+        "label": "OpenAI",
+        "env_var": "OPENAI_API_KEY",
+        "default_model": "gpt-4o",
+        "default_base_url": "https://api.openai.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("openai", [])),
+        "category": "easy_start",
+    },
+    # ── Open / self-hosted ─────────────────────────────────────────────
+    "ollama": {
+        "label": "Ollama",
+        "env_var": "OLLAMA_API_KEY",
+        "default_model": "qwen3:32b",
+        "default_base_url": "http://localhost:11434/v1",
+        "requires_base_url": True,
+        # Local Ollama runs keyless by default — only Ollama Cloud requires
+        # OLLAMA_API_KEY.  The wizard accepts an empty api_key for this
+        # provider; users with auth enabled can still type one.  See #1499.
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
+    },
+    "lmstudio": {
+        "label": "LM Studio",
+        # Canonical env var matches the agent CLI runtime (hermes_cli/auth.py:182,
+        # api_key_env_vars=("LM_API_KEY",)).  Onboarding writes this name so the
+        # agent runtime actually picks up the key on the next chat — pre-#1499/#1500
+        # the WebUI wrote LMSTUDIO_API_KEY which the agent runtime ignored, masked
+        # in practice by the LMSTUDIO_NOAUTH_PLACEHOLDER fallback for keyless installs.
+        "env_var": "LM_API_KEY",
+        # Legacy env var written by older WebUI builds (≤ v0.50.272).  Detection
+        # paths (_provider_api_key_present here, _provider_has_key in providers.py)
+        # also read this name so existing users with the old key in their .env
+        # don't flip to "no key" in Settings → Providers after upgrading.
+        # Onboarding only writes the canonical name going forward.
+        "env_var_aliases": ["LMSTUDIO_API_KEY"],
+        "default_model": "gpt-4o-mini",
+        "default_base_url": "http://localhost:1234/v1",
+        "requires_base_url": True,
+        # Most LM Studio installs run keyless (LMSTUDIO_NOAUTH_PLACEHOLDER on the
+        # agent side handles this).  The wizard accepts an empty api_key; auth-
+        # enabled servers still need one but the user types it in the same field.
+        # See #1499 (third sub-bug from #1420).
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
+    },
+    "custom": {
+        "label": "Custom OpenAI-compatible",
+        "env_var": "OPENAI_API_KEY",
+        "default_model": "gpt-4o-mini",
+        "requires_base_url": True,
+        # Many self-hosted OpenAI-compatible servers (vLLM, llama-server,
+        # TabbyAPI, etc.) run keyless behind a private network.  The wizard
+        # accepts an empty api_key — auth-protected endpoints can still
+        # supply one.  See #1499.
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
+    },
+    # ── Specialized / extended ──────────────────────────────────────────
+    "gemini": {
+        "label": "Google Gemini",
+        "env_var": "GOOGLE_API_KEY",
+        "default_model": "gemini-3.1-pro-preview",
+        "default_base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "requires_base_url": False,
+        # _PROVIDER_MODELS in api/config.py is keyed under "google" even though
+        # the agent's alias map normalizes "google" → "gemini".  Use the catalog
+        # key here so the wizard surfaces the actual model list.
+        "models": list(_PROVIDER_MODELS.get("google", [])),
+        "category": "specialized",
+    },
+    "deepseek": {
+        "label": "DeepSeek",
+        "env_var": "DEEPSEEK_API_KEY",
+        "default_model": "deepseek-v4-flash",
+        "default_base_url": "https://api.deepseek.com",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("deepseek", [])),
+        "category": "specialized",
+    },
+    "zai": {
+        "label": "Z.AI / GLM (智谱)",
+        "env_var": "GLM_API_KEY",
+        "default_model": "glm-5.1",
+        "default_base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("zai", [])),
+        "category": "specialized",
+    },
+    "nvidia": {
+        "label": "NVIDIA NIM",
+        "env_var": "NVIDIA_API_KEY",
+        "default_model": "nvidia/llama-3.3-nemotron-super-49b-v1.5",
+        "default_base_url": "https://integrate.api.nvidia.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("nvidia", [])),
+        "category": "specialized",
+    },
+    "mistralai": {
+        "label": "Mistral",
+        "env_var": "MISTRAL_API_KEY",
+        "default_model": "mistral-large-latest",
+        "default_base_url": "https://api.mistral.ai/v1",
+        "requires_base_url": False,
+        # No catalog entry for mistralai today — wizard shows a free-text input.
+        "models": list(_PROVIDER_MODELS.get("mistralai", [])),
+        "category": "specialized",
+    },
+    "x-ai": {
+        "label": "xAI (Grok)",
+        "env_var": "XAI_API_KEY",
+        "default_model": "grok-4.20",
+        "default_base_url": "https://api.x.ai/v1",
+        "requires_base_url": False,
+        # Agent normalizes "x-ai" → "xai"; _PROVIDER_MODELS is also keyed "xai"
+        # when populated, so check both keys for forward-compatibility.
+        "models": list(_PROVIDER_MODELS.get("xai", []) or _PROVIDER_MODELS.get("x-ai", [])),
+        "category": "specialized",
+    },
+}
+
+_PROVIDER_CATEGORIES = [
+    {"id": "easy_start", "label": "Easy start", "order": 0},
+    {"id": "self_hosted", "label": "Open / self-hosted", "order": 1},
+    {"id": "specialized", "label": "Specialized", "order": 2},
+]
+
+_UNSUPPORTED_PROVIDER_NOTE = (
+    "OAuth and advanced provider flows such as Nous Portal, OpenAI Codex, and GitHub "
+    "Copilot are still terminal-first. Use `hermes model` for those flows."
+)
+
+
+def _get_active_hermes_home() -> Path:
+    try:
+        from api.profiles import get_active_hermes_home
+
+        return get_active_hermes_home()
+    except ImportError:
+        return Path.home() / ".hermes"
+
+
+def _load_env_file(env_path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not env_path.exists():
+        return values
+    try:
+        for raw in env_path.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    except Exception:
+        return {}
+    return values
+
+
+
+def _load_yaml_config(config_path: Path) -> dict:
+    try:
+        import yaml as _yaml
+    except ImportError:
+        return {}
+
+    if not config_path.exists():
+        return {}
+    try:
+        loaded = _yaml.safe_load(config_path.read_text(encoding="utf-8"))
+        return loaded if isinstance(loaded, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_yaml_config(config_path: Path, config: dict) -> None:
+    try:
+        import yaml as _yaml
+    except ImportError as exc:
+        raise RuntimeError("PyYAML is required to write Hermes config.yaml") from exc
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(
+        _yaml.safe_dump(config, sort_keys=False, allow_unicode=True),
+        encoding="utf-8",
+    )
+
+
+def _normalize_model_for_provider(provider: str, model: str) -> str:
+    clean = (model or "").strip()
+    if not clean:
+        return ""
+    if provider in {"anthropic", "openai"} and clean.startswith(provider + "/"):
+        return clean.split("/", 1)[1]
+    return clean
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return (base_url or "").strip().rstrip("/")
+
+
+# ── Provider endpoint probe (#1499) ─────────────────────────────────────────
+
+# Probe error codes — stable strings the frontend can switch on for inline
+# error rendering.  Add new codes only by extending this set; never reuse.
+PROBE_ERROR_CODES = (
+    "invalid_url",       # base_url failed urlparse / scheme / host check
+    "dns",               # hostname did not resolve
+    "connect_refused",   # TCP RST on connect (server not listening)
+    "timeout",           # exceeded probe timeout
+    "http_4xx",          # endpoint returned 4xx (auth required, wrong path, …)
+    "http_5xx",          # endpoint returned 5xx (server-side fault)
+    "parse",             # body not JSON or not the OpenAI /models shape
+    "unreachable",       # other network / SSL / unknown error
+)
+
+PROBE_TIMEOUT_SECONDS = 5.0
+# OpenAI /models response can list dozens of entries on Ollama / LM Studio.
+# 256 KB is more than enough for any realistic catalog and bounds the worst
+# case for a hostile / mis-pointed endpoint that streams forever.
+PROBE_MAX_BYTES = 256 * 1024
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Refuse to follow HTTP redirects on the probe path.
+
+    `urllib.request.urlopen` follows redirects by default — without this
+    handler, a probe at `http://example.com/v1/models` could be redirected
+    to `http://internal-service:8080/admin`, surfacing internal HTTP services
+    to whatever the probe targets next.  The probe is already gated behind
+    WebUI auth and the local-network check, so the threat model is
+    "authenticated user enumerating internal services" — same as `curl`
+    from their browser DevTools.  Disabling redirects tightens defaults
+    without breaking any legitimate use case (a self-hosted /models endpoint
+    that 3xx-redirects is itself misconfigured).  Redirects surface to the
+    caller as `unreachable` (mapped from `HTTPError(3xx)` in the probe).
+    Reviewer-flagged in PR #1501 (#1499 + #1500).
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # tell urllib to NOT follow; raises HTTPError(3xx) instead
+
+
+_PROBE_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+
+
+def probe_provider_endpoint(
+    provider: str,
+    base_url: str,
+    api_key: str | None = None,
+    timeout: float = PROBE_TIMEOUT_SECONDS,
+) -> dict:
+    """Probe `<base_url>/models` for a self-hosted OpenAI-compatible provider.
+
+    Used by the onboarding wizard to validate the user's configured base URL
+    before persisting (#1499).  Distinguishes failure modes so the frontend
+    can render a precise inline error instead of a generic "could not save."
+
+    Returns one of:
+
+      {"ok": True, "models": [{"id": "...", "label": "..."}, ...]}
+      {"ok": False, "error": "<code>", "detail": "<human string>"}
+
+    Where ``<code>`` is one of ``PROBE_ERROR_CODES``.
+
+    The probe is a single HTTP GET — no retries.  The timeout is short by
+    design: the wizard runs the probe synchronously on the user's submit
+    click, and we'd rather report "timeout" quickly than block the UI for
+    the kernel default ~75s.
+
+    The probe response is NOT persisted.  This function returns model IDs
+    so the wizard can populate its dropdown, but ``apply_onboarding_setup``
+    only writes the user's typed selection — never auto-pinning a stale
+    list of models to ``config.yaml``.
+
+    SSRF: ``base_url`` is whatever the user typed in the onboarding form.
+    The wizard is gated behind authentication (post-onboarding, the user
+    has already authenticated to the WebUI), and the legitimate target is
+    a local LM Studio / Ollama / vLLM server, so we deliberately do not
+    block private-IP ranges — that would make the feature useless.  The
+    risk surface is "authenticated user crafts a probe to enumerate
+    internal HTTP services," which is a different threat model from
+    unauthenticated SSRF.
+    """
+    base_url = _normalize_base_url(base_url)
+    if not base_url:
+        return {"ok": False, "error": "invalid_url", "detail": "base_url is required"}
+
+    parsed = urlparse(base_url)
+    if parsed.scheme not in {"http", "https"}:
+        return {
+            "ok": False,
+            "error": "invalid_url",
+            "detail": "base_url must start with http:// or https://",
+        }
+    if not parsed.hostname:
+        return {"ok": False, "error": "invalid_url", "detail": "base_url has no host"}
+
+    # Build the probe URL.  OpenAI-compatible servers expose /v1/models or
+    # /models.  Most users supply a base URL ending in /v1, so we just append
+    # /models to whatever they typed.  Strip the trailing slash and append
+    # rather than urljoin to avoid eating the /v1 segment when there's no
+    # trailing slash.
+    probe_url = f"{base_url}/models"
+
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": "hermes-webui-onboarding-probe",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    req = urllib.request.Request(probe_url, headers=headers, method="GET")
+
+    try:
+        with _PROBE_OPENER.open(req, timeout=timeout) as resp:
+            status = resp.status
+            body = resp.read(PROBE_MAX_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        # 3xx / 4xx / 5xx with a body — categorize.  3xx happens when the
+        # endpoint redirects (we refuse to follow on the probe path — see
+        # _NoRedirectHandler).  Map to `unreachable` rather than introducing a
+        # new error code, since a self-hosted /models endpoint that 3xx-
+        # redirects is itself misconfigured.
+        if 300 <= exc.code < 400:
+            code = "unreachable"
+            detail = (
+                f"HTTP {exc.code} — endpoint returned a redirect "
+                f"(probe does not follow redirects).  Point base_url at the "
+                f"final URL directly."
+            )
+            return {"ok": False, "error": code, "detail": detail, "status": exc.code}
+        code = "http_4xx" if 400 <= exc.code < 500 else "http_5xx"
+        # Try to surface a useful detail (LM Studio sometimes returns text/plain).
+        try:
+            err_body = exc.read(2048).decode("utf-8", errors="replace").strip()
+        except Exception:
+            err_body = ""
+        detail = f"HTTP {exc.code}"
+        if err_body:
+            err_first = err_body.splitlines()[0][:200]
+            detail = f"{detail}: {err_first}"
+        return {"ok": False, "error": code, "detail": detail, "status": exc.code}
+    except urllib.error.URLError as exc:
+        # Distinguish DNS / connect-refused / timeout / generic.
+        reason = exc.reason
+        if isinstance(reason, socket.timeout) or "timed out" in str(reason).lower():
+            return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
+        if isinstance(reason, socket.gaierror):
+            return {
+                "ok": False,
+                "error": "dns",
+                "detail": f"could not resolve host '{parsed.hostname}'",
+            }
+        if isinstance(reason, ConnectionRefusedError) or "refused" in str(reason).lower():
+            port_hint = parsed.port or ("443" if parsed.scheme == "https" else "80")
+            return {
+                "ok": False,
+                "error": "connect_refused",
+                "detail": f"connection refused at {parsed.hostname}:{port_hint}",
+            }
+        return {"ok": False, "error": "unreachable", "detail": str(reason)[:200]}
+    except (TimeoutError, socket.timeout):
+        return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
+    except Exception as exc:  # pragma: no cover — defensive net
+        logger.debug("probe_provider_endpoint unexpected error", exc_info=True)
+        return {"ok": False, "error": "unreachable", "detail": str(exc)[:200]}
+
+    # If the response was huge, refuse to parse.  256 KB cap is generous;
+    # anything bigger is likely the user pointed us at the wrong service.
+    if len(body) > PROBE_MAX_BYTES:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": f"response exceeded {PROBE_MAX_BYTES // 1024} KB cap",
+        }
+
+    try:
+        payload = json.loads(body.decode("utf-8", errors="replace"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": f"response is not JSON ({exc.__class__.__name__})",
+        }
+
+    # Accept both the OpenAI shape (`{"data": [{"id": ...}, ...]}`) and the
+    # bare-list shape some self-hosted servers return (`[{"id": ...}, ...]`).
+    if isinstance(payload, dict) and isinstance(payload.get("data"), list):
+        entries = payload["data"]
+    elif isinstance(payload, list):
+        entries = payload
+    else:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": "response is not in OpenAI /models shape (expected {'data': [...]} or [...])",
+        }
+
+    models = []
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("id"):
+            mid = str(entry["id"]).strip()
+            if mid:
+                models.append({"id": mid, "label": mid})
+        elif isinstance(entry, str) and entry.strip():
+            models.append({"id": entry.strip(), "label": entry.strip()})
+
+    return {"ok": True, "models": models, "status": status}
+
+
+def _extract_current_provider(cfg: dict) -> str:
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, dict):
+        provider = str(model_cfg.get("provider") or "").strip().lower()
+        if provider:
+            return provider
+    return ""
+
+
+def _extract_current_model(cfg: dict) -> str:
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, str):
+        return model_cfg.strip()
+    if isinstance(model_cfg, dict):
+        return str(model_cfg.get("default") or "").strip()
+    return ""
+
+
+def _extract_current_base_url(cfg: dict) -> str:
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, dict):
+        return _normalize_base_url(str(model_cfg.get("base_url") or ""))
+    return ""
+
+
+def _provider_api_key_present(
+    provider: str, cfg: dict, env_values: dict[str, str]
+) -> bool:
+    provider = (provider or "").strip().lower()
+    if not provider:
+        return False
+
+    env_var = _SUPPORTED_PROVIDER_SETUPS.get(provider, {}).get("env_var")
+    if env_var and env_values.get(env_var):
+        return True
+
+    # Legacy env-var aliases (read-only fallback for env vars renamed in past
+    # releases — e.g. lmstudio's LM_API_KEY canonical + LMSTUDIO_API_KEY legacy
+    # in #1500).  Canonical name is what onboarding writes going forward;
+    # aliases keep existing users' detection working without forcing an .env
+    # rewrite.
+    for alias in _SUPPORTED_PROVIDER_SETUPS.get(provider, {}).get("env_var_aliases", []) or []:
+        if alias and env_values.get(alias):
+            return True
+
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, dict) and str(model_cfg.get("api_key") or "").strip():
+        return True
+
+    providers_cfg = cfg.get("providers", {})
+    if isinstance(providers_cfg, dict):
+        provider_cfg = providers_cfg.get(provider, {})
+        if (
+            isinstance(provider_cfg, dict)
+            and str(provider_cfg.get("api_key") or "").strip()
+        ):
+            return True
+        if provider == "custom":
+            custom_cfg = providers_cfg.get("custom", {})
+            if (
+                isinstance(custom_cfg, dict)
+                and str(custom_cfg.get("api_key") or "").strip()
+            ):
+                return True
+
+    # For providers not in _SUPPORTED_PROVIDER_SETUPS (e.g. minimax-cn, deepseek,
+    # xai, etc.), ask the hermes_cli auth registry — it knows every provider's env
+    # var names and can check os.environ for a valid key.
+    # Exclude known OAuth/token-flow providers — those are handled separately by
+    # _provider_oauth_authenticated() and should not be short-circuited here.
+    _known_oauth = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous"}
+    if provider not in _SUPPORTED_PROVIDER_SETUPS and provider not in _known_oauth:
+        try:
+            from hermes_cli.auth import get_auth_status as _gas
+            status = _gas(provider)
+            if isinstance(status, dict) and status.get("logged_in"):
+                return True
+        except Exception:
+            pass
+
+    return False
+
+
+
+def _oauth_payload_has_token(payload: dict) -> bool:
+    """Return True if an auth payload contains usable token material."""
+    if not isinstance(payload, dict):
+        return False
+
+    token_fields = (
+        payload,
+        payload.get("tokens") if isinstance(payload.get("tokens"), dict) else {},
+    )
+    for candidate in token_fields:
+        if not isinstance(candidate, dict):
+            continue
+        if any(
+            str(candidate.get(key) or "").strip()
+            for key in ("access_token", "refresh_token", "api_key")
+        ):
+            return True
+    return False
+
+
+
+def _provider_oauth_authenticated(provider: str, hermes_home: "Path") -> bool:
+    """Return True if the provider has valid OAuth credentials.
+
+    Reads the profile-scoped auth.json directly so onboarding respects the
+    requested Hermes home. Known OAuth providers may store auth either in the
+    legacy providers[provider_id] singleton state or in credential_pool entries
+    used by current Hermes runtime auth resolution.
+    """
+    provider = (provider or "").strip().lower()
+    if not provider:
+        return False
+
+    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous"}
+    if provider not in _known_oauth_providers:
+        return False
+
+    try:
+        import json as _j
+
+        auth_path = hermes_home / "auth.json"
+        if not auth_path.exists():
+            return False
+        store = _j.loads(auth_path.read_text(encoding="utf-8"))
+
+        providers_store = store.get("providers")
+        if isinstance(providers_store, dict):
+            state = providers_store.get(provider)
+            if _oauth_payload_has_token(state):
+                return True
+
+        pool_store = store.get("credential_pool")
+        if isinstance(pool_store, dict):
+            entries = pool_store.get(provider)
+            if isinstance(entries, list):
+                return any(_oauth_payload_has_token(entry) for entry in entries)
+
+        return False
+    except Exception:
+        return False
+
+
+def _status_from_runtime(cfg: dict, imports_ok: bool) -> dict:
+    provider = _extract_current_provider(cfg)
+    model = _extract_current_model(cfg)
+    base_url = _extract_current_base_url(cfg)
+    env_values = _load_env_file(_get_active_hermes_home() / ".env")
+
+    provider_configured = bool(provider and model)
+    provider_ready = False
+
+    if provider_configured:
+        meta = _SUPPORTED_PROVIDER_SETUPS.get(provider, {})
+        if provider in _SUPPORTED_PROVIDER_SETUPS:
+            # key_optional providers (lmstudio, ollama, custom) are ready as
+            # soon as the user has saved a provider+model+base_url; an api_key
+            # is allowed but not required.  The agent runtime substitutes a
+            # placeholder for keyless local servers (LMSTUDIO_NOAUTH_PLACEHOLDER
+            # for lmstudio, equivalent paths for ollama / custom).  See #1499
+            # third sub-bug from #1420.
+            if meta.get("key_optional"):
+                if meta.get("requires_base_url"):
+                    provider_ready = bool(base_url)
+                else:
+                    provider_ready = True
+            else:
+                # Standard wizard provider (openrouter, anthropic, openai, gemini,
+                # deepseek, zai, …) — needs an api_key.  Custom historically also
+                # took this branch, but is now key_optional via the meta flag.
+                if meta.get("requires_base_url"):
+                    provider_ready = bool(
+                        base_url
+                        and _provider_api_key_present(provider, cfg, env_values)
+                    )
+                else:
+                    provider_ready = _provider_api_key_present(provider, cfg, env_values)
+        else:
+            # Unknown provider — may be an OAuth flow (openai-codex, copilot, etc.)
+            # OR an API-key provider not in the quick-setup list (minimax-cn, deepseek,
+            # xai, etc.).  Check both: api key presence first (covers the majority of
+            # third-party providers), then OAuth auth.json.
+            provider_ready = (
+                _provider_api_key_present(provider, cfg, env_values)
+                or _provider_oauth_authenticated(provider, _get_active_hermes_home())
+            )
+
+    chat_ready = bool(_HERMES_FOUND and imports_ok and provider_ready)
+
+    if not _HERMES_FOUND or not imports_ok:
+        state = "agent_unavailable"
+        note = (
+            "Hermes is not fully importable from the Web UI yet. Finish bootstrap or fix the "
+            "agent install before provider setup will work."
+        )
+    elif chat_ready:
+        state = "ready"
+        provider_name = _PROVIDER_DISPLAY.get(
+            provider, provider.title() if provider else "Hermes"
+        )
+        note = f"Hermes is minimally configured and ready to chat via {provider_name}."
+    elif provider_configured:
+        state = "provider_incomplete"
+        if provider == "custom" and not base_url:
+            note = (
+                "Hermes has a saved provider/model selection but still needs the "
+                "base URL and API key required to chat."
+            )
+        elif provider not in _SUPPORTED_PROVIDER_SETUPS:
+            # OAuth / unsupported provider: avoid misleading "API key" wording.
+            note = (
+                f"Provider '{provider}' is configured but not yet authenticated. "
+                "Run 'hermes auth' or 'hermes model' in a terminal to complete "
+                "setup, then reload the Web UI."
+            )
+        else:
+            note = (
+                "Hermes has a saved provider/model selection but still needs the "
+                "API key required to chat."
+            )
+    else:
+        state = "needs_provider"
+        note = "Hermes is installed, but you still need to choose a provider and save working credentials."
+
+    return {
+        "provider_configured": provider_configured,
+        "provider_ready": provider_ready,
+        "chat_ready": chat_ready,
+        "setup_state": state,
+        "provider_note": note,
+        "current_provider": provider or None,
+        "current_model": model or None,
+        "current_base_url": base_url or None,
+        "env_path": str(_get_active_hermes_home() / ".env"),
+    }
+
+
+def _build_setup_catalog(cfg: dict) -> dict:
+    current_provider = _extract_current_provider(cfg) or "openrouter"
+    current_model = _extract_current_model(cfg)
+    current_base_url = _extract_current_base_url(cfg)
+
+    providers = []
+    for provider_id, meta in _SUPPORTED_PROVIDER_SETUPS.items():
+        providers.append(
+            {
+                "id": provider_id,
+                "label": meta["label"],
+                "env_var": meta["env_var"],
+                "default_model": meta["default_model"],
+                "default_base_url": meta.get("default_base_url") or "",
+                "requires_base_url": bool(meta.get("requires_base_url")),
+                # #1499 (third sub-bug from #1420) — providers that may run
+                # keyless (lmstudio, ollama, custom).  Frontend uses this to
+                # show a "(optional)" hint and allow Continue without a key.
+                "key_optional": bool(meta.get("key_optional")),
+                "models": list(meta.get("models", [])),
+                "category": meta.get("category", "easy_start"),
+                "quick": meta.get("quick", False),
+            }
+        )
+
+    # Sort providers by category order, then alphabetically within each category.
+    cat_order = {c["id"]: c["order"] for c in _PROVIDER_CATEGORIES}
+    providers.sort(key=lambda p: (cat_order.get(p["category"], 99), p["label"]))
+
+    # Group providers by category for the frontend.
+    categories = []
+    for cat in sorted(_PROVIDER_CATEGORIES, key=lambda c: c["order"]):
+        categories.append({
+            "id": cat["id"],
+            "label": cat["label"],
+            "providers": [p["id"] for p in providers if p["category"] == cat["id"]],
+        })
+
+    # Flag whether the currently-configured provider is OAuth-based (not in the
+    # API-key flow).  The frontend uses this to show a confirmation card instead
+    # of a key input when the user has already authenticated via 'hermes auth'.
+    current_is_oauth = current_provider not in _SUPPORTED_PROVIDER_SETUPS and bool(
+        current_provider
+    )
+
+    return {
+        "providers": providers,
+        "categories": categories,
+        "unsupported_note": _UNSUPPORTED_PROVIDER_NOTE,
+        "current_is_oauth": current_is_oauth,
+        "current": {
+            "provider": current_provider,
+            "model": current_model
+            or _SUPPORTED_PROVIDER_SETUPS.get(current_provider, {}).get(
+                "default_model", ""
+            ),
+            "base_url": current_base_url,
+        },
+    }
+
+
+def get_onboarding_status() -> dict:
+    settings = load_settings()
+    cfg = get_config()
+    imports_ok, missing, errors = verify_hermes_imports()
+    runtime = _status_from_runtime(cfg, imports_ok)
+    workspaces = load_workspaces()
+    last_workspace = get_last_workspace()
+    available_models = get_available_models()
+
+    # HERMES_WEBUI_SKIP_ONBOARDING=1 lets hosting providers (e.g. Agent37) ship
+    # a pre-configured instance without the wizard blocking the first load.
+    # This is an operator-level override and is honoured unconditionally —
+    # the operator knows their deployment is configured; we must not second-guess
+    # it by requiring chat_ready to also be true.
+    skip_env = os.environ.get("HERMES_WEBUI_SKIP_ONBOARDING", "").strip()
+    skip_requested = skip_env in {"1", "true", "yes"}
+    auto_completed = skip_requested  # unconditional: operator says skip, we skip
+
+    # Auto-complete for existing Hermes users: if config.yaml already exists
+    # AND the provider is configured (or the system is chat_ready), treat onboarding
+    # as done.  These users configured Hermes via the CLI before the Web UI existed;
+    # they must never be shown the first-run wizard — it would silently overwrite their
+    # config.  We use provider_configured (not chat_ready) so that users with
+    # non-wizard providers (ollama-cloud, deepseek, xai, kimi, etc.) are not forced
+    # through the wizard just because their provider doesn't have a detectable API key
+    # — the wizard cannot represent their provider and would overwrite their config
+    # with whichever wizard-supported provider they accidentally select.
+    config_exists = Path(_get_config_path()).exists()
+
+    # For providers not in the wizard's quick-setup list (e.g. ollama-cloud, deepseek,
+    # xai, kimi-k2.6), the wizard can never help — it only knows how to configure
+    # openrouter/anthropic/openai/google/custom.  If such a user has a configured
+    # provider + model in config.yaml, showing the wizard would only confuse them
+    # (or worse, let them accidentally overwrite their config with gpt-5.4-mini).
+    _current_provider = str(
+        (cfg.get("model", {}) or {}).get("provider", "") if isinstance(cfg.get("model"), dict)
+        else ""
+    ).strip().lower()
+    _is_non_wizard_provider = bool(
+        _current_provider and _current_provider not in _SUPPORTED_PROVIDER_SETUPS
+    )
+
+    config_auto_completed = config_exists and (
+        bool(runtime.get("chat_ready"))
+        or (_is_non_wizard_provider and bool(runtime.get("provider_configured")))
+    )
+
+    # Persist the flag so it survives future transient import failures (e.g. after
+    # a git branch switch in the hermes-agent repo).  Without this, a CLI-configured
+    # user who never ran the wizard has no onboarding_completed flag — any momentary
+    # imports_ok=False during restart makes chat_ready=False, config_auto_completed=False,
+    # and the wizard reappears with a broken dropdown that clobbers their config.
+    #
+    # Best-effort: if save_settings raises (read-only FS, disk full, permission error),
+    # log and continue.  The `config_auto_completed` branch of `completed=` below still
+    # returns True for this request, so the user sees the correct state — only the
+    # persistence-across-restart guarantee is degraded.  Raising here would turn every
+    # /api/onboarding/status call into a 500 until disk was writable, which is worse UX
+    # than losing the next-restart protection.
+    if config_auto_completed and not settings.get("onboarding_completed"):
+        try:
+            save_settings({"onboarding_completed": True})
+            settings["onboarding_completed"] = True
+        except Exception:
+            logger.debug("Failed to persist onboarding_completed", exc_info=True)
+
+    return {
+        "completed": bool(settings.get("onboarding_completed")) or auto_completed or config_auto_completed,
+        "settings": {
+            "default_model": settings.get("default_model") or DEFAULT_MODEL,
+            "default_workspace": settings.get("default_workspace")
+            or str(DEFAULT_WORKSPACE),
+            "password_enabled": is_auth_enabled(),
+            "bot_name": settings.get("bot_name") or "Hermes",
+        },
+        "system": {
+            "hermes_found": bool(_HERMES_FOUND),
+            "imports_ok": bool(imports_ok),
+            "missing_modules": missing,
+            "import_errors": errors,
+            "config_path": str(_get_config_path()),
+            "config_exists": Path(_get_config_path()).exists(),
+            **runtime,
+        },
+        "setup": _build_setup_catalog(cfg),
+        "workspaces": {
+            "items": workspaces,
+            "last": last_workspace,
+        },
+        "models": available_models,
+    }
+
+
+def apply_onboarding_setup(body: dict) -> dict:
+    # Hard guard: if the operator set SKIP_ONBOARDING, the wizard should never
+    # have appeared.  Even if the frontend somehow calls this endpoint anyway
+    # (e.g. a stale JS bundle or a curious user), we must not overwrite the
+    # operator's config.yaml or .env files.  Just mark onboarding complete and
+    # return the current status — no file writes.
+    skip_env = os.environ.get("HERMES_WEBUI_SKIP_ONBOARDING", "").strip()
+    if skip_env in {"1", "true", "yes"}:
+        save_settings({"onboarding_completed": True})
+        return get_onboarding_status()
+
+    provider = str(body.get("provider") or "").strip().lower()
+    model = str(body.get("model") or "").strip()
+    api_key = str(body.get("api_key") or "").strip()
+    base_url = _normalize_base_url(str(body.get("base_url") or ""))
+
+    if provider not in _SUPPORTED_PROVIDER_SETUPS:
+        # Unsupported providers (openai-codex, copilot, nous, etc.) are already
+        # configured via the CLI. Just mark onboarding as complete and let the
+        # user through — the agent is already set up, no further setup needed.
+        save_settings({"onboarding_completed": True})
+        return get_onboarding_status()
+    if not model:
+        raise ValueError("model is required")
+
+    provider_meta = _SUPPORTED_PROVIDER_SETUPS[provider]
+    if provider_meta.get("requires_base_url"):
+        if not base_url:
+            raise ValueError("base_url is required for custom endpoints")
+        parsed = urlparse(base_url)
+        if parsed.scheme not in {"http", "https"}:
+            raise ValueError("base_url must start with http:// or https://")
+
+    config_path = _get_config_path()
+    # Guard: if config.yaml already exists and the caller did not explicitly
+    # acknowledge the overwrite, refuse to proceed.  The frontend must pass
+    # confirm_overwrite=True after showing the user a confirmation step.
+    if Path(config_path).exists() and not body.get("confirm_overwrite"):
+        return {
+            "error": "config_exists",
+            "message": (
+                "Hermes is already configured (config.yaml exists). "
+                "Pass confirm_overwrite=true to overwrite it."
+            ),
+            "requires_confirm": True,
+        }
+
+    cfg = _load_yaml_config(config_path)
+    env_path = _get_active_hermes_home() / ".env"
+    env_values = _load_env_file(env_path)
+
+    if not api_key and not _provider_api_key_present(provider, cfg, env_values):
+        # Providers that may run keyless (lmstudio, ollama, custom — gated by
+        # `key_optional` in _SUPPORTED_PROVIDER_SETUPS) are allowed to onboard
+        # with no api_key.  The agent runtime substitutes a placeholder
+        # (LMSTUDIO_NOAUTH_PLACEHOLDER) for those, and the probe (#1499) gives
+        # the user immediate feedback if their server actually does require
+        # auth (http_4xx with status 401).  See #1499 third sub-bug from #1420.
+        if not provider_meta.get("key_optional"):
+            raise ValueError(f"{provider_meta['env_var']} is required")
+
+    model_cfg = cfg.get("model", {})
+    if not isinstance(model_cfg, dict):
+        model_cfg = {}
+
+    model_cfg["provider"] = provider
+    model_cfg["default"] = _normalize_model_for_provider(provider, model)
+
+    if provider_meta.get("requires_base_url"):
+        model_cfg["base_url"] = base_url
+    elif provider_meta.get("default_base_url"):
+        model_cfg["base_url"] = provider_meta["default_base_url"]
+    else:
+        model_cfg.pop("base_url", None)
+
+    cfg["model"] = model_cfg
+    _save_yaml_config(config_path, cfg)
+
+    if api_key:
+        _write_env_file(env_path, {provider_meta["env_var"]: api_key})
+
+    # Reload the hermes_cli provider/config cache so the next streaming call
+    # picks up the new key without requiring a server restart.
+    try:
+        from api.profiles import _reload_dotenv
+        _reload_dotenv(_get_active_hermes_home())
+    except Exception:
+        logger.debug("Failed to reload dotenv")
+
+    # Belt-and-braces: set directly on os.environ AFTER _reload_dotenv so the
+    # value survives even if _reload_dotenv cleared it (e.g. when _write_env_file
+    # wrote to disk but the profile isolation tracking hasn't seen it yet).
+    if api_key:
+        os.environ[provider_meta["env_var"]] = api_key
+
+    try:
+        # hermes_cli may cache config at import time; ask it to reload if possible.
+        from hermes_cli.config import reload as _cli_reload
+        _cli_reload()
+    except Exception:
+        logger.debug("Failed to reload hermes_cli config")
+
+    reload_config()
+    return get_onboarding_status()
+
+
+def complete_onboarding() -> dict:
+    save_settings({"onboarding_completed": True})
+    return get_onboarding_status()

api/profiles.py

@@ -9,12 +9,15 @@ cached paths in hermes-agent modules (skills_tool, cron/jobs) that snapshot
 HERMES_HOME at import time.
 """
 import json
+import logging
 import os
 import re
 import shutil
 import threading
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 # ── Constants (match hermes_cli.profiles upstream) ─────────────────────────
 _PROFILE_ID_RE = re.compile(r'^[a-z0-9][a-z0-9_-]{0,63}$')
 _PROFILE_DIRS = [
@@ -26,6 +29,13 @@ _CLONE_CONFIG_FILES = ['config.yaml', '.env', 'SOUL.md']
 # ── Module state ────────────────────────────────────────────────────────────
 _active_profile = 'default'
 _profile_lock = threading.Lock()
+_loaded_profile_env_keys: set[str] = set()
+
+# Thread-local profile context: set per-request by server.py, cleared after.
+# Enables per-client profile isolation (issue #798) — each HTTP request thread
+# reads its own profile from the hermes_profile cookie instead of the
+# process-global _active_profile.
+_tls = threading.local()
 
 def _resolve_base_hermes_home() -> Path:
     """Return the BASE ~/.hermes directory — the root that contains profiles/.
@@ -71,31 +81,164 @@ def _read_active_profile_file() -> str:
     ap_file = _DEFAULT_HERMES_HOME / 'active_profile'
     if ap_file.exists():
         try:
-            name = ap_file.read_text().strip()
+            name = ap_file.read_text(encoding="utf-8").strip()
             if name:
                 return name
         except Exception:
-            pass
+            logger.debug("Failed to read active profile file")
     return 'default'
 
 
 # ── Public API ──────────────────────────────────────────────────────────────
 
 def get_active_profile_name() -> str:
-    """Return the currently active profile name."""
+    """Return the currently active profile name.
+
+    Priority:
+      1. Thread-local (set per-request from hermes_profile cookie) — issue #798
+      2. Process-level default (_active_profile)
+    """
+    tls_name = getattr(_tls, 'profile', None)
+    if tls_name is not None:
+        return tls_name
     return _active_profile
 
 
+def set_request_profile(name: str) -> None:
+    """Set the per-request profile context for this thread.
+
+    Called by server.py at the start of each request when a hermes_profile
+    cookie is present.  Always paired with clear_request_profile() in a
+    finally block so the thread-local is released after the request.
+    """
+    _tls.profile = name
+
+
+def clear_request_profile() -> None:
+    """Clear the per-request profile context for this thread.
+
+    Called by server.py in the finally block of do_GET / do_POST.
+    Safe to call even if set_request_profile() was never called.
+    """
+    _tls.profile = None
+
+
 def get_active_hermes_home() -> Path:
-    """Return the HERMES_HOME path for the currently active profile."""
-    if _active_profile == 'default':
+    """Return the HERMES_HOME path for the currently active profile.
+
+    Uses get_active_profile_name() so per-request TLS context (issue #798)
+    is respected, not just the process-level global.
+    """
+    name = get_active_profile_name()
+    if name == 'default':
         return _DEFAULT_HERMES_HOME
-    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / _active_profile
+    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / name
     if profile_dir.is_dir():
         return profile_dir
     return _DEFAULT_HERMES_HOME
 
 
+
+def get_hermes_home_for_profile(name: str) -> Path:
+    """Return the HERMES_HOME Path for *name* without mutating any process state.
+
+    Safe to call from per-request context (streaming, session creation) because
+    it reads only the filesystem — it never touches os.environ, module-level
+    cached paths, or the process-level _active_profile global.
+
+    Falls back to _DEFAULT_HERMES_HOME (same as 'default') when *name* is None,
+    empty, 'default', or does not match the profile-name format (rejects path
+    traversal such as '../../etc').
+    """
+    if not name or name == 'default' or not _PROFILE_ID_RE.fullmatch(name):
+        return _DEFAULT_HERMES_HOME
+    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / name
+    return profile_dir
+
+
+_TERMINAL_ENV_MAPPINGS = {
+    'backend': 'TERMINAL_ENV',
+    'env_type': 'TERMINAL_ENV',
+    'cwd': 'TERMINAL_CWD',
+    'timeout': 'TERMINAL_TIMEOUT',
+    'lifetime_seconds': 'TERMINAL_LIFETIME_SECONDS',
+    'modal_mode': 'TERMINAL_MODAL_MODE',
+    'docker_image': 'TERMINAL_DOCKER_IMAGE',
+    'docker_forward_env': 'TERMINAL_DOCKER_FORWARD_ENV',
+    'docker_env': 'TERMINAL_DOCKER_ENV',
+    'docker_mount_cwd_to_workspace': 'TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE',
+    'singularity_image': 'TERMINAL_SINGULARITY_IMAGE',
+    'modal_image': 'TERMINAL_MODAL_IMAGE',
+    'daytona_image': 'TERMINAL_DAYTONA_IMAGE',
+    'container_cpu': 'TERMINAL_CONTAINER_CPU',
+    'container_memory': 'TERMINAL_CONTAINER_MEMORY',
+    'container_disk': 'TERMINAL_CONTAINER_DISK',
+    'container_persistent': 'TERMINAL_CONTAINER_PERSISTENT',
+    'docker_volumes': 'TERMINAL_DOCKER_VOLUMES',
+    'persistent_shell': 'TERMINAL_PERSISTENT_SHELL',
+    'ssh_host': 'TERMINAL_SSH_HOST',
+    'ssh_user': 'TERMINAL_SSH_USER',
+    'ssh_port': 'TERMINAL_SSH_PORT',
+    'ssh_key': 'TERMINAL_SSH_KEY',
+    'ssh_persistent': 'TERMINAL_SSH_PERSISTENT',
+    'local_persistent': 'TERMINAL_LOCAL_PERSISTENT',
+}
+
+
+def _stringify_env_value(value) -> str:
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    if isinstance(value, (list, dict)):
+        return json.dumps(value)
+    return str(value)
+
+
+def get_profile_runtime_env(home: Path) -> dict[str, str]:
+    """Return env vars needed to run an agent turn for a profile home.
+
+    WebUI profile switching is per-client/cookie scoped, so it intentionally
+    does not call ``switch_profile(..., process_wide=True)`` for every browser.
+    Agent/tool code still consumes terminal backend settings through
+    environment variables (matching ``hermes -p <profile>``), so streaming must
+    apply the selected profile's terminal config and ``.env`` for the duration
+    of that run.
+    """
+    home = Path(home).expanduser()
+    env: dict[str, str] = {}
+
+    try:
+        import yaml as _yaml
+
+        cfg_path = home / 'config.yaml'
+        cfg = _yaml.safe_load(cfg_path.read_text(encoding='utf-8')) if cfg_path.exists() else {}
+        if not isinstance(cfg, dict):
+            cfg = {}
+    except Exception:
+        cfg = {}
+
+    terminal_cfg = cfg.get('terminal', {}) if isinstance(cfg, dict) else {}
+    if isinstance(terminal_cfg, dict):
+        for key, env_key in _TERMINAL_ENV_MAPPINGS.items():
+            if key in terminal_cfg and terminal_cfg[key] is not None:
+                env[env_key] = _stringify_env_value(terminal_cfg[key])
+
+    env_path = home / '.env'
+    if env_path.exists():
+        try:
+            for line in env_path.read_text(encoding='utf-8').splitlines():
+                line = line.strip()
+                if line and not line.startswith('#') and '=' in line:
+                    k, v = line.split('=', 1)
+                    k = k.strip()
+                    v = v.strip().strip('"').strip("'")
+                    if k and v:
+                        env[k] = v
+        except Exception:
+            logger.debug("Failed to read runtime env from %s", env_path)
+
+    return env
+
+
 def _set_hermes_home(home: Path):
     """Set HERMES_HOME env var and monkey-patch cached module-level paths."""
     os.environ['HERMES_HOME'] = str(home)
@@ -106,7 +249,7 @@ def _set_hermes_home(home: Path):
         _sk.HERMES_HOME = home
         _sk.SKILLS_DIR = home / 'skills'
     except (ImportError, AttributeError):
-        pass
+        logger.debug("Failed to patch skills_tool module")
 
     # Patch cron/jobs module-level cache
     try:
@@ -116,16 +259,29 @@ def _set_hermes_home(home: Path):
         _cj.JOBS_FILE = _cj.CRON_DIR / 'jobs.json'
         _cj.OUTPUT_DIR = _cj.CRON_DIR / 'output'
     except (ImportError, AttributeError):
-        pass
+        logger.debug("Failed to patch cron.jobs module")
 
 
 def _reload_dotenv(home: Path):
-    """Load .env from the profile dir into os.environ (additive)."""
+    """Load .env from the profile dir into os.environ with profile isolation.
+
+    Clears env vars that were loaded from the previously active profile before
+    applying the current profile's .env. This prevents API keys and other
+    profile-scoped secrets from leaking across profile switches.
+    """
+    global _loaded_profile_env_keys
+
+    # Remove keys loaded from the previous profile first.
+    for key in list(_loaded_profile_env_keys):
+        os.environ.pop(key, None)
+    _loaded_profile_env_keys = set()
+
     env_path = home / '.env'
     if not env_path.exists():
         return
     try:
-        for line in env_path.read_text().splitlines():
+        loaded_keys: set[str] = set()
+        for line in env_path.read_text(encoding="utf-8").splitlines():
             line = line.strip()
             if line and not line.startswith('#') and '=' in line:
                 k, v = line.split('=', 1)
@@ -133,11 +289,14 @@ def _reload_dotenv(home: Path):
                 v = v.strip().strip('"').strip("'")
                 if k and v:
                     os.environ[k] = v
+                    loaded_keys.add(k)
+        _loaded_profile_env_keys = loaded_keys
     except Exception:
-        pass
+        _loaded_profile_env_keys = set()
+        logger.debug("Failed to reload dotenv from %s", env_path)
 
 
-def init_profile_state():
+def init_profile_state() -> None:
     """Initialize profile state at server startup.
 
     Reads ~/.hermes/active_profile, sets HERMES_HOME env var, patches
@@ -150,12 +309,18 @@ def init_profile_state():
     _reload_dotenv(home)
 
 
-def switch_profile(name: str) -> dict:
+def switch_profile(name: str, *, process_wide: bool = True) -> dict:
     """Switch the active profile.
 
     Validates the profile exists, updates process state, patches module caches,
     reloads .env, and reloads config.yaml.
 
+    Args:
+        name: Profile name to switch to.
+        process_wide: If True (default), updates the process-global
+            _active_profile.  Set to False for per-client switches from the
+            WebUI where the profile is managed via cookie + thread-local (#798).
+
     Returns: {'profiles': [...], 'active': name}
     Raises ValueError if profile doesn't exist or agent is busy.
     """
@@ -176,29 +341,45 @@ def switch_profile(name: str) -> dict:
     if name == 'default':
         home = _DEFAULT_HERMES_HOME
     else:
-        home = _DEFAULT_HERMES_HOME / 'profiles' / name
+        home = _resolve_named_profile_home(name)
         if not home.is_dir():
             raise ValueError(f"Profile '{name}' does not exist.")
 
     with _profile_lock:
-        _active_profile = name
-        _set_hermes_home(home)
-        _reload_dotenv(home)
+        if process_wide:
+            global _active_profile
+            _active_profile = name
+            _set_hermes_home(home)
+            _reload_dotenv(home)
 
-    # Write sticky default for CLI consistency
-    try:
-        ap_file = _DEFAULT_HERMES_HOME / 'active_profile'
-        ap_file.write_text(name if name != 'default' else '')
-    except Exception:
-        pass
+    if process_wide:
+        # Write sticky default for CLI consistency
+        try:
+            ap_file = _DEFAULT_HERMES_HOME / 'active_profile'
+            ap_file.write_text(name if name != 'default' else '', encoding='utf-8')
+        except Exception:
+            logger.debug("Failed to write active profile file")
 
-    # Reload config.yaml from the new profile
-    reload_config()
+        # Reload config.yaml from the new profile
+        reload_config()
 
-    # Return profile-specific defaults so frontend can apply them
-    from api.workspace import get_last_workspace
-    from api.config import get_config
-    cfg = get_config()
+    # Return profile-specific defaults so frontend can apply them.
+    # For process_wide=False (per-client switch), read the target profile's
+    # config.yaml directly from disk rather than from _cfg_cache (process-global),
+    # since reload_config() was intentionally skipped.
+    if process_wide:
+        from api.config import get_config
+        cfg = get_config()
+    else:
+        # Direct disk read — does not touch _cfg_cache
+        try:
+            import yaml as _yaml
+            cfg_path = home / 'config.yaml'
+            cfg = _yaml.safe_load(cfg_path.read_text(encoding='utf-8')) if cfg_path.exists() else {}
+            if not isinstance(cfg, dict):
+                cfg = {}
+        except Exception:
+            cfg = {}
     model_cfg = cfg.get('model', {})
     default_model = None
     if isinstance(model_cfg, str):
@@ -206,11 +387,57 @@ def switch_profile(name: str) -> dict:
     elif isinstance(model_cfg, dict):
         default_model = model_cfg.get('default')
 
+    # Read the target profile's workspace directly from *home* rather than via
+    # get_last_workspace() which routes through the thread-local/process-global active
+    # profile — both of which still point to the OLD profile during process_wide=False
+    # switches (the Set-Cookie has been sent but hasn't been processed by a new request
+    # yet).  We derive workspace in priority order:
+    #   1. {home}/webui_state/last_workspace.txt  (previously chosen workspace for this profile)
+    #   2. cfg terminal.cwd / workspace / default_workspace keys
+    #   3. Boot-time DEFAULT_WORKSPACE constant
+    # Use the module-level ``Path`` (imported at line 17) rather than re-importing
+    # it locally — keeps the exception fallback simple and avoids a latent NameError
+    # if a future refactor moves the inner imports.
+    default_workspace = None
+    try:
+        from api.config import DEFAULT_WORKSPACE as _DW
+        lw_file = home / 'webui_state' / 'last_workspace.txt'
+        if lw_file.exists():
+            _p = lw_file.read_text(encoding='utf-8').strip()
+            if _p:
+                _pp = Path(_p).expanduser()
+                if _pp.is_dir():
+                    default_workspace = str(_pp.resolve())
+        if default_workspace is None:
+            for _key in ('workspace', 'default_workspace'):
+                _v = cfg.get(_key)
+                if _v:
+                    _pp = Path(str(_v)).expanduser().resolve()
+                    if _pp.is_dir():
+                        default_workspace = str(_pp)
+                        break
+        if default_workspace is None:
+            _tc = cfg.get('terminal', {})
+            if isinstance(_tc, dict):
+                _cwd = _tc.get('cwd', '')
+                if _cwd and str(_cwd) not in ('.', ''):
+                    _pp = Path(str(_cwd)).expanduser().resolve()
+                    if _pp.is_dir():
+                        default_workspace = str(_pp)
+        if default_workspace is None:
+            default_workspace = str(_DW)
+    except Exception:
+        try:
+            from api.config import DEFAULT_WORKSPACE as _DW2
+            default_workspace = str(_DW2)
+        except Exception:
+            default_workspace = str(Path.home())
+
     return {
         'profiles': list_profiles_api(),
         'active': name,
         'default_model': default_model,
-        'default_workspace': get_last_workspace(),
+        'default_workspace': default_workspace,
     }
 
 
@@ -223,7 +450,7 @@ def list_profiles_api() -> list:
         # hermes_cli not available -- return just the default
         return [_default_profile_dict()]
 
-    active = _active_profile
+    active = get_active_profile_name()
     result = []
     for p in infos:
         result.append({
@@ -267,6 +494,24 @@ def _validate_profile_name(name: str):
         )
 
 
+def _profiles_root() -> Path:
+    """Return the canonical root that contains named profiles."""
+    return (_DEFAULT_HERMES_HOME / 'profiles').resolve()
+
+
+def _resolve_named_profile_home(name: str) -> Path:
+    """Resolve a named profile to a directory under the profiles root.
+
+    Validates *name* as a logical profile identifier first, then resolves the
+    final filesystem path and enforces containment under ~/.hermes/profiles.
+    """
+    _validate_profile_name(name)
+    profiles_root = _profiles_root()
+    candidate = (profiles_root / name).resolve()
+    candidate.relative_to(profiles_root)
+    return candidate
+
+
 def _create_profile_fallback(name: str, clone_from: str = None,
                               clone_config: bool = False) -> Path:
     """Create a profile directory without hermes_cli (Docker/standalone fallback)."""
@@ -294,8 +539,38 @@ def _create_profile_fallback(name: str, clone_from: str = None,
     return profile_dir
 
 
+def _write_endpoint_to_config(profile_dir: Path, base_url: str = None, api_key: str = None) -> None:
+    """Write custom endpoint fields into config.yaml for a profile."""
+    if not base_url and not api_key:
+        return
+    config_path = profile_dir / 'config.yaml'
+    try:
+        import yaml as _yaml
+    except ImportError:
+        return
+    cfg = {}
+    if config_path.exists():
+        try:
+            loaded = _yaml.safe_load(config_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                cfg = loaded
+        except Exception:
+            logger.debug("Failed to load config from %s", config_path)
+    model_section = cfg.get('model', {})
+    if not isinstance(model_section, dict):
+        model_section = {}
+    if base_url:
+        model_section['base_url'] = base_url
+    if api_key:
+        model_section['api_key'] = api_key
+    cfg['model'] = model_section
+    config_path.write_text(_yaml.dump(cfg, default_flow_style=False, allow_unicode=True), encoding='utf-8')
+
+
 def create_profile_api(name: str, clone_from: str = None,
-                       clone_config: bool = False) -> dict:
+                       clone_config: bool = False,
+                       base_url: str = None,
+                       api_key: str = None) -> dict:
     """Create a new profile. Returns the new profile info dict."""
     _validate_profile_name(name)
     # Defense-in-depth: validate clone_from here too, even though routes.py
@@ -315,11 +590,26 @@ def create_profile_api(name: str, clone_from: str = None,
     except ImportError:
         _create_profile_fallback(name, clone_from, clone_config)
 
+    # Resolve the profile directory from the profile list when possible.
+    # hermes_cli and the webui runtime do not always agree on the exact root,
+    # so we prefer the path returned by list_profiles_api() and fall back to the
+    # standard profile location only if the profile cannot be found there yet.
+    profile_path = _DEFAULT_HERMES_HOME / 'profiles' / name
+    for p in list_profiles_api():
+        if p['name'] == name:
+            try:
+                profile_path = Path(p.get('path') or profile_path)
+            except Exception:
+                logger.debug("Failed to parse profile path")
+            break
+
+    profile_path.mkdir(parents=True, exist_ok=True)
+    _write_endpoint_to_config(profile_path, base_url=base_url, api_key=api_key)
+
     # Find and return the newly created profile info.
     # When hermes_cli is not importable, list_profiles_api() also falls back
     # to the stub default-only list and won't find the new profile by name.
     # In that case, return a complete profile dict directly.
-    profile_path = _DEFAULT_HERMES_HOME / 'profiles' / name
     for p in list_profiles_api():
         if p['name'] == name:
             return p
@@ -340,6 +630,7 @@ def delete_profile_api(name: str) -> dict:
     """Delete a profile. Switches to default first if it's the active one."""
     if name == 'default':
         raise ValueError("Cannot delete the default profile.")
+    _validate_profile_name(name)
 
     # If deleting the active profile, switch to default first
     if _active_profile == name:
@@ -357,7 +648,7 @@ def delete_profile_api(name: str) -> dict:
     except ImportError:
         # Manual fallback: just remove the directory
         import shutil
-        profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / name
+        profile_dir = _resolve_named_profile_home(name)
         if profile_dir.is_dir():
             shutil.rmtree(str(profile_dir))
         else:

api/providers.py

@@ -0,0 +1,624 @@
+"""Hermes Web UI -- provider management endpoints.
+
+Provides CRUD operations for configuring provider API keys post-onboarding.
+Closes #586 (allow provider key update) and part of #604 (model picker
+multi-provider support).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from api.config import (
+    _PROVIDER_DISPLAY,
+    _PROVIDER_MODELS,
+    _get_config_path,
+    _save_yaml_config_file,
+    get_config,
+    invalidate_models_cache,
+    reload_config,
+)
+
+logger = logging.getLogger(__name__)
+
+# SECTION: Provider ↔ env var mapping
+
+# Maps canonical provider slug → env var name for API key.
+# Providers not listed here (OAuth/token-flow providers like copilot, nous,
+# openai-codex) cannot have their keys managed from the WebUI.
+_PROVIDER_ENV_VAR: dict[str, str] = {
+    "openrouter": "OPENROUTER_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "zai": "GLM_API_KEY",
+    "kimi-coding": "KIMI_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "minimax": "MINIMAX_API_KEY",
+    "minimax-cn": "MINIMAX_CN_API_KEY",
+    "mistralai": "MISTRAL_API_KEY",
+    "x-ai": "XAI_API_KEY",
+    "opencode-zen": "OPENCODE_ZEN_API_KEY",
+    "opencode-go": "OPENCODE_GO_API_KEY",
+    # NOTE: bare "ollama" (local) deliberately omitted — local Ollama is keyless
+    # by default and the runtime in hermes_cli/runtime_provider.py only consumes
+    # OLLAMA_API_KEY when the base URL hostname is ollama.com (Ollama Cloud).
+    # If we mapped both providers to the same env var, configuring Ollama Cloud
+    # would falsely flip the local Ollama card to "API key configured" (#1410).
+    # Users who genuinely run an authenticated local Ollama can still set a key
+    # via providers.ollama.api_key in config.yaml — that path remains supported
+    # by _provider_has_key().
+    "ollama-cloud": "OLLAMA_API_KEY",
+    # Bare "lmstudio" maps to LM_API_KEY — the canonical env var the agent CLI
+    # runtime reads (hermes_cli/auth.py:182, api_key_env_vars=("LM_API_KEY",)).
+    # Pre-#1499/#1500 the WebUI used LMSTUDIO_API_KEY here, which made Settings
+    # report keys correctly but the agent runtime ignored them — masked in
+    # practice by the LMSTUDIO_NOAUTH_PLACEHOLDER for keyless local installs.
+    # Aligning to LM_API_KEY makes a configured LM Studio key actually work
+    # for chat. The legacy LMSTUDIO_API_KEY name is read by `_provider_has_key`
+    # via _PROVIDER_ENV_VAR_ALIASES below so existing users don't see Settings
+    # flip to "no key" after upgrading.
+    "lmstudio": "LM_API_KEY",
+    "nvidia": "NVIDIA_API_KEY",
+}
+
+# Read-only legacy env-var aliases.  When `_provider_has_key(pid)` looks up its
+# canonical env var name and finds nothing, it also checks any aliases listed
+# here.  Onboarding (api/onboarding.py:apply_onboarding_setup) only writes the
+# canonical name.  Use this for env vars that were renamed in a past release;
+# add an entry, ship for a few releases, then remove the alias once enough
+# users have upgraded.
+_PROVIDER_ENV_VAR_ALIASES: dict[str, tuple[str, ...]] = {
+    # #1500 — agent runtime reads LM_API_KEY (canonical), but WebUI builds
+    # ≤ v0.50.272 wrote LMSTUDIO_API_KEY into .env.  Keep reading both.
+    "lmstudio": ("LMSTUDIO_API_KEY",),
+}
+
+# Providers that use OAuth or token flows — their credentials are managed
+# through the Hermes CLI, not via API keys.  The WebUI cannot set these.
+_OAUTH_PROVIDERS = frozenset({
+    "copilot",
+    "copilot-acp",
+    "nous",
+    "openai-codex",
+    "qwen-oauth",
+})
+
+# SECTION: Helper functions
+
+
+def _get_hermes_home() -> Path:
+    """Return the active Hermes home directory."""
+    try:
+        from api.profiles import get_active_hermes_home
+        return get_active_hermes_home()
+    except ImportError:
+        return Path.home() / ".hermes"
+
+
+def _load_env_file(env_path: Path) -> dict[str, str]:
+    """Read key=value pairs from a .env file."""
+    values: dict[str, str] = {}
+    if not env_path.exists():
+        return values
+    try:
+        for raw in env_path.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    except Exception:
+        return {}
+    return values
+
+
+def _write_env_file(env_path: Path, updates: dict[str, str | None]) -> None:
+    """Write key=value pairs to the .env file.
+
+    Values of ``None`` cause the key to be removed.
+
+    Preserves comments, blank lines, and original key order (#1164).
+    New keys are appended at the end of the file with a blank-line separator.
+
+    Holds ``_ENV_LOCK`` from ``api.streaming`` for the entire load → modify →
+    write cycle to prevent TOCTOU races between concurrent POST /api/providers
+    calls (each reading the same file baseline and overwriting the other's key).
+    Also serialises os.environ mutations with streaming sessions.
+    """
+    from api.streaming import _ENV_LOCK
+    import stat as _stat
+
+    with _ENV_LOCK:
+        # ── Read existing lines (preserving comments and blank lines) ──
+        existing_lines: list[str] = []
+        if env_path.exists():
+            try:
+                existing_lines = env_path.read_text(encoding="utf-8").splitlines()
+            except Exception:
+                existing_lines = []
+
+        # Map each existing key to its line index so we can update in-place.
+        existing_key_indices: dict[str, int] = {}
+        for _i, _raw in enumerate(existing_lines):
+            _stripped = _raw.strip()
+            if _stripped and not _stripped.startswith("#") and "=" in _stripped:
+                _existing_key_indices_key = _stripped.split("=", 1)[0].strip()
+                existing_key_indices[_existing_key_indices_key] = _i
+
+        output_lines = list(existing_lines)
+        new_keys: list[str] = []
+
+        for key, value in updates.items():
+            if value is None:
+                # Mark the line for removal (None sentinel) and clear env.
+                os.environ.pop(key, None)
+                if key in existing_key_indices:
+                    output_lines[existing_key_indices[key]] = None  # type: ignore[assignment]
+                continue
+            clean = str(value).strip()
+            if not clean:
+                continue
+            # Reject embedded newlines/carriage returns to prevent .env injection
+            if "\n" in clean or "\r" in clean:
+                raise ValueError("API key must not contain newline characters.")
+            os.environ[key] = clean
+
+            if key in existing_key_indices:
+                output_lines[existing_key_indices[key]] = f"{key}={clean}"
+            else:
+                new_keys.append(f"{key}={clean}")
+
+        # Remove deleted lines (None sentinels)
+        output_lines = [l for l in output_lines if l is not None]
+
+        # Append new keys after a blank-line separator
+        if new_keys:
+            if output_lines and output_lines[-1].strip() != "":
+                output_lines.append("")
+            output_lines.extend(new_keys)
+
+        env_path.parent.mkdir(parents=True, exist_ok=True)
+        content = "\n".join(output_lines)
+        if content:
+            content += "\n"
+        # Atomic write via tempfile + os.replace so cross-process readers
+        # (Telegram bot, CLI) never see a half-truncated file.  The shared
+        # ``~/.hermes/.env`` is also written by ``hermes_cli.config.save_env_value``
+        # using the same atomic pattern; matching it here closes the
+        # cross-process leg of #1164 (within-process is covered by _ENV_LOCK).
+        _mode = _stat.S_IRUSR | _stat.S_IWUSR  # 0o600
+        import tempfile as _tempfile
+        _tmp_fd, _tmp_path = _tempfile.mkstemp(
+            dir=str(env_path.parent), prefix=".env_", suffix=".tmp"
+        )
+        try:
+            with os.fdopen(_tmp_fd, "w", encoding="utf-8") as _f:
+                _f.write(content)
+                _f.flush()
+                os.fsync(_f.fileno())
+            os.chmod(_tmp_path, _mode)  # tighten before rename so readers see 0600
+            os.replace(_tmp_path, env_path)
+        except BaseException:
+            try:
+                os.unlink(_tmp_path)
+            except OSError:
+                pass
+            raise
+        try:
+            env_path.chmod(_mode)
+        except OSError:
+            pass
+
+
+def _provider_has_key(provider_id: str) -> bool:
+    """Check whether a provider has a configured API key.
+
+    Checks (in order):
+    1. ``~/.hermes/.env`` for the known env var
+    2. ``os.environ`` for the known env var
+    3. ``config.yaml → model.api_key`` (only if provider is the active one)
+    4. ``config.yaml → providers.<id>.api_key``
+    5. ``config.yaml → custom_providers[].api_key`` (for custom providers)
+    """
+    env_var = _PROVIDER_ENV_VAR.get(provider_id)
+    if env_var:
+        env_path = _get_hermes_home() / ".env"
+        env_values = _load_env_file(env_path)
+        if env_values.get(env_var):
+            return True
+        if os.getenv(env_var):
+            return True
+        # Fall back to legacy env-var aliases (e.g. lmstudio's pre-#1500
+        # LMSTUDIO_API_KEY name) so existing users don't lose detection
+        # after an env-var rename.  See _PROVIDER_ENV_VAR_ALIASES.
+        for alias in _PROVIDER_ENV_VAR_ALIASES.get(provider_id, ()) or ():
+            if env_values.get(alias):
+                return True
+            if os.getenv(alias):
+                return True
+
+    cfg = get_config()
+    # Check model.api_key — only match if this provider is the active one.
+    # Previously this checked globally, causing all providers to show
+    # "configured" when the active provider had a top-level api_key.
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, dict) and str(model_cfg.get("api_key") or "").strip():
+        active_provider = model_cfg.get("provider")
+        if active_provider and str(active_provider).strip().lower() == provider_id.lower():
+            return True
+    # Check providers.<id>.api_key
+    providers_cfg = cfg.get("providers", {})
+    if isinstance(providers_cfg, dict):
+        provider_cfg = providers_cfg.get(provider_id, {})
+        if isinstance(provider_cfg, dict) and str(provider_cfg.get("api_key") or "").strip():
+            return True
+    # Check custom_providers
+    custom_providers = cfg.get("custom_providers", [])
+    if isinstance(custom_providers, list):
+        for cp in custom_providers:
+            if isinstance(cp, dict):
+                cp_name = (cp.get("name") or "").strip().lower().replace(" ", "-")
+                if f"custom:{cp_name}" == provider_id or cp.get("name", "").strip().lower() == provider_id:
+                    if str(cp.get("api_key") or "").strip():
+                        return True
+    return False
+
+
+def _provider_is_oauth(provider_id: str) -> bool:
+    """Check whether a provider uses OAuth/token flows (managed by CLI)."""
+    return provider_id in _OAUTH_PROVIDERS
+
+
+# SECTION: Public API
+
+
+def get_providers() -> dict[str, Any]:
+    """Return a list of all known providers with their configuration status.
+
+    Each entry contains:
+    - ``id``: canonical provider slug
+    - ``display_name``: human-readable name
+    - ``has_key``: whether an API key is configured
+    - ``configurable``: whether the key can be set from the WebUI
+    - ``key_source``: where the key was found (``env_file``, ``env_var``,
+      ``config_yaml``, ``oauth``, ``none``)
+    - ``models``: list of known model IDs for this provider
+    """
+    providers = []
+
+    # Collect all known provider IDs from multiple sources
+    known_ids = set(_PROVIDER_DISPLAY.keys()) | set(_PROVIDER_MODELS.keys())
+
+    # Also detect providers from config.yaml providers section
+    cfg = get_config()
+    providers_cfg = cfg.get("providers", {})
+    if isinstance(providers_cfg, dict):
+        known_ids.update(providers_cfg.keys())
+
+    # Add OAuth providers even if not in _PROVIDER_DISPLAY
+    known_ids.update(_OAUTH_PROVIDERS)
+
+    for pid in sorted(known_ids):
+        display_name = _PROVIDER_DISPLAY.get(pid, pid.replace("-", " ").title())
+        is_oauth = _provider_is_oauth(pid)
+        has_key = _provider_has_key(pid)
+
+        # Determine key source
+        key_source = "none"
+        auth_error = None
+        if is_oauth:
+            key_source = "oauth"
+            # Check if actually authenticated via hermes_cli.
+            # IMPORTANT: do not unconditionally overwrite has_key from _provider_has_key().
+            # A token in config.yaml is a valid credential even when get_auth_status()
+            # returns logged_in=False (e.g. token not in the hermes credential pool,
+            # or refresh token consumed by native Codex CLI / VS Code extension).
+            try:
+                from hermes_cli.auth import get_auth_status as _gas
+                status = _gas(pid)
+                if isinstance(status, dict) and status.get("logged_in"):
+                    has_key = True
+                    key_source = status.get("key_source", "oauth")
+                elif has_key:
+                    # _provider_has_key() found a token in config.yaml — respect it
+                    # rather than hiding a working credential from the Settings UI.
+                    key_source = "config_yaml"
+                    auth_error = status.get("error") if isinstance(status, dict) else None
+                else:
+                    has_key = False
+                    auth_error = status.get("error") if isinstance(status, dict) else None
+            except Exception:
+                # Import failed or auth check errored — don't override a known-good
+                # key just because the hermes_cli auth module is unavailable.
+                logger.debug("hermes_cli auth check failed for %s", pid, exc_info=True)
+                # keep has_key from _provider_has_key()
+        elif has_key:
+            env_var = _PROVIDER_ENV_VAR.get(pid)
+            if env_var:
+                env_path = _get_hermes_home() / ".env"
+                env_values = _load_env_file(env_path)
+                if env_values.get(env_var):
+                    key_source = "env_file"
+                elif os.getenv(env_var):
+                    key_source = "env_var"
+                else:
+                    # Canonical name not set; check legacy aliases (e.g. lmstudio's
+                    # pre-#1500 LMSTUDIO_API_KEY) so existing users see "env_file"
+                    # instead of being misreported as "config_yaml" when the key
+                    # actually lives in .env under the old name.
+                    aliased = False
+                    for alias in _PROVIDER_ENV_VAR_ALIASES.get(pid, ()) or ():
+                        if env_values.get(alias):
+                            key_source = "env_file"
+                            aliased = True
+                            break
+                        if os.getenv(alias):
+                            key_source = "env_var"
+                            aliased = True
+                            break
+                    if not aliased:
+                        key_source = "config_yaml"
+            else:
+                key_source = "config_yaml"
+        elif pid not in _PROVIDER_ENV_VAR:
+            # Fallback: provider is not a known API-key provider and not in
+            # the hardcoded _OAUTH_PROVIDERS set.  It may be a custom or
+            # newly-added OAuth provider (e.g. Anthropic connected via OAuth).
+            # Check live auth status so the Providers tab agrees with the
+            # model picker (#1212).
+            #
+            # IMPORTANT: we skip providers in _PROVIDER_ENV_VAR because they
+            # are pure API-key providers — calling get_auth_status() for every
+            # unconfigured API-key provider would add unnecessary latency
+            # (network round-trip per provider) on the Settings page.
+            # Validate pid looks like a real provider before probing
+            import re as _re
+            if _re.match(r'^[a-z][a-z0-9_-]{0,63}$', pid):
+                try:
+                    from hermes_cli.auth import get_auth_status as _gas
+                    status = _gas(pid)
+                    if isinstance(status, dict) and status.get("logged_in"):
+                        has_key = True
+                        # Constrain key_source to a known-safe closed set
+                        _raw_ks = status.get("key_source", "")
+                        key_source = _raw_ks if _raw_ks in {"oauth", "env", "config", "token"} else "oauth"
+                        is_oauth = True
+                except Exception:
+                    pass
+
+        models = list(_PROVIDER_MODELS.get(pid, []))
+        # Nous Portal: prefer the live catalog so the providers card matches
+        # the dropdown picker (#1538). Same fallback shape as the static-only
+        # case below — when hermes_cli is unavailable or its lookup raises,
+        # we keep the four-entry curated list.
+        if pid == "nous":
+            try:
+                from hermes_cli.models import provider_model_ids as _provider_model_ids
+
+                live_ids = _provider_model_ids("nous") or []
+                if live_ids:
+                    # Lazy-import to avoid circular dep with api.config.
+                    from api.config import _format_nous_label
+
+                    models = [
+                        {"id": f"@nous:{mid}", "label": _format_nous_label(mid)}
+                        for mid in live_ids
+                    ]
+            except Exception:
+                logger.debug("Failed to load Nous Portal models from hermes_cli")
+        # Also include models from config.yaml providers section
+        if isinstance(providers_cfg, dict):
+            provider_cfg = providers_cfg.get(pid, {})
+            if isinstance(provider_cfg, dict) and "models" in provider_cfg:
+                cfg_models = provider_cfg["models"]
+                if isinstance(cfg_models, dict):
+                    models = models + [{"id": k, "label": k} for k in cfg_models.keys()]
+                elif isinstance(cfg_models, list):
+                    models = models + [{"id": k, "label": k} for k in cfg_models]
+
+        providers.append({
+            "id": pid,
+            "display_name": display_name,
+            "has_key": has_key,
+            "configurable": not is_oauth and pid in _PROVIDER_ENV_VAR,
+            "is_oauth": is_oauth,
+            "key_source": key_source,
+            "auth_error": auth_error,
+            "models": models,
+        })
+
+    # Scan custom_providers from config.yaml (e.g. glmcode, timicc)
+    custom_providers_cfg = cfg.get("custom_providers", [])
+    if isinstance(custom_providers_cfg, list):
+        for cp in custom_providers_cfg:
+            if not isinstance(cp, dict) or not cp.get("name"):
+                continue
+            cp_name = str(cp["name"]).strip()
+            cp_id = f"custom:{cp_name}"
+            # Collect models from `models` list or `model` single
+            cp_models = []
+            if isinstance(cp.get("models"), list):
+                cp_models = [{"id": str(m), "label": str(m)} for m in cp["models"]]
+            elif cp.get("model"):
+                cp_models = [{"id": cp["model"], "label": cp["model"]}]
+            # Check for env var reference (${VAR_NAME} pattern)
+            cp_api_key = str(cp.get("api_key") or "")
+            cp_has_key = bool(cp_api_key.strip())
+            # Replace env var reference to check actual value
+            if cp_api_key.startswith("${") and cp_api_key.endswith("}"):
+                env_var = cp_api_key[2:-1]
+                cp_has_key = bool(os.getenv(env_var, "").strip())
+            providers.append({
+                "id": cp_id,
+                "display_name": cp_name,
+                "has_key": cp_has_key,
+                "configurable": False,  # custom providers managed via config.yaml
+                "key_source": "config_yaml" if cp_has_key else "none",
+                "models": cp_models,
+            })
+
+    # Determine active provider
+    active_provider = None
+    model_cfg = cfg.get("model", {})
+    if isinstance(model_cfg, dict):
+        active_provider = model_cfg.get("provider")
+
+    return {
+        "providers": providers,
+        "active_provider": active_provider,
+    }
+
+
+def set_provider_key(provider_id: str, api_key: str | None) -> dict[str, Any]:
+    """Set or update the API key for a provider.
+
+    Writes the key to ``~/.hermes/.env`` using the standard env var name.
+    If ``api_key`` is None or empty, the key is removed.
+
+    Returns a status dict with the operation result.
+    """
+    provider_id = provider_id.strip().lower()
+
+    if not provider_id:
+        return {"ok": False, "error": "Provider ID is required."}
+
+    if _provider_is_oauth(provider_id):
+        return {
+            "ok": False,
+            "error": f"'{_PROVIDER_DISPLAY.get(provider_id, provider_id)}' uses OAuth authentication. "
+                     f"Use `hermes model` in the terminal to configure it.",
+        }
+
+    env_var = _PROVIDER_ENV_VAR.get(provider_id)
+    if not env_var:
+        return {
+            "ok": False,
+            "error": f"Cannot configure API key for '{_PROVIDER_DISPLAY.get(provider_id, provider_id)}'. "
+                     f"This provider does not have a known env var mapping.",
+        }
+
+    # Validate API key format (basic sanity check)
+    if api_key:
+        api_key = api_key.strip()
+        if "\n" in api_key or "\r" in api_key:
+            return {"ok": False, "error": "API key must not contain newline characters."}
+        if len(api_key) < 8:
+            return {"ok": False, "error": "API key appears too short."}
+
+    env_path = _get_hermes_home() / ".env"
+    try:
+        _write_env_file(env_path, {env_var: api_key})
+    except ValueError as exc:
+        return {"ok": False, "error": str(exc)}
+    except Exception as exc:
+        logger.exception("Failed to write env file for provider %s", provider_id)
+        return {"ok": False, "error": f"Failed to save API key: {exc}"}
+
+    # Invalidate the model cache so the dropdown refreshes on next request.
+    # Using invalidate_models_cache() instead of reload_config() to avoid
+    # disrupting active streaming sessions that may be reading config.cfg.
+    invalidate_models_cache()
+
+    return {
+        "ok": True,
+        "provider": provider_id,
+        "display_name": _PROVIDER_DISPLAY.get(provider_id, provider_id),
+        "action": "updated" if api_key else "removed",
+    }
+
+
+def remove_provider_key(provider_id: str) -> dict[str, Any]:
+    """Remove the API key for a provider.
+
+    Removes the key from ``~/.hermes/.env`` (via ``set_provider_key``)
+    and also cleans up ``config.yaml`` if the key is stored there
+    (``providers.<id>.api_key`` or top-level ``model.api_key`` when this
+    provider is the active one).
+
+    Returns a status dict with the operation result.
+    """
+    result = set_provider_key(provider_id, None)
+
+    # Even if the .env removal succeeded, the key might also live in
+    # config.yaml (e.g. providers.<id>.api_key or model.api_key).
+    # Clean those up so _provider_has_key() returns False after removal.
+    if result.get("ok"):
+        _clean_provider_key_from_config(provider_id)
+
+    return result
+
+
+def _clean_provider_key_from_config(provider_id: str) -> None:
+    """Remove provider API key entries from config.yaml.
+
+    Handles three storage locations:
+    1. ``providers.<id>.api_key`` — per-provider key
+    2. ``model.api_key`` — top-level key (only if provider is active)
+    3. ``custom_providers[].api_key`` — custom provider entries
+
+    Writes back to config.yaml only if something was actually removed.
+    Uses ``_cfg_lock`` to prevent TOCTOU races.
+    """
+    from api.config import _cfg_lock
+
+    try:
+        config_path = _get_config_path()
+    except Exception:
+        return
+
+    if not config_path.exists():
+        return
+
+    try:
+        import yaml as _yaml
+
+        changed = False
+
+        with _cfg_lock:
+            raw = config_path.read_text(encoding="utf-8")
+            cfg = _yaml.safe_load(raw)
+            if not isinstance(cfg, dict):
+                return
+
+            # 1. Clean providers.<id>.api_key
+            providers_cfg = cfg.get("providers", {})
+            if isinstance(providers_cfg, dict):
+                provider_cfg = providers_cfg.get(provider_id, {})
+                if isinstance(provider_cfg, dict) and provider_cfg.get("api_key"):
+                    del provider_cfg["api_key"]
+                    changed = True
+
+            # 2. Clean model.api_key — only if this provider is the active one
+            model_cfg = cfg.get("model", {})
+            if isinstance(model_cfg, dict) and model_cfg.get("api_key"):
+                active_provider = model_cfg.get("provider")
+                if active_provider and str(active_provider).strip().lower() == provider_id.lower():
+                    del model_cfg["api_key"]
+                    changed = True
+
+            # 3. Clean custom_providers[].api_key
+            custom_providers = cfg.get("custom_providers", [])
+            if isinstance(custom_providers, list):
+                for cp in custom_providers:
+                    if isinstance(cp, dict):
+                        cp_name = (cp.get("name") or "").strip().lower().replace(" ", "-")
+                        if f"custom:{cp_name}" == provider_id or cp.get("name", "").strip().lower() == provider_id:
+                            if cp.get("api_key"):
+                                del cp["api_key"]
+                                changed = True
+
+            if changed:
+                _save_yaml_config_file(config_path, cfg)
+        # Sync in-memory cache and bust model TTL cache
+        # MUST be called outside _cfg_lock to avoid deadlock:
+        # _cfg_lock is a threading.Lock (non-reentrant) and
+        # reload_config() also acquires _cfg_lock internally.
+        if changed:
+            reload_config()
+    except Exception:
+        logger.exception("Failed to clean provider key from config.yaml for %s", provider_id)

api/rollback.py

@@ -0,0 +1,320 @@
+"""
+Hermes Web UI -- Filesystem checkpoint (rollback) API.
+
+Provides endpoints to list, diff, and restore filesystem checkpoints
+created by the Hermes agent's CheckpointManager.  Checkpoints live at
+``{hermes_home}/checkpoints/<hash>/`` as shadow git repositories.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Checkpoint identifiers are SHA-style hex hashes from the agent's
+# CheckpointManager. We only allow [A-Za-z0-9_.-]{1,64} (no '/' so the
+# value cannot be a path separator, no leading '.' so it cannot escape
+# upward via '..'/'.'). This is defense-in-depth: the workspace arg is
+# already allowlisted, but ``Path() / "../escape"`` does not normalize,
+# so without this guard a `checkpoint` value of `../<other-ws-hash>/<sha>`
+# would let any authenticated caller diff or restore from another
+# allowlisted workspace's checkpoint store. (Opus pre-release advisor.)
+_CHECKPOINT_ID_RE = re.compile(r"^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,63}$")
+
+
+def _validate_checkpoint_id(checkpoint: str) -> str:
+    cid = str(checkpoint or "").strip()
+    if not cid or cid in (".", "..") or not _CHECKPOINT_ID_RE.fullmatch(cid):
+        raise ValueError(
+            "checkpoint id must match [A-Za-z0-9_-][A-Za-z0-9_.-]{0,63}"
+        )
+    return cid
+
+
+def _hermes_home() -> Path:
+    """Return the active Hermes home directory."""
+    try:
+        from api.profiles import get_active_hermes_home
+        return Path(get_active_hermes_home())
+    except Exception:
+        return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
+
+
+def _workspace_hash(workspace: str) -> str:
+    """Derive the checkpoint directory name from a workspace path.
+
+    Matches the agent's CheckpointManager._get_checkpoint_dir logic:
+    SHA-256 of the canonical workspace path.
+    """
+    try:
+        canonical = os.path.realpath(workspace)
+    except (OSError, ValueError):
+        canonical = workspace
+    return hashlib.sha256(canonical.encode()).hexdigest()[:12]
+
+
+def _checkpoint_root() -> Path:
+    return _hermes_home() / "checkpoints"
+
+
+def _resolve_workspace(workspace: str) -> str:
+    """Validate and return the canonical workspace path.
+
+    Security: workspace must match a known configured workspace
+    (from workspaces.json or session-attached workspaces).
+    """
+    if not workspace or not isinstance(workspace, str):
+        raise ValueError("workspace is required")
+    # Basic path validation
+    resolved = os.path.realpath(workspace)
+    if not os.path.isdir(resolved):
+        raise ValueError(f"Workspace does not exist: {workspace}")
+    # Security: confirm workspace is in the known list
+    try:
+        from api.workspace import load_workspaces
+        known_paths = set()
+        for ws in load_workspaces():
+            p = ws.get("path", "")
+            if p:
+                known_paths.add(os.path.realpath(p))
+        if resolved not in known_paths:
+            raise ValueError(f"Workspace not in configured list: {workspace}")
+    except ImportError:
+        logger.warning("Could not load workspace list for rollback validation")
+    return resolved
+
+
+def _find_git() -> str:
+    """Return the path to the git binary."""
+    return shutil.which("git") or "git"
+
+
+# ── Public API functions (called from routes.py) ────────────────────────────
+
+
+def list_checkpoints(workspace: str) -> dict[str, Any]:
+    """List all checkpoints for a workspace.
+
+    Returns a dict with:
+        checkpoints: list of checkpoint objects
+        workspace: resolved workspace path
+        checkpoint_dir: the checkpoint directory path
+    """
+    resolved = _resolve_workspace(workspace)
+    ws_hash = _workspace_hash(resolved)
+    ckpt_dir = _checkpoint_root() / ws_hash
+
+    checkpoints = []
+    if not ckpt_dir.is_dir():
+        return {"checkpoints": [], "workspace": resolved, "checkpoint_dir": str(ckpt_dir)}
+
+    # Each checkpoint is a git repo in <ckpt_dir>/<commit_hash>/
+    git = _find_git()
+    for entry in sorted(ckpt_dir.iterdir(), key=lambda p: p.stat().st_mtime if p.is_dir() else 0, reverse=True):
+        if not entry.is_dir():
+            continue
+        ckpt_info = _inspect_checkpoint(entry, git)
+        if ckpt_info:
+            checkpoints.append(ckpt_info)
+
+    return {
+        "checkpoints": checkpoints,
+        "workspace": resolved,
+        "checkpoint_dir": str(ckpt_dir),
+    }
+
+
+def _inspect_checkpoint(ckpt_path: Path, git: str) -> dict[str, Any] | None:
+    """Extract metadata from a single checkpoint directory."""
+    git_dir = ckpt_path / ".git"
+    if not git_dir.is_dir():
+        return None
+
+    name = ckpt_path.name
+    try:
+        result = subprocess.run(
+            [git, "-C", str(ckpt_path), "log", "--format=%H%n%s%n%aI", "-1"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return None
+
+        lines = result.stdout.strip().split("\n")
+        commit_hash = lines[0] if len(lines) > 0 else name
+        message = lines[1] if len(lines) > 1 else "checkpoint"
+        date_str = lines[2] if len(lines) > 2 else ""
+
+        # Parse date for display
+        date_display = ""
+        if date_str:
+            try:
+                dt = datetime.fromisoformat(date_str)
+                date_display = dt.strftime("%Y-%m-%d %H:%M")
+            except (ValueError, TypeError):
+                date_display = date_str
+
+        # Count files
+        files_result = subprocess.run(
+            [git, "-C", str(ckpt_path), "ls-files"],
+            capture_output=True, text=True, timeout=5,
+        )
+        file_count = len(files_result.stdout.strip().split("\n")) if files_result.stdout.strip() else 0
+
+        return {
+            "id": name,
+            "commit": commit_hash[:12],
+            "message": message,
+            "date": date_str,
+            "date_display": date_display,
+            "files": file_count,
+            "path": str(ckpt_path),
+        }
+    except (subprocess.TimeoutExpired, OSError) as e:
+        logger.debug("Failed to inspect checkpoint %s: %s", ckpt_path, e)
+        return None
+
+
+def get_checkpoint_diff(workspace: str, checkpoint: str) -> dict[str, Any]:
+    """Show the diff between a checkpoint and the current workspace state.
+
+    Returns a dict with:
+        diff: unified diff text
+        files_changed: list of changed file paths
+    """
+    resolved = _resolve_workspace(workspace)
+    checkpoint = _validate_checkpoint_id(checkpoint)
+    ws_hash = _workspace_hash(resolved)
+    ckpt_dir = _checkpoint_root() / ws_hash / checkpoint
+
+    if not ckpt_dir.is_dir():
+        raise ValueError(f"Checkpoint not found: {checkpoint}")
+
+    git = _find_git()
+
+    # Get list of files in the checkpoint
+    ls_result = subprocess.run(
+        [git, "-C", str(ckpt_dir), "ls-files"],
+        capture_output=True, text=True, timeout=10,
+    )
+    if ls_result.returncode != 0:
+        raise ValueError("Failed to list checkpoint files")
+
+    ckpt_files = [f for f in ls_result.stdout.strip().split("\n") if f]
+    files_changed = []
+    diff_lines = []
+
+    for rel_path in ckpt_files:
+        ckpt_file = ckpt_dir / rel_path
+        ws_file = Path(resolved) / rel_path
+
+        if not ckpt_file.is_file():
+            continue
+
+        # Read checkpoint version
+        try:
+            ckpt_content = ckpt_file.read_text(errors="replace")
+        except OSError:
+            continue
+
+        # Read workspace version (if exists)
+        if ws_file.is_file():
+            try:
+                ws_content = ws_file.read_text(errors="replace")
+            except OSError:
+                ws_content = ""
+        else:
+            ws_content = None  # File was deleted in workspace
+
+        if ws_content is None:
+            # File exists in checkpoint but not in workspace (deleted)
+            files_changed.append({"file": rel_path, "status": "deleted"})
+            diff_lines.append(f"--- a/{rel_path}")
+            diff_lines.append(f"+++ /dev/null")
+            diff_lines.append("@@ -1,{lines} +0,0 @@".format(lines=len(ckpt_content.splitlines())))
+            for line in ckpt_content.splitlines():
+                diff_lines.append(f"-{line}")
+        elif ckpt_content != ws_content:
+            # File changed
+            import difflib
+            ckpt_lines = ckpt_content.splitlines(keepends=True)
+            ws_lines = ws_content.splitlines(keepends=True)
+            diff = list(difflib.unified_diff(ckpt_lines, ws_lines, fromfile=f"a/{rel_path}", tofile=f"b/{rel_path}", lineterm=""))
+            if diff:
+                files_changed.append({"file": rel_path, "status": "modified"})
+                diff_lines.extend(diff)
+
+    # Check for new files in workspace that aren't in checkpoint
+    # (skip for performance — diff is primarily for seeing what the checkpoint captures)
+
+    return {
+        "checkpoint": checkpoint,
+        "workspace": resolved,
+        "diff": "\n".join(diff_lines) if diff_lines else "",
+        "files_changed": files_changed,
+        "total_changes": len(files_changed),
+    }
+
+
+def restore_checkpoint(workspace: str, checkpoint: str) -> dict[str, Any]:
+    """Restore a checkpoint by copying files back to the workspace.
+
+    Only restores files that exist in the checkpoint.  Does NOT delete
+    files that were added after the checkpoint was created.
+
+    Returns a dict with:
+        ok: True
+        files_restored: list of restored file paths
+    """
+    resolved = _resolve_workspace(workspace)
+    checkpoint = _validate_checkpoint_id(checkpoint)
+    ws_hash = _workspace_hash(resolved)
+    ckpt_dir = _checkpoint_root() / ws_hash / checkpoint
+
+    if not ckpt_dir.is_dir():
+        raise ValueError(f"Checkpoint not found: {checkpoint}")
+
+    git = _find_git()
+
+    # Get list of files in the checkpoint
+    ls_result = subprocess.run(
+        [git, "-C", str(ckpt_dir), "ls-files"],
+        capture_output=True, text=True, timeout=10,
+    )
+    if ls_result.returncode != 0:
+        raise ValueError("Failed to list checkpoint files")
+
+    ckpt_files = [f for f in ls_result.stdout.strip().split("\n") if f]
+    restored = []
+    errors = []
+
+    for rel_path in ckpt_files:
+        ckpt_file = ckpt_dir / rel_path
+        ws_file = Path(resolved) / rel_path
+
+        if not ckpt_file.is_file():
+            continue
+
+        try:
+            ws_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(ckpt_file), str(ws_file))
+            restored.append(rel_path)
+        except OSError as e:
+            errors.append({"file": rel_path, "error": str(e)})
+            logger.warning("Failed to restore %s: %s", rel_path, e)
+
+    return {
+        "ok": True,
+        "checkpoint": checkpoint,
+        "workspace": resolved,
+        "files_restored": restored,
+        "files_restored_count": len(restored),
+        "errors": errors,
+    }

api/session_ops.py

@@ -0,0 +1,195 @@
+"""Session-mutation operations for slash commands (/retry, /undo) and
+read-only aggregators (/status, /usage). Operates on the webui's own
+JSON Session store (api/models.py), not on hermes-agent's SQLite.
+
+Behavior parity reference: gateway/run.py:_handle_*_command in
+the hermes-agent repo.
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+
+from api.config import LOCK, _get_session_agent_lock
+from api.models import get_session, SESSIONS
+
+logger = logging.getLogger(__name__)
+
+
+def _truncate_at_last_user(messages):
+    history = messages or []
+    last_user_idx = None
+    for i in range(len(history) - 1, -1, -1):
+        if isinstance(history[i], dict) and history[i].get('role') == 'user':
+            last_user_idx = i
+            break
+    if last_user_idx is None:
+        return None
+    return history[:last_user_idx]
+
+
+def retry_last(session_id: str) -> dict[str, Any]:
+    """Truncate the session to before the last user message, return its text.
+
+    Mirrors gateway/run.py:_handle_retry_command. Caller (webui frontend)
+    is expected to put the returned text back in the composer and call
+    send() to resume the conversation -- the agent's gateway calls its own
+    _handle_message; the webui has no equivalent in-process pipeline.
+
+    Raises:
+        KeyError: session not found
+        ValueError: no user message in transcript
+    """
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        # get_session() and Session.save() both acquire the module-level LOCK
+        # internally (the latter via _write_session_index()), and LOCK is a
+        # non-reentrant threading.Lock — so they MUST be called outside our
+        # own `with LOCK:` block to avoid self-deadlocking.
+        #
+        # The race we close is the read-modify-write of s.messages: two
+        # concurrent /api/session/retry calls could otherwise both compute the
+        # same last_user_idx from the same history and double-truncate. We
+        # serialize just the in-memory mutation; persistence happens inside
+        # the per-session lock so the checkpoint thread cannot race us.
+        #
+        # Stale-object guard: on a cache miss, two concurrent get_session()
+        # calls can each load and cache a *different* Session instance for the
+        # same session_id (the second store clobbers the first). Re-bind to
+        # the canonical cached instance inside the lock so the mutation lands
+        # on the object the next reader will see, not a stale parallel copy.
+        s = get_session(session_id)  # raises KeyError if missing
+        with LOCK:
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('No previous message to retry.')
+
+            last_user_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()
+    return {'last_user_text': last_user_text, 'removed_count': removed_count}
+
+
+def undo_last(session_id: str) -> dict[str, Any]:
+    """Remove the most recent user message and everything after it.
+
+    Mirrors gateway/run.py:_handle_undo_command. Returns a preview of the
+    removed text so the UI can confirm to the user.
+
+    Raises:
+        KeyError: session not found
+        ValueError: no user message in transcript
+    """
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        s = get_session(session_id)  # acquires LOCK transiently
+        with LOCK:
+            # Stale-object guard — see retry_last for the rationale.
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('Nothing to undo.')
+
+            removed_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()  # outside LOCK -- save() re-acquires LOCK via _write_session_index()
+    preview = (removed_text[:40] + '...') if len(removed_text) > 40 else removed_text
+    return {
+        'removed_count': removed_count,
+        'removed_preview': preview,
+    }
+
+
+def session_status(session_id: str) -> dict[str, Any]:
+    """Return a snapshot of session state for /status.
+
+    Webui equivalent of gateway/run.py:_handle_status_command. The agent's
+    "agent_running" comes from `session_key in self._running_agents`; the
+    webui equivalent is whether the session has an active stream
+    (active_stream_id is set).
+    """
+    s = get_session(session_id)
+    inp = int(s.input_tokens or 0)
+    out = int(s.output_tokens or 0)
+    profile = getattr(s, 'profile', None) or 'default'
+    try:
+        from api.profiles import get_hermes_home_for_profile
+        hermes_home = str(get_hermes_home_for_profile(profile))
+    except Exception:
+        hermes_home = ''
+    return {
+        'session_id': s.session_id,
+        'title': s.title,
+        'model': s.model,
+        'profile': profile,
+        'hermes_home': hermes_home,
+        'workspace': s.workspace,
+        'personality': s.personality,
+        'message_count': len(s.messages or []),
+        'created_at': s.created_at,
+        'updated_at': s.updated_at,
+        'agent_running': bool(getattr(s, 'active_stream_id', None)),
+        'input_tokens': inp,
+        'output_tokens': out,
+        'total_tokens': inp + out,
+        'estimated_cost': s.estimated_cost,
+    }
+
+
+def session_usage(session_id: str) -> dict[str, Any]:
+    """Return token usage and cost for /usage.
+
+    Mirrors gateway/run.py:_handle_usage_command's basic counters. The
+    agent shows additional fields (rate-limit headroom etc.) that depend
+    on provider API responses we don't have in webui -- those are deferred.
+    """
+    s = get_session(session_id)
+    inp = int(s.input_tokens or 0)
+    out = int(s.output_tokens or 0)
+    return {
+        'input_tokens': inp,
+        'output_tokens': out,
+        'total_tokens': inp + out,
+        'estimated_cost': s.estimated_cost,
+        'model': s.model,
+    }
+
+
+def _extract_text(content: Any) -> str:
+    """Flatten message content to plain text. Agent stores either a string
+    or a list of {type, text|...} parts; webui needs the user-typed text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for p in content:
+            if isinstance(p, dict) and p.get('type') == 'text':
+                parts.append(p.get('text', ''))
+        return ' '.join(parts)
+    return str(content)

api/startup.py

@@ -0,0 +1,128 @@
+"""Hermes Web UI -- startup helpers."""
+from __future__ import annotations
+import os, stat, subprocess, sys
+from pathlib import Path
+
+# Credential files that should never be world-readable
+_SENSITIVE_FILES = (
+    '.env',
+    'google_token.json',
+    'google_client_secret.json',
+    '.signing_key',
+    'auth.json',
+)
+
+
+def fix_credential_permissions() -> None:
+    """Ensure sensitive files in HERMES_HOME have safe permissions.
+
+    Respects:
+      - HERMES_SKIP_CHMOD=1  → bypass entirely
+      - HERMES_HOME_MODE     → group bits are allowed if set by the operator,
+                               only world-readable/world-writable files are fixed
+    """
+    if os.environ.get('HERMES_SKIP_CHMOD', '').strip() in ('1', 'true'):
+        return
+
+    # Parse operator-declared mode to know if group bits are intentional
+    declared_mode = None
+    raw_mode = os.environ.get('HERMES_HOME_MODE', '').strip()
+    if raw_mode:
+        try:
+            declared_mode = int(raw_mode, 8)
+        except ValueError:
+            pass
+
+    hermes_home = Path(os.environ.get('HERMES_HOME', str(Path.home() / '.hermes')))
+    if not hermes_home.is_dir():
+        return
+    for name in _SENSITIVE_FILES:
+        fpath = hermes_home / name
+        if not fpath.exists():
+            continue
+        try:
+            current = stat.S_IMODE(fpath.stat().st_mode)
+            # If operator declared a mode, allow group bits but still fix world bits
+            if declared_mode is not None:
+                if current & 0o007:  # other bits set (world-readable/writable)
+                    fpath.chmod(current & ~0o007)
+                    print(f'  [security] removed world bits on {fpath.name} ({oct(current)} -> {oct(current & ~0o007)})', flush=True)
+            else:
+                if current & 0o077:  # group or other bits set
+                    fpath.chmod(0o600)
+                    print(f'  [security] fixed permissions on {fpath.name} ({oct(current)} -> 0600)', flush=True)
+        except OSError:
+            pass  # best-effort; don't abort startup
+
+
+def _agent_dir() -> Path | None:
+    hermes_home = Path(os.environ.get('HERMES_HOME', str(Path.home() / '.hermes')))
+    for raw in [os.environ.get('HERMES_WEBUI_AGENT_DIR', '').strip(), str(hermes_home / 'hermes-agent')]:
+        if not raw:
+            continue
+        p = Path(raw).expanduser()
+        if p.is_dir():
+            return p.resolve()
+    return None
+
+def _trusted_agent_dir(agent_dir: Path) -> bool:
+    """Return True if agent_dir passes ownership and permission checks.
+
+    Validates that the directory is not world- or group-writable and,
+    on POSIX systems, is owned by the current process user.
+
+    Intentionally does NOT enforce a canonical path (i.e. does not require
+    the dir to be ~/.hermes/hermes-agent), so custom HERMES_WEBUI_AGENT_DIR
+    paths work correctly when HERMES_WEBUI_AUTO_INSTALL=1 is set.
+    """
+    try:
+        st = agent_dir.stat()
+        if stat.S_IMODE(st.st_mode) & 0o022:
+            # World- or group-writable — untrusted
+            return False
+        if hasattr(os, 'getuid') and st.st_uid != os.getuid():
+            # Not owned by current user (POSIX only; Windows fallback skips)
+            return False
+        return True
+    except OSError:
+        return False
+
+
+def auto_install_agent_deps() -> bool:
+    enabled = os.environ.get('HERMES_WEBUI_AUTO_INSTALL', '').strip().lower() in ('1', 'true', 'yes')
+    if not enabled:
+        print('[!!] Auto-install disabled. Set HERMES_WEBUI_AUTO_INSTALL=1 to enable.', flush=True)
+        return False
+    agent_dir = _agent_dir()
+    if agent_dir is None:
+        print('[!!] Auto-install skipped: agent directory not found.', flush=True)
+        return False
+    if not _trusted_agent_dir(agent_dir):
+        print('[!!] Auto-install skipped: agent directory failed trust check (check ownership/permissions).', flush=True)
+        return False
+    req_file = agent_dir / 'requirements.txt'
+    pyproject = agent_dir / 'pyproject.toml'
+    if req_file.exists():
+        install_args = [sys.executable, '-m', 'pip', 'install', '--quiet', '-r', str(req_file)]
+        print(f'     Installing from {req_file} ...', flush=True)
+    elif pyproject.exists():
+        install_args = [sys.executable, '-m', 'pip', 'install', '--quiet', str(agent_dir)]
+        print(f'     Installing from {agent_dir} (pyproject.toml) ...', flush=True)
+    else:
+        print('[!!] Auto-install skipped: no requirements.txt or pyproject.toml in agent dir.', flush=True)
+        return False
+    try:
+        result = subprocess.run(install_args, capture_output=True, text=True, timeout=120)
+        if result.returncode != 0:
+            print(f'[!!] pip install failed (exit {result.returncode}):', flush=True)
+            for line in (result.stderr or '').splitlines()[-10:]:
+                print(f'     {line}', flush=True)
+            return False
+        print('[ok] pip install completed.', flush=True)
+        return True
+    except subprocess.TimeoutExpired:
+        print('[!!] Auto-install timed out after 120s.', flush=True)
+        return False
+    except Exception as e:
+        print(f'[!!] Auto-install error: {e}', flush=True)
+        return False

api/state_sync.py

@@ -13,9 +13,12 @@ The bridge uses absolute token counts (not deltas) because the WebUI
 Session object already accumulates totals across turns. This avoids
 any double-counting risk.
 """
+import logging
 import os
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 def _get_state_db():
     """Get a SessionDB instance for the active profile's state.db.
@@ -31,6 +34,7 @@ def _get_state_db():
         from api.profiles import get_active_hermes_home
         hermes_home = Path(get_active_hermes_home()).expanduser().resolve()
     except Exception:
+        logger.debug("Failed to resolve hermes home, using default")
         hermes_home = Path(os.getenv('HERMES_HOME', str(Path.home() / '.hermes')))
 
     db_path = hermes_home / 'state.db'
@@ -40,10 +44,11 @@ def _get_state_db():
     try:
         return SessionDB(db_path)
     except Exception:
+        logger.debug("Failed to open state.db")
         return None
 
 
-def sync_session_start(session_id, model=None):
+def sync_session_start(session_id: str, model=None) -> None:
     """Register a WebUI session in state.db (idempotent).
     Called when a session's first message is sent.
     """
@@ -57,16 +62,17 @@ def sync_session_start(session_id, model=None):
             model=model,
         )
     except Exception:
-        pass  # never crash the WebUI for sync failures
+        logger.debug("Failed to sync session start to state.db")
     finally:
         try:
             db.close()
         except Exception:
-            pass
+            logger.debug("Failed to close state.db")
 
 
-def sync_session_usage(session_id, input_tokens=0, output_tokens=0,
-                       estimated_cost=None, model=None, title=None):
+def sync_session_usage(session_id: str, input_tokens: int=0, output_tokens: int=0,
+                       estimated_cost=None, model=None, title: str=None,
+                       message_count: int=None) -> None:
     """Update token usage and title for a WebUI session in state.db.
     Called after each turn completes. Uses absolute=True to set totals
     (the WebUI Session already accumulates across turns).
@@ -91,11 +97,22 @@ def sync_session_usage(session_id, input_tokens=0, output_tokens=0,
             try:
                 db.set_session_title(session_id, title)
             except Exception:
-                pass
+                logger.debug("Failed to sync session title to state.db")
+        # Update message count
+        if message_count is not None:
+            try:
+                def _set_msg_count(conn):
+                    conn.execute(
+                        "UPDATE sessions SET message_count = ? WHERE id = ?",
+                        (message_count, session_id),
+                    )
+                db._execute_write(_set_msg_count)
+            except Exception:
+                logger.debug("Failed to sync message count to state.db")
     except Exception:
-        pass  # never crash the WebUI for sync failures
+        logger.debug("Failed to sync session usage to state.db")
     finally:
         try:
             db.close()
         except Exception:
-            pass
+            logger.debug("Failed to close state.db")

api/terminal.py

@@ -0,0 +1,248 @@
+"""Embedded workspace terminal support for Hermes Web UI.
+
+The terminal is intentionally independent from the agent execution path.  It
+starts a shell with an explicit cwd/env per process and never mutates
+process-global os.environ, which avoids expanding the session-env race tracked
+in the agent execution layer.
+"""
+
+from __future__ import annotations
+
+import errno
+import codecs
+import fcntl
+import os
+import queue
+import select
+import shutil
+import signal
+import struct
+import subprocess
+import termios
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _set_nonblocking(fd: int) -> None:
+    flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+    fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+
+def _winsize(rows: int, cols: int) -> bytes:
+    rows = max(8, min(int(rows or 24), 80))
+    cols = max(20, min(int(cols or 80), 240))
+    return struct.pack("HHHH", rows, cols, 0, 0)
+
+
+@dataclass
+class TerminalSession:
+    session_id: str
+    workspace: str
+    proc: subprocess.Popen
+    master_fd: int
+    rows: int = 24
+    cols: int = 80
+    output: queue.Queue = field(default_factory=lambda: queue.Queue(maxsize=2000))
+    closed: threading.Event = field(default_factory=threading.Event)
+    reader: threading.Thread | None = None
+
+    def is_alive(self) -> bool:
+        return not self.closed.is_set() and self.proc.poll() is None
+
+    def put_output(self, event: str, payload: dict) -> None:
+        try:
+            self.output.put_nowait((event, payload))
+        except queue.Full:
+            # Keep the terminal responsive by dropping the oldest queued chunk.
+            try:
+                self.output.get_nowait()
+            except queue.Empty:
+                pass
+            try:
+                self.output.put_nowait((event, payload))
+            except queue.Full:
+                pass
+
+
+_TERMINALS: dict[str, TerminalSession] = {}
+_LOCK = threading.RLock()
+
+
+def _decode_terminal_output(decoder, data: bytes) -> str:
+    """Decode PTY bytes without stripping terminal control sequences."""
+    return decoder.decode(data)
+
+
+def _shell_path() -> str:
+    shell = os.environ.get("SHELL") or ""
+    if shell and Path(shell).exists():
+        return shell
+    return shutil.which("zsh") or shutil.which("bash") or shutil.which("sh") or "/bin/sh"
+
+
+def _shell_argv(shell: str) -> list[str]:
+    name = Path(shell).name
+    if name in {"zsh", "bash", "sh"}:
+        return [shell, "-i"]
+    return [shell]
+
+
+def _reader_loop(term: TerminalSession) -> None:
+    decoder = codecs.getincrementaldecoder("utf-8")("replace")
+    try:
+        while not term.closed.is_set():
+            if term.proc.poll() is not None:
+                break
+            try:
+                ready, _, _ = select.select([term.master_fd], [], [], 0.25)
+            except (OSError, ValueError):
+                break
+            if not ready:
+                continue
+            try:
+                data = os.read(term.master_fd, 8192)
+            except OSError as exc:
+                if exc.errno in (errno.EIO, errno.EBADF):
+                    break
+                raise
+            if not data:
+                break
+            text = _decode_terminal_output(decoder, data)
+            if text:
+                term.put_output("output", {"text": text})
+    except Exception as exc:
+        term.put_output("terminal_error", {"error": str(exc)})
+    finally:
+        term.closed.set()
+        code = term.proc.poll()
+        term.put_output("terminal_closed", {"exit_code": code})
+
+
+def _set_size(term: TerminalSession, rows: int, cols: int) -> None:
+    term.rows = max(8, min(int(rows or term.rows or 24), 80))
+    term.cols = max(20, min(int(cols or term.cols or 80), 240))
+    try:
+        fcntl.ioctl(term.master_fd, termios.TIOCSWINSZ, _winsize(term.rows, term.cols))
+    except OSError:
+        pass
+    try:
+        if term.proc.poll() is None:
+            os.killpg(term.proc.pid, signal.SIGWINCH)
+    except (OSError, ProcessLookupError):
+        pass
+
+
+def start_terminal(session_id: str, workspace: Path, rows: int = 24, cols: int = 80, restart: bool = False) -> TerminalSession:
+    """Start or return the embedded terminal for a WebUI session."""
+    sid = str(session_id or "").strip()
+    if not sid:
+        raise ValueError("session_id is required")
+    cwd = str(Path(workspace).expanduser().resolve())
+    if not Path(cwd).is_dir():
+        raise ValueError("workspace is not a directory")
+
+    with _LOCK:
+        current = _TERMINALS.get(sid)
+        if current and current.is_alive() and not restart and current.workspace == cwd:
+            _set_size(current, rows, cols)
+            return current
+        if current:
+            close_terminal(sid)
+
+        master_fd, slave_fd = os.openpty()
+        # Build a safe env: allowlist common shell vars, strip API keys and secrets.
+        # The PTY shell is an interactive UI surface — do not leak server credentials.
+        _SAFE_ENV_KEYS = {
+            "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL",
+            "LC_CTYPE", "LC_MESSAGES", "LANGUAGE", "TZ", "TMPDIR", "TEMP",
+            "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME",
+        }
+        env = {k: v for k, v in os.environ.items() if k in _SAFE_ENV_KEYS}
+        env.update(
+            {
+                "TERM": "xterm-256color",
+                "COLORTERM": "truecolor",
+                "COLUMNS": str(cols),
+                "LINES": str(rows),
+                "PWD": cwd,
+                "HERMES_WEBUI_TERMINAL": "1",
+            }
+        )
+        shell = _shell_path()
+        proc = subprocess.Popen(
+            _shell_argv(shell),
+            cwd=cwd,
+            env=env,
+            stdin=slave_fd,
+            stdout=slave_fd,
+            stderr=slave_fd,
+            close_fds=True,
+            start_new_session=True,
+        )
+        os.close(slave_fd)
+        _set_nonblocking(master_fd)
+
+        term = TerminalSession(
+            session_id=sid,
+            workspace=cwd,
+            proc=proc,
+            master_fd=master_fd,
+            rows=rows,
+            cols=cols,
+        )
+        _set_size(term, rows, cols)
+        term.reader = threading.Thread(target=_reader_loop, args=(term,), daemon=True)
+        term.reader.start()
+        _TERMINALS[sid] = term
+        return term
+
+
+def get_terminal(session_id: str) -> TerminalSession | None:
+    with _LOCK:
+        term = _TERMINALS.get(str(session_id or ""))
+        if term and term.is_alive():
+            return term
+        return term
+
+
+def write_terminal(session_id: str, data: str) -> None:
+    term = get_terminal(session_id)
+    if not term or not term.is_alive():
+        raise KeyError("terminal not running")
+    os.write(term.master_fd, str(data or "").encode("utf-8", errors="replace"))
+
+
+def resize_terminal(session_id: str, rows: int, cols: int) -> None:
+    term = get_terminal(session_id)
+    if not term:
+        raise KeyError("terminal not running")
+    _set_size(term, rows, cols)
+
+
+def close_terminal(session_id: str) -> bool:
+    sid = str(session_id or "")
+    with _LOCK:
+        term = _TERMINALS.pop(sid, None)
+    if not term:
+        return False
+    term.closed.set()
+    try:
+        if term.proc.poll() is None:
+            try:
+                os.killpg(term.proc.pid, signal.SIGHUP)
+            except ProcessLookupError:
+                pass
+            try:
+                term.proc.wait(timeout=1.5)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(term.proc.pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+    finally:
+        try:
+            os.close(term.master_fd)
+        except OSError:
+            pass
+    return True

api/updates.py

@@ -0,0 +1,431 @@
+"""
+Hermes Web UI -- Self-update checker.
+
+Checks if the webui and hermes-agent git repos are behind their upstream
+branches. Results are cached server-side (30-min TTL) so git fetch runs
+at most twice per hour regardless of client count.
+
+Skips repos that are not git checkouts (e.g. Docker baked images where
+.git does not exist).
+"""
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+from api.config import REPO_ROOT
+
+# Lazy -- may be None if agent not found
+try:
+    from api.config import _AGENT_DIR
+except ImportError:
+    _AGENT_DIR = None
+
+_update_cache = {'webui': None, 'agent': None, 'checked_at': 0}
+_cache_lock = threading.Lock()
+_check_in_progress = False
+_apply_lock = threading.Lock()   # prevents concurrent stash/pull/pop on same repo
+CACHE_TTL = 1800  # 30 minutes
+
+
+def _run_git(args, cwd, timeout=10):
+    """Run a git command and return (useful output, ok).
+
+    On failure, returns stderr (or stdout as fallback) so callers can
+    surface actionable git error messages instead of empty strings.
+    """
+    try:
+        r = subprocess.run(
+            ['git'] + args, cwd=str(cwd), capture_output=True,
+            text=True, timeout=timeout,
+        )
+        stdout = r.stdout.strip()
+        stderr = r.stderr.strip()
+        if r.returncode == 0:
+            return stdout, True
+        return stderr or stdout or f"git exited with status {r.returncode}", False
+    except subprocess.TimeoutExpired as exc:
+        detail = (getattr(exc, 'stderr', None) or getattr(exc, 'stdout', None) or '').strip()
+        return detail or f"git {' '.join(args)} timed out after {timeout}s", False
+    except FileNotFoundError:
+        return 'git executable not found', False
+    except OSError as exc:
+        return f'git failed to start: {exc}', False
+
+
+def _detect_webui_version() -> str:
+    """Detect the running WebUI version from git or a baked-in fallback file.
+
+    Resolution order:
+      1. ``git describe --tags --always --dirty`` — works in any git checkout.
+         Returns the exact tag on tagged commits (e.g. ``v0.50.124``), a
+         post-tag descriptor between releases (e.g. ``v0.50.124-1-ge91325d``),
+         or a bare SHA when no tags exist (shallow clones, fresh forks).
+      2. ``api/_version.py`` — a fallback written by the Docker / CI release
+         workflow when ``.git`` is not present in the image.  Expected to define
+         ``__version__ = 'vX.Y.Z'``.
+      3. ``'unknown'`` — last resort; displayed as-is in the settings badge.
+    """
+    # Timeout capped at 3s: git describe on a healthy local repo is <50ms;
+    # a 10s stall on import (NFS-mounted .git, broken git binary) is unacceptable.
+    out, ok = _run_git(['describe', '--tags', '--always', '--dirty'], REPO_ROOT, timeout=3)
+    if ok and out:
+        return out
+
+    # Docker / baked-image fallback: api/_version.py written by CI at build time.
+    # Parse with regex rather than exec() — the file holds exactly one assignment
+    # and regex is sufficient; exec() on a build artifact is an unnecessary surface.
+    version_file = REPO_ROOT / 'api' / '_version.py'
+    if version_file.exists():
+        try:
+            import re as _re
+            m = _re.search(
+                r"""__version__\s*=\s*['"]([^'"]+)['"]""",
+                version_file.read_text(encoding='utf-8'),
+            )
+            if m:
+                return m.group(1)
+        except Exception:
+            pass
+
+    return 'unknown'
+
+
+# Resolved once at import time — tags cannot change without a process restart.
+WEBUI_VERSION: str = _detect_webui_version()
+
+
+def _split_remote_ref(ref):
+    """Split 'origin/branch-name' into ('origin', 'branch-name').
+
+    Returns (None, ref) if ref contains no slash.
+    """
+    if '/' not in ref:
+        return None, ref
+    remote, branch = ref.split('/', 1)
+    return remote, branch
+
+
+def _detect_default_branch(path):
+    """Detect the remote default branch (master or main)."""
+    out, ok = _run_git(['symbolic-ref', 'refs/remotes/origin/HEAD'], path)
+    if ok and out:
+        # refs/remotes/origin/master -> master
+        return out.split('/')[-1]
+    # Fallback: try master, then main
+    for branch in ('master', 'main'):
+        _, ok = _run_git(['rev-parse', '--verify', f'origin/{branch}'], path)
+        if ok:
+            return branch
+    return 'master'
+
+
+def _check_repo(path, name):
+    """Check if a git repo is behind its upstream. Returns dict or None."""
+    if path is None or not (path / '.git').exists():
+        return None
+
+    # Fetch latest from origin (network call, cached by TTL)
+    _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
+    if not fetch_ok:
+        return {'name': name, 'behind': 0, 'error': 'fetch failed'}
+
+    # Use the current branch's upstream tracking branch, not the repo default.
+    # This avoids false "N updates behind" alerts when the user is on a feature
+    # branch and master/main has moved forward with unrelated commits.
+    # If no upstream is set (brand-new local branch), fall back to the default branch.
+    upstream, ok = _run_git(['rev-parse', '--abbrev-ref', '@{upstream}'], path)
+    if ok and upstream:
+        # upstream is like "origin/feat/foo" — use it directly in rev-list
+        compare_ref = upstream
+    else:
+        branch = _detect_default_branch(path)
+        compare_ref = f'origin/{branch}'
+
+    # Count commits behind
+    out, ok = _run_git(['rev-list', '--count', f'HEAD..{compare_ref}'], path)
+    behind = int(out) if ok and out.isdigit() else 0
+
+    # Get short SHAs for display
+    current, _ = _run_git(['rev-parse', '--short', 'HEAD'], path)
+    latest, _ = _run_git(['rev-parse', '--short', compare_ref], path)
+
+    return {
+        'name': name,
+        'behind': behind,
+        'current_sha': current,
+        'latest_sha': latest,
+        'branch': compare_ref,
+    }
+
+
+def check_for_updates(force=False):
+    """Return cached update status for webui and agent repos."""
+    global _check_in_progress
+    with _cache_lock:
+        if not force and time.time() - _update_cache['checked_at'] < CACHE_TTL:
+            return dict(_update_cache)
+        if _check_in_progress:
+            return dict(_update_cache)  # another thread is already checking
+        _check_in_progress = True
+
+    try:
+        # Run checks outside the lock (network I/O)
+        webui_info = _check_repo(REPO_ROOT, 'webui')
+        agent_info = _check_repo(_AGENT_DIR, 'agent')
+
+        with _cache_lock:
+            _update_cache['webui'] = webui_info
+            _update_cache['agent'] = agent_info
+            _update_cache['checked_at'] = time.time()
+            return dict(_update_cache)
+    finally:
+        _check_in_progress = False
+
+
+def _schedule_restart(delay: float = 2.0) -> None:
+    """Re-exec this process after *delay* seconds.
+
+    Called after a successful update so that the freshly-pulled code is
+    loaded on the next request, rather than running with a mix of old and
+    new Python modules in sys.modules.
+
+    os.execv() replaces the current process image with a fresh interpreter
+    running the same argv — sessions are preserved on disk, the HTTP port
+    is reclaimed within the delay window, and the client's own
+    ``setTimeout(() => location.reload(), 2500)`` lands after the restart.
+
+    Coordinates with ``_apply_lock``: when the user updates both webui
+    and agent, the client POSTs them sequentially.  Without coordination
+    the restart timer scheduled by the first update's success would fire
+    while the second update's git-pull is still running, killing it mid-
+    stream and leaving the second repo in an unknown partial state.
+    Blocking on ``_apply_lock`` before ``os.execv`` means a pending
+    second update always completes before the restart happens.
+    """
+    import os
+    import sys
+
+    def _do():
+        import time
+        time.sleep(delay)
+        # Hold _apply_lock through os.execv so no new update can start between
+        # the lock-release and the process replacement.  Any in-flight update
+        # finishes first (since it holds the lock), and then the process is
+        # replaced while still holding the lock — meaning no new update can
+        # sneak in during the brief TOCTOU window that existed with the
+        # original acquire-release-execv sequence.
+        # Threads die when execv replaces the process image, so the lock is
+        # released atomically by the kernel.
+        with _apply_lock:
+            try:
+                os.execv(sys.executable, [sys.executable] + sys.argv)
+            except Exception:
+                # Last-resort: if execv fails (e.g. frozen binary), just exit
+                # so the process supervisor (start.sh / Docker) restarts us.
+                os._exit(0)
+
+    threading.Thread(target=_do, daemon=True).start()
+
+
+def apply_force_update(target: str) -> dict:
+    """Force-reset the target repo to the latest remote HEAD.
+
+    Unlike apply_update() which requires a clean working tree and refuses
+    merge conflicts, this discards all local modifications (checkout .) and
+    resets to origin/<branch> — equivalent to what the diverged/conflict
+    error messages ask the user to run manually.
+
+    Should only be called when apply_update() has already returned a
+    response with ``conflict: True`` or ``diverged: True`` and the user
+    has confirmed they want to discard local changes.
+    """
+    if not _apply_lock.acquire(blocking=False):
+        return {'ok': False, 'message': 'Update already in progress'}
+    try:
+        if target == 'webui':
+            path = REPO_ROOT
+        elif target == 'agent':
+            path = _AGENT_DIR
+        else:
+            return {'ok': False, 'message': f'Unknown target: {target}'}
+
+        if path is None or not (path / '.git').exists():
+            return {'ok': False, 'message': 'Not a git repository'}
+
+        _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
+        if not fetch_ok:
+            return {
+                'ok': False,
+                'message': 'Could not reach the remote repository. Check your connection.',
+            }
+
+        upstream, ok = _run_git(['rev-parse', '--abbrev-ref', '@{upstream}'], path)
+        if ok and upstream:
+            compare_ref = upstream
+        else:
+            branch = _detect_default_branch(path)
+            compare_ref = f'origin/{branch}'
+
+        # Discard local modifications then reset to remote HEAD
+        _run_git(['checkout', '.'], path)
+        _, ok = _run_git(['reset', '--hard', compare_ref], path)
+        if not ok:
+            return {'ok': False, 'message': f'Force reset to {compare_ref} failed'}
+
+        with _cache_lock:
+            _update_cache['checked_at'] = 0
+
+        _schedule_restart()
+
+        return {
+            'ok': True,
+            'message': f'{target} force-updated to {compare_ref}',
+            'target': target,
+            'restart_scheduled': True,
+        }
+    finally:
+        _apply_lock.release()
+
+
+def apply_update(target):
+    """Stash, pull --ff-only, pop for the given target repo."""
+    if not _apply_lock.acquire(blocking=False):
+        return {'ok': False, 'message': 'Update already in progress'}
+    try:
+        return _apply_update_inner(target)
+    finally:
+        _apply_lock.release()
+
+
+def _apply_update_inner(target):
+    """Inner implementation of apply_update, called under _apply_lock."""
+    if target == 'webui':
+        path = REPO_ROOT
+    elif target == 'agent':
+        path = _AGENT_DIR
+    else:
+        return {'ok': False, 'message': f'Unknown target: {target}'}
+
+    if path is None or not (path / '.git').exists():
+        return {'ok': False, 'message': 'Not a git repository'}
+
+    # Use the current branch's upstream for pull, matching the behaviour
+    # of _check_repo. Falls back to default branch if no upstream is set.
+    upstream, ok = _run_git(['rev-parse', '--abbrev-ref', '@{upstream}'], path)
+    if ok and upstream:
+        compare_ref = upstream
+    else:
+        branch = _detect_default_branch(path)
+        compare_ref = f'origin/{branch}'
+
+    # Fetch before attempting pull, so the remote ref is current.
+    _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
+    if not fetch_ok:
+        return {
+            'ok': False,
+            'message': (
+                'Could not reach the remote repository. '
+                'Check your internet connection and try again.'
+            ),
+        }
+
+    # Check for dirty working tree (ignore untracked files — git stash
+    # doesn't include them, so stashing on '??' alone leaves nothing to pop)
+    status_out, status_ok = _run_git(
+        ['status', '--porcelain', '--untracked-files=no'], path
+    )
+    if not status_ok:
+        return {'ok': False, 'message': f'Failed to inspect repo status: {status_out[:200]}'}
+    # Fail early on unresolved merge conflicts
+    if any(line[:2] in {'DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'}
+           for line in status_out.splitlines()):
+        return {
+            'ok': False,
+            'message': (
+                f'The local {target} repo has unresolved merge conflicts. '
+                'To reset to the latest remote version run: '
+                'git -C ' + str(path) + ' checkout . && '
+                'git -C ' + str(path) + ' pull --ff-only'
+            ),
+            'conflict': True,
+        }
+    stashed = False
+    if status_out:
+        _, ok = _run_git(['stash'], path)
+        if not ok:
+            return {'ok': False, 'message': 'Failed to stash local changes'}
+        stashed = True
+
+    # Pull with ff-only (no merge commits).
+    # Split tracking refs like 'origin/main' into separate remote + branch
+    # arguments — git treats 'origin/main' as a repository name otherwise.
+    remote, branch = _split_remote_ref(compare_ref)
+    pull_args = ['pull', '--ff-only']
+    if remote:
+        pull_args.extend([remote, branch])
+    else:
+        pull_args.append(compare_ref)
+    pull_out, pull_ok = _run_git(pull_args, path, timeout=30)
+    if not pull_ok:
+        if stashed:
+            _run_git(['stash', 'pop'], path)
+
+        # Diagnose the most common failure modes and surface actionable messages.
+        pull_lower = pull_out.lower()
+        if 'not possible to fast-forward' in pull_lower or 'diverged' in pull_lower:
+            return {
+                'ok': False,
+                'message': (
+                    f'The local {target} repo has commits that are not on the remote '
+                    'branch, so a fast-forward update is not possible. '
+                    'Run: git -C ' + str(path) + ' fetch origin && '
+                    'git -C ' + str(path) + ' reset --hard ' + compare_ref
+                ),
+                'diverged': True,
+            }
+        if 'does not track' in pull_lower or 'no tracking information' in pull_lower:
+            return {
+                'ok': False,
+                'message': (
+                    f'The local {target} branch has no upstream tracking branch configured. '
+                    'Run: git -C ' + str(path) + ' branch --set-upstream-to=' + compare_ref
+                ),
+            }
+        # Generic fallback — include the raw git output for debugging.
+        detail = pull_out.strip()[:300] if pull_out.strip() else '(no output from git)'
+        return {'ok': False, 'message': f'Pull failed: {detail}'}
+
+    # Pop stash if we stashed
+    if stashed:
+        _, pop_ok = _run_git(['stash', 'pop'], path)
+        if not pop_ok:
+            return {
+                'ok': False,
+                'message': 'Updated but stash pop failed -- manual merge needed',
+                'stash_conflict': True,
+            }
+
+    # Invalidate cache
+    with _cache_lock:
+        _update_cache['checked_at'] = 0
+
+    # Schedule a self-restart so the updated code is loaded fresh.  A plain
+    # git pull leaves stale Python modules in sys.modules — agent imports that
+    # reference new symbols (functions, classes) added in the update will fail
+    # on the next request with AttributeError / ImportError.  os.execv() re-
+    # execs the same interpreter with the same argv, picking up the new code
+    # cleanly without requiring the user to restart manually.
+    #
+    # The 2 s delay gives the HTTP response time to flush to the client before
+    # the process replaces itself.  The client already does
+    # setTimeout(() => location.reload(), 1500) on success, so the page reload
+    # and the restart land at roughly the same time.
+    _schedule_restart()
+
+    return {
+        'ok': True,
+        'message': f'{target} updated successfully',
+        'target': target,
+        'restart_scheduled': True,
+    }

api/upload.py

@@ -1,8 +1,10 @@
 """
 Hermes Web UI -- File upload: multipart parser and upload handler.
 """
+import mimetypes
 import re as _re
 import email.parser
+import tempfile
 from pathlib import Path
 
 from api.config import MAX_UPLOAD_BYTES
@@ -11,7 +13,7 @@ from api.models import get_session
 from api.workspace import safe_resolve_ws
 
 
-def parse_multipart(rfile, content_type, content_length):
+def parse_multipart(rfile, content_type, content_length) -> tuple:
     import re as _re, email.parser as _ep
     m = _re.search(r'boundary=([^;\s]+)', content_type)
     if not m:
@@ -50,8 +52,15 @@ def parse_multipart(rfile, content_type, content_length):
     return fields, files
 
 
+def _sanitize_upload_name(filename: str) -> str:
+    safe_name = _re.sub(r'[^\w.\-]', '_', Path(filename).name)[:200]
+    if not safe_name or safe_name.strip('.') == '':
+        raise ValueError('Invalid filename')
+    return safe_name
+
+
 def handle_upload(handler):
-    import re as _re, traceback as _tb
+    import traceback as _tb
     try:
         content_type = handler.headers.get('Content-Type', '')
         content_length = int(handler.headers.get('Content-Length', 0) or 0)
@@ -69,14 +78,207 @@ def handle_upload(handler):
         except KeyError:
             return j(handler, {'error': 'Session not found'}, status=404)
         workspace = Path(s.workspace)
-        safe_name = _re.sub(r'[^\w.\-]', '_', Path(filename).name)[:200]
-        # Reject names that are purely dots (path traversal: ".." survives regex)
-        if not safe_name or safe_name.strip('.') == '':
-            return j(handler, {'error': 'Invalid filename'}, status=400)
-        # Verify the resolved path stays within the workspace
+        safe_name = _sanitize_upload_name(filename)
         dest = safe_resolve_ws(workspace, safe_name)
         dest.write_bytes(file_bytes)
-        return j(handler, {'filename': safe_name, 'path': str(dest), 'size': dest.stat().st_size})
-    except Exception as e:
+        mime = mimetypes.guess_type(safe_name)[0] or 'application/octet-stream'
+        return j(handler, {
+            'filename': safe_name,
+            'path': str(dest),
+            'size': dest.stat().st_size,
+            'mime': mime,
+            'is_image': mime.startswith('image/'),
+        })
+    except ValueError as e:
+        return j(handler, {'error': str(e)}, status=400)
+    except Exception:
         print('[webui] upload error: ' + _tb.format_exc(), flush=True)
         return j(handler, {'error': 'Upload failed'}, status=500)
+
+
+# Maximum total extracted bytes — guards against zip/tar bombs.
+# Set to 10x the upload limit; a legitimate archive rarely exceeds 3-4x.
+_MAX_EXTRACTED_BYTES = 10 * 20 * 1024 * 1024  # 200 MB
+
+
+def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
+    """Extract a zip or tar archive into the workspace.
+
+    Returns a dict with ``extracted`` (int), ``files`` (list[str]).
+    Raises ValueError on zip-slip or unsupported format.
+    """
+    import zipfile, tarfile, io, os, shutil
+
+    name = Path(filename).name
+    stem = Path(filename).stem  # strip .zip / .tar.gz etc.
+
+    if name.lower().endswith(('.zip',)):
+        _mode = 'zip'
+    elif name.lower().endswith(('.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tar.xz', '.txz')):
+        _mode = 'tar'
+    else:
+        raise ValueError(f'Unsupported archive format: {filename}')
+
+    # Determine destination directory — use archive stem as folder name
+    dest_dir = safe_resolve_ws(workspace, stem)
+    # Avoid overwriting existing files by appending a suffix
+    if dest_dir.exists():
+        import string, random
+        while dest_dir.exists():
+            suffix = ''.join(random.choices(string.digits, k=3))
+            dest_dir = dest_dir.with_name(stem + '_' + suffix)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    extracted_files = []
+    total_extracted = 0
+
+    try:
+        if _mode == 'zip':
+            with zipfile.ZipFile(io.BytesIO(file_bytes)) as zf:
+                for member in zf.infolist():
+                    # Skip directories
+                    if member.is_dir():
+                        continue
+                    # Zip-slip protection
+                    member_path = (dest_dir / member.filename).resolve()
+                    if not member_path.is_relative_to(dest_dir.resolve()):
+                        raise ValueError(f'Zip-slip blocked: {member.filename}')
+                    # Zip-bomb protection: track actual extracted bytes (not declared file_size)
+                    if total_extracted > _MAX_EXTRACTED_BYTES:
+                        raise ValueError(
+                            f'Extraction too large ({total_extracted // (1024*1024)} MB > '
+                            f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                            f'Possible zip bomb.'
+                        )
+                    member_path.parent.mkdir(parents=True, exist_ok=True)
+                    with zf.open(member) as src, open(member_path, 'wb') as dst:
+                        _chunk_size = 65536
+                        while True:
+                            chunk = src.read(_chunk_size)
+                            if not chunk:
+                                break
+                            total_extracted += len(chunk)
+                            if total_extracted > _MAX_EXTRACTED_BYTES:
+                                raise ValueError(
+                                    f'Extraction too large (> '
+                                    f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                                    f'Possible zip bomb.'
+                                )
+                            dst.write(chunk)
+                    extracted_files.append(str(member_path.relative_to(workspace.resolve())))
+
+        elif _mode == 'tar':
+            with tarfile.open(fileobj=io.BytesIO(file_bytes)) as tf:
+                for member in tf.getmembers():
+                    if not member.isfile():
+                        continue
+                    # Tar-slip protection
+                    member_path = (dest_dir / member.name).resolve()
+                    if not member_path.is_relative_to(dest_dir.resolve()):
+                        raise ValueError(f'Tar-slip blocked: {member.name}')
+                    # Tar-bomb protection: track actual extracted bytes (not declared size)
+                    if total_extracted > _MAX_EXTRACTED_BYTES:
+                        raise ValueError(
+                            f'Extraction too large ({total_extracted // (1024*1024)} MB > '
+                            f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                            f'Possible zip bomb.'
+                        )
+                    member_path.parent.mkdir(parents=True, exist_ok=True)
+                    src_obj = tf.extractfile(member)
+                    if src_obj:
+                        with src_obj as src, open(member_path, 'wb') as dst:
+                            _chunk_size = 65536
+                            while True:
+                                chunk = src.read(_chunk_size)
+                                if not chunk:
+                                    break
+                                total_extracted += len(chunk)
+                                if total_extracted > _MAX_EXTRACTED_BYTES:
+                                    raise ValueError(
+                                        f'Extraction too large (> '
+                                        f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                                        f'Possible zip bomb.'
+                                    )
+                                dst.write(chunk)
+                    extracted_files.append(str(member_path.relative_to(workspace.resolve())))
+    except Exception:
+        # Clean up partially-extracted directory to avoid orphaned folders
+        try:
+            shutil.rmtree(dest_dir, ignore_errors=True)
+        except Exception:
+            pass
+        raise
+
+    return {'extracted': len(extracted_files), 'files': extracted_files, 'dest': str(dest_dir)}
+
+
+def handle_upload_extract(handler):
+    """Handle archive upload and extraction."""
+    import traceback as _tb
+    try:
+        content_type = handler.headers.get('Content-Type', '')
+        content_length = int(handler.headers.get('Content-Length', 0) or 0)
+        if content_length > MAX_UPLOAD_BYTES:
+            return j(handler, {'error': f'File too large (max {MAX_UPLOAD_BYTES//1024//1024}MB)'}, status=413)
+        fields, files = parse_multipart(handler.rfile, content_type, content_length)
+        session_id = fields.get('session_id', '')
+        if 'file' not in files:
+            return j(handler, {'error': 'No file field in request'}, status=400)
+        filename, file_bytes = files['file']
+        if not filename:
+            return j(handler, {'error': 'No filename in upload'}, status=400)
+        try:
+            s = get_session(session_id)
+        except KeyError:
+            return j(handler, {'error': 'Session not found'}, status=404)
+        workspace = Path(s.workspace)
+        result = extract_archive(file_bytes, filename, workspace)
+        return j(handler, {'ok': True, **result})
+    except ValueError as e:
+        return j(handler, {'error': str(e)}, status=400)
+    except Exception:
+        print('[webui] upload extract error: ' + _tb.format_exc(), flush=True)
+        return j(handler, {'error': 'Archive extraction failed'}, status=500)
+
+
+def handle_transcribe(handler):
+    import traceback as _tb
+    temp_path = None
+    try:
+        content_type = handler.headers.get('Content-Type', '')
+        content_length = int(handler.headers.get('Content-Length', 0) or 0)
+        if content_length > MAX_UPLOAD_BYTES:
+            return j(handler, {'error': f'File too large (max {MAX_UPLOAD_BYTES//1024//1024}MB)'}, status=413)
+        fields, files = parse_multipart(handler.rfile, content_type, content_length)
+        if 'file' not in files:
+            return j(handler, {'error': 'No file field in request'}, status=400)
+        filename, file_bytes = files['file']
+        if not filename:
+            return j(handler, {'error': 'No filename in upload'}, status=400)
+        safe_name = _sanitize_upload_name(filename)
+        suffix = Path(safe_name).suffix or '.webm'
+        with tempfile.NamedTemporaryFile(prefix='webui-stt-', suffix=suffix, delete=False) as tmp:
+            temp_path = tmp.name
+            tmp.write(file_bytes)
+        try:
+            from tools.transcription_tools import transcribe_audio
+        except ImportError:
+            return j(handler, {'error': 'Speech-to-text is unavailable on this server'}, status=503)
+        result = transcribe_audio(temp_path)
+        if not result.get('success'):
+            msg = str(result.get('error') or 'Transcription failed')
+            status = 503 if 'unavailable' in msg.lower() or 'not configured' in msg.lower() else 400
+            return j(handler, {'error': msg}, status=status)
+        transcript = str(result.get('transcript') or '').strip()
+        return j(handler, {'ok': True, 'transcript': transcript})
+    except ValueError as e:
+        return j(handler, {'error': str(e)}, status=400)
+    except Exception:
+        print('[webui] transcribe error: ' + _tb.format_exc(), flush=True)
+        return j(handler, {'error': 'Transcription failed'}, status=500)
+    finally:
+        if temp_path:
+            try:
+                Path(temp_path).unlink(missing_ok=True)
+            except Exception:
+                pass

api/workspace.py

@@ -8,10 +8,14 @@ profile has its own workspace configuration.  State files live at
 paths are used as fallback when no profile module is available.
 """
 import json
+import logging
 import os
 import subprocess
+import concurrent.futures
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 from api.config import (
     WORKSPACES_FILE as _GLOBAL_WS_FILE,
     LAST_WORKSPACE_FILE as _GLOBAL_LW_FILE,
@@ -37,7 +41,7 @@ def _profile_state_dir() -> Path:
             d.mkdir(parents=True, exist_ok=True)
             return d
     except ImportError:
-        pass
+        logger.debug("Failed to import profiles module, using global state dir")
     return _GLOBAL_WS_FILE.parent
 
 
@@ -80,7 +84,7 @@ def _profile_default_workspace() -> str:
                 if p.is_dir():
                     return str(p)
     except (ImportError, Exception):
-        pass
+        logger.debug("Failed to load profile default workspace config")
     return str(_BOOT_DEFAULT_WORKSPACE)
 
 
@@ -89,7 +93,6 @@ def _profile_default_workspace() -> str:
 def _clean_workspace_list(workspaces: list) -> list:
     """Sanitize a workspace list:
     - Remove entries whose paths no longer exist on disk.
-    - Remove entries that look like test artifacts (webui-mvp-test, test-workspace).
     - Remove entries whose paths live inside another profile's directory
       (e.g. ~/.hermes/profiles/X/... should not appear on a different profile).
     - Rename any entry whose name is literally 'default' to 'Home' (avoids
@@ -102,18 +105,24 @@ def _clean_workspace_list(workspaces: list) -> list:
         path = w.get('path', '')
         name = w.get('name', '')
         p = Path(path).resolve() if path else Path('/')
-        # Skip test artifacts
-        if 'test-workspace' in path or 'webui-mvp-test' in path:
-            continue
         # Skip paths that no longer exist
         if not p.is_dir():
             continue
-        # Skip paths inside a named profile's directory (cross-profile leak)
+        # Skip paths inside a DIFFERENT profile's directory (cross-profile leak).
+        # Allow paths inside the CURRENT profile's own directory (e.g. test workspaces
+        # created under ~/.hermes/profiles/webui/webui-mvp-test/).
         try:
             p.relative_to(hermes_profiles)
-            continue  # it IS under profiles/ — remove it
+            # p is under ~/.hermes/profiles/ — only skip if it's under a DIFFERENT profile
+            try:
+                from api.profiles import get_active_hermes_home
+                own_profile_dir = get_active_hermes_home().resolve()
+                p.relative_to(own_profile_dir)
+                # p is under our own profile dir — keep it
+            except (ValueError, Exception):
+                continue  # under profiles/ but not our own — cross-profile leak, skip
         except ValueError:
-            pass
+            pass  # not under profiles/ at all — keep it
         # Rename confusing 'default' label to 'Home'
         if name.lower() == 'default':
             name = 'Home'
@@ -156,10 +165,10 @@ def load_workspaces() -> list:
                         json.dumps(cleaned, ensure_ascii=False, indent=2), encoding='utf-8'
                     )
                 except Exception:
-                    pass
+                    logger.debug("Failed to persist cleaned workspace list")
             return cleaned or [{'path': _profile_default_workspace(), 'name': 'Home'}]
         except Exception:
-            pass
+            logger.debug("Failed to load workspaces from %s", ws_file)
     # No profile-local file yet.
     # For the DEFAULT profile: migrate from the legacy global file (one-time cleanup).
     # For NAMED profiles: always start clean with just their own workspace.
@@ -176,7 +185,7 @@ def load_workspaces() -> list:
     return [{'path': _profile_default_workspace(), 'name': 'Home'}]
 
 
-def save_workspaces(workspaces: list):
+def save_workspaces(workspaces: list) -> None:
     ws_file = _workspaces_file()
     ws_file.parent.mkdir(parents=True, exist_ok=True)
     ws_file.write_text(json.dumps(workspaces, ensure_ascii=False, indent=2), encoding='utf-8')
@@ -190,7 +199,7 @@ def get_last_workspace() -> str:
             if p and Path(p).is_dir():
                 return p
         except Exception:
-            pass
+            logger.debug("Failed to read last workspace from %s", lw_file)
     # Fallback: try global file
     if _GLOBAL_LW_FILE.exists():
         try:
@@ -198,44 +207,490 @@ def get_last_workspace() -> str:
             if p and Path(p).is_dir():
                 return p
         except Exception:
-            pass
+            logger.debug("Failed to read global last workspace")
     return _profile_default_workspace()
 
 
-def set_last_workspace(path: str):
+def set_last_workspace(path: str) -> None:
     try:
         lw_file = _last_workspace_file()
         lw_file.parent.mkdir(parents=True, exist_ok=True)
         lw_file.write_text(str(path), encoding='utf-8')
+    except Exception:
+        logger.debug("Failed to set last workspace")
+
+
+def _safe_resolve(p: Path) -> Path:
+    """Path.resolve() that never raises — falls back to the input path on error."""
+    try:
+        return p.resolve()
+    except (OSError, RuntimeError):
+        return p
+
+
+# Per-user temp directories that sit nominally under a "system" prefix but are
+# actually user-writable scratch space.  Workspaces registered here (e.g. by
+# pytest's ``tmp_path_factory`` on macOS, which uses ``/var/folders/<hash>/T/``)
+# must remain accepted even though their parent (``/var``) is blocked.  These
+# carve-outs apply to BOTH workspace registration and runtime file ops so a
+# symlink target inside the carve-out is also reachable.
+_USER_TMP_PREFIXES: tuple[Path, ...] = (
+    Path('/var/folders'),         # macOS per-user tmp (literal form)
+    Path('/private/var/folders'),  # macOS per-user tmp (resolved form)
+    Path('/var/tmp'),               # Linux/macOS system-wide tmp (user-writable)
+    Path('/private/var/tmp'),       # macOS resolved form
+)
+
+
+def _workspace_blocked_roots() -> tuple[Path, ...]:
+    """System roots that must never be accepted as workspace candidates.
+
+    Returns both the literal path and its symlink-resolved canonical form,
+    deduped.  This matters on macOS where ``/etc``, ``/var``, and ``/tmp``
+    are symlinks to ``/private/etc`` etc.  Without the resolved forms,
+    callers that pass a ``.resolve()``-d candidate (every caller does)
+    would compare ``/private/etc`` against literal ``Path('/etc')`` and the
+    ``relative_to`` check would miss — letting ``/etc`` through as a
+    registered workspace on macOS.
+
+    Carve-outs for legitimate user-tmp paths nominally under these roots
+    (e.g. ``/var/folders/.../T/`` on macOS) are handled by
+    :func:`_is_blocked_system_path`, not by exclusion from this list.
+    """
+    _raw = (
+        # Linux / macOS
+        '/etc',
+        '/usr',
+        '/var',
+        '/bin',
+        '/sbin',
+        '/boot',
+        '/proc',
+        '/sys',
+        '/dev',
+        '/lib',
+        '/lib64',
+        '/opt/homebrew',
+        '/System',
+        '/Library',
+    )
+    _seen: set[Path] = set()
+    _out: list[Path] = []
+    for _p in _raw:
+        for _form in (Path(_p), _safe_resolve(Path(_p))):
+            if _form not in _seen:
+                _seen.add(_form)
+                _out.append(_form)
+    return tuple(_out)
+
+
+def _is_blocked_system_path(candidate: Path) -> bool:
+    """Return True if *candidate* falls under a blocked system root.
+
+    Honours :data:`_USER_TMP_PREFIXES` carve-outs so per-user tmp directories
+    nominally under ``/var`` (``/var/folders`` on macOS, ``/var/tmp`` on
+    Linux/macOS) remain valid workspace candidates and reachable file targets.
+    """
+    for tmp in _USER_TMP_PREFIXES:
+        if _is_within(candidate, tmp):
+            return False
+    for blocked in _workspace_blocked_roots():
+        if _is_within(candidate, blocked):
+            return True
+    return False
+
+
+def _workspace_blocked_resolved_subtrees() -> tuple[Path, ...]:
+    roots = list(_workspace_blocked_roots()) + [Path('/private/etc')]
+    resolved: list[Path] = []
+    for root in roots:
+        try:
+            p = root.expanduser().resolve()
+        except Exception:
+            p = root
+        if p not in resolved:
+            resolved.append(p)
+    return tuple(resolved)
+
+
+def _workspace_blocked_exact_roots() -> tuple[Path, ...]:
+    roots = [Path('/'), Path('/private/var')]
+    for root in _workspace_blocked_roots():
+        try:
+            roots.append(root.expanduser().resolve())
+        except Exception:
+            roots.append(root)
+    unique: list[Path] = []
+    for root in roots:
+        if root not in unique:
+            unique.append(root)
+    return tuple(unique)
+
+
+def _is_blocked_workspace_path(candidate: Path, raw_path: str | Path | None = None) -> bool:
+    """Return True when candidate points at a known OS/system directory.
+
+    Compare both the original spelling and the resolved path.  This closes the
+    macOS /etc -> /private/etc bypass without globally banning temporary pytest
+    paths under /private/var/folders.
+    """
+    raw = None
+    if raw_path not in (None, ""):
+        try:
+            raw = Path(raw_path).expanduser()
+        except Exception:
+            raw = None
+
+    exact = _workspace_blocked_exact_roots()
+    if candidate in exact or (raw is not None and raw in _workspace_blocked_roots()):
+        return True
+
+    for tmp in _USER_TMP_PREFIXES:
+        if _is_within(candidate, tmp) or (raw is not None and _is_within(raw, tmp)):
+            return False
+
+    # Raw paths under literal roots (e.g. /etc/ssh, /var/db) are always blocked.
+    if raw is not None:
+        for blocked in _workspace_blocked_roots():
+            if _is_within(raw, blocked):
+                return True
+
+    # Resolved subtree checks catch symlink aliases such as /private/etc.  The
+    # macOS temp root /private/var/folders is intentionally allowed for pytest
+    # and per-user temporary workspaces; other direct /private/var system data
+    # such as /private/var/db and /private/var/log remains blocked.
+    allowed_private_var = (Path('/private/var/folders'), Path('/private/var/tmp'))
+    for blocked in _workspace_blocked_resolved_subtrees():
+        if blocked == Path('/private/var'):
+            if candidate == blocked:
+                return True
+            if any(_is_within(candidate, allowed) for allowed in allowed_private_var):
+                continue
+            if _is_within(candidate, blocked):
+                return True
+            continue
+        if _is_within(candidate, blocked):
+            return True
+    return False
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _trusted_workspace_roots() -> list[Path]:
+    roots: list[Path] = []
+
+    def add(candidate: str | Path | None) -> None:
+        if candidate in (None, ""):
+            return
+        try:
+            p = Path(candidate).expanduser().resolve()
+        except Exception:
+            return
+        if not p.exists() or not p.is_dir():
+            return
+        if _is_blocked_workspace_path(p, candidate):
+            return
+        if p not in roots:
+            roots.append(p)
+
+    add(Path.home())
+    add(_BOOT_DEFAULT_WORKSPACE)
+    for w in load_workspaces():
+        add(w.get("path"))
+    roots.sort(key=lambda p: len(str(p)))
+    return roots
+
+
+def list_workspace_suggestions(prefix: str = "", limit: int = 12) -> list[str]:
+    """Return workspace path suggestions under trusted roots only.
+
+    Suggestions are limited to directories under one of:
+      - Path.home()
+      - the boot default workspace
+      - already-saved workspace roots
+
+    Arbitrary system prefixes return an empty list rather than an error so the
+    UI can safely autocomplete while the user types.
+    """
+    roots = _trusted_workspace_roots()
+    if not roots:
+        return []
+
+    raw = (prefix or "").strip()
+    if not raw:
+        return [str(p) for p in roots[:limit]]
+
+    if raw.startswith("~"):
+        target = Path(raw).expanduser()
+    elif Path(raw).is_absolute():
+        target = Path(raw)
+    else:
+        target = Path.home() / raw
+
+    normalized = str(target)
+    normalized_lower = normalized.lower()
+    suggestions: list[str] = []
+
+    def add(path: Path) -> None:
+        value = str(path)
+        if value not in suggestions:
+            suggestions.append(value)
+
+    # If the user is typing a partial trusted root like /Users/xuef..., suggest
+    # the matching trusted roots without scanning arbitrary system parents.
+    for root in roots:
+        if str(root).lower().startswith(normalized_lower):
+            add(root)
+
+    in_root = [
+        root
+        for root in roots
+        if normalized == str(root) or normalized.startswith(str(root) + os.sep)
+    ]
+    if not in_root:
+        return suggestions[:limit]
+
+    anchor_root = max(in_root, key=lambda p: len(str(p)))
+    ends_with_sep = raw.endswith(os.sep) or raw.endswith('/')
+    parent = target if ends_with_sep else target.parent
+    leaf = '' if ends_with_sep else target.name
+    show_hidden = leaf.startswith('.')
+
+    try:
+        parent_resolved = parent.expanduser().resolve()
+    except Exception:
+        return suggestions[:limit]
+
+    if not parent_resolved.exists() or not parent_resolved.is_dir():
+        return suggestions[:limit]
+    if not _is_within(parent_resolved, anchor_root):
+        return suggestions[:limit]
+
+    leaf_lower = leaf.lower()
+    try:
+        children = sorted(parent_resolved.iterdir(), key=lambda p: p.name.lower())
+    except OSError:
+        return suggestions[:limit]
+
+    for child in children:
+        if not child.is_dir():
+            continue
+        if child.name.startswith('.') and not show_hidden:
+            continue
+        if leaf_lower and not child.name.lower().startswith(leaf_lower):
+            continue
+        add(child.resolve())
+        if len(suggestions) >= limit:
+            break
+    return suggestions[:limit]
+
+
+def resolve_trusted_workspace(path: str | Path | None = None) -> Path:
+    """Resolve and validate a workspace path.
+
+    A path is trusted if it satisfies at least one of:
+      (A) It is under the user's home directory (Path.home()).
+          Works cross-platform: ~/... on Linux/macOS, C:\\Users\\... on Windows.
+      (B) It is already in the profile's saved workspace list.
+          This covers self-hosted deployments where workspaces live outside home
+          (e.g. /data/projects, /opt/workspace) — once a workspace is saved by
+          an admin, it can be reused without re-validation.
+
+    Additionally enforced regardless of (A)/(B):
+      1. The path must exist.
+      2. The path must be a directory.
+      3. The path must not be a known system root (/etc, /usr, /var, /bin, /sbin,
+         /boot, /proc, /sys, /dev, /root on Linux/macOS; Windows system dirs).
+         This prevents even admin-saved workspaces from pointing at OS internals.
+
+    None/empty path falls back to the boot-time DEFAULT_WORKSPACE, which is always
+    trusted (it was validated at server startup).
+    """
+    if path in (None, ""):
+        return Path(_BOOT_DEFAULT_WORKSPACE).expanduser().resolve()
+
+    candidate = Path(path).expanduser().resolve()
+
+    if not candidate.exists():
+        raise ValueError(f"Path does not exist: {candidate}")
+    if not candidate.is_dir():
+        raise ValueError(f"Path is not a directory: {candidate}")
+
+    # (A) Trusted if under the user's home directory — cross-platform via Path.home()
+    # Must be checked before system roots to allow symlinks like /var/home.
+    _home = Path.home().resolve()
+    if _home != Path("/"):
+        try:
+            candidate.relative_to(_home)
+            return candidate
+        except ValueError:
+            pass
+
+    # Block known system roots and their children.
+    if _is_blocked_workspace_path(candidate, path):
+        raise ValueError(f"Path points to a system directory: {candidate}")
+
+    # (B) Trusted if already in the saved workspace list — covers non-home installs
+    try:
+        saved = load_workspaces()
+        saved_paths = {Path(w["path"]).resolve() for w in saved if w.get("path")}
+        if candidate in saved_paths:
+            return candidate
     except Exception:
         pass
 
+    # (C) Trusted if it is equal to or under the boot-time DEFAULT_WORKSPACE.
+    #     In Docker deployments HERMES_WEBUI_DEFAULT_WORKSPACE is often set to a
+    #     volume mount outside the user's home (e.g. /data/workspace).  That path
+    #     was already validated at server startup, so any sub-path of it is safe
+    #     without requiring the user to add it to the workspace list manually.
+    try:
+        boot_default = Path(_BOOT_DEFAULT_WORKSPACE).expanduser().resolve()
+        candidate.relative_to(boot_default)
+        return candidate
+    except ValueError:
+        pass
+
+    raise ValueError(
+        f"Path is outside the user home directory, not in the saved workspace "
+        f"list, and not under the default workspace: {candidate}. "
+        f"Add it via Settings → Workspaces first."
+    )
+
+
+
+
+def validate_workspace_to_add(path: str) -> Path:
+    """Validate a path for *adding* to the workspace list (less restrictive than resolve_trusted_workspace).
+
+    When a user explicitly adds a new workspace path, we trust their intent — they
+    have console or filesystem access to that path and are consciously registering it.
+    We only block: non-existent paths, non-directories, and known system roots.
+
+    The stricter ``resolve_trusted_workspace`` is used when *using* an existing workspace
+    (file reads/writes) to prevent path traversal after the list is built.
+    """
+    candidate = Path(path).expanduser().resolve()
+
+    if not candidate.exists():
+        raise ValueError(f"Path does not exist: {candidate}")
+    if not candidate.is_dir():
+        raise ValueError(f"Path is not a directory: {candidate}")
+
+    # Home directory is always trusted regardless of where it lives on disk
+    # (e.g. /var/home/... on systemd-homed Fedora/RHEL).
+    _home = Path.home().resolve()
+    if _home != Path("/") and _is_within(candidate, _home):
+        return candidate
+
+    # Block known system roots and their immediate children.
+    if _is_blocked_workspace_path(candidate, path):
+        raise ValueError(f"Path points to a system directory: {candidate}")
+
+    return candidate
 
 def safe_resolve_ws(root: Path, requested: str) -> Path:
-    """Resolve a relative path inside a workspace root, raising ValueError on traversal."""
-    resolved = (root / requested).resolve()
-    resolved.relative_to(root.resolve())
+    """Resolve a relative path inside a workspace root, raising ValueError on traversal.
+
+    Symlinks whose *unresolved* path is within the workspace root are allowed —
+    the user placed them there intentionally.  Only raw ``..`` traversal outside
+    the root is blocked.
+    """
+    import os
+    unresolved = root / requested
+    resolved = unresolved.resolve()
+    # Fast path: resolved path is inside root (covers most cases)
+    try:
+        resolved.relative_to(root.resolve())
+        return resolved
+    except ValueError:
+        pass
+    # Symlink path: normalize '..' (without following symlinks) and check
+    # os.path.normpath collapses '..' but does NOT follow symlinks.
+    norm = Path(os.path.normpath(str(unresolved)))
+    try:
+        norm.relative_to(root)
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {requested}")
+    # Symlink points outside workspace root — additionally block system directories.
+    # Even if the user placed the symlink intentionally, prevent reads from
+    # /etc, /proc, /sys, /dev and other blocked roots (LLM agents can call
+    # read_file_content via tool calls, not just human users).
+    if _is_blocked_system_path(resolved):
+        raise ValueError(f"Path traversal blocked (system dir): {requested}")
     return resolved
 
 
-def list_dir(workspace: Path, rel='.'):
+def list_dir(workspace: Path, rel: str='.'):
     target = safe_resolve_ws(workspace, rel)
     if not target.is_dir():
         raise FileNotFoundError(f"Not a directory: {rel}")
+    ws_resolved = workspace.resolve()
     entries = []
-    for item in sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower())):
-        entries.append({
-            'name': item.name,
-            'path': str(item.relative_to(workspace)),
-            'type': 'dir' if item.is_dir() else 'file',
-            'size': item.stat().st_size if item.is_file() else None,
-        })
+    for item in sorted(target.iterdir(), key=lambda p: (not p.is_symlink(), p.is_file(), p.name.lower())):
+        if item.is_symlink():
+            # Resolve the symlink target and check if it stays within workspace
+            try:
+                link_target = item.resolve()
+            except OSError:
+                continue
+            # Cycle detection: skip if symlink points back to current dir,
+            # workspace root, or any ancestor of current dir.
+            # This must run REGARDLESS of whether target is inside workspace.
+            if (link_target == target.resolve() or link_target == target
+                    or link_target == ws_resolved):
+                continue
+            try:
+                target.resolve().relative_to(link_target)
+                # target is under link_target — link_target is an ancestor → cycle
+                continue
+            except ValueError:
+                pass
+            # Block symlinks that resolve to system directories.
+            if _is_blocked_system_path(link_target):
+                continue
+            is_dir = link_target.is_dir()
+            # Keep the display path relative to workspace (don't follow the link)
+            display_path = str(Path(item.name))
+            if rel and rel != '.':
+                display_path = rel + '/' + display_path
+            entry = {
+                'name': item.name,
+                'path': display_path,
+                'type': 'symlink',
+                'target': str(link_target),
+                'is_dir': is_dir,
+            }
+            if not is_dir:
+                try:
+                    entry['size'] = link_target.stat().st_size
+                except OSError:
+                    entry['size'] = None
+            entries.append(entry)
+        else:
+            # Use rel-based path so entries under symlink targets (outside
+            # the workspace root) still get a valid workspace-relative path.
+            entry_path = item.name
+            if rel and rel != '.':
+                entry_path = rel + '/' + item.name
+            entries.append({
+                'name': item.name,
+                'path': entry_path,
+                'type': 'dir' if item.is_dir() else 'file',
+                'size': item.stat().st_size if item.is_file() else None,
+            })
         if len(entries) >= 200:
             break
     return entries
 
 
-def read_file_content(workspace: Path, rel: str):
+def read_file_content(workspace: Path, rel: str) -> dict:
     target = safe_resolve_ws(workspace, rel)
     if not target.is_file():
         raise FileNotFoundError(f"Not a file: {rel}")
@@ -267,22 +722,35 @@ def git_info_for_workspace(workspace: Path) -> dict:
     branch = _run_git(['rev-parse', '--abbrev-ref', 'HEAD'], workspace)
     if branch is None:
         return None
-    # Status counts
-    status_out = _run_git(['status', '--porcelain'], workspace) or ''
-    lines = [l for l in status_out.splitlines() if l]
-    # git status --porcelain: XY format where X=index, Y=worktree
-    modified = sum(1 for l in lines if len(l) >= 2 and (l[0] in 'MAR' or l[1] in 'MAR'))
-    untracked = sum(1 for l in lines if l.startswith('??'))
-    dirty = len(lines)
-    # Ahead/behind
-    ahead = _run_git(['rev-list', '--count', '@{u}..HEAD'], workspace)
-    behind = _run_git(['rev-list', '--count', 'HEAD..@{u}'], workspace)
+    # Run the remaining git commands in parallel via threads — they are
+    # independent subprocess calls and together can take 50-200ms when run
+    # serially.  Threading is safe here because each call blocks only on the
+    # subprocess pipe, not on the GIL.
+    def _ahead():
+        r = _run_git(['rev-list', '--count', '@{u}..HEAD'], workspace)
+        return int(r) if r and r.isdigit() else 0
+    def _behind():
+        r = _run_git(['rev-list', '--count', 'HEAD..@{u}'], workspace)
+        return int(r) if r and r.isdigit() else 0
+    def _status():
+        out = _run_git(['status', '--porcelain'], workspace) or ''
+        lines = [l for l in out.splitlines() if l]
+        modified = sum(1 for l in lines if len(l) >= 2 and (l[0] in 'MAR' or l[1] in 'MAR'))
+        untracked = sum(1 for l in lines if l.startswith('??'))
+        return len(lines), modified, untracked
+    with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
+        f_status = pool.submit(_status)
+        f_ahead  = pool.submit(_ahead)
+        f_behind = pool.submit(_behind)
+        dirty, modified, untracked = f_status.result()
+        ahead  = f_ahead.result()
+        behind = f_behind.result()
     return {
         'branch': branch,
         'dirty': dirty,
         'modified': modified,
         'untracked': untracked,
-        'ahead': int(ahead) if ahead and ahead.isdigit() else 0,
-        'behind': int(behind) if behind and behind.isdigit() else 0,
+        'ahead': ahead,
+        'behind': behind,
         'is_git': True,
     }

bootstrap.py

@@ -0,0 +1,434 @@
+#!/usr/bin/env python3
+"""One-shot bootstrap launcher for Hermes Web UI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+import venv
+import webbrowser
+from pathlib import Path
+
+
+INSTALLER_URL = "https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh"
+REPO_ROOT = Path(__file__).resolve().parent
+
+
+def _load_repo_dotenv() -> None:
+    """Load REPO_ROOT/.env into os.environ.
+
+    Mirrors what start.sh does via ``set -a; source .env`` so that running
+    ``python3 bootstrap.py`` directly behaves identically to ``./start.sh``.
+    Variables are set unconditionally (matching shell source semantics), so a
+    value in .env overrides one already present in the shell environment.
+    To keep a CLI-supplied value, unset it from .env or launch via start.sh
+    and override there.
+
+    Only loads the webui repo .env — not ~/.hermes/.env, which the server
+    loads independently at startup for provider credentials.
+
+    Note: does not handle the ``export FOO=bar`` prefix — strip ``export``
+    from .env values if copy-pasting from a shell rc file.
+    """
+    env_path = REPO_ROOT / ".env"
+    if not env_path.exists():
+        return
+    try:
+        for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            k = k.strip()
+            # Strip optional 'export' prefix (common in copy-pasted shell snippets)
+            if k.startswith("export "):
+                k = k[7:].strip()
+            v = v.strip().strip('"').strip("'")
+            if k:
+                os.environ[k] = v
+    except Exception as exc:
+        import sys as _sys
+        print(f"[bootstrap] Warning: could not load .env — {exc}", file=_sys.stderr)
+
+
+# Side effect: loads REPO_ROOT/.env into os.environ on import.
+# Must run before DEFAULT_HOST / DEFAULT_PORT so os.getenv() picks up
+# values from .env even when bootstrap.py is invoked directly (not via start.sh).
+_load_repo_dotenv()
+
+DEFAULT_HOST = os.getenv("HERMES_WEBUI_HOST", "127.0.0.1")
+DEFAULT_PORT = int(os.getenv("HERMES_WEBUI_PORT", "8787"))
+# Set HERMES_WEBUI_SKIP_ONBOARDING=1 to bypass the first-run wizard when
+# the environment is already fully configured (e.g. managed hosting).
+
+
+def info(msg: str) -> None:
+    print(f"[bootstrap] {msg}", flush=True)
+
+
+def is_wsl() -> bool:
+    if platform.system() != "Linux":
+        return False
+    release = platform.release().lower()
+    return (
+        "microsoft" in release or "wsl" in release or bool(os.getenv("WSL_DISTRO_NAME"))
+    )
+
+
+def ensure_supported_platform() -> None:
+    if platform.system() == "Windows" and not is_wsl():
+        raise RuntimeError(
+            "Native Windows is not supported for this bootstrap yet. "
+            "Please run it from Linux, macOS, or inside WSL2."
+        )
+
+
+def discover_agent_dir() -> Path | None:
+    home = Path(os.getenv("HERMES_HOME", str(Path.home() / ".hermes"))).expanduser()
+    candidates = [
+        os.getenv("HERMES_WEBUI_AGENT_DIR", ""),
+        str(home / "hermes-agent"),
+        str(REPO_ROOT.parent / "hermes-agent"),
+        str(Path.home() / ".hermes" / "hermes-agent"),
+        str(Path.home() / "hermes-agent"),
+    ]
+    for raw in candidates:
+        if not raw:
+            continue
+        candidate = Path(raw).expanduser().resolve()
+        if candidate.exists() and (candidate / "run_agent.py").exists():
+            return candidate
+    return None
+
+
+def discover_launcher_python(agent_dir: Path | None) -> str:
+    env_python = os.getenv("HERMES_WEBUI_PYTHON")
+    if env_python:
+        return env_python
+    if agent_dir:
+        for rel in ("venv/bin/python", "venv/Scripts/python.exe", ".venv/bin/python", ".venv/Scripts/python.exe"):
+            candidate = agent_dir / rel
+            if candidate.exists():
+                return str(candidate)
+    for rel in (".venv/bin/python", ".venv/Scripts/python.exe"):
+        candidate = REPO_ROOT / rel
+        if candidate.exists():
+            return str(candidate)
+    return shutil.which("python3") or shutil.which("python") or sys.executable
+
+
+def _python_can_run_webui_and_agent(python_exe: str, agent_dir: Path | None = None) -> bool:
+    script = "import yaml\nfrom run_agent import AIAgent\n"
+    env = os.environ.copy()
+    if agent_dir:
+        # PREPEND agent_dir to PYTHONPATH so an `agent_dir/run_agent.py` wins
+        # over any stale `run_agent` package in system site-packages (sys.path
+        # order: script-dir → PYTHONPATH entries → site-packages). The
+        # "if PYTHONPATH unset" branch avoids a leading os.pathsep, which
+        # CPython would interpret as "current directory" — a footgun.
+        env["PYTHONPATH"] = (
+            str(agent_dir)
+            if not env.get("PYTHONPATH")
+            else f"{agent_dir}{os.pathsep}{env['PYTHONPATH']}"
+        )
+    check = subprocess.run(
+        [python_exe, "-c", script],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+    return check.returncode == 0
+
+
+def ensure_python_has_webui_deps(python_exe: str, agent_dir: Path | None = None) -> str:
+    """Return a Python executable that can run both WebUI and Hermes Agent.
+
+    The WebUI can be launched directly with its local .venv. That venv has the
+    WebUI dependencies (for example PyYAML), but may not have Hermes Agent on its
+    import path. In that case the server starts healthy, then chat fails later
+    with "AIAgent not available". Prefer the agent venv when it is usable, and
+    validate the final interpreter before starting the server.
+    """
+    if _python_can_run_webui_and_agent(python_exe, agent_dir):
+        return python_exe
+
+    agent_candidates: list[Path] = []
+    if agent_dir:
+        for rel in (
+            "venv/bin/python",
+            "venv/Scripts/python.exe",
+            ".venv/bin/python",
+            ".venv/Scripts/python.exe",
+        ):
+            agent_candidates.append(agent_dir / rel)
+        for candidate in agent_candidates:
+            if str(candidate) != python_exe and candidate.exists():
+                if _python_can_run_webui_and_agent(str(candidate), agent_dir):
+                    return str(candidate)
+
+    venv_dir = REPO_ROOT / ".venv"
+    venv_python = venv_dir / (
+        "Scripts/python.exe" if platform.system() == "Windows" else "bin/python"
+    )
+    if not venv_python.exists():
+        info(f"Creating local virtualenv at {venv_dir}")
+        venv.EnvBuilder(with_pip=True).create(venv_dir)
+
+    info("Installing WebUI dependencies into local virtualenv")
+    subprocess.run(
+        [str(venv_python), "-m", "pip", "install", "--quiet", "--upgrade", "pip"],
+        check=True,
+    )
+    subprocess.run(
+        [
+            str(venv_python),
+            "-m",
+            "pip",
+            "install",
+            "--quiet",
+            "-r",
+            str(REPO_ROOT / "requirements.txt"),
+        ],
+        check=True,
+    )
+    if _python_can_run_webui_and_agent(str(venv_python), agent_dir):
+        return str(venv_python)
+    raise RuntimeError(
+        "Python environment cannot import both WebUI dependencies and Hermes Agent. "
+        "Set HERMES_WEBUI_PYTHON to the Hermes Agent venv Python or install the "
+        "WebUI requirements into that environment."
+    )
+
+
+def hermes_command_exists() -> bool:
+    return shutil.which("hermes") is not None
+
+
+def install_hermes_agent() -> None:
+    info(f"Hermes Agent not found. Attempting install via {INSTALLER_URL}")
+    subprocess.run(
+        ["/bin/bash", "-lc", f"curl -fsSL {INSTALLER_URL} | bash"], check=True
+    )
+
+
+def wait_for_health(url: str, timeout: float = 25.0) -> bool:
+    deadline = time.time() + timeout
+    # Validate URL scheme to prevent file:// and other dangerous schemes
+    if not url.startswith(("http://", "https://")):
+        raise ValueError(f"Invalid health check URL: {url}")
+    while time.time() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=2) as response:  # nosec B310
+                if b'"status": "ok"' in response.read():
+                    return True
+        except Exception:
+            time.sleep(0.4)
+    return False
+
+
+def open_browser(url: str) -> None:
+    try:
+        webbrowser.open(url)
+    except Exception as exc:
+        info(f"Could not open browser automatically: {exc}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Bootstrap Hermes Web UI onboarding.")
+    parser.add_argument("port", nargs="?", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--host", default=DEFAULT_HOST)
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not open a browser tab automatically.",
+    )
+    parser.add_argument(
+        "--skip-agent-install",
+        action="store_true",
+        help="Fail instead of attempting the official Hermes installer.",
+    )
+    parser.add_argument(
+        "--foreground",
+        action="store_true",
+        help=(
+            "Run server.py in this process (via os.execv) instead of spawning a "
+            "child. Use this under launchd / systemd / supervisord so the "
+            "supervisor sees the long-lived server as the original child. "
+            "Implies --no-browser. Skips the post-launch health probe — the "
+            "supervisor's own KeepAlive / Restart=on-failure handles liveness."
+        ),
+    )
+    return parser.parse_args()
+
+
+# Env vars whose presence indicates this process was launched by a supervisor
+# that wants to manage the server's lifecycle (KeepAlive, Restart=always, etc.).
+# When any is set, we auto-promote to --foreground so we don't double-fork.
+#
+# - INVOCATION_ID            systemd (set on every service activation)
+# - JOURNAL_STREAM           systemd (set when stdio is wired to the journal)
+# - NOTIFY_SOCKET            systemd Type=notify, s6 sd_notify-style
+# - XPC_SERVICE_NAME         launchd (set to the Label of the running plist)
+# - SUPERVISOR_ENABLED       supervisord
+# - HERMES_WEBUI_FOREGROUND  explicit user opt-in (=1 / true / yes / on)
+#
+# Note on XPC_SERVICE_NAME: macOS launchd sets this in EVERY Terminal-launched
+# shell too — typical values include "0" (truthy in Python!) and
+# "application.com.apple.Terminal.<UUID>". A bare existence check would
+# false-positive on every Mac dev machine running ./start.sh interactively.
+# We narrow to launchd Label-style names (com.<reverse-dns>.<svc>) — those
+# are real services. Verified with `launchctl getenv XPC_SERVICE_NAME` and
+# Apple's documented launchd behavior.
+_SUPERVISOR_ENV_VARS = (
+    "INVOCATION_ID",
+    "JOURNAL_STREAM",
+    "NOTIFY_SOCKET",
+    "XPC_SERVICE_NAME",
+    "SUPERVISOR_ENABLED",
+)
+
+
+def _is_real_supervisor_value(name: str, value: str) -> bool:
+    """Filter out known-noise env-var values that aren't actual supervisors.
+
+    Most env vars in _SUPERVISOR_ENV_VARS are only set by the supervisor we
+    care about, so any non-empty value is meaningful. XPC_SERVICE_NAME is the
+    exception: macOS launchd sets it in every Terminal-spawned shell with
+    values like "0" or "application.com.apple.Terminal.<UUID>". A real
+    launchd-managed service has a reverse-DNS Label like "com.example.foo".
+    """
+    if not value:
+        return False
+    if name == "XPC_SERVICE_NAME":
+        # Reject Apple's noise values; accept Label-style names.
+        if value == "0":
+            return False
+        if value.startswith("application."):
+            return False
+    return True
+
+
+def _detect_supervisor() -> str | None:
+    """Return the name of the detected supervisor env var, or None.
+
+    Pure inspection of os.environ — no side effects. Returned name is the env
+    var that triggered detection, useful for log messages and for tests.
+    """
+    explicit = os.environ.get("HERMES_WEBUI_FOREGROUND", "").strip().lower()
+    if explicit in ("1", "true", "yes", "on"):
+        return "HERMES_WEBUI_FOREGROUND"
+    for name in _SUPERVISOR_ENV_VARS:
+        value = os.environ.get(name, "")
+        if _is_real_supervisor_value(name, value):
+            return name
+    return None
+
+
+def main() -> int:
+    args = parse_args()
+    ensure_supported_platform()
+
+    agent_dir = discover_agent_dir()
+    if not agent_dir and not hermes_command_exists():
+        if args.skip_agent_install:
+            raise RuntimeError(
+                "Hermes Agent was not found and auto-install was disabled."
+            )
+        install_hermes_agent()
+        agent_dir = discover_agent_dir()
+
+    python_exe = ensure_python_has_webui_deps(discover_launcher_python(agent_dir), agent_dir)
+    state_dir = Path(
+        os.getenv("HERMES_WEBUI_STATE_DIR", str(Path.home() / ".hermes" / "webui"))
+    ).expanduser()
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    # Mutate os.environ so child (or post-execv) inherits the resolved values.
+    os.environ["HERMES_WEBUI_HOST"] = args.host
+    os.environ["HERMES_WEBUI_PORT"] = str(args.port)
+    os.environ.setdefault("HERMES_WEBUI_STATE_DIR", str(state_dir))
+    if agent_dir:
+        os.environ["HERMES_WEBUI_AGENT_DIR"] = str(agent_dir)
+
+    server_cwd = str(agent_dir or REPO_ROOT)
+    server_path = str(REPO_ROOT / "server.py")
+
+    # --foreground (or auto-detected supervisor): replace this process with the
+    # server. The supervisor sees the long-lived server as the original child,
+    # so KeepAlive / Restart=always / autorestart=true work correctly. No
+    # health probe — the supervisor's own restart-on-exit handles liveness.
+    foreground_reason = "--foreground" if args.foreground else _detect_supervisor()
+    if foreground_reason:
+        info(
+            f"Starting Hermes Web UI on http://{args.host}:{args.port} "
+            f"(foreground mode: {foreground_reason})"
+        )
+        try:
+            os.chdir(server_cwd)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Could not chdir to {server_cwd!r} before exec: {exc}"
+            ) from exc
+        # Defensive check: if python_exe is missing or non-executable, execv
+        # raises OSError, the wrapper catches and SystemExit(1)s, and the
+        # supervisor restarts — looping forever, exactly the failure mode this
+        # PR is meant to eliminate. Convert to a single visible error.
+        if not os.access(python_exe, os.X_OK):
+            raise RuntimeError(
+                f"Python interpreter at {python_exe!r} is not executable. "
+                f"Set HERMES_WEBUI_PYTHON to a working interpreter or fix "
+                f"the agent venv at {agent_dir}."
+            )
+        # os.execv replaces the current process image. Anything after this line
+        # only runs if execv itself fails (it raises OSError on failure).
+        os.execv(python_exe, [python_exe, server_path])
+        # Unreachable — execv either replaces the process or raises.
+        raise RuntimeError("os.execv returned unexpectedly")
+
+    # Default (legacy) path: spawn the server as a detached child, probe
+    # /health, then return. Suitable for an interactive `bash start.sh` run.
+    log_path = state_dir / f"bootstrap-{args.port}.log"
+
+    info(f"Starting Hermes Web UI on http://{args.host}:{args.port}")
+    with log_path.open("ab") as log_file:
+        proc = subprocess.Popen(
+            [python_exe, server_path],
+            cwd=server_cwd,
+            env=os.environ.copy(),
+            stdout=log_file,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+
+    health_url = f"http://{args.host}:{args.port}/health"
+    if not wait_for_health(health_url):
+        raise RuntimeError(
+            f"Web UI did not become healthy at {health_url}. "
+            f"Check the log at {log_path}. Server PID: {proc.pid}"
+        )
+
+    app_url = (
+        f"http://localhost:{args.port}"
+        if args.host in ("127.0.0.1", "localhost")
+        else f"http://{args.host}:{args.port}"
+    )
+    info(f"Web UI is ready: {app_url}")
+    info(f"Log file: {log_path}")
+    if not args.no_browser:
+        open_browser(app_url)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:
+        print(f"[bootstrap] ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(1)

docker-compose.three-container.yml

@@ -0,0 +1,154 @@
+# Three-container Docker Compose: Hermes Agent + Dashboard + WebUI
+#
+# QUICK START:
+#   docker compose -f docker-compose.three-container.yml up -d
+#   Open http://localhost:8787 (chat) and http://localhost:9119 (dashboard)
+#
+# This extends the two-container setup with the Hermes Dashboard for
+# monitoring agent activity, sessions, and resource usage.
+#
+# Services:
+#   hermes-agent     — gateway API on port 8642 (CLI, Telegram, cron, tools)
+#   hermes-dashboard — monitoring dashboard on port 9119
+#   hermes-webui     — browser chat interface on port 8787
+#
+# All three share the same hermes-home volume so config, sessions,
+# skills, and memory are consistent across all surfaces.
+#
+# WHEN NOT TO USE THIS:
+#   - You hit "Permission denied" trying to share an existing ~/.hermes directory
+#     → use docker-compose.yml (single-container) instead, OR
+#     → keep this file but switch to NAMED VOLUMES (the default) instead of bind mounts
+#   - You're on Podman 3.4 or older without keep-id namespace support
+#     → see https://github.com/sunnysktsang/hermes-suite for an all-in-one image
+#
+# KNOWN LIMITATION (#681): tools triggered from the WebUI run in the WebUI
+# container, not the agent container. See docker-compose.two-container.yml
+# for context.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box. If you prefer bind mounts (e.g. to an existing
+#   directory), see docker-compose.two-container.yml for a bind-mount example.
+#   When using bind mounts, ALL THREE containers must mount the same host path
+#   AND run as the same UID/GID (set via the UID/GID env vars below).
+
+services:
+  hermes-agent:
+    image: nousresearch/hermes-agent:latest
+    container_name: hermes-agent
+    command: gateway run
+    ports:
+      - "127.0.0.1:8642:8642"
+    volumes:
+      # Persist config, state, sessions, skills, memory across restarts
+      - hermes-home:/home/hermes/.hermes
+      # Expose agent source so the WebUI can install dependencies from it
+      - hermes-agent-src:/opt/hermes
+    environment:
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      # Bind-mount permission handling for the agent — narrow set of overrides.
+      # NOTE: The agent's HERMES_HOME_MODE applies to the HERMES_HOME *directory*
+      # mode (default 0700) — NOT to credential files like the WebUI's variant.
+      # If you set this, you MUST keep the owner-execute bit so the agent can
+      # traverse its own home directory. 0640 BREAKS the agent (no x bit → no
+      # traversal). Use 0750 for group-traversable or 0701 for x-only.
+      # The agent's container detection (/.dockerenv) already auto-skips
+      # credential chmod inside Docker, so HERMES_SKIP_CHMOD is redundant here.
+      # - HERMES_HOME_MODE=0750
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+          cpus: "2.0"
+    networks:
+      - hermes-net
+
+  hermes-dashboard:
+    image: nousresearch/hermes-agent:latest
+    container_name: hermes-dashboard
+    command: dashboard --host 0.0.0.0 --insecure
+    ports:
+      - "127.0.0.1:9119:9119"
+    volumes:
+      - hermes-home:/home/hermes/.hermes
+    environment:
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      # Dashboard connects to the gateway for health/session data
+      - GATEWAY_HEALTH_URL=http://hermes-agent:8642
+    depends_on:
+      - hermes-agent
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "0.5"
+    networks:
+      - hermes-net
+
+  hermes-webui:
+    image: ghcr.io/nesquena/hermes-webui:latest
+    container_name: hermes-webui
+    depends_on:
+      - hermes-agent
+    ports:
+      # Expose on localhost only. Remove 127.0.0.1: to expose on all interfaces
+      # (set HERMES_WEBUI_PASSWORD if doing so).
+      - "127.0.0.1:8787:8787"
+    volumes:
+      # Same hermes home as the agent — shares config, sessions, state
+      - hermes-home:/home/hermeswebui/.hermes
+      # Agent source mounted where docker_init.bash expects it.
+      # At startup the init script runs:
+      #   uv pip install /home/hermeswebui/.hermes/hermes-agent
+      # which installs the agent and all its Python dependencies.
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
+      # Workspace directory — browse and edit files from the WebUI.
+      # Adapt the host path to your project directory.
+      - ${HERMES_WORKSPACE:-~/workspace}:/workspace
+    environment:
+      - HERMES_WEBUI_HOST=0.0.0.0
+      - HERMES_WEBUI_PORT=8787
+      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
+      # Match your host user's UID/GID for correct file permissions.
+      # Run `id -u` and `id -g` to find your values.
+      # On macOS, UIDs start at 501 (not 1000) — set these in a .env file:
+      #   echo "UID=$(id -u)" >> .env && echo "GID=$(id -g)" >> .env
+      - WANTED_UID=${UID:-1000}
+      - WANTED_GID=${GID:-1000}
+      # NOTE: When using bind-mount volumes shared across containers, ALL containers
+      # that write to the same host directory must run as the same UID/GID.
+      # If hermes-agent initialises the state dir as root (UID 0), hermes-webui
+      # will get a PermissionError accessing those paths — including a crash on every
+      # HTTP request if the auth signing-key file is unreadable. Either set WANTED_UID
+      # to match the agent container's UID, or use a named Docker volume (preferred).
+      # Optional: set a password for remote access
+      # - HERMES_WEBUI_PASSWORD=your-secret-password
+      # Bind-mount permission handling for the WebUI (fixes #1389, #1399).
+      # NOTE: WebUI's HERMES_HOME_MODE is a credential-file threshold (allow
+      # group bits on .env/.signing_key/etc.), DIFFERENT from the agent's
+      # which applies to the HERMES_HOME directory itself. 0640 is correct
+      # for the WebUI; do NOT copy this value to the agent service block.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
+    restart: unless-stopped
+    networks:
+      - hermes-net
+
+networks:
+  hermes-net:
+    driver: bridge
+
+volumes:
+  hermes-home:
+  hermes-agent-src:

docker-compose.two-container.yml

@@ -0,0 +1,133 @@
+# Two-container Docker Compose: Hermes Agent + Hermes WebUI
+#
+# QUICK START:
+#   docker compose -f docker-compose.two-container.yml up -d
+#   Open http://localhost:8787
+#
+# This runs the agent and web UI in separate containers connected via shared
+# Docker volumes. The WebUI installs the agent's Python dependencies from the
+# shared agent source volume at startup.
+#
+# WHEN TO USE THIS:
+#   - You want isolation between the agent gateway and the WebUI
+#   - You're already running hermes-agent in its own container
+#   - You don't need the dashboard (use docker-compose.three-container.yml for that)
+#
+# WHEN NOT TO USE THIS:
+#   - You hit "Permission denied" trying to share an existing ~/.hermes directory
+#     → use docker-compose.yml (single-container) instead, OR
+#     → keep this file but switch to NAMED VOLUMES (the default) instead of bind mounts
+#   - You're on Podman 3.4 or older without keep-id namespace support
+#     → see https://github.com/sunnysktsang/hermes-suite for an all-in-one image
+#
+# KNOWN LIMITATION (#681): tools triggered from the WebUI run in the WebUI
+# container, not the agent container. If you need git/node/etc. on the
+# WebUI's filesystem, install them in the WebUI image — or use a single-
+# container setup where everything lives in one place.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box on every Docker installation. If you prefer bind mounts
+#   to share an existing host directory:
+#
+#     volumes:
+#       hermes-home:
+#         driver: local
+#         driver_opts:
+#           type: none
+#           o: bind
+#           device: /home/youruser/.hermes
+#
+#   When using bind mounts, BOTH containers must mount the same host path,
+#   AND your host directory must be readable by UID 1000 (the default). Run:
+#     id -u && id -g
+#   to find your host UID/GID, then put them in a .env file:
+#     echo "UID=$(id -u)" >> .env
+#     echo "GID=$(id -g)" >> .env
+
+services:
+  hermes-agent:
+    image: nousresearch/hermes-agent:latest
+    container_name: hermes-agent
+    command: gateway run
+    ports:
+      # Gateway API — exposed on localhost only.
+      # Other containers on hermes-net reach it via http://hermes-agent:8642.
+      # Remove 127.0.0.1: to expose on the host network (e.g. for remote clients).
+      - "127.0.0.1:8642:8642"
+    volumes:
+      # Persist config, state, sessions, skills, memory across restarts
+      - hermes-home:/home/hermes/.hermes
+      # Expose agent source so the WebUI can install dependencies from it
+      - hermes-agent-src:/opt/hermes
+    environment:
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      # The agent image's entrypoint already supports usermod remapping.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      # Bind-mount permission handling for the agent — narrow set of overrides.
+      # NOTE: The agent's HERMES_HOME_MODE applies to the HERMES_HOME *directory*
+      # mode (default 0700) — NOT to credential files like the WebUI's variant.
+      # If you set this, you MUST keep the owner-execute bit so the agent can
+      # traverse its own home directory. 0640 BREAKS the agent (no x bit → no
+      # traversal). Use 0750 for group-traversable or 0701 for x-only.
+      # The agent's container detection (/.dockerenv) already auto-skips
+      # credential chmod inside Docker, so HERMES_SKIP_CHMOD is redundant here.
+      # - HERMES_HOME_MODE=0750
+    restart: unless-stopped
+    networks:
+      - hermes-net
+
+  hermes-webui:
+    image: ghcr.io/nesquena/hermes-webui:latest
+    container_name: hermes-webui
+    depends_on:
+      - hermes-agent
+    ports:
+      - "127.0.0.1:8787:8787"
+    volumes:
+      # Same hermes home as the agent — shares config, sessions, state
+      - hermes-home:/home/hermeswebui/.hermes
+      # Agent source mounted where docker_init.bash expects it.
+      # At startup the init script runs:
+      #   uv pip install /home/hermeswebui/.hermes/hermes-agent
+      # which installs the agent and all its Python dependencies.
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
+      # Workspace directory — browse and edit files from the WebUI.
+      # Adapt the host path to your project directory.
+      # Override with: HERMES_WORKSPACE=/your/path docker compose up
+      - ${HERMES_WORKSPACE:-~/workspace}:/workspace
+    environment:
+      - HERMES_WEBUI_HOST=0.0.0.0
+      - HERMES_WEBUI_PORT=8787
+      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
+      # Match your host user's UID/GID for correct file permissions.
+      # In two-container setups the WebUI auto-detects UID/GID from the shared
+      # hermes-home volume, but you can override explicitly if needed (#668):
+      # Run `id -u` and `id -g` to find your values.
+      # On macOS, UIDs start at 501 — set these in a .env file:
+      #   echo "UID=$(id -u)" >> .env && echo "GID=$(id -g)" >> .env
+      - WANTED_UID=${UID:-1000}
+      - WANTED_GID=${GID:-1000}
+      # Optional: set a password for remote access
+      # - HERMES_WEBUI_PASSWORD=your-secret-password
+      # Bind-mount permission handling for the WebUI (fixes #1389, #1399).
+      # NOTE: WebUI's HERMES_HOME_MODE is a credential-file threshold (allow
+      # group bits on .env/.signing_key/etc.), DIFFERENT from the agent's
+      # which applies to the HERMES_HOME directory itself. 0640 is correct
+      # for the WebUI; do NOT copy this value to the agent service block.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
+    restart: unless-stopped
+    networks:
+      - hermes-net
+
+networks:
+  hermes-net:
+    driver: bridge
+
+volumes:
+  hermes-home:
+  hermes-agent-src:

docker-compose.yml

@@ -1,22 +1,57 @@
-version: "3.8"
+# Hermes WebUI — single-container Docker Compose
+#
+# QUICK START (most users):
+#   1. (Optional) Copy .env.docker.example to .env and edit values
+#   2. docker compose up -d
+#   3. Open http://localhost:8787
+#
+# This is the simplest setup: one WebUI container that runs the agent in-process.
+# The WebUI auto-detects host UID/GID from the mounted .hermes volume.
+#
+# For multi-container setups (separate agent + webui or agent+webui+dashboard),
+# see docker-compose.two-container.yml or docker-compose.three-container.yml.
 
 services:
   hermes-webui:
     build: .
     ports:
+    # select only one; use 127.0.0.1 version to expose to localhost only
       - "127.0.0.1:8787:8787"
+#      - "8787:8787"
     volumes:
-      # Persist session data, settings, and projects across restarts
-      - hermes-data:/data
-      # Mount hermes home for agent features and profile management
-      - ${HERMES_HOME:-${HOME}/.hermes}:/root/.hermes
+      # Mount your Hermes home directory into the container.
+      # The default (${HOME}/.hermes) works on both macOS (/Users/<you>/.hermes)
+      # and Linux (/home/<you>/.hermes) — no change needed for standard installs.
+      # Only set HERMES_HOME explicitly if your .hermes lives somewhere non-standard.
+      # macOS note: set UID and GID below to match your user ID (run `id -u` and `id -g`).
+      - ${HERMES_HOME:-${HOME}/.hermes}:/home/hermeswebui/.hermes
+      # Your workspace directory shown on first launch (adapt if yours is different, the container will use the mounted /workspace)
+      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
     environment:
+      # Set to your host user ID: run `id -u` and `id -g` to find them.
+      # On macOS, UIDs start at 501 (not 1000), so set UID and GID in a .env file:
+      #   echo "UID=$(id -u)" >> .env
+      #   echo "GID=$(id -g)" >> .env
+      # Without this, the container may not be able to read your mounted files.
+      - WANTED_UID=${UID:-1000}
+      - WANTED_GID=${GID:-1000}
+      # Required: bind address and port
       - HERMES_WEBUI_HOST=0.0.0.0
       - HERMES_WEBUI_PORT=8787
-      - HERMES_WEBUI_STATE_DIR=/data
+      # Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)
+      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
+      # Default workspace directory shown on first launch
+#      - HERMES_WEBUI_DEFAULT_WORKSPACE=/workspace
       # Optional: set a password for remote access
       # - HERMES_WEBUI_PASSWORD=your-secret-password
+      #
+      # Bind-mount permission handling (fixes #1389, #1399):
+      #   When you mount an EXISTING ~/.hermes directory (the common case),
+      #   the WebUI's startup credential-permission fixer can clash with
+      #   your host file modes (e.g. 0640 group-readable .env files).
+      #   Set HERMES_SKIP_CHMOD=1 to bypass the fixer entirely, OR set
+      #   HERMES_HOME_MODE=0640 to allow group bits while still stripping
+      #   world-readable. Both are documented in api/startup.py.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
     restart: unless-stopped
-
-volumes:
-  hermes-data:

docker_init.bash

@@ -0,0 +1,345 @@
+#!/bin/bash
+
+set -e
+
+error_exit() {
+  echo -n "!! ERROR: "
+  echo $*
+  echo "!! Exiting script (ID: $$)"
+  exit 1
+}
+
+ok_exit() {
+  echo $*
+  echo "++ Exiting script (ID: $$)"
+  exit 0
+}
+
+## Environment variables loaded when passing environment variables from user to user
+# Ignore list: variables to ignore when loading environment variables from user to user
+export ENV_IGNORELIST="HOME PWD USER SHLVL TERM OLDPWD SHELL _ SUDO_COMMAND HOSTNAME LOGNAME MAIL SUDO_GID SUDO_UID SUDO_USER CHECK_NV_CUDNN_VERSION VIRTUAL_ENV VIRTUAL_ENV_PROMPT ENV_IGNORELIST ENV_OBFUSCATE_PART"
+# Obfuscate part: part of the key to obfuscate when loading environment variables from user to user, ex: HF_TOKEN, ...
+export ENV_OBFUSCATE_PART="TOKEN API KEY"
+
+# Check for ENV_IGNORELIST and ENV_OBFUSCATE_PART
+if [ -z "${ENV_IGNORELIST+x}" ]; then error_exit "ENV_IGNORELIST not set"; fi
+if [ -z "${ENV_OBFUSCATE_PART+x}" ]; then error_exit "ENV_OBFUSCATE_PART not set"; fi
+
+whoami=`whoami`
+script_dir=$(dirname $0)
+script_name=$(basename $0)
+echo ""; echo ""
+echo "======================================"
+echo "=================== Starting script (ID: $$)"
+echo "== Running ${script_name} in ${script_dir} as ${whoami}"
+script_fullname=$0
+echo "  - script_fullname: ${script_fullname}"
+ignore_value="VALUE_TO_IGNORE"
+
+# everyone can read our files by default
+umask 0022
+
+# Write a world-writeable file (preferably inside /tmp -- ie within the container)
+write_worldtmpfile() {
+  tmpfile=$1
+  if [ -z "${tmpfile}" ]; then error_exit "write_worldfile: missing argument"; fi
+  if [ -f $tmpfile ]; then rm -f $tmpfile; fi
+  echo -n $2 > ${tmpfile}
+  chmod 777 ${tmpfile}
+}
+
+itdir=/tmp/hermeswebui_init
+if [ ! -d $itdir ]; then mkdir $itdir; chmod 777 $itdir; fi
+if [ ! -d $itdir ]; then error_exit "Failed to create $itdir"; fi
+
+# Set user and group id
+# logic: if not set and file exists, use file value, else use default. Create file for persistence when the container is re-run
+# reasoning: needed when using docker compose as the file will exist in the stopped container, and changing the value from environment variables or configuration file must be propagated from hermeswebuitoo to hermeswebuitoo transition (those values are the only ones loaded before the environment variables dump file are loaded)
+it=$itdir/hermeswebui_user_uid
+if [ -z "${WANTED_UID+x}" ]; then
+  if [ -f $it ]; then WANTED_UID=$(cat $it); fi
+fi
+# Auto-detect from mounted volumes if still unset (#569, #668).
+# On macOS, host UIDs start at 501. Using the wrong UID means the container
+# user cannot read the bind-mounted files, making the workspace appear empty.
+# In two-container setups (hermes-agent + hermes-webui), the shared hermes-home
+# volume may be owned by the agent container's UID — detect from there first.
+if [ -z "${WANTED_UID+x}" ] || [ "${WANTED_UID}" = "1024" ]; then
+  # Priority 1: hermes-home shared volume — covers two-container Zeabur/Compose setups (#668)
+  for _probe_dir in "/home/hermeswebui/.hermes" "$HERMES_HOME" "/opt/data"; do
+    if [ -d "$_probe_dir" ]; then
+      _detected_uid=$(stat -c '%u' "$_probe_dir" 2>/dev/null || echo "")
+      if [ -n "$_detected_uid" ] && [ "$_detected_uid" != "0" ]; then
+        echo "-- Auto-detected UID: $_detected_uid (from $_probe_dir)"
+        WANTED_UID=$_detected_uid
+        break
+      fi
+    fi
+  done
+fi
+if [ -z "${WANTED_UID+x}" ] || [ "${WANTED_UID}" = "1024" ]; then
+  # Priority 2: /workspace bind-mount — the standard single-container mount point
+  if [ -d "/workspace" ]; then
+    _detected_uid=$(stat -c '%u' "/workspace" 2>/dev/null || echo "")
+    if [ -n "$_detected_uid" ] && [ "$_detected_uid" != "0" ]; then
+      echo "-- Auto-detected workspace UID: $_detected_uid (from /workspace)"
+      WANTED_UID=$_detected_uid
+    fi
+  fi
+fi
+WANTED_UID=${WANTED_UID:-1024}
+write_worldtmpfile $it "$WANTED_UID"
+echo "-- WANTED_UID: \"${WANTED_UID}\""
+
+it=$itdir/hermeswebui_user_gid
+if [ -z "${WANTED_GID+x}" ]; then
+  if [ -f $it ]; then WANTED_GID=$(cat $it); fi
+fi
+# Auto-detect GID from mounted volumes to match (#569, #668)
+if [ -z "${WANTED_GID+x}" ] || [ "${WANTED_GID}" = "1024" ]; then
+  # Priority 1: hermes-home shared volume
+  for _probe_dir in "/home/hermeswebui/.hermes" "$HERMES_HOME" "/opt/data"; do
+    if [ -d "$_probe_dir" ]; then
+      _detected_gid=$(stat -c '%g' "$_probe_dir" 2>/dev/null || echo "")
+      if [ -n "$_detected_gid" ] && [ "$_detected_gid" != "0" ]; then
+        echo "-- Auto-detected GID: $_detected_gid (from $_probe_dir)"
+        WANTED_GID=$_detected_gid
+        break
+      fi
+    fi
+  done
+fi
+if [ -z "${WANTED_GID+x}" ] || [ "${WANTED_GID}" = "1024" ]; then
+  # Priority 2: /workspace bind-mount
+  if [ -d "/workspace" ]; then
+    _detected_gid=$(stat -c '%g' "/workspace" 2>/dev/null || echo "")
+    if [ -n "$_detected_gid" ] && [ "$_detected_gid" != "0" ]; then
+      echo "-- Auto-detected workspace GID: $_detected_gid (from /workspace)"
+      WANTED_GID=$_detected_gid
+    fi
+  fi
+fi
+WANTED_GID=${WANTED_GID:-1024}
+write_worldtmpfile $it "$WANTED_GID"
+echo "-- WANTED_GID: \"${WANTED_GID}\""
+
+echo "== Most Environment variables set"
+
+# Check user id and group id
+new_gid=`id -g`
+new_uid=`id -u`
+echo "== user ($whoami)"
+echo "  uid: $new_uid / WANTED_UID: $WANTED_UID"
+echo "  gid: $new_gid / WANTED_GID: $WANTED_GID"
+
+save_env() {
+  tosave=$1
+  echo "-- Saving environment variables to $tosave"
+  env | sort > "$tosave"
+}
+
+load_env() {
+  tocheck=$1
+  overwrite_if_different=$2
+  ignore_list="${ENV_IGNORELIST}"
+  obfuscate_part="${ENV_OBFUSCATE_PART}"
+  if [ -f "$tocheck" ]; then
+    echo "-- Loading environment variables from $tocheck (overwrite existing: $overwrite_if_different) (ignorelist: $ignore_list) (obfuscate: $obfuscate_part)"
+    while IFS='=' read -r key value; do
+      doit=false
+      # checking if the key is in the ignorelist
+      for i in $ignore_list; do
+        if [[ "A$key" ==  "A$i" ]]; then doit=ignore; break; fi
+      done
+      if [[ "A$doit" == "Aignore" ]]; then continue; fi
+      rvalue=$value
+      # checking if part of the key is in the obfuscate list
+      doobs=false
+      for i in $obfuscate_part; do
+        if [[ "A$key" == *"$i"* ]]; then doobs=obfuscate; break; fi
+      done
+      if [[ "A$doobs" == "Aobfuscate" ]]; then rvalue="**OBFUSCATED**"; fi
+
+      if [ -z "${!key}" ]; then
+        echo "  ++ Setting environment variable $key [$rvalue]"
+        doit=true
+      elif [ "A$overwrite_if_different" == "Atrue" ]; then
+        cvalue="${!key}"
+        if [[ "A${doobs}" == "Aobfuscate" ]]; then cvalue="**OBFUSCATED**"; fi
+        if [[ "A${!key}" != "A${value}" ]]; then
+          echo "  @@ Overwriting environment variable $key [$cvalue] -> [$rvalue]"
+          doit=true
+        else
+          echo "  == Environment variable $key [$rvalue] already set and value is unchanged"
+        fi
+      fi
+      if [[ "A$doit" == "Atrue" ]]; then
+        export "$key=$value"
+      fi
+    done < "$tocheck"
+  fi
+}
+
+# hermeswebuitoo is a specfiic user not existing by default on ubuntu, we can check its whomai
+if [ "A${whoami}" == "Ahermeswebuitoo" ]; then 
+  echo "-- Running as hermeswebuitoo, will switch hermeswebui to the desired UID/GID"
+  # The script is started as hermeswebuitoo -- UID/GID 1025/1025
+
+  # We are altering the UID/GID of the hermeswebui user to the desired ones and restarting as that user
+  # using usermod for the already create hermeswebui user, knowing it is not already in use
+  # per usermod manual: "You must make certain that the named user is not executing any processes when this command is being executed"
+  sudo groupmod -o -g ${WANTED_GID} hermeswebui || error_exit "Failed to set GID of hermeswebui user"
+  sudo usermod -o -u ${WANTED_UID} hermeswebui || error_exit "Failed to set UID of hermeswebui user"
+  sudo chown -R ${WANTED_UID}:${WANTED_GID} /home/hermeswebui || error_exit "Failed to set owner of /home/hermeswebui"
+  save_env /tmp/hermeswebuitoo_env.txt  
+  # restart the script as hermeswebui set with the correct UID/GID this time
+  echo "-- Restarting as hermeswebui user with UID ${WANTED_UID} GID ${WANTED_GID}"
+  sudo su hermeswebui $script_fullname || error_exit "subscript failed"
+  ok_exit "Clean exit"
+fi
+
+# If we are here, the script is started as another user than hermeswebuitoo
+# because the whoami value for the hermeswebui user can be any existing user, we can not check against it
+# instead we check if the UID/GID are the expected ones
+if [ "$WANTED_GID" != "$new_gid" ]; then error_exit "hermeswebui MUST be running as UID ${WANTED_UID} GID ${WANTED_GID}, current UID ${new_uid} GID ${new_gid}"; fi
+if [ "$WANTED_UID" != "$new_uid" ]; then error_exit "hermeswebui MUST be running as UID ${WANTED_UID} GID ${WANTED_GID}, current UID ${new_uid} GID ${new_gid}"; fi
+
+########## 'hermeswebui' specific section below
+
+# We are therefore running as hermeswebui
+echo ""; echo "== Running as hermeswebui"
+
+# Load environment variables one by one if they do not exist from /tmp/hermeswebuitoo_env.txt
+it=/tmp/hermeswebuitoo_env.txt
+if [ -f $it ]; then
+  echo "-- Loading not already set environment variables from $it"
+  load_env $it true
+fi
+
+##
+echo ""; echo "-- Making sure /app is owned by the hermeswebui user to avoid permission issues when running the server "
+sudo mkdir -p /app || error_exit "Failed to create /app directory"
+sudo chown hermeswebui:hermeswebui /app || error_exit "Failed to set owner of /app to hermeswebui user"
+sudo rsync -av --chown=hermeswebui:hermeswebui /apptoo/ /app/ || error_exit "Failed to sync /apptoo to /app with correct ownership"
+it=/app/.testfile; touch $it || error_exit "Failed to verify /app directory"
+rm -f $it || error_exit "Failed to delete test file in /app"
+
+######## Environment variables (consume AFTER the load_env)
+
+echo ""; echo "== Checking required environment variables for hermes-webui"
+
+echo ""; echo "-- HERMES_WEBUI_VERSION: Where to store sessions, workspaces, and other state (default: ~/.hermes/webui-mvp)"
+if [ -z "${HERMES_WEBUI_STATE_DIR+x}" ]; then error_exit "HERMES_WEBUI_STATE_DIR not set"; fi; 
+echo "-- HERMES_WEBUI_STATE_DIR: $HERMES_WEBUI_STATE_DIR"
+if [ ! -d "$HERMES_WEBUI_STATE_DIR" ]; then mkdir -p $HERMES_WEBUI_STATE_DIR || error_exit "Failed to create state directory at $HERMES_WEBUI_STATE_DIR"; fi
+if [ ! -d "$HERMES_WEBUI_STATE_DIR" ]; then error_exit "HERMES_WEBUI_STATE_DIR directory does not exist at $HERMES_WEBUI_STATE_DIR"; fi
+it="$HERMES_WEBUI_STATE_DIR/.testfile"; touch $it || error_exit "Failed to verify state directory at $HERMES_WEBUI_STATE_DIR"
+rm -f $it || error_exit "Failed to delete test file in $HERMES_WEBUI_STATE_DIR"
+
+echo ""; echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE: Default workspace directory shown on first launch"
+if [ -z "${HERMES_WEBUI_DEFAULT_WORKSPACE+x}" ]; then echo "HERMES_WEBUI_DEFAULT_WORKSPACE not set, setting to /workspace"; export HERMES_WEBUI_DEFAULT_WORKSPACE="/workspace"; fi;
+echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE: $HERMES_WEBUI_DEFAULT_WORKSPACE"
+# Use sudo for mkdir — Docker may auto-create bind-mount directories as root (#357).
+# Skip mkdir if the directory already exists (e.g. a read-only mount — #670).
+if [ ! -d "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then
+  sudo mkdir -p "$HERMES_WEBUI_DEFAULT_WORKSPACE" || error_exit "Failed to create default workspace at $HERMES_WEBUI_DEFAULT_WORKSPACE"
+fi
+if [ ! -d "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then error_exit "HERMES_WEBUI_DEFAULT_WORKSPACE directory does not exist at $HERMES_WEBUI_DEFAULT_WORKSPACE"; fi
+# Only chown and write-test if the workspace is writable. Read-only bind-mounts
+# (:ro) are valid — the workspace is used for browsing, not writing by the server.
+if [ -w "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then
+  sudo chown hermeswebui:hermeswebui "$HERMES_WEBUI_DEFAULT_WORKSPACE" || echo "!! WARNING: Could not chown $HERMES_WEBUI_DEFAULT_WORKSPACE (continuing)"
+  it="$HERMES_WEBUI_DEFAULT_WORKSPACE/.testfile"; touch $it && rm -f $it || echo "!! WARNING: Could not write to $HERMES_WEBUI_DEFAULT_WORKSPACE (continuing)"
+else
+  echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE is read-only — skipping chown/write check (read-only workspace is supported)"
+fi
+
+echo ""; echo "==================="
+echo ""; echo "== Installing uv and creating a new virtual environment for hermes-webui"
+
+export PATH="/home/hermeswebui/.local/bin/:$PATH"
+if command -v uv &>/dev/null; then
+  echo "-- uv already installed ($(uv --version)), skipping download"
+else
+  echo "-- uv not found, downloading..."
+  curl -LsSf https://astral.sh/uv/install.sh | sh || error_exit "Failed to install uv — check network connectivity"
+fi
+export UV_PROJECT_ENVIRONMENT=venv
+
+export UV_CACHE_DIR=/uv_cache
+sudo mkdir -p ${UV_CACHE_DIR} || error_exit "Failed to create /uv_cache directory"
+sudo chown hermeswebui:hermeswebui ${UV_CACHE_DIR} || error_exit "Failed to set owner of ${UV_CACHE_DIR} to hermeswebui user"
+
+cd /app
+if [ -f /app/venv/bin/python3 ]; then
+  echo ""; echo "== Existing virtual environment found — reusing (fast restart)"
+else
+  echo ""; echo "== Creating new virtual environment"
+  uv venv venv
+fi
+export VIRTUAL_ENV=/app/venv
+test -d /app/venv
+test -f /app/venv/bin/activate
+
+echo "";echo "== Activating hermes webui's virtual environment"
+source /app/venv/bin/activate || error_exit "Failed to activate hermeswebui virtual environment"
+test -x /app/venv/bin/python3
+
+ensure_hindsight_client_docker_dependency() {
+  # Keep this outside the .deps_installed fast-restart guard so existing
+  # two-container Docker venvs self-heal after this dependency was added.
+  _hindsight_client_requirement="hindsight-client>=0.4.22"
+  echo ""; echo "== Checking Hindsight memory provider dependency"
+  if uv pip show hindsight-client >/dev/null 2>&1; then
+    echo "-- hindsight-client already installed"
+  else
+    echo "-- Installing ${_hindsight_client_requirement} for Hindsight memory provider support"
+    uv pip install "${_hindsight_client_requirement}" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hindsight-client"
+  fi
+}
+
+if [ -f /app/venv/.deps_installed ]; then
+  echo ""; echo "== Dependencies already installed — skipping (fast restart)"
+else
+  echo ""; echo "== Installing hermes-webui dependencies"
+  uv pip install -r requirements.txt --trusted-host pypi.org --trusted-host files.pythonhosted.org
+  uv pip install -U pip setuptools --trusted-host pypi.org --trusted-host files.pythonhosted.org
+  test -x /app/venv/bin/pip
+
+  echo ""; echo "== Adding hermes-agent's pyproject.toml base dependencies to the virtual environment"
+  _agent_paths=(
+    "/home/hermeswebui/.hermes/hermes-agent"
+    "/opt/hermes"
+  )
+  _agent_src=""
+  for _p in "${_agent_paths[@]}"; do
+    if [ -d "$_p" ] && [ -f "$_p/pyproject.toml" ]; then
+      _agent_src="$_p"
+      break
+    fi
+  done
+  if [ -n "$_agent_src" ]; then
+    uv pip install "$_agent_src[all]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
+  else
+    echo ""
+    echo "!! WARNING: hermes-agent source not found."
+    echo "!!   Looked in: ${_agent_paths[0]}"
+    echo "!!              ${_agent_paths[1]}"
+    echo "!! The WebUI will start with reduced functionality (no model auto-detection,"
+    echo "!! no personality routing, no CLI session imports)."
+    echo "!! To fix: mount the agent source volume into the container:"
+    echo "!!   -v /path/to/hermes-agent:/home/hermeswebui/.hermes/hermes-agent"
+    echo "!! Or see the two-container compose example:"
+    echo "!!   https://github.com/nesquena/hermes-webui/blob/master/docker-compose.two-container.yml"
+    echo ""
+  fi
+  touch /app/venv/.deps_installed
+fi
+
+ensure_hindsight_client_docker_dependency
+
+echo ""; echo "== Running hermes-webui"
+cd /app; python server.py || error_exit "hermes-webui failed or exited with an error"
+
+# we should never be here because the server should be running indefinitely, but if we are, we exit safely
+ok_exit "Clean exit"

docs/EXTENSIONS.md

@@ -0,0 +1,212 @@
+# WebUI Extensions
+
+Hermes WebUI supports a small, opt-in extension surface for self-hosted installs.
+It lets an administrator serve local static assets and inject same-origin CSS or
+JavaScript into the app shell without editing the WebUI source tree.
+
+> **Trust model — read this first.** Extensions execute with full WebUI session
+> authority. An extension JS file can call any API the logged-in user can call,
+> including reading conversation history, sending messages, modifying settings,
+> and triggering tool actions. **Only enable extensions you wrote yourself or
+> from sources you trust as much as the WebUI source itself.** If your WebUI is
+> shared with users you do not fully trust, do not enable extensions.
+> Do not point `HERMES_WEBUI_EXTENSION_DIR` at a user-writable directory.
+
+This is intentionally not a plugin marketplace or dependency system. It is a
+safe escape hatch for local dashboards, internal tooling, and workflow-specific
+panels that should not live in core Hermes WebUI.
+
+## What extensions can do
+
+Extensions can:
+
+- serve files from one configured local directory at `/extensions/...`
+- inject configured same-origin stylesheets into `<head>`
+- inject configured same-origin scripts before `</body>`
+- call the normal WebUI APIs available to the browser session
+
+Extensions cannot, by themselves:
+
+- bypass WebUI authentication
+- serve files outside the configured extension directory
+- load third-party scripts/styles through the built-in injection config
+- change Hermes Agent permissions, models, memory, or tools unless they call
+  existing authenticated APIs that already allow those changes
+
+## Configuration
+
+Extensions are disabled by default. Configure them with environment variables
+before starting the WebUI server. `HERMES_WEBUI_EXTENSION_DIR` must point to an
+existing directory before any script or stylesheet URLs are injected:
+
+```bash
+export HERMES_WEBUI_EXTENSION_DIR=/path/to/my-extension/static
+export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js
+export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css
+./start.sh
+```
+
+Multiple URLs may be comma-separated:
+
+```bash
+export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/runtime.js,/extensions/app.js
+export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/base.css,/extensions/theme.css
+```
+
+## URL rules
+
+Injected asset URLs are deliberately restricted:
+
+- must be same-origin paths
+- must start with `/extensions/` or `/static/`
+- must not include a URL scheme, host, fragment, quote, angle bracket, newline,
+  NUL byte, or backslash
+
+Allowed examples:
+
+```text
+/extensions/app.js
+/extensions/app.css
+/extensions/app.js?v=1
+/static/theme.css
+```
+
+Rejected examples:
+
+```text
+https://example.com/app.js
+//example.com/app.js
+javascript:alert(1)
+/api/session
+/extensions/app.js#fragment
+```
+
+These restrictions keep the existing Content Security Policy intact and avoid
+turning the extension hook into a third-party script loader. Invalid configured
+URLs are ignored rather than injected.
+
+## Static file serving
+
+When `HERMES_WEBUI_EXTENSION_DIR` points at an existing directory, files under
+that directory are available below `/extensions/`:
+
+```text
+/path/to/my-extension/static/app.js  ->  /extensions/app.js
+/path/to/my-extension/static/ui.css  ->  /extensions/ui.css
+```
+
+The static handler is sandboxed:
+
+- path traversal is rejected, including encoded traversal
+- dotfiles and dot-directories are not served
+- symlinks that resolve outside the extension directory are rejected
+- missing or invalid extension directories behave as disabled
+- failures return a generic 404 without exposing local filesystem paths
+
+## Security notes
+
+Only enable extensions from directories you control. Extension JavaScript runs in
+the WebUI origin and can call the same authenticated WebUI APIs as the logged-in
+browser session.
+
+For shared or remotely exposed installations:
+
+- keep `HERMES_WEBUI_PASSWORD` enabled
+- bind to loopback unless you intentionally expose the service
+- review extension code before enabling it
+- prefer small, auditable extension files
+- avoid serving generated or user-writable directories as extension roots
+
+## Extension authoring guidance
+
+Extensions share the page with the WebUI app, so they should be additive and
+reversible. Prefer small, well-scoped DOM changes that can be removed or hidden
+without breaking the built-in Chat, Tasks, Settings, or session views.
+
+Recommended patterns:
+
+- create extension-specific containers with unique IDs or class prefixes
+- add UI next to existing views instead of replacing large app containers
+- keep event listeners scoped to extension-owned elements where possible
+- preserve built-in navigation behavior and restore any view state you change
+- use `hidden`, `aria-*`, and extension-scoped CSS for panels or overlays
+- guard initialization so reloading or re-injecting the script does not create
+  duplicate buttons, panels, timers, or event listeners
+
+Avoid destructive mutations such as replacing `document.body.innerHTML`,
+`main.innerHTML`, or other broad WebUI containers. Those patterns can remove or
+mask the app's existing panels and leave normal navigation unable to recover
+after an extension view is opened.
+
+For custom pages, prefer adding a dedicated panel and toggling it alongside the
+built-in views:
+
+```javascript
+(() => {
+  if (document.getElementById('my-extension-panel')) return;
+
+  const panel = document.createElement('section');
+  panel.id = 'my-extension-panel';
+  panel.className = 'main-view my-extension-panel';
+  panel.hidden = true;
+  panel.textContent = 'My extension page';
+
+  document.querySelector('main')?.appendChild(panel);
+
+  function showPanel() {
+    document.querySelectorAll('main > .main-view').forEach((view) => {
+      view.hidden = view !== panel;
+    });
+  }
+
+  // Wire showPanel() to an extension-owned button or menu item.
+})();
+```
+
+If host CSS overrides `[hidden]`, add an extension-scoped rule such as:
+
+```css
+.my-extension-panel[hidden] {
+  display: none !important;
+}
+```
+
+## Minimal example
+
+Create a local extension directory:
+
+```bash
+mkdir -p ~/.hermes/webui-extension
+cat > ~/.hermes/webui-extension/app.css <<'CSS'
+.my-extension-badge {
+  position: fixed;
+  right: 12px;
+  bottom: 12px;
+  padding: 6px 10px;
+  border-radius: 999px;
+  background: #202236;
+  color: #fff;
+  font: 12px system-ui, sans-serif;
+  z-index: 9999;
+}
+CSS
+cat > ~/.hermes/webui-extension/app.js <<'JS'
+(() => {
+  const badge = document.createElement('div');
+  badge.className = 'my-extension-badge';
+  badge.textContent = 'Extension loaded';
+  document.body.appendChild(badge);
+})();
+JS
+```
+
+Start WebUI with the extension enabled:
+
+```bash
+HERMES_WEBUI_EXTENSION_DIR=~/.hermes/webui-extension \
+HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css \
+HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js \
+./start.sh
+```
+
+Open the WebUI and confirm the badge appears.

docs/ISSUES.md

@@ -0,0 +1,23 @@
+# Upstream Issues — Root Cause Analysis
+
+## #1256: Browser tools fail with "Playwright not installed"
+
+### Root Cause
+The check lives in **hermes-agent** (upstream), not hermes-webui:
+
+```
+hermes-agent/tools/browser_tool.py → check_browser_requirements()
+```
+
+`check_browser_requirements()` does not recognize CDP (Chrome DevTools Protocol) mode — it only looks for a local Playwright/Puppeteer install. When the agent runs in CDP mode (connecting to an existing browser), the check still fails.
+
+### WebUI side
+The WebUI already passes `CLI_TOOLSETS` correctly per-request. The `enabled_toolsets` field in the cron/chat config is dynamic and works as intended.
+
+### Fix required
+The fix must happen in `hermes-agent/tools/browser_tool.py`:
+- `check_browser_requirements()` should skip the Playwright check when CDP mode is configured
+- Or add a `BROWSER_MODE=cdp` env var that bypasses the local browser requirement
+
+### Workaround
+Use `CLOUD_BROWSER=true` or configure `browser.base_url` to point to a remote CDP endpoint. This bypasses the local Playwright requirement.

docs/docker.md

@@ -0,0 +1,202 @@
+# Hermes WebUI — Docker setup guide
+
+This is the comprehensive Docker reference. For a 5-minute quickstart, see the [README Docker section](../README.md#docker).
+
+## TL;DR — pick one
+
+| Setup | When to use | File |
+|---|---|---|
+| **Single-container** (recommended) | You just want chat working. WebUI runs the agent in-process. | `docker-compose.yml` |
+| **Two-container** | You want isolation between gateway (CLI/Telegram/cron) and chat UI. | `docker-compose.two-container.yml` |
+| **Three-container** | Two-container PLUS the dashboard for monitoring. | `docker-compose.three-container.yml` |
+| **All-in-one image** (community fork — third-party, not maintained by us) | Podman 3.4 / multi-arch / supervisord-style preference. | [sunnysktsang/hermes-suite](https://github.com/sunnysktsang/hermes-suite) — see [#1399](https://github.com/nesquena/hermes-webui/issues/1399) for the original discussion |
+
+If something stops working, **start with the single-container setup** — it's the simplest path and fixes most permission/UID/path-mismatch issues by construction.
+
+## 5-minute quickstart (single container)
+
+```bash
+git clone https://github.com/nesquena/hermes-webui
+cd hermes-webui
+cp .env.docker.example .env
+# Edit .env if needed (most users can skip this on Linux)
+docker compose up -d
+open http://localhost:8787
+```
+
+That's it. Your existing `~/.hermes` directory is mounted, your `~/workspace` is browsable, and the WebUI auto-detects your UID/GID from the mounted volume.
+
+## What goes wrong (and how to fix it)
+
+### 1. "Permission denied" at startup
+
+**Symptom**: Container starts but immediately crashes, logs show:
+```
+PermissionError: [Errno 13] Permission denied: '/home/hermeswebui/.hermes/...'
+```
+
+**Cause**: The container's user (UID 1000 by default) can't read your bind-mounted directory because your host files are owned by a different UID.
+
+**Fix**: Set `UID` and `GID` in `.env` to match your host:
+```bash
+echo "UID=$(id -u)" >> .env
+echo "GID=$(id -g)" >> .env
+docker compose down && docker compose up -d
+```
+
+On macOS, host UIDs start at 501. On Linux, the first interactive user is usually UID 1000.
+
+> **macOS Docker Desktop**: if UID mapping still misbehaves after the env fix, try toggling **Settings → General → File sharing implementation** between VirtioFS and gRPC-FUSE. Different implementations preserve UIDs across the host/container boundary differently.
+
+### 2. ".env file mode 0640 → permission denied" (#1389)
+
+**Symptom**: You set `HERMES_HOME_MODE=0640` (or some other group-readable mode) on your host `.env` file, container starts, then errors out:
+```
+[security] fixed permissions on .env (0o640 -> 0600)
+failed to load .env: open .env: permission denied
+```
+
+**Cause**: WebUI's `fix_credential_permissions()` startup hook enforces 0600 by default. This is the right thing for a clean install but conflicts with operator-set modes.
+
+**Fix**: Set one of these env vars in your `.env`:
+- `HERMES_SKIP_CHMOD=1` — bypass the fixer entirely
+- `HERMES_HOME_MODE=0640` — allow group bits, only strip world-readable
+
+Both are documented in `api/startup.py::fix_credential_permissions()`.
+
+> ⚠️ **Multi-container warning**: `HERMES_HOME_MODE` has DIFFERENT semantics in the agent image vs. the WebUI:
+> - **WebUI**: credential FILE mode threshold (`0640` allows group bits on `.env`)
+> - **Agent**: `HERMES_HOME` *directory* mode (default `0700`)
+>
+> `0640` on a directory has no owner-execute bit, so the agent can't traverse its own home → bricked. For multi-container setups, use `HERMES_HOME_MODE=0750` (group-traversable) or `0701` (x-only). The compose files have per-service comments that match each side's semantics.
+
+### 3. "Workspace appears empty even though my files are there"
+
+**Symptom**: WebUI loads but `/workspace` shows no files.
+
+**Cause**: Same as #1 — UID mismatch on the bind mount.
+
+**Fix**: Same as #1 — match host UID/GID via `.env`.
+
+### 4. "Two-container setup: WebUI can't find agent source" (#858)
+
+**Symptom**: WebUI logs at startup:
+```
+!! WARNING: hermes-agent source not found.
+!!   Looked in: /home/hermeswebui/.hermes/hermes-agent
+!!              /opt/hermes
+```
+
+**Cause**: The agent's source (`/opt/hermes` inside the agent container) needs to be exposed to the WebUI container via a shared volume. The two-container compose file does this via `hermes-agent-src` named volume, but if you're using bind mounts incorrectly the path won't resolve.
+
+**Fix**: Use the named volumes that ship with `docker-compose.two-container.yml` — don't replace them with bind mounts unless you know what you're doing. The agent container writes its source to `/opt/hermes`, and the WebUI mounts that volume at `/home/hermeswebui/.hermes/hermes-agent`.
+
+If you must use a bind mount: pick a host path, then mount it to `/opt/hermes` in the agent container AND `/home/hermeswebui/.hermes/hermes-agent` in the WebUI container.
+
+### 5. "Tools (git, node, etc.) missing in two-container setup" (#681)
+
+**Symptom**: You ask the agent to run `git status` in chat and it errors with `command not found`.
+
+**Cause**: This is **architectural, not a bug**. In the two-container setup, agent processes started by the WebUI run **inside the WebUI container**, not the agent container. The WebUI image doesn't include git/node by design (it's a UI image, not a tool host).
+
+**Workarounds**:
+- **Single-container setup** (`docker-compose.yml`) — everything in one container, no boundary
+- **Custom WebUI image** — extend the `Dockerfile` to install the tools you need
+- **Combined image** ([sunnysktsang/hermes-suite](https://github.com/sunnysktsang/hermes-suite)) — community fork that ships agent+webui+dashboard in one container
+
+### 6. "config.yaml not loaded"
+
+**Symptom**: You have a `config.yaml` in your host `~/.hermes/`, but the WebUI shows "no model configured" or doesn't pick up your custom providers.
+
+**Cause**: Either the file isn't readable (UID/GID issue, see #1) or it's not in the expected path inside the container.
+
+**Fix**:
+- Verify: `docker exec hermes-webui ls -la /home/hermeswebui/.hermes/config.yaml`
+- If it doesn't exist: your host bind mount is pointing at the wrong directory.
+- If it exists but is unreadable: see #1 for the UID/GID fix.
+
+### 7. "On Podman: can't share .hermes between containers"
+
+**Symptom**: Two-container setup works on Docker but fails on Podman with permission errors no matter what UID/GID you set.
+
+**Cause**: Podman 3.4 (Ubuntu 22.04 default) has limited support for `userns_mode: keep-id` across multiple containers — files written by one container appear with a different UID in the other.
+
+**Fix**: Either upgrade to Podman 4+ (which fixes this), or use the [single-container setup](#5-minute-quickstart-single-container), or use the [community all-in-one image](https://github.com/sunnysktsang/hermes-suite).
+
+## Multi-container architecture
+
+The two- and three-container setups use **named Docker volumes** (not bind mounts) by default for a reason: named volumes solve the UID/GID problem by construction. Docker creates the volume's root directory with the correct ownership, all containers reading/writing to it see the same files, no host-side permission setup required.
+
+```
+                 ┌─────────────────────────────────┐
+                 │      hermes-home (volume)       │
+                 │  (config, sessions, state, ...)  │
+                 └─────────────────────────────────┘
+                          ↑              ↑
+                          │ rw           │ rw
+                          │              │
+      ┌──────────────┐    │              │    ┌──────────────┐
+      │ hermes-agent │────┘              └────│ hermes-webui │
+      │  (port 8642) │                        │  (port 8787) │
+      └──────────────┘                        └──────────────┘
+              │                                       ↑
+              │ rw                                    │ ro
+              ↓                                       │
+      ┌─────────────────────────┐                     │
+      │ hermes-agent-src (vol)  │─────────────────────┘
+      │ (agent's Python source) │
+      └─────────────────────────┘
+```
+
+The WebUI container doesn't ship with the agent's Python deps — at startup it runs `uv pip install /home/hermeswebui/.hermes/hermes-agent` to install them from the shared volume.
+
+## Bind-mount migration (advanced)
+
+If you really need to bind-mount an existing host `~/.hermes` (e.g. you're keeping config in dotfiles, sharing with a non-Docker `hermes` install, etc.):
+
+```yaml
+volumes:
+  hermes-home:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: /home/youruser/.hermes
+  hermes-agent-src:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: /opt/hermes-agent-source
+```
+
+**Critical requirements**:
+
+1. The host directory MUST be readable by your container UID. Run `id -u` on the host and ensure `~/.hermes` is owned by that UID (or readable via group bits).
+2. ALL containers sharing the volume must run as the SAME UID/GID. Set `UID=$(id -u)` and `GID=$(id -g)` in `.env`.
+3. If your host `.env` is mode 0640, set `HERMES_SKIP_CHMOD=1` or `HERMES_HOME_MODE=0640` so the startup hook doesn't try to enforce 0600.
+
+## Reference
+
+- [`docker-compose.yml`](../docker-compose.yml) — single container (recommended)
+- [`docker-compose.two-container.yml`](../docker-compose.two-container.yml) — agent + webui
+- [`docker-compose.three-container.yml`](../docker-compose.three-container.yml) — agent + dashboard + webui
+- [`.env.docker.example`](../.env.docker.example) — environment variable template
+- [`Dockerfile`](../Dockerfile) — single-container build
+- [`docker_init.bash`](../docker_init.bash) — container entrypoint script
+
+## Related issues
+
+- #1389 — `HERMES_HOME_MODE` override (fixed in v0.50.254 — agent honors `HERMES_SKIP_CHMOD` and `HERMES_HOME_MODE`)
+- #1399 — UID alignment in compose files (fixed in v0.50.260 via PR #1428 + this guide)
+- #858 — two-container `/opt/hermes` path confusion
+- #681 — tools running in WebUI container, not agent container (architectural)
+- #668 — auto-detect UID/GID from mounted volume
+- #569 — UID/GID detection priority order
+
+If you hit a new failure mode not covered here, please [open an issue](https://github.com/nesquena/hermes-webui/issues/new) with:
+
+1. Which compose file you used
+2. The error from `docker logs hermes-webui`
+3. `docker exec hermes-webui id` output
+4. `docker exec hermes-webui ls -la /home/hermeswebui/.hermes` output

docs/supervisor.md

@@ -0,0 +1,237 @@
+# Running Hermes Web UI under a process supervisor
+
+Use a process supervisor (launchd, systemd, supervisord, runit, s6) when you
+want the Web UI to start at boot, restart on crash, or be managed alongside
+other services.
+
+## TL;DR
+
+Pass ``--foreground`` to ``bootstrap.py`` (or ``bash start.sh``):
+
+```bash
+bash start.sh --foreground
+```
+
+Or set ``HERMES_WEBUI_FOREGROUND=1`` in the environment. The Web UI will
+auto-detect launchd / systemd / supervisord even without the flag, but being
+explicit is safer.
+
+## Why ``--foreground`` matters
+
+Without it, ``bootstrap.py`` does this:
+
+1. Spawn ``server.py`` as a detached subprocess (``start_new_session=True``)
+2. Probe ``/health`` until the server is up
+3. Exit 0
+
+That works for an interactive shell run (``./start.sh`` returns to your
+prompt with the server alive in the background). It is **broken** under any
+process supervisor: the supervisor sees its tracked PID exit, marks the job
+as completed, and respawns ``bootstrap.py``. The respawn fails to bind port
+8787 (the orphaned server still has it), exits non-zero, supervisor
+respawns again — loop.
+
+In foreground mode, ``bootstrap.py`` does its setup work and then calls
+``os.execv`` to replace its own process with ``server.py``. The supervisor
+sees the long-lived server as the original child. ``KeepAlive=true`` /
+``Restart=always`` work correctly.
+
+## launchd (macOS)
+
+``~/Library/LaunchAgents/com.example.hermes-webui.plist``:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.example.hermes-webui</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/Users/yourname/hermes-webui/start.sh</string>
+        <string>--foreground</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>/Users/yourname/hermes-webui</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/yourname/.hermes/webui/launchd-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/Users/yourname/.hermes/webui/launchd-stderr.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>/Users/yourname</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>
+```
+
+Load:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.example.hermes-webui.plist
+launchctl print gui/$(id -u)/com.example.hermes-webui   # check state
+```
+
+Reload after editing the plist:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.example.hermes-webui.plist
+launchctl load   ~/Library/LaunchAgents/com.example.hermes-webui.plist
+```
+
+launchd sets ``XPC_SERVICE_NAME`` automatically, so even without the
+``--foreground`` argument the Web UI will auto-promote to foreground mode.
+The flag is still recommended as documentation of intent.
+
+## systemd (Linux)
+
+``~/.config/systemd/user/hermes-webui.service``:
+
+```ini
+[Unit]
+Description=Hermes Web UI
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/hermes-webui
+ExecStart=/bin/bash %h/hermes-webui/start.sh --foreground
+Restart=on-failure
+RestartSec=5
+
+# Optional: route stdout/stderr to journald instead of files
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+Enable + start:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now hermes-webui.service
+journalctl --user -u hermes-webui.service -f
+```
+
+systemd sets ``INVOCATION_ID`` and ``JOURNAL_STREAM`` (when stdio is wired to
+the journal), both of which auto-promote to foreground mode.
+
+## supervisord (cross-platform)
+
+``/etc/supervisor/conf.d/hermes-webui.conf``:
+
+```ini
+[program:hermes-webui]
+command=/bin/bash /home/youruser/hermes-webui/start.sh --foreground
+directory=/home/youruser/hermes-webui
+user=youruser
+autostart=true
+autorestart=true
+stopsignal=TERM
+stopwaitsecs=10
+stdout_logfile=/var/log/hermes-webui.out.log
+stderr_logfile=/var/log/hermes-webui.err.log
+environment=HOME="/home/youruser",PATH="/usr/local/bin:/usr/bin:/bin"
+```
+
+Reload + start:
+
+```bash
+sudo supervisorctl reread
+sudo supervisorctl update
+sudo supervisorctl status hermes-webui
+```
+
+supervisord sets ``SUPERVISOR_ENABLED``, which auto-promotes to foreground
+mode.
+
+## Auto-detected env vars (full list)
+
+These trigger ``--foreground`` behavior even when the flag is not passed:
+
+| Env var | Set by | Notes |
+|---|---|---|
+| ``INVOCATION_ID`` | systemd | Set on every service activation |
+| ``JOURNAL_STREAM`` | systemd | Set when stdio is wired to journald |
+| ``NOTIFY_SOCKET`` | systemd ``Type=notify`` / s6 | sd_notify-style notification socket |
+| ``XPC_SERVICE_NAME`` | launchd | Set to the plist Label — narrowed to ``com.<rdns>.<svc>`` form (see below) |
+| ``SUPERVISOR_ENABLED`` | supervisord | Always set under supervisord |
+| ``HERMES_WEBUI_FOREGROUND`` | you | Explicit opt-in; accepts ``1`` / ``true`` / ``yes`` / ``on`` |
+
+### XPC_SERVICE_NAME noise filter
+
+macOS launchd sets ``XPC_SERVICE_NAME`` in **every Terminal-spawned shell**,
+not just real services. Typical noise values:
+
+- ``0`` — set on launchd descendants generally
+- ``application.com.apple.Terminal.<UUID>`` — Terminal.app shells
+- ``application.com.googlecode.iterm2`` — iTerm2
+- ``application.com.microsoft.VSCode`` — VSCode integrated terminal
+
+A bare existence check on this var would auto-promote interactive
+``./start.sh`` runs to foreground mode on every Mac dev machine, breaking
+the most common installation path. We narrow detection to launchd
+**Label-style** names (typically reverse-DNS like ``com.example.foo``).
+Real launchd plists always use this form. If you ever see
+``XPC_SERVICE_NAME=0`` in your service environment, the auto-detect will
+ignore it — set ``HERMES_WEBUI_FOREGROUND=1`` or pass ``--foreground``
+explicitly to be safe.
+
+### Supervisors that are NOT auto-detected
+
+The following set no env var that we can reliably detect. Pass
+``--foreground`` (or ``HERMES_WEBUI_FOREGROUND=1``) explicitly:
+
+- **runit** (without sd_notify) — pure runit chains
+- **daemontools** / ``svc``
+- **PM2** (Node.js process manager occasionally repurposed for Python)
+- **Foreman** / **Honcho** (Procfile-style)
+- **Docker** with a custom CMD entrypoint that doesn't already use ``exec``
+- **Custom shell-script supervisors** that fork-and-wait
+
+If your supervisor isn't in the auto-detect list and you see the orphan-PID
+respawn loop, set ``HERMES_WEBUI_FOREGROUND=1`` in the service environment.
+
+## Diagnostic recipe
+
+If the Web UI keeps getting respawned and you suspect the double-fork loop:
+
+```bash
+# Check the running PID for the server
+lsof -iTCP:8787 -sTCP:LISTEN
+
+# Get its parent — should be the supervisor itself, NOT init (PID 1)
+PID=$(lsof -tiTCP:8787 -sTCP:LISTEN)
+ps -p "$PID" -o pid,ppid,cmd
+ps -p "$(ps -o ppid= -p "$PID" | tr -d ' ')" -o pid,cmd
+```
+
+A healthy foreground-mode setup looks like:
+
+```
+PID    PPID  CMD
+12345  6789  /path/to/python /path/to/server.py
+6789   1     /sbin/launchd        # or /usr/lib/systemd/systemd, etc.
+```
+
+If PPID is ``1`` (init) when it should be the supervisor, the orphan-server
+loop is happening — re-check that ``--foreground`` (or one of the env vars)
+is reaching the process.

docs/ui-ux/index.html

@@ -0,0 +1,838 @@
+<!doctype html>
+<html lang="en" data-theme="slate">
+<head>
+  <meta charset="utf-8">
+  <title>Hermes WebUI — Messages UI Inventory</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <!-- Real app stylesheet -->
+  <link rel="stylesheet" href="../../static/style.css">
+  <!-- Prism (same theme the app pulls at runtime) -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
+  <!-- KaTeX -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
+  <style>
+    /* Showcase scaffold — styles only for the doc chrome. Everything inside
+       .messages uses the real app CSS unchanged. */
+    /* Real app CSS makes <body> a fixed-height flex shell. Undo that so this
+       doc page can scroll normally with a stacked header + main. */
+    body{display:block !important;height:auto !important;min-height:100vh;overflow:auto !important;}
+    .doc-main{display:block;}
+    .doc-header{position:sticky;top:0;z-index:50;background:var(--topbar-bg);backdrop-filter:blur(12px);border-bottom:1px solid var(--border);padding:14px 24px;display:flex;flex-wrap:wrap;align-items:center;gap:14px;}
+    .doc-title{font-size:16px;font-weight:700;letter-spacing:-.01em;color:var(--text);}
+    .doc-title small{display:block;font-size:11px;font-weight:500;color:var(--muted);margin-top:3px;}
+    .doc-toggles{display:flex;flex-wrap:wrap;gap:6px;margin-left:auto;}
+    .doc-toggles button{font:inherit;font-size:11px;padding:5px 10px;border-radius:7px;border:1px solid var(--border2);background:var(--input-bg);color:var(--muted);cursor:pointer;}
+    .doc-toggles button.on{background:rgba(124,185,255,.12);border-color:rgba(124,185,255,.4);color:var(--blue);}
+    .doc-main{max-width:1100px;margin:0 auto;padding:24px 24px 120px;}
+    .doc-section{margin:40px 0 8px;padding-top:20px;border-top:1px dashed var(--border);}
+    .doc-section:first-of-type{border-top:none;padding-top:0;margin-top:0;}
+    .doc-kicker{font-size:10px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--blue);}
+    .doc-h{font-size:18px;font-weight:700;color:var(--text);margin:4px 0 4px;}
+    .doc-note{font-size:12px;color:var(--muted);line-height:1.55;max-width:760px;margin-bottom:10px;}
+    .doc-card{position:relative;background:var(--main-bg);border:1px solid var(--border);border-radius:12px;padding:4px 6px;margin:12px 0;}
+    .doc-label{position:absolute;top:-9px;left:12px;font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;padding:2px 8px;background:var(--bg);color:var(--muted);border:1px solid var(--border);border-radius:999px;}
+    /* Force-show hover-only affordances inside explicitly flagged demos */
+    .force-show .msg-actions,
+    .force-show .msg-time,
+    .force-show .msg-foot{opacity:1 !important;}
+    /* Chat demo container mimics the app's .messages scroll wrapper but not fullscreen */
+    .messages.doc-messages{overflow:visible;display:block;}
+    .messages-inner.doc-inner{padding:14px 16px;}
+    /* Make the in-page demos of approval/clarify cards visible without JS */
+    .approval-card.doc-visible,
+    .clarify-card.doc-visible{display:block;}
+    .reconnect-banner.doc-visible{display:flex;align-items:center;justify-content:space-between;gap:12px;background:rgba(201,168,76,.12);border:1px solid rgba(201,168,76,.3);color:var(--gold);padding:8px 14px;border-radius:8px;font-size:12px;}
+    .reconnect-banner.doc-visible .reconnect-btn{background:none;border:1px solid rgba(201,168,76,.35);color:var(--gold);padding:4px 10px;border-radius:6px;font-size:11px;cursor:pointer;}
+    .bg-error-banner.doc-visible{border-radius:8px;}
+    /* Two-up grid for short comparisons */
+    .doc-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:12px;}
+  </style>
+</head>
+<body>
+
+<header class="doc-header">
+  <div class="doc-title">Hermes WebUI — Messages UI Inventory<small>Every message-area element &amp; combination, wired to the real <code>static/style.css</code>. &nbsp;·&nbsp; <a href="./two-stage-proposal.html" style="color:var(--blue);text-decoration:none;">Two-stage proposal (#536) →</a></small></div>
+  <div class="doc-toggles">
+    <strong style="font-size:10px;color:var(--muted);letter-spacing:.08em;text-transform:uppercase;align-self:center;margin-right:4px;">Theme</strong>
+    <button data-theme-btn="default">Default</button>
+    <button data-theme-btn="slate" class="on">Slate</button>
+    <button data-theme-btn="light">Light</button>
+    <button data-theme-btn="solarized">Solarized</button>
+    <button data-theme-btn="monokai">Monokai</button>
+    <button data-theme-btn="nord">Nord</button>
+    <button data-theme-btn="oled">OLED</button>
+    <span style="width:1px;height:18px;background:var(--border);margin:0 4px;align-self:center;"></span>
+  </div>
+</header>
+
+<main class="doc-main">
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">1 · Empty state</div>
+  <h2 class="doc-h">First load / no messages</h2>
+  <p class="doc-note">Renders inside <code>#messages</code> when <code>S.messages</code> is empty. Logo + title + subtitle + 3 suggestion buttons.</p>
+  <div class="doc-card"><span class="doc-label">.empty-state</span>
+    <div class="messages doc-messages">
+      <div class="empty-state" style="min-height:340px;flex:0 0 auto;">
+        <div class="empty-logo">H</div>
+        <h2>What can I help with?</h2>
+        <p>Ask anything, run commands, explore files, or manage your scheduled tasks.</p>
+        <div class="suggestion-grid">
+          <button class="suggestion">📁 What files are in this workspace?</button>
+          <button class="suggestion">📅 What's on my schedule today?</button>
+          <button class="suggestion">🗺️ Help me plan a small project.</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">2 · User messages</div>
+  <h2 class="doc-h">Right-aligned bubble, attachments, and edit mode</h2>
+  <p class="doc-note">User rows have no avatar/label — the right-edge alignment and tinted bubble identify the sender. Timestamp + edit/copy live in a <code>.msg-foot</code> below the bubble, revealed on hover (forced visible here).</p>
+
+  <div class="doc-card"><span class="doc-label">.msg-row[data-role="user"] — plain</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row force-show" data-role="user" data-raw-text="How do I run the dev server and point it at a specific workspace path?">
+        <div class="msg-body"><p>How do I run the dev server and point it at a specific workspace path?</p></div>
+        <div class="msg-foot">
+          <span class="msg-time" title="Thu, Apr 16 2026, 10:42 AM">10:42</span>
+          <span class="msg-actions">
+            <button class="msg-action-btn" title="Edit"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"/></svg></button>
+            <button class="msg-copy-btn msg-action-btn" title="Copy"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button>
+          </span>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.msg-files — attachments above body (right-aligned)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row" data-role="user">
+        <div class="msg-files">
+          <span class="msg-file-badge">📎 architecture-notes.pdf</span>
+          <span class="msg-file-badge">📎 Q1-forecast.xlsx</span>
+          <span class="msg-file-badge">📎 meeting.docx</span>
+          <span class="msg-file-badge">📎 screenshot.png</span>
+        </div>
+        <div class="msg-body"><p>Please review these docs and summarise the key decisions.</p></div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.msg-edit-area + .msg-edit-bar — edit mode</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row" data-role="user" data-editing="1">
+        <textarea class="msg-edit-area">How do I run the dev server and point it at a specific workspace path — and can I do it without docker?</textarea>
+        <div class="msg-edit-bar">
+          <button class="msg-edit-send">Send edit</button>
+          <button class="msg-edit-cancel">Cancel</button>
+        </div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">3 · Assistant — markdown basics</div>
+  <h2 class="doc-h">Paragraphs, emphasis, lists, blockquote, hr, links</h2>
+  <p class="doc-note">Assistant output is a single <code>.msg-row.assistant-turn</code> that holds one role header + an <code>.assistant-turn-blocks</code> column of one-or-more <code>.assistant-segment</code> children. Each segment may contain a <code>.thinking-card</code>, a <code>.msg-body</code>, and its own <code>.msg-foot</code> (copy / regen). This lets a turn stream reasoning → text → tool calls → more text without repeating the Hermes avatar each time.</p>
+
+  <div class="doc-card"><span class="doc-label">.msg-body — rich prose</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn force-show" data-role="assistant">
+        <div class="msg-role assistant" title="Thu, Apr 16 2026, 10:42 AM">
+          <span class="role-icon assistant">H</span>
+          <span>Hermes</span>
+        </div>
+        <div class="assistant-turn-blocks">
+          <div class="assistant-segment" data-raw-text="Running the dev server...">
+            <div class="msg-body">
+              <h1>Running the dev server</h1>
+              <p>You can start Hermes with the built-in launcher. The <strong>simplest path</strong> is <em>no docker, no proxy</em> — the CLI handles everything.</p>
+              <h2>Prerequisites</h2>
+              <ul>
+                <li>Node <code>&gt;= 18</code></li>
+                <li>A workspace directory you own
+                  <ul>
+                    <li>Read/write permissions</li>
+                    <li>No existing <code>.hermes</code> folder</li>
+                  </ul>
+                </li>
+                <li>An API key set via <code>HERMES_API_KEY</code></li>
+              </ul>
+              <h2>Steps</h2>
+              <ol>
+                <li>Clone the repo</li>
+                <li>Run <code>npm install</code></li>
+                <li>Start with <code>npm run dev -- --workspace ~/code</code></li>
+              </ol>
+              <blockquote>Tip: the <code>--workspace</code> flag accepts absolute or <code>~</code>-prefixed paths. Relative paths are resolved against the CWD.</blockquote>
+              <hr>
+              <p>For full setup options see the <a href="#">configuration guide</a>.</p>
+            </div>
+            <div class="msg-foot">
+              <span class="msg-actions">
+                <button class="msg-copy-btn msg-action-btn" title="Copy"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button>
+                <button class="msg-action-btn" title="Regenerate"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="1 4 1 10 7 10"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/></svg></button>
+              </span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.msg-body table</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks">
+          <div class="assistant-segment">
+            <div class="msg-body">
+              <p>Model comparison:</p>
+              <table>
+                <thead><tr><th>Model</th><th>Context</th><th>Good for</th><th>Cost / 1M in</th></tr></thead>
+                <tbody>
+                  <tr><td>Opus 4.6</td><td>1M</td><td>Deep reasoning, long code</td><td><code>$15.00</code></td></tr>
+                  <tr><td>Sonnet 4.6</td><td>1M</td><td>Daily driver, agents</td><td><code>$3.00</code></td></tr>
+                  <tr><td>Haiku 4.5</td><td>200k</td><td>Fast tasks, tool loops</td><td><code>$0.80</code></td></tr>
+                </tbody>
+              </table>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">4 · Code blocks</div>
+  <h2 class="doc-h">Plain, with header, with copy button, multi-language</h2>
+
+  <div class="doc-card"><span class="doc-label">pre + code (no header)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+<pre><code class="language-bash">npm install
+npm run dev -- --workspace ~/code</code></pre>
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.pre-header + pre + .code-copy-btn</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+            <div style="position:relative;">
+              <div class="pre-header">typescript <button class="code-copy-btn" style="margin-left:auto;">Copy</button></div>
+<pre><code class="language-typescript">export async function startServer(opts: ServerOptions) {
+  const port = opts.port ?? 3000;
+  const app = createApp();
+  app.listen(port, () =&gt; {
+    console.log(`Hermes listening on :${port}`);
+  });
+  return app;
+}</code></pre>
+            </div>
+            <div style="position:relative;margin-top:14px;">
+              <div class="pre-header">python <button class="code-copy-btn" style="margin-left:auto;">Copy</button></div>
+<pre><code class="language-python">from hermes import Agent
+
+def main() -&gt; None:
+    agent = Agent(model="claude-opus-4-6")
+    reply = agent.run("Summarise today's commits")
+    print(reply)
+
+if __name__ == "__main__":
+    main()</code></pre>
+            </div>
+            <div style="position:relative;margin-top:14px;">
+              <div class="pre-header">json <button class="code-copy-btn" style="margin-left:auto;">Copy</button></div>
+<pre><code class="language-json">{
+  "model": "claude-sonnet-4-6",
+  "stream": true,
+  "tools": ["bash", "edit_file", "search"]
+}</code></pre>
+            </div>
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">5 · Inline media</div>
+  <h2 class="doc-h">Images (default &amp; zoomed) and downloadable links</h2>
+
+  <div class="doc-card"><span class="doc-label">.msg-media-img (default + .msg-media-img--full)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+            <p>Here's the screenshot you asked for (click to zoom):</p>
+            <img class="msg-media-img" alt="demo" src="data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='640' height='360'%3E%3Cdefs%3E%3ClinearGradient id='g' x1='0' x2='1'%3E%3Cstop offset='0' stop-color='%237cb9ff'/%3E%3Cstop offset='1' stop-color='%23c9a84c'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect fill='url(%23g)' width='640' height='360'/%3E%3Ctext x='50%25' y='50%25' font-family='system-ui' font-size='28' fill='white' text-anchor='middle' dominant-baseline='middle'%3E.msg-media-img (480×400 cap)%3C/text%3E%3C/svg%3E">
+            <p style="margin-top:10px;">And the full-width variant:</p>
+            <img class="msg-media-img msg-media-img--full" alt="demo-full" src="data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1280' height='320'%3E%3Crect fill='%231e2023' width='1280' height='320'/%3E%3Ctext x='50%25' y='50%25' font-family='system-ui' font-size='28' fill='%2382aaff' text-anchor='middle' dominant-baseline='middle'%3E.msg-media-img--full (unbounded)%3C/text%3E%3C/svg%3E">
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.msg-media-link — non-image downloads</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+            <p>I saved the generated files:</p>
+            <p><a class="msg-media-link" href="#">📎 report-2026-Q1.pdf</a> <a class="msg-media-link" href="#">📎 revenue.csv</a> <a class="msg-media-link" href="#">📎 diagram.svg</a></p>
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">6 · Math &amp; diagrams</div>
+  <h2 class="doc-h">KaTeX inline / block &amp; Mermaid block</h2>
+
+  <div class="doc-card"><span class="doc-label">.katex-inline + .katex-block</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+            <p>Inline math: <span class="katex-inline" data-math-inline>\(E = mc^2\)</span> and the quadratic formula below:</p>
+            <div class="katex-block" data-math-block>$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$</div>
+            <p>A tidier form: <span class="katex-inline" data-math-inline>\(\sum_{i=1}^{n} i = \frac{n(n+1)}{2}\)</span>.</p>
+            <div class="katex-block" data-math-block>$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}$$</div>
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.mermaid-block (pre-render placeholder)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body">
+            <p>The request flow:</p>
+            <div class="mermaid-block"><pre style="margin:0;background:none;border:none;padding:0;color:var(--muted);font-family:'SF Mono',ui-monospace,monospace;font-size:12px;">graph LR
+  U[User] --&gt; C[Composer]
+  C --&gt; API[/api/chat/]
+  API --&gt; M((Model))
+  M --&gt; T{tool?}
+  T -- yes --&gt; X[Tool Runner]
+  T -- no  --&gt; R[Reply]
+  X --&gt; R
+  R --&gt; U</pre></div>
+          </div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">7 · Thinking / reasoning</div>
+  <h2 class="doc-h">Bordered panel (collapsed / open, animated), live loader, streaming cursor</h2>
+  <p class="doc-note">Thinking cards are rendered at the top of an <code>.assistant-segment</code>. They're now bordered gold-tinted panels (no more left-rule-only look) and expand/collapse with a <code>max-height</code> + opacity transition. Click the header in either example below to see the animation live.</p>
+
+  <div class="doc-grid">
+    <div class="doc-card"><span class="doc-label">.thinking-card (collapsed, inside .assistant-segment)</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner" style="padding-top:8px;">
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+            <div class="thinking-card">
+              <div class="thinking-card-header">
+                <span class="thinking-card-icon">💡</span>
+                <span class="thinking-card-label">Thought for 4.3s</span>
+                <span class="thinking-card-toggle">▶</span>
+              </div>
+              <div class="thinking-card-body"><pre>The user asked about the dev server...</pre></div>
+            </div>
+            <div class="msg-body"><p>Here's the shortest path…</p></div>
+          </div></div>
+        </div>
+      </div></div>
+    </div>
+
+    <div class="doc-card"><span class="doc-label">.thinking-card.open (animated — max-height + opacity)</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner" style="padding-top:8px;">
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+            <div class="thinking-card open">
+              <div class="thinking-card-header">
+                <span class="thinking-card-icon">💡</span>
+                <span class="thinking-card-label">Thought for 4.3s</span>
+                <span class="thinking-card-toggle">▶</span>
+              </div>
+              <div class="thinking-card-body"><pre>The user is asking about launching the dev server.
+Options: npm script, docker, or the bundled CLI.
+The CLI is the simplest — no container runtime needed.
+I should show the exact commands and the --workspace flag,
+then mention the env var for the API key at the end.</pre></div>
+            </div>
+            <div class="msg-body"><p>Here's the shortest path…</p></div>
+          </div></div>
+        </div>
+      </div></div>
+    </div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.thinking — live 3-dot loader (pre-reasoning)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment" data-live-assistant="1">
+          <div class="thinking">Thinking <span class="dot"></span><span class="dot"></span><span class="dot"></span></div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">[data-live-assistant="1"] — streaming cursor at end of last child</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant" id="liveAssistantTurn">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment" data-live-assistant="1">
+          <div class="msg-body"><p>Sure — the simplest way is to run <code>npm run dev</code>. The CLI will pick up the default</p></div>
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">8 · Tool cards</div>
+  <h2 class="doc-h">Running, done, expanded, subagent, error, multi-card toggle</h2>
+  <p class="doc-note">Tool cards sit in <code>.tool-card-row</code> wrappers (no longer nested under <code>.msg-row</code>). The details panel now animates open/closed via <code>max-height</code> + opacity — click any header below to see the transition.</p>
+
+  <div class="doc-card"><span class="doc-label">.tool-card.tool-card-running (collapsed, pulsing dot)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-card-row">
+        <div class="tool-card tool-card-running">
+          <div class="tool-card-header">
+            <span class="tool-card-running-dot"></span>
+            <span class="tool-card-icon">⚡</span>
+            <span class="tool-card-name">bash</span>
+            <span class="tool-card-preview">npm run build</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.tool-card — done, collapsed</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-card-row">
+        <div class="tool-card">
+          <div class="tool-card-header">
+            <span class="tool-card-icon">📄</span>
+            <span class="tool-card-name">read_file</span>
+            <span class="tool-card-preview">static/style.css · 1155 lines</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.tool-card.open — args table + result snippet + Show more (animated detail)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-card-row">
+        <div class="tool-card open">
+          <div class="tool-card-header">
+            <span class="tool-card-icon">⚡</span>
+            <span class="tool-card-name">bash</span>
+            <span class="tool-card-preview">grep -rn "msg-role" static/ · exit 0 · 380ms</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+          <div class="tool-card-detail">
+            <div class="tool-card-args">
+              <div><span class="tool-arg-key">command:</span> <span class="tool-arg-val">grep -rn "msg-role" static/</span></div>
+              <div><span class="tool-arg-key">cwd:</span> <span class="tool-arg-val">/Users/aron/hermes-webui</span></div>
+              <div><span class="tool-arg-key">timeout:</span> <span class="tool-arg-val">30000</span></div>
+            </div>
+            <div class="tool-card-result">
+<pre>static/style.css:430:  .msg-role{font-size:12px;font-weight:500...}
+static/style.css:431:  .msg-role.user{color:rgba(124,185,255,0.65);}
+static/style.css:432:  .msg-role.assistant{color:rgba(201,168,76,0.6);}
+static/ui.js:1141:    const roleEl = el('div', 'msg-role ' + role);</pre>
+              <button class="tool-card-more">Show more (+142 lines)</button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.tool-card.tool-card-subagent — delegated work</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-card-row">
+        <div class="tool-card tool-card-subagent">
+          <div class="tool-card-header">
+            <span class="tool-card-icon">🤖</span>
+            <span class="tool-card-name">Subagent</span>
+            <span class="tool-card-preview">Explore · Map chat messages UI elements</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+        </div>
+      </div>
+      <div class="tool-card-row">
+        <div class="tool-card tool-card-subagent">
+          <div class="tool-card-header">
+            <span class="tool-card-icon">🤖</span>
+            <span class="tool-card-name">Delegate task</span>
+            <span class="tool-card-preview">Plan · Propose redesign variants</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.tool-card (error snippet)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-card-row">
+        <div class="tool-card open">
+          <div class="tool-card-header">
+            <span class="tool-card-icon">⚡</span>
+            <span class="tool-card-name">bash</span>
+            <span class="tool-card-preview">npm run typecheck · exit 1 · 2.3s</span>
+            <span class="tool-card-toggle">▶</span>
+          </div>
+          <div class="tool-card-detail">
+            <div class="tool-card-args">
+              <div><span class="tool-arg-key">command:</span> <span class="tool-arg-val">npm run typecheck</span></div>
+            </div>
+            <div class="tool-card-result">
+<pre style="color:#fca5a5;">src/server.ts:42:7 - error TS2345: Argument of type 'string | undefined'
+  is not assignable to parameter of type 'number'.
+
+42       app.listen(opts.port, () =&gt; {
+         ~~~~~~~~~</pre>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.tool-cards-toggle — Expand/Collapse All (≥2 cards)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="tool-cards-toggle">
+        <button>Expand all (3)</button>
+        <button>Collapse all</button>
+      </div>
+      <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">📄</span><span class="tool-card-name">read_file</span><span class="tool-card-preview">package.json</span><span class="tool-card-toggle">▶</span></div></div></div>
+      <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">🔎</span><span class="tool-card-name">grep</span><span class="tool-card-preview">"listen" in src/</span><span class="tool-card-toggle">▶</span></div></div></div>
+      <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">⚡</span><span class="tool-card-name">bash</span><span class="tool-card-preview">npm run typecheck · exit 0 · 4.1s</span><span class="tool-card-toggle">▶</span></div></div></div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">9 · Meta affordances</div>
+  <h2 class="doc-h">Role timestamp tooltip, footer action toolbar, token-usage badge</h2>
+  <p class="doc-note">Assistant timestamps live on the <code>.msg-role</code> <code>title</code> attribute (hover for full date). Copy/regen buttons sit in the per-segment <code>.msg-foot</code>, 45% opacity at rest, full on turn hover. The <code>.msg-usage</code> badge is always visible at the bottom of the turn.</p>
+
+  <div class="doc-card"><span class="doc-label">Full hover state — .msg-foot actions + .msg-usage</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn force-show" data-role="assistant">
+        <div class="msg-role assistant" title="Thu, Apr 16 2026, 10:42 AM">
+          <span class="role-icon assistant">H</span>
+          <span>Hermes</span>
+        </div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+          <div class="msg-body"><p>Built and type-checked successfully — server is running on <code>:3000</code>.</p></div>
+          <div class="msg-foot">
+            <span class="msg-actions">
+              <button class="msg-copy-btn msg-action-btn" title="Copy"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button>
+              <button class="msg-action-btn" title="Regenerate"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="1 4 1 10 7 10"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/></svg></button>
+            </span>
+          </div>
+        </div></div>
+        <div class="msg-usage">3.2K in · 481 out · ~$0.012</div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">10 · Full composition</div>
+  <h2 class="doc-h">User turn → assistant turn (segment 1: thinking + body + tool cards) → usage</h2>
+  <p class="doc-note">A realistic turn: one role header up top, then the segment hosting a thinking card plus the first body; tool cards follow as siblings of the turn inside <code>.messages-inner</code>; the usage badge closes the turn.</p>
+
+  <div class="doc-card"><span class="doc-label">All-in-one turn</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row force-show" data-role="user">
+        <div class="msg-files"><span class="msg-file-badge">📎 server.ts</span></div>
+        <div class="msg-body"><p>The build fails — can you type-check and explain?</p></div>
+        <div class="msg-foot">
+          <span class="msg-time">10:40</span>
+          <span class="msg-actions">
+            <button class="msg-action-btn" title="Edit">✎</button>
+            <button class="msg-copy-btn msg-action-btn" title="Copy">⎘</button>
+          </span>
+        </div>
+      </div>
+
+      <div class="msg-row assistant-turn force-show" data-role="assistant">
+        <div class="msg-role assistant" title="Thu, Apr 16 2026, 10:42 AM">
+          <span class="role-icon assistant">H</span><span>Hermes</span>
+        </div>
+        <div class="assistant-turn-blocks">
+          <div class="assistant-segment">
+            <div class="thinking-card open">
+              <div class="thinking-card-header"><span class="thinking-card-icon">💡</span><span class="thinking-card-label">Thought for 2.1s</span><span class="thinking-card-toggle">▶</span></div>
+              <div class="thinking-card-body"><pre>Attached server.ts — probably typing issue.
+Run typecheck to confirm, then patch.</pre></div>
+            </div>
+            <div class="msg-body">
+              <p>The build fails because <code>opts.port</code> can be <code>undefined</code>. Two fixes below — pick the one that matches your intent.</p>
+              <h3>Option A — require the port</h3>
+<pre><code class="language-typescript">export function startServer(opts: { port: number }) {
+  app.listen(opts.port);
+}</code></pre>
+              <h3>Option B — default to 3000</h3>
+<pre><code class="language-typescript">export function startServer(opts: { port?: number } = {}) {
+  const port = opts.port ?? 3000;
+  app.listen(port);
+}</code></pre>
+              <p>I ran the checks below to confirm.</p>
+            </div>
+            <div class="msg-foot">
+              <span class="msg-actions">
+                <button class="msg-copy-btn msg-action-btn" title="Copy">⎘</button>
+                <button class="msg-action-btn" title="Regenerate">↻</button>
+              </span>
+            </div>
+          </div>
+        </div>
+        <div class="msg-usage">11.4K in · 612 out · ~$0.049</div>
+      </div>
+
+      <div class="tool-cards-toggle">
+        <button>Expand all (3)</button><button>Collapse all</button>
+      </div>
+      <div class="tool-card-row"><div class="tool-card open">
+        <div class="tool-card-header"><span class="tool-card-icon">📄</span><span class="tool-card-name">read_file</span><span class="tool-card-preview">src/server.ts · 58 lines</span><span class="tool-card-toggle">▶</span></div>
+        <div class="tool-card-detail">
+          <div class="tool-card-args"><div><span class="tool-arg-key">path:</span> <span class="tool-arg-val">src/server.ts</span></div></div>
+          <div class="tool-card-result"><pre>export function startServer(opts: ServerOptions) {
+  app.listen(opts.port, () =&gt; { ... });
+}</pre></div>
+        </div>
+      </div></div>
+      <div class="tool-card-row"><div class="tool-card">
+        <div class="tool-card-header"><span class="tool-card-icon">⚡</span><span class="tool-card-name">bash</span><span class="tool-card-preview">npm run typecheck · exit 1 · 2.3s</span><span class="tool-card-toggle">▶</span></div>
+      </div></div>
+      <div class="tool-card-row"><div class="tool-card">
+        <div class="tool-card-header"><span class="tool-card-icon">✏️</span><span class="tool-card-name">edit_file</span><span class="tool-card-preview">src/server.ts +1 / -1</span><span class="tool-card-toggle">▶</span></div>
+      </div></div>
+    </div></div>
+  </div>
+</section>
+
+
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">12 · System / inline notes</div>
+  <h2 class="doc-h">Compression, cancellation, errors — rendered as italicised assistant messages</h2>
+
+  <div class="doc-card"><span class="doc-label">Italic system notices (still italic — info, not errors)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks">
+          <div class="assistant-segment"><div class="msg-body"><p><em>[Context was auto-compressed to continue the conversation]</em></p></div></div>
+          <div class="assistant-segment"><div class="msg-body"><p><em>Task cancelled.</em></p></div></div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.assistant-segment[data-error="1"] — real error card, red accent, no italic</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks">
+          <div class="assistant-segment" data-error="1"><div class="msg-body"><p><strong>Error:</strong> Connection lost. Your last message was saved — refresh to continue.</p></div></div>
+          <div class="assistant-segment" data-error="1"><div class="msg-body"><p><strong>Error:</strong> Upstream rate-limited (429). Retrying in 30s…</p></div></div>
+        </div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">12b · Turn boundaries &amp; date separators</div>
+  <h2 class="doc-h">Right-alignment separates user turns · day-change separator</h2>
+  <p class="doc-note">The dashed divider before each user turn was removed — the right-edge bubble alignment is its own visual break, so only a small vertical gap (10px top margin) remains between turns. Day changes still get a centred <code>.msg-date-sep</code>.</p>
+  <div class="doc-card"><span class="doc-label">.msg-date-sep — Today / Yesterday / weekday / date</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-date-sep">Yesterday</div>
+      <div class="msg-row" data-role="user"><div class="msg-body"><p>Can you summarise the PR I opened earlier?</p></div></div>
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment"><div class="msg-body"><p>Yes — three files changed, net +42 / -18. Main change is the new rail variable…</p></div></div></div>
+      </div>
+      <div class="msg-date-sep">Today</div>
+      <div class="msg-row" data-role="user"><div class="msg-body"><p>Did CI pass overnight?</p></div></div>
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment"><div class="msg-body"><p>All green — three jobs, 4m 12s total. Here's the breakdown:</p></div></div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">13 · Overlay cards (adjacent to transcript)</div>
+  <h2 class="doc-h">Approval &amp; Clarify cards + reconnect banner</h2>
+
+  <div class="doc-card"><span class="doc-label">.approval-card — 4 button variants (once / session / always / deny)</span>
+    <div class="approval-card doc-visible">
+      <div class="approval-inner">
+        <div class="approval-header">⚠ Approval required</div>
+        <div class="approval-desc" style="font-size:12px;color:var(--muted);margin-bottom:8px;">The agent wants to run a shell command in <code>/Users/aron/hermes-webui</code>.</div>
+        <div class="approval-cmd">rm -rf node_modules &amp;&amp; npm install</div>
+        <div class="approval-btns">
+          <button class="approval-btn once">✓ <span class="approval-btn-label">Allow once</span><kbd class="approval-kbd">↵</kbd></button>
+          <button class="approval-btn session">🔒 <span class="approval-btn-label">Allow session</span></button>
+          <button class="approval-btn always">★ <span class="approval-btn-label">Always allow</span></button>
+          <button class="approval-btn deny">✕ <span class="approval-btn-label">Deny</span></button>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">.clarify-card — choice buttons + free-text fallback</span>
+    <div class="clarify-card doc-visible">
+      <div class="clarify-inner">
+        <div class="clarify-header">? Clarification needed</div>
+        <div class="clarify-question">Which environment should I deploy this to?</div>
+        <div class="clarify-choices">
+          <button class="clarify-choice"><span class="clarify-choice-badge">A</span><span class="clarify-choice-text">Staging — safe sandbox, auto-teardown nightly</span></button>
+          <button class="clarify-choice"><span class="clarify-choice-badge">B</span><span class="clarify-choice-text">Production EU — customer-facing, requires change ticket</span></button>
+          <button class="clarify-choice"><span class="clarify-choice-badge">C</span><span class="clarify-choice-text">Production US — same caveats as EU</span></button>
+          <button class="clarify-choice other"><span class="clarify-choice-badge other">✎</span><span class="clarify-choice-text">Other — I'll type it below</span></button>
+        </div>
+        <div class="clarify-response">
+          <input class="clarify-input" type="text" placeholder="Type your response…">
+          <button class="clarify-submit">Send</button>
+        </div>
+        <div class="clarify-hint">Pick a choice, or type your own answer below.</div>
+      </div>
+    </div>
+  </div>
+
+  <div class="doc-card"><span class="doc-label">Reconnect / mid-stream recovery banner</span>
+    <div class="reconnect-banner doc-visible">
+      <span>⚠ A response may have been in progress when you last left. Reload messages?</span>
+      <div style="display:flex;gap:8px;">
+        <button class="reconnect-btn">Dismiss</button>
+        <button class="reconnect-btn">↻ Reload</button>
+      </div>
+    </div>
+    <div class="bg-error-banner doc-visible" style="margin-top:8px;">
+      <span>⚠ Agent run exited with non-zero status (code 1). Check the logs.</span>
+      <button class="reconnect-btn">Dismiss</button>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">14 · Structure &amp; data-attribute cheat sheet</div>
+  <h2 class="doc-h">Wrappers and state markers produced by <code>renderMessages()</code></h2>
+
+  <div class="doc-card" style="padding:14px 18px;">
+    <h3 style="font-size:13px;color:var(--text);margin:0 0 8px;">Wrappers</h3>
+    <ul style="color:var(--muted);font-size:12px;line-height:1.9;list-style:disc;padding-left:20px;">
+      <li><code>.msg-row[data-role="user"]</code> — one user turn (right-aligned bubble, 60% max-width)</li>
+      <li><code>.msg-row.assistant-turn[data-role="assistant"]</code> — one assistant turn; contains <strong>one</strong> <code>.msg-role</code> and <strong>one</strong> <code>.assistant-turn-blocks</code></li>
+      <li><code>.assistant-turn-blocks</code> — flex-column holder for segments</li>
+      <li><code>.assistant-segment</code> — a single logical chunk inside a turn: optional <code>.thinking-card</code> + optional <code>.msg-body</code> + optional <code>.msg-foot</code></li>
+      <li><code>.assistant-segment-anchor</code> — hidden segment kept as a DOM anchor for tool cards when the model emitted no text</li>
+      <li><code>.tool-card-row</code> — per-tool-card wrapper, sibling of the turn inside <code>.messages-inner</code></li>
+      <li><code>.msg-foot</code> — per-segment (or per-user-row) footer holding <code>.msg-time</code> + <code>.msg-actions</code></li>
+    </ul>
+    <h3 style="font-size:13px;color:var(--text);margin:14px 0 8px;">Data attributes &amp; IDs</h3>
+    <ul style="color:var(--muted);font-size:12px;line-height:1.9;list-style:disc;padding-left:20px;">
+      <li><code>data-role="user|assistant"</code> — role marker on the row</li>
+      <li><code>data-msgIdx="N"</code> — index into <code>S.messages</code>; on user rows <em>and</em> assistant segments</li>
+      <li><code>data-raw-text="…"</code> — plain-text source for copy (now lives on <code>.assistant-segment</code> for assistant output)</li>
+      <li><code>data-live-assistant="1"</code> — the segment that's currently streaming</li>
+      <li><code>data-editing="1"</code> — row is in edit mode</li>
+      <li><code>data-error="1"</code> — error state; applies to <code>.msg-row</code> (user) or <code>.assistant-segment</code></li>
+      <li><code>id="liveAssistantTurn"</code> — on the turn that contains the streaming segment</li>
+      <li><code>.tool-card-row[data-live-tid="…"]</code> — live tool-call card (removed when the turn settles)</li>
+      <li><code>data-mermaid-id</code>, <code>data-katex</code>, <code>data-rendered</code> — block rendering state</li>
+    </ul>
+  </div>
+</section>
+
+</main>
+
+<!-- ============================================================= -->
+<!-- Prism autoloader for real syntax highlighting -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
+<!-- KaTeX auto-render -->
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"
+  onload="renderMathInElement(document.body,{delimiters:[{left:'$$',right:'$$',display:true},{left:'\\[',right:'\\]',display:true},{left:'\\(',right:'\\)',display:false},{left:'$',right:'$',display:false}],throwOnError:false});"></script>
+
+<script>
+  // Theme picker
+  document.querySelectorAll('[data-theme-btn]').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const t = btn.dataset.themeBtn;
+      if (t === 'default') document.documentElement.removeAttribute('data-theme');
+      else document.documentElement.setAttribute('data-theme', t);
+      document.querySelectorAll('[data-theme-btn]').forEach(b => b.classList.toggle('on', b === btn));
+    });
+  });
+  // Bubble-layout toggle
+
+  // Thinking / tool-card click-to-toggle (so the demo feels live)
+  document.querySelectorAll('.thinking-card-header, .tool-card-header').forEach(h => {
+    h.addEventListener('click', () => h.parentElement.classList.toggle('open'));
+  });
+</script>
+
+</body>
+</html>

docs/ui-ux/two-stage-proposal.html

@@ -0,0 +1,742 @@
+<!doctype html>
+<html lang="en" data-theme="slate">
+<head>
+  <meta charset="utf-8">
+  <title>Hermes WebUI — Two-Stage Chat Proposal (Issue #536)</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <link rel="stylesheet" href="../../static/style.css">
+  <style>
+    /* ──────────────────────────────────────────────────────────────
+       Doc-chrome scaffold (same pattern as index.html) — real app CSS
+       is used unchanged inside .messages / .msg-row. New proposed
+       elements are prefixed .p2s- so nothing collides with the app.
+       ────────────────────────────────────────────────────────────── */
+    body{display:block !important;height:auto !important;min-height:100vh;overflow:auto !important;}
+    .doc-header{position:sticky;top:0;z-index:50;background:var(--topbar-bg);backdrop-filter:blur(12px);border-bottom:1px solid var(--border);padding:14px 24px;display:flex;flex-wrap:wrap;align-items:center;gap:14px;}
+    .doc-title{font-size:16px;font-weight:700;letter-spacing:-.01em;color:var(--text);}
+    .doc-title small{display:block;font-size:11px;font-weight:500;color:var(--muted);margin-top:3px;}
+    .doc-title a{color:var(--blue);text-decoration:none;}
+    .doc-toggles{display:flex;flex-wrap:wrap;gap:6px;margin-left:auto;}
+    .doc-toggles button{font:inherit;font-size:11px;padding:5px 10px;border-radius:7px;border:1px solid var(--border2);background:var(--input-bg);color:var(--muted);cursor:pointer;}
+    .doc-toggles button.on{background:rgba(124,185,255,.12);border-color:rgba(124,185,255,.4);color:var(--blue);}
+    .doc-main{max-width:1180px;margin:0 auto;padding:24px 24px 120px;}
+    .doc-section{margin:48px 0 8px;padding-top:22px;border-top:1px dashed var(--border);}
+    .doc-section:first-of-type{border-top:none;padding-top:0;margin-top:0;}
+    .doc-kicker{font-size:10px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--blue);}
+    .doc-h{font-size:20px;font-weight:700;color:var(--text);margin:4px 0 6px;letter-spacing:-.01em;}
+    .doc-note{font-size:12.5px;color:var(--muted);line-height:1.6;max-width:780px;margin-bottom:14px;}
+    .doc-note code{color:var(--text);background:rgba(255,255,255,.05);padding:1px 5px;border-radius:4px;font-size:11.5px;}
+    .doc-card{position:relative;background:var(--main-bg);border:1px solid var(--border);border-radius:14px;padding:6px 8px;margin:14px 0;}
+    .doc-label{position:absolute;top:-9px;left:14px;font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;padding:2px 9px;background:var(--bg);color:var(--muted);border:1px solid var(--border);border-radius:999px;}
+    .doc-label.current{color:var(--muted);}
+    .doc-label.proposed{color:var(--gold);border-color:rgba(201,168,76,.35);background:var(--bg);}
+    .force-show .msg-actions,.force-show .msg-time,.force-show .msg-foot{opacity:1 !important;}
+    .messages.doc-messages{overflow:visible;display:block;}
+    .messages-inner.doc-inner{padding:14px 16px;}
+    .approval-card.doc-visible,.clarify-card.doc-visible{display:block;}
+    .doc-grid-2{display:grid;grid-template-columns:repeat(auto-fit,minmax(440px,1fr));gap:14px;}
+
+    /* ──────────────────────────────────────────────────────────────
+       Proposed two-stage elements (prefix .p2s-)
+
+       The proposal introduces one container (.p2s-stage1) that wraps
+       the execution history (thinking + tool cards) and one visual
+       treatment (.p2s-answer) for the final-answer segment. The same
+       DOM can be rendered in three modes:
+
+         .p2s-stage1.is-live      →  Working timer + expanded history
+         .p2s-stage1.is-settled   →  Collapsed to one-line summary
+         .p2s-stage1.is-settled.is-open → expanded on demand
+
+       Everything else (thinking-card, tool-card-row, msg-body) is the
+       existing app CSS unchanged.
+       ────────────────────────────────────────────────────────────── */
+
+    /* Worklog bar — the header of Stage 1.
+       Aligns with every other rail child via --msg-rail / --msg-max. */
+    .p2s-worklog{
+      display:flex;align-items:center;gap:10px;
+      margin:4px 0 6px var(--msg-rail);
+      max-width:var(--msg-max);
+      padding:8px 12px;
+      border:1px solid var(--border);
+      border-radius:10px;
+      background:rgba(255,255,255,.025);
+      font-size:12px;color:var(--muted);
+      cursor:pointer;user-select:none;
+      transition:border-color .15s,background .15s;
+    }
+    .p2s-worklog:hover{border-color:var(--border2);background:rgba(255,255,255,.04);}
+    .p2s-worklog-dot{
+      width:8px;height:8px;border-radius:50%;background:var(--gold);flex-shrink:0;
+      box-shadow:0 0 0 0 rgba(201,168,76,.4);
+    }
+    .p2s-stage1.is-live .p2s-worklog-dot{
+      animation:p2sPulse 1.4s ease-in-out infinite;
+    }
+    .p2s-stage1.is-settled .p2s-worklog-dot{
+      background:var(--muted);opacity:.6;
+    }
+    @keyframes p2sPulse{
+      0%,100%{box-shadow:0 0 0 0 rgba(201,168,76,.45);}
+      50%{box-shadow:0 0 0 6px rgba(201,168,76,0);}
+    }
+    .p2s-worklog-label{color:var(--text);font-weight:500;}
+    .p2s-worklog-stats{margin-left:auto;display:flex;gap:12px;color:var(--muted);font-size:11.5px;}
+    .p2s-worklog-stats b{color:var(--text);font-weight:600;}
+    .p2s-worklog-caret{
+      display:inline-block;width:14px;height:14px;line-height:14px;text-align:center;
+      color:var(--muted);font-size:10px;transition:transform .2s;
+      margin-left:6px;
+    }
+    .p2s-stage1.is-live .p2s-worklog-caret{display:none;}
+    .p2s-stage1.is-settled.is-open .p2s-worklog-caret{transform:rotate(90deg);}
+
+    /* Stage 1 body — holds thinking + tool cards + round separators. */
+    .p2s-stage1-body{
+      overflow:hidden;
+      transition:max-height .35s ease,opacity .25s ease;
+    }
+    .p2s-stage1.is-live .p2s-stage1-body,
+    .p2s-stage1.is-settled.is-open .p2s-stage1-body{
+      max-height:2000px;opacity:1;
+    }
+    .p2s-stage1.is-settled:not(.is-open) .p2s-stage1-body{
+      max-height:0;opacity:0;pointer-events:none;
+    }
+
+    /* Round separator — shown inside Stage 1 between execution rounds. */
+    .p2s-round-sep{
+      display:flex;align-items:center;gap:10px;
+      margin:10px 0 6px var(--msg-rail);
+      max-width:var(--msg-max);
+      color:var(--muted);
+      font-size:10.5px;font-weight:700;letter-spacing:.1em;text-transform:uppercase;
+    }
+    .p2s-round-sep::before,.p2s-round-sep::after{
+      content:"";flex:1;height:1px;background:var(--border);
+    }
+
+    /* Stage 1 → Stage 2 transition divider. */
+    .p2s-transition{
+      margin:14px 0 10px var(--msg-rail);
+      max-width:var(--msg-max);
+      height:1px;
+      background:linear-gradient(
+        to right,transparent,var(--border) 20%,var(--border) 80%,transparent
+      );
+    }
+
+    /* Stage 2 — the final answer wrapper.
+
+       Design intent: nothing loud. A small "Answer" kicker in gold,
+       slightly taller line-height, the existing .msg-body styling,
+       and a gentle top breathing-space. The user arrives at this
+       block and it *feels* like a conclusion, not another tool row.
+    */
+    .p2s-answer{margin-top:8px;}
+    .p2s-answer-kicker{
+      margin:0 0 4px var(--msg-rail);
+      max-width:var(--msg-max);
+      font-size:10px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;
+      color:var(--gold);opacity:.8;
+    }
+    .p2s-answer .msg-body{
+      font-size:14.5px;line-height:1.78;
+    }
+
+    /* Clarify slot — placed at the transition rather than inline. */
+    .p2s-clarify-slot{
+      margin:12px 0 4px var(--msg-rail);
+      max-width:var(--msg-max);
+    }
+    .p2s-clarify-slot .clarify-card{margin:0;}
+
+    /* Comparison-grid accents. */
+    .doc-compare-caption{
+      font-size:11px;color:var(--muted);text-align:center;padding:6px 0;
+    }
+  </style>
+</head>
+<body>
+
+<header class="doc-header">
+  <div class="doc-title">
+    Two-Stage Chat UX — Proposal for <a href="https://github.com/nesquena/hermes-webui/issues/536" target="_blank">issue #536</a>
+    <small>Companion to <a href="./index.html">index.html</a> — shows <em>Working → Final answer</em> as a distinct two-phase interaction model.</small>
+  </div>
+  <div class="doc-toggles">
+    <strong style="font-size:10px;color:var(--muted);letter-spacing:.08em;text-transform:uppercase;align-self:center;margin-right:4px;">Theme</strong>
+    <button data-theme-btn="default">Default</button>
+    <button data-theme-btn="slate" class="on">Slate</button>
+    <button data-theme-btn="light">Light</button>
+    <button data-theme-btn="solarized">Solarized</button>
+    <button data-theme-btn="monokai">Monokai</button>
+    <button data-theme-btn="nord">Nord</button>
+    <button data-theme-btn="oled">OLED</button>
+  </div>
+</header>
+
+<main class="doc-main">
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">0 · The model</div>
+  <h2 class="doc-h">One turn, two stages</h2>
+  <p class="doc-note">
+    Today an assistant turn is a flat stream: thinking card → tool cards → answer, all stacked
+    inline with equal visual weight. The proposal wraps the execution history in a
+    <code>.p2s-stage1</code> container with a <em>worklog bar</em> as its header, and marks the
+    final answer as <code>.p2s-answer</code>. The same DOM renders three ways:
+  </p>
+  <ul class="doc-note" style="padding-left:18px;list-style:disc;">
+    <li><b>Live</b> — worklog shows <em>Working… 0:42 · 2 tools</em> with a pulsing dot; history is fully visible.</li>
+    <li><b>Settled</b> — worklog collapses to a single line (<em>Worked 1:42 · 4 tools · 2 thinking</em>); final answer sits below as the calm conclusion.</li>
+    <li><b>Settled + opened</b> — user clicks the worklog to re-expand the history for audit.</li>
+  </ul>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">1 · Current vs proposed — settled turn</div>
+  <h2 class="doc-h">Side-by-side comparison</h2>
+  <p class="doc-note">
+    Same turn, same tool calls, same answer. Left is what #587 ships today. Right is the
+    proposal: execution history collapses to a one-line summary; the final answer stands alone
+    with a small <em>Answer</em> kicker.
+  </p>
+
+  <div class="doc-grid-2">
+
+    <!-- CURRENT ──────────────────────────────────────────────── -->
+    <div class="doc-card"><span class="doc-label current">Current (PR #587)</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner">
+        <div class="msg-row" data-role="user">
+          <div class="msg-body"><p>Does our dev server pick up the workspace from an env var or a flag?</p></div>
+        </div>
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+            <div class="thinking-card open">
+              <div class="thinking-card-header">
+                <span class="thinking-card-icon">💡</span>
+                <span class="thinking-card-label">Thought for 3.1s</span>
+                <span class="thinking-card-toggle">▶</span>
+              </div>
+              <div class="thinking-card-body"><pre>Check how the CLI resolves workspace:
+grep for HERMES_WORKSPACE and --workspace
+inspect argv vs env precedence.</pre></div>
+            </div>
+          </div></div>
+        </div>
+        <div class="tool-card-row">
+          <div class="tool-card open">
+            <div class="tool-card-header">
+              <span class="tool-card-icon">⚡</span>
+              <span class="tool-card-name">bash</span>
+              <span class="tool-card-preview">grep -rn "HERMES_WORKSPACE" . · exit 0</span>
+              <span class="tool-card-toggle">▶</span>
+            </div>
+            <div class="tool-card-detail">
+              <div class="tool-card-result"><pre>cli/main.py:14:WORKSPACE_ENV = "HERMES_WORKSPACE"
+cli/main.py:92:    ws = os.getenv(WORKSPACE_ENV) or args.workspace</pre></div>
+            </div>
+          </div>
+        </div>
+        <div class="tool-card-row">
+          <div class="tool-card">
+            <div class="tool-card-header">
+              <span class="tool-card-icon">📄</span>
+              <span class="tool-card-name">read_file</span>
+              <span class="tool-card-preview">cli/main.py · 148 lines</span>
+              <span class="tool-card-toggle">▶</span>
+            </div>
+          </div>
+        </div>
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+            <div class="msg-body">
+              <p>Both work, but <strong>env wins</strong>. The CLI reads
+              <code>HERMES_WORKSPACE</code> first and only falls back to the
+              <code>--workspace</code> flag if the env var is unset.</p>
+              <p>So in practice:</p>
+              <ul>
+                <li>CI / daemons → set the env var.</li>
+                <li>Ad-hoc runs → pass <code>--workspace</code>.</li>
+              </ul>
+            </div>
+          </div></div>
+        </div>
+      </div></div>
+      <div class="doc-compare-caption">Everything stacks equally — the answer is just the next block.</div>
+    </div>
+
+    <!-- PROPOSED ─────────────────────────────────────────────── -->
+    <div class="doc-card"><span class="doc-label proposed">Proposed — two-stage, settled</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner">
+        <div class="msg-row" data-role="user">
+          <div class="msg-body"><p>Does our dev server pick up the workspace from an env var or a flag?</p></div>
+        </div>
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+
+            <!-- Stage 1 — settled, collapsed to summary (click to expand) -->
+            <div class="p2s-stage1 is-settled" data-p2s-toggle>
+              <div class="p2s-worklog">
+                <span class="p2s-worklog-dot"></span>
+                <span class="p2s-worklog-label">Worked for 0:08</span>
+                <span class="p2s-worklog-stats">
+                  <span><b>2</b> tools</span>
+                  <span><b>1</b> thinking round</span>
+                </span>
+                <span class="p2s-worklog-caret">▶</span>
+              </div>
+              <div class="p2s-stage1-body">
+                <div class="thinking-card open">
+                  <div class="thinking-card-header">
+                    <span class="thinking-card-icon">💡</span>
+                    <span class="thinking-card-label">Thought for 3.1s</span>
+                    <span class="thinking-card-toggle">▶</span>
+                  </div>
+                  <div class="thinking-card-body"><pre>Check how the CLI resolves workspace:
+grep for HERMES_WORKSPACE and --workspace
+inspect argv vs env precedence.</pre></div>
+                </div>
+                <div class="tool-card-row">
+                  <div class="tool-card">
+                    <div class="tool-card-header">
+                      <span class="tool-card-icon">⚡</span>
+                      <span class="tool-card-name">bash</span>
+                      <span class="tool-card-preview">grep -rn "HERMES_WORKSPACE" . · exit 0</span>
+                      <span class="tool-card-toggle">▶</span>
+                    </div>
+                  </div>
+                </div>
+                <div class="tool-card-row">
+                  <div class="tool-card">
+                    <div class="tool-card-header">
+                      <span class="tool-card-icon">📄</span>
+                      <span class="tool-card-name">read_file</span>
+                      <span class="tool-card-preview">cli/main.py · 148 lines</span>
+                      <span class="tool-card-toggle">▶</span>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <!-- Stage 2 — the final answer -->
+            <div class="p2s-transition"></div>
+            <div class="p2s-answer">
+              <div class="p2s-answer-kicker">Answer</div>
+              <div class="msg-body">
+                <p>Both work, but <strong>env wins</strong>. The CLI reads
+                <code>HERMES_WORKSPACE</code> first and only falls back to the
+                <code>--workspace</code> flag if the env var is unset.</p>
+                <p>So in practice:</p>
+                <ul>
+                  <li>CI / daemons → set the env var.</li>
+                  <li>Ad-hoc runs → pass <code>--workspace</code>.</li>
+                </ul>
+              </div>
+            </div>
+
+          </div></div>
+        </div>
+      </div></div>
+      <div class="doc-compare-caption">Click the worklog bar to expand the execution history.</div>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">2 · Stage 1 · Live run</div>
+  <h2 class="doc-h">Working timer + live execution history</h2>
+  <p class="doc-note">
+    The worklog bar at the top is the anchor for the whole active run: pulsing dot, elapsed
+    timer that ticks every second, and live counts that increment as tool cards resolve.
+    Thinking cards and tool cards render inside <code>.p2s-stage1-body</code> exactly as today.
+    A <em>Round N</em> separator is inserted when the agent starts a new reasoning/tool cycle.
+  </p>
+
+  <div class="doc-card"><span class="doc-label proposed">.p2s-stage1.is-live — Round 1 done, Round 2 running</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment" data-live-assistant="1">
+
+          <div class="p2s-stage1 is-live">
+            <div class="p2s-worklog">
+              <span class="p2s-worklog-dot"></span>
+              <span class="p2s-worklog-label">Working… <span id="p2sTimer">0:42</span></span>
+              <span class="p2s-worklog-stats">
+                <span><b>3</b> tools</span>
+                <span><b>2</b> thinking</span>
+              </span>
+            </div>
+            <div class="p2s-stage1-body">
+
+              <div class="thinking-card open">
+                <div class="thinking-card-header">
+                  <span class="thinking-card-icon">💡</span>
+                  <span class="thinking-card-label">Thought for 2.4s</span>
+                  <span class="thinking-card-toggle">▶</span>
+                </div>
+                <div class="thinking-card-body"><pre>Need to map the streaming code path first,
+then check the persistence layer.</pre></div>
+              </div>
+
+              <div class="tool-card-row">
+                <div class="tool-card">
+                  <div class="tool-card-header">
+                    <span class="tool-card-icon">📄</span>
+                    <span class="tool-card-name">read_file</span>
+                    <span class="tool-card-preview">api/streaming.py · 612 lines</span>
+                    <span class="tool-card-toggle">▶</span>
+                  </div>
+                </div>
+              </div>
+
+              <div class="tool-card-row">
+                <div class="tool-card">
+                  <div class="tool-card-header">
+                    <span class="tool-card-icon">⚡</span>
+                    <span class="tool-card-name">bash</span>
+                    <span class="tool-card-preview">grep -rn "tool_call_id" api/ · exit 0 · 88ms</span>
+                    <span class="tool-card-toggle">▶</span>
+                  </div>
+                </div>
+              </div>
+
+              <div class="p2s-round-sep">Round 2</div>
+
+              <div class="thinking-card">
+                <div class="thinking-card-header">
+                  <span class="thinking-card-icon">💡</span>
+                  <span class="thinking-card-label">Thought for 1.8s</span>
+                  <span class="thinking-card-toggle">▶</span>
+                </div>
+                <div class="thinking-card-body"><pre>Streaming looks fine — drill into how
+tool_calls get attached before save.</pre></div>
+              </div>
+
+              <div class="tool-card-row">
+                <div class="tool-card tool-card-running">
+                  <div class="tool-card-header">
+                    <span class="tool-card-running-dot"></span>
+                    <span class="tool-card-icon">⚡</span>
+                    <span class="tool-card-name">bash</span>
+                    <span class="tool-card-preview">pytest tests/test_tool_call_persistence.py -q</span>
+                    <span class="tool-card-toggle">▶</span>
+                  </div>
+                </div>
+              </div>
+
+            </div>
+          </div>
+
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">3 · Approve vs Clarify — placement</div>
+  <h2 class="doc-h">Approvals stay in Stage 1; Clarify moves to the transition</h2>
+  <p class="doc-note">
+    Per the issue: <em>approvals are part of doing the work</em> (they gate a single tool),
+    <em>clarifications stabilise the answer path</em> (they precede the conclusion). The
+    proposal keeps <code>.approval-card</code> inline among tool cards, and places
+    <code>.clarify-card</code> at the Stage 1 → Stage 2 seam, above the final answer.
+  </p>
+
+  <div class="doc-grid-2">
+
+    <!-- Approve inline in Stage 1 -->
+    <div class="doc-card"><span class="doc-label proposed">Approve card — inline in Stage 1</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner">
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment" data-live-assistant="1">
+
+            <div class="p2s-stage1 is-live">
+              <div class="p2s-worklog">
+                <span class="p2s-worklog-dot"></span>
+                <span class="p2s-worklog-label">Working… 0:18</span>
+                <span class="p2s-worklog-stats"><span><b>1</b> tool</span></span>
+              </div>
+              <div class="p2s-stage1-body">
+                <div class="tool-card-row">
+                  <div class="tool-card">
+                    <div class="tool-card-header">
+                      <span class="tool-card-icon">⚡</span>
+                      <span class="tool-card-name">bash</span>
+                      <span class="tool-card-preview">ls -la ~/.hermes/sessions · exit 0</span>
+                      <span class="tool-card-toggle">▶</span>
+                    </div>
+                  </div>
+                </div>
+                <div class="approval-card doc-visible">
+                  <div class="approval-card-header">
+                    <span class="approval-card-icon">🔐</span>
+                    <span class="approval-card-title">Approve command</span>
+                  </div>
+                  <div class="approval-card-body">
+                    <p class="approval-card-desc">Hermes wants to run a potentially destructive command:</p>
+                    <pre class="approval-card-cmd">rm -rf ~/.hermes/sessions/*.json.bak</pre>
+                  </div>
+                  <div class="approval-card-actions">
+                    <button class="approval-btn approve">Approve</button>
+                    <button class="approval-btn deny">Deny</button>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+          </div></div>
+        </div>
+      </div></div>
+      <div class="doc-compare-caption">Permission gate sits next to the tools it gates.</div>
+    </div>
+
+    <!-- Clarify at transition -->
+    <div class="doc-card"><span class="doc-label proposed">Clarify card — Stage 1 → Stage 2 transition</span>
+      <div class="messages doc-messages"><div class="messages-inner doc-inner">
+        <div class="msg-row assistant-turn" data-role="assistant">
+          <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+          <div class="assistant-turn-blocks"><div class="assistant-segment">
+
+            <div class="p2s-stage1 is-settled" data-p2s-toggle>
+              <div class="p2s-worklog">
+                <span class="p2s-worklog-dot"></span>
+                <span class="p2s-worklog-label">Worked for 0:12</span>
+                <span class="p2s-worklog-stats"><span><b>2</b> tools</span></span>
+                <span class="p2s-worklog-caret">▶</span>
+              </div>
+              <div class="p2s-stage1-body">
+                <div class="tool-card-row">
+                  <div class="tool-card">
+                    <div class="tool-card-header">
+                      <span class="tool-card-icon">📄</span>
+                      <span class="tool-card-name">read_file</span>
+                      <span class="tool-card-preview">package.json · 48 lines</span>
+                      <span class="tool-card-toggle">▶</span>
+                    </div>
+                  </div>
+                </div>
+                <div class="tool-card-row">
+                  <div class="tool-card">
+                    <div class="tool-card-header">
+                      <span class="tool-card-icon">⚡</span>
+                      <span class="tool-card-name">bash</span>
+                      <span class="tool-card-preview">ls src/ · exit 0</span>
+                      <span class="tool-card-toggle">▶</span>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <div class="p2s-transition"></div>
+            <div class="p2s-clarify-slot">
+              <div class="clarify-card doc-visible">
+                <div class="clarify-card-header">
+                  <span class="clarify-card-icon">❓</span>
+                  <span class="clarify-card-title">One quick question before I answer</span>
+                </div>
+                <div class="clarify-card-body">
+                  <p>I can wire the dev server either as an <strong>npm script</strong> in the
+                  existing <code>package.json</code>, or as a standalone <strong>CLI
+                  entry-point</strong>. Which would you prefer?</p>
+                </div>
+                <div class="clarify-card-actions">
+                  <button class="clarify-opt">npm script</button>
+                  <button class="clarify-opt">CLI entry-point</button>
+                  <button class="clarify-opt">Let Hermes pick</button>
+                </div>
+              </div>
+            </div>
+
+          </div></div>
+        </div>
+      </div></div>
+      <div class="doc-compare-caption">Stage 1 is already settled; the answer is paused on clarification.</div>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">4 · Stage 2 · Calm conclusion</div>
+  <h2 class="doc-h">What the "Answer" stage looks like on its own</h2>
+  <p class="doc-note">
+    Three small choices distinguish Stage 2 from a regular text block:
+    (1) a thin horizontal divider above it, (2) a tiny gold <em>Answer</em> kicker aligned to
+    the text rail, (3) a slightly taller line-height. No heavy borders, no boxed treatment —
+    the emphasis comes from <em>what is missing around it</em>, not ornament.
+  </p>
+
+  <div class="doc-card"><span class="doc-label proposed">.p2s-answer (Stage 1 collapsed above)</span>
+    <div class="messages doc-messages"><div class="messages-inner doc-inner">
+      <div class="msg-row assistant-turn" data-role="assistant">
+        <div class="msg-role assistant"><span class="role-icon assistant">H</span><span>Hermes</span></div>
+        <div class="assistant-turn-blocks"><div class="assistant-segment">
+
+          <div class="p2s-stage1 is-settled" data-p2s-toggle>
+            <div class="p2s-worklog">
+              <span class="p2s-worklog-dot"></span>
+              <span class="p2s-worklog-label">Worked for 1:42</span>
+              <span class="p2s-worklog-stats">
+                <span><b>4</b> tools</span>
+                <span><b>2</b> thinking</span>
+                <span><b>1</b> approval</span>
+              </span>
+              <span class="p2s-worklog-caret">▶</span>
+            </div>
+            <div class="p2s-stage1-body">
+              <div class="thinking-card"><div class="thinking-card-header"><span class="thinking-card-icon">💡</span><span class="thinking-card-label">Thought for 2.4s</span><span class="thinking-card-toggle">▶</span></div></div>
+              <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">📄</span><span class="tool-card-name">read_file</span><span class="tool-card-preview">api/streaming.py</span><span class="tool-card-toggle">▶</span></div></div></div>
+              <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">⚡</span><span class="tool-card-name">bash</span><span class="tool-card-preview">grep -rn "tool_call_id" api/</span><span class="tool-card-toggle">▶</span></div></div></div>
+              <div class="p2s-round-sep">Round 2</div>
+              <div class="thinking-card"><div class="thinking-card-header"><span class="thinking-card-icon">💡</span><span class="thinking-card-label">Thought for 1.8s</span><span class="thinking-card-toggle">▶</span></div></div>
+              <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">⚡</span><span class="tool-card-name">bash</span><span class="tool-card-preview">pytest -q · exit 0 · 2.4s</span><span class="tool-card-toggle">▶</span></div></div></div>
+              <div class="tool-card-row"><div class="tool-card"><div class="tool-card-header"><span class="tool-card-icon">✍️</span><span class="tool-card-name">edit_file</span><span class="tool-card-preview">api/streaming.py · +12 −3</span><span class="tool-card-toggle">▶</span></div></div></div>
+            </div>
+          </div>
+
+          <div class="p2s-transition"></div>
+          <div class="p2s-answer">
+            <div class="p2s-answer-kicker">Answer</div>
+            <div class="msg-body">
+              <p>Tool-call persistence was breaking because <code>session.tool_calls</code> was
+              written <em>after</em> <code>s.save()</code> in <code>api/streaming.py</code>.
+              I moved the attach step above the save, and added a fallback that reconstructs
+              ordering from live tool-progress events when <code>tool_call_id</code> is absent
+              on older sessions.</p>
+              <p>Net result:</p>
+              <ul>
+                <li>Reloading mid-stream now preserves every tool card with args + output snippet.</li>
+                <li>Last-turn reasoning survives reload.</li>
+                <li>No schema migration needed — old sessions degrade gracefully.</li>
+              </ul>
+              <p>Covered by the new regression in <code>tests/test_tool_call_persistence.py</code>.</p>
+            </div>
+            <div class="msg-foot" style="opacity:1;padding-left:var(--msg-rail);">
+              <span class="msg-time">11:42 AM · 2,481 tokens · 1.42s</span>
+              <span class="msg-actions">
+                <button class="msg-act" title="Copy">⧉</button>
+                <button class="msg-act" title="Regenerate">↻</button>
+              </span>
+            </div>
+          </div>
+
+        </div></div>
+      </div>
+    </div></div>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">5 · Open-question answers (picked defaults)</div>
+  <h2 class="doc-h">What this proposal commits to</h2>
+  <div class="doc-card" style="padding:16px 20px;">
+    <ul style="color:var(--muted);font-size:13px;line-height:1.85;list-style:disc;padding-left:22px;margin:0;">
+      <li><b style="color:var(--text);">Stage 1 on settle →</b> <em>partial</em> collapse to a
+        single worklog bar with counts. Click to re-expand. No "nuke to black box", no "keep
+        everything open forever".</li>
+      <li><b style="color:var(--text);">Final answer placement →</b> sits <em>beneath</em> Stage 1,
+        not replacing it. Visual distinction comes from the divider + kicker + spacing, not from
+        a two-panel layout.</li>
+      <li><b style="color:var(--text);">Clarify placement →</b> at the Stage 1 → Stage 2 seam.
+        Approvals stay inline with tools.</li>
+      <li><b style="color:var(--text);">Timer →</b> lives on Stage 1 only. Stops when the agent
+        emits the first Stage 2 token; final label becomes "Worked for N:NN".</li>
+      <li><b style="color:var(--text);">Signal for "answer has started" →</b> first assistant
+        text delta after all tool calls have resolved and no new <code>tool_use</code> is pending
+        in the current round. Already present in the SSE stream per maintainer comment.</li>
+    </ul>
+  </div>
+</section>
+
+<!-- ============================================================= -->
+<section class="doc-section">
+  <div class="doc-kicker">6 · DOM cheat-sheet</div>
+  <h2 class="doc-h">What changes vs index.html</h2>
+  <div class="doc-card" style="padding:14px 18px;">
+    <h3 style="font-size:13px;color:var(--text);margin:0 0 8px;">New wrappers</h3>
+    <ul style="color:var(--muted);font-size:12px;line-height:1.9;list-style:disc;padding-left:20px;">
+      <li><code>.p2s-stage1[is-live|is-settled][is-open]</code> — wraps the execution history inside an <code>.assistant-segment</code>.</li>
+      <li><code>.p2s-worklog</code> — header of Stage 1. Pulsing dot + label + counts + caret. Clickable when settled.</li>
+      <li><code>.p2s-stage1-body</code> — holds <code>.thinking-card</code> + <code>.tool-card-row</code> + <code>.p2s-round-sep</code>. Animated via <code>max-height</code>.</li>
+      <li><code>.p2s-round-sep</code> — inline horizontal separator between tool/reasoning rounds.</li>
+      <li><code>.p2s-transition</code> — thin gradient divider between Stage 1 and Stage 2.</li>
+      <li><code>.p2s-answer</code> — wraps the final <code>.msg-body</code> + <code>.msg-foot</code>.</li>
+      <li><code>.p2s-answer-kicker</code> — small gold <em>Answer</em> label.</li>
+      <li><code>.p2s-clarify-slot</code> — placement slot for <code>.clarify-card</code> at the Stage 1/2 seam.</li>
+    </ul>
+    <h3 style="font-size:13px;color:var(--text);margin:14px 0 8px;">Unchanged</h3>
+    <ul style="color:var(--muted);font-size:12px;line-height:1.9;list-style:disc;padding-left:20px;">
+      <li><code>.thinking-card</code>, <code>.tool-card</code>, <code>.approval-card</code>, <code>.clarify-card</code>, <code>.msg-body</code>, <code>.msg-foot</code> — all existing app CSS and existing markup.</li>
+      <li><code>.assistant-turn-blocks</code> and <code>.assistant-segment</code> remain the top-level wrappers.</li>
+      <li>Tool cards still live as <code>.tool-card-row</code> siblings — now nested <em>inside</em> <code>.p2s-stage1-body</code> rather than as direct children of <code>.messages-inner</code>.</li>
+    </ul>
+    <h3 style="font-size:13px;color:var(--text);margin:14px 0 8px;">Implementation notes</h3>
+    <ul style="color:var(--muted);font-size:12px;line-height:1.9;list-style:disc;padding-left:20px;">
+      <li>Renderer in <code>static/messages.js</code> wraps an assistant turn's non-final blocks in <code>.p2s-stage1-body</code> and appends the <code>.p2s-worklog</code> header once; toggles <code>is-live</code>/<code>is-settled</code> based on <code>data-live-assistant</code>.</li>
+      <li><code>static/boot.js</code> SSE handler ticks the timer while <code>is-live</code>, increments counts on each <code>tool_use</code>, and flips the class when the first Stage 2 delta arrives.</li>
+      <li>Persistence: no schema change needed — the worklog summary can be derived on reload from the existing persisted tool-call list + thinking rounds.</li>
+    </ul>
+  </div>
+</section>
+
+</main>
+
+<script>
+  // Theme picker (matches index.html)
+  document.querySelectorAll('[data-theme-btn]').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const t = btn.dataset.themeBtn;
+      if (t === 'default') document.documentElement.removeAttribute('data-theme');
+      else document.documentElement.setAttribute('data-theme', t);
+      document.querySelectorAll('[data-theme-btn]').forEach(b => b.classList.toggle('on', b === btn));
+    });
+  });
+
+  // Existing thinking/tool cards click-to-toggle.
+  document.querySelectorAll('.thinking-card-header, .tool-card-header').forEach(h => {
+    h.addEventListener('click', (e) => {
+      e.stopPropagation();
+      h.parentElement.classList.toggle('open');
+    });
+  });
+
+  // Click the worklog bar on a settled Stage 1 to expand/collapse the history.
+  document.querySelectorAll('.p2s-stage1[data-p2s-toggle] .p2s-worklog').forEach(bar => {
+    bar.addEventListener('click', () => {
+      const stage = bar.closest('.p2s-stage1');
+      if (!stage.classList.contains('is-settled')) return;
+      stage.classList.toggle('is-open');
+    });
+  });
+
+  // Live timer demo in section 2 — ticks so the page feels alive.
+  (function(){
+    const el = document.getElementById('p2sTimer');
+    if (!el) return;
+    let [m, s] = el.textContent.split(':').map(Number);
+    setInterval(() => {
+      s = (s + 1) % 60;
+      if (s === 0) m += 1;
+      el.textContent = m + ':' + String(s).padStart(2,'0');
+    }, 1000);
+  })();
+</script>
+
+</body>
+</html>

server.py

@@ -3,22 +3,56 @@ Hermes Web UI -- Main server entry point.
 Thin routing shell: imports Handler, delegates to api/routes.py, runs server.
 All business logic lives in api/*.
 """
+import logging
+import socket
+import sys
 import time
 import traceback
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from urllib.parse import urlparse
 
+logger = logging.getLogger(__name__)
+
 from api.auth import check_auth
 from api.config import HOST, PORT, STATE_DIR, SESSION_DIR, DEFAULT_WORKSPACE
-from api.helpers import j
+from api.helpers import j, get_profile_cookie
+from api.profiles import set_request_profile, clear_request_profile
 from api.routes import handle_get, handle_post
+from api.startup import auto_install_agent_deps, fix_credential_permissions
+from api.updates import WEBUI_VERSION
+
+
+class QuietHTTPServer(ThreadingHTTPServer):
+    """Custom HTTP server that silently handles common network errors."""
+    daemon_threads = True
+    request_queue_size = 64
+    
+    def handle_error(self, request, client_address):
+        """Override to suppress logging for common client disconnect errors."""
+        exc_type, exc_value, _ = sys.exc_info()
+        
+        # Silently ignore common connection errors caused by client disconnects
+        if exc_type in (ConnectionResetError, BrokenPipeError, ConnectionAbortedError, TimeoutError):
+            return
+        
+        # Also handle socket errors that indicate client disconnect
+        if issubclass(exc_type, OSError):
+            # errno 54 is Connection reset by peer on macOS/BSD
+            # errno 104 is Connection reset by peer on Linux
+            if getattr(exc_value, 'errno', None) in (32, 54, 104, 110):  # EPIPE, ECONNRESET, ETIMEDOUT
+                return
+        
+        # For other errors, use default logging
+        super().handle_error(request, client_address)
 
 
 class Handler(BaseHTTPRequestHandler):
-    server_version = 'HermesWebUI/0.2'
+    timeout = 30  # seconds — kills idle/incomplete connections to prevent thread exhaustion
+    _ver_suffix = WEBUI_VERSION.removeprefix('v')
+    server_version = ('HermesWebUI/' + _ver_suffix) if _ver_suffix != 'unknown' else 'HermesWebUI'
     def log_message(self, fmt, *args): pass  # suppress default Apache-style log
 
-    def log_request(self, code='-', size='-'):
+    def log_request(self, code: str='-', size: str='-') -> None:
         """Structured JSON logs for each request."""
         import json as _json
         duration_ms = round((time.time() - getattr(self, '_req_t0', time.time())) * 1000, 1)
@@ -31,8 +65,12 @@ class Handler(BaseHTTPRequestHandler):
         })
         print(f'[webui] {record}', flush=True)
 
-    def do_GET(self):
+    def do_GET(self) -> None:
         self._req_t0 = time.time()
+        # Per-request profile context from cookie (issue #798)
+        cookie_profile = get_profile_cookie(self)
+        if cookie_profile:
+            set_request_profile(cookie_profile)
         try:
             parsed = urlparse(self.path)
             if not check_auth(self, parsed): return
@@ -42,9 +80,15 @@ class Handler(BaseHTTPRequestHandler):
         except Exception as e:
             print(f'[webui] ERROR {self.command} {self.path}\n' + traceback.format_exc(), flush=True)
             return j(self, {'error': 'Internal server error'}, status=500)
+        finally:
+            clear_request_profile()
 
-    def do_POST(self):
+    def do_POST(self) -> None:
         self._req_t0 = time.time()
+        # Per-request profile context from cookie (issue #798)
+        cookie_profile = get_profile_cookie(self)
+        if cookie_profile:
+            set_request_profile(cookie_profile)
         try:
             parsed = urlparse(self.path)
             if not check_auth(self, parsed): return
@@ -54,30 +98,101 @@ class Handler(BaseHTTPRequestHandler):
         except Exception as e:
             print(f'[webui] ERROR {self.command} {self.path}\n' + traceback.format_exc(), flush=True)
             return j(self, {'error': 'Internal server error'}, status=500)
+        finally:
+            clear_request_profile()
 
 
-def main():
+def main() -> None:
     from api.config import print_startup_config, verify_hermes_imports, _HERMES_FOUND
 
     print_startup_config()
 
+    # Fix sensitive file permissions before doing anything else
+    fix_credential_permissions()
+
+    within_container = False
+    # Check for the "/.within_container" file to determine if we're running inside a container; this file is created in the Dockerfile
+    try:
+        with open('/.within_container', 'r') as f:
+            within_container = True
+    except FileNotFoundError:
+        pass
+
+    if within_container:
+        print('[ok] Running within container.', flush=True)
+
+    # Security: warn if binding non-loopback without authentication
+    from api.auth import is_auth_enabled
+    if HOST not in ('127.0.0.1', '::1', 'localhost') and not is_auth_enabled():
+        print(f'[!!] WARNING: Binding to {HOST} with NO PASSWORD SET.', flush=True)
+        print(f'     Anyone on the network can access your filesystem and agent.', flush=True)
+        print(f'     Set a password via Settings or HERMES_WEBUI_PASSWORD env var.', flush=True)
+        print(f'     To suppress: bind to 127.0.0.1 or set a password.', flush=True)
+        if within_container:
+            print(f'     Note: You are running within a container, must bind to 0.0.0.0 to publish the port.', flush=True)
+    elif not is_auth_enabled():
+        print(f'  [tip] No password set. Any process on this machine can read sessions', flush=True)
+        print(f'        and memory via the local API. Set HERMES_WEBUI_PASSWORD to', flush=True)
+        print(f'        enable authentication.', flush=True)
+
     ok, missing, errors = verify_hermes_imports()
     if not ok and _HERMES_FOUND:
         print(f'[!!] Warning: Hermes agent found but missing modules: {missing}', flush=True)
         for mod, err in errors.items():
             print(f'     {mod}: {err}', flush=True)
-        print('     Agent features may not work correctly.', flush=True)
+        print('     Attempting to install missing dependencies from agent requirements.txt...', flush=True)
+        auto_install_agent_deps()
+        ok, missing, errors = verify_hermes_imports()
+        if not ok:
+            print(f'[!!] Still missing after install attempt: {missing}', flush=True)
+            for mod, err in errors.items():
+                print(f'     {mod}: {err}', flush=True)
+            print('     Agent features may not work correctly.', flush=True)
+        else:
+            print('[ok] Agent dependencies installed successfully.', flush=True)
 
     STATE_DIR.mkdir(parents=True, exist_ok=True)
     SESSION_DIR.mkdir(parents=True, exist_ok=True)
     DEFAULT_WORKSPACE.mkdir(parents=True, exist_ok=True)
-    httpd = ThreadingHTTPServer((HOST, PORT), Handler)
-    print(f'  Hermes Web UI listening on http://{HOST}:{PORT}', flush=True)
-    if HOST == '127.0.0.1':
+
+    # Start the gateway session watcher for real-time SSE updates
+    try:
+        from api.gateway_watcher import start_watcher
+        start_watcher()
+    except Exception as e:
+        print(f'[!!] WARNING: Gateway watcher failed to start: {e}', flush=True)
+
+    httpd = QuietHTTPServer((HOST, PORT), Handler)
+
+    # ── TLS/HTTPS setup (optional) ─────────────────────────────────────────
+    from api.config import TLS_ENABLED, TLS_CERT, TLS_KEY
+    scheme = 'https' if TLS_ENABLED else 'http'
+    if TLS_ENABLED:
+        try:
+            import ssl
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+            ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+            ctx.load_cert_chain(TLS_CERT, TLS_KEY)
+            httpd.socket = ctx.wrap_socket(httpd.socket, server_side=True)
+            print(f'  TLS enabled: cert={TLS_CERT}, key={TLS_KEY}', flush=True)
+        except Exception as e:
+            print(f'[!!] WARNING: TLS setup failed ({e}), falling back to HTTP', flush=True)
+            scheme = 'http'
+
+    print(f'  Hermes Web UI listening on {scheme}://{HOST}:{PORT}', flush=True)
+    if HOST == '127.0.0.1' or within_container:
         print(f'  Remote access: ssh -N -L {PORT}:127.0.0.1:{PORT} <user>@<your-server>', flush=True)
-    print(f'  Then open:     http://localhost:{PORT}', flush=True)
+    print(f'  Then open:     {scheme}://localhost:{PORT}', flush=True)
     print('', flush=True)
-    httpd.serve_forever()
+    try:
+        httpd.serve_forever()
+    finally:
+        # Stop the gateway watcher on shutdown
+        try:
+            from api.gateway_watcher import stop_watcher
+            stop_watcher()
+        except Exception:
+            logger.debug("Failed to stop gateway watcher during shutdown")
 
 if __name__ == '__main__':
     main()

start.sh

@@ -1,260 +1,25 @@
 #!/usr/bin/env bash
-# ============================================================
-# Hermes Web UI -- portable bootstrap
-# Usage: ./start.sh [port]
-#
-# One-command startup. Discovers your Hermes install, sets up
-# a local virtualenv if needed, installs dependencies, then
-# launches the server and prints everything you need to know.
-#
-# Override any step with environment variables:
-#   HERMES_WEBUI_AGENT_DIR   path to hermes-agent checkout
-#   HERMES_WEBUI_PYTHON      python executable to use
-#   HERMES_WEBUI_PORT        port to listen on (default: 8787)
-#   HERMES_WEBUI_HOST        bind address (default: 127.0.0.1)
-#   HERMES_HOME              override ~/.hermes base
-#   HERMES_WEBUI_STATE_DIR   override state directory
-# ============================================================
-
 set -euo pipefail
 
-# ── Load .env if present (machine-local overrides, not committed) ─────────────
-_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-if [[ -f "${_SCRIPT_DIR}/.env" ]]; then
-    set -a
-    # shellcheck source=/dev/null
-    source "${_SCRIPT_DIR}/.env"
-    set +a
-fi
-
-# ── Colours ──────────────────────────────────────────────────────────────────
-RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
-CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
-ok()   { echo -e "${GREEN}[ok]${RESET} $*"; }
-warn() { echo -e "${YELLOW}[!!]${RESET} $*"; }
-die()  { echo -e "${RED}[XX]${RESET} $*" >&2; exit 1; }
-info() { echo -e "${CYAN}[--]${RESET} $*"; }
-hdr()  { echo -e "\n${BOLD}$*${RESET}"; }
-
-# ── Resolve repo root (the directory this script lives in) ───────────────────
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-info "Repo root: ${REPO_ROOT}"
 
-# ── Port ─────────────────────────────────────────────────────────────────────
-PORT="${1:-${HERMES_WEBUI_PORT:-8787}}"
-export HERMES_WEBUI_PORT="${PORT}"
-
-# ── Python discovery ─────────────────────────────────────────────────────────
-hdr "Discovering Python..."
-
-_find_python() {
-    # 1. Explicit env var
-    if [[ -n "${HERMES_WEBUI_PYTHON:-}" ]]; then
-        echo "${HERMES_WEBUI_PYTHON}"; return
-    fi
-
-    # 2. Agent venv (discovered below -- call again after agent dir found)
-    # (handled after agent dir discovery)
-
-    # 3. Local .venv in repo
-    if [[ -x "${REPO_ROOT}/.venv/bin/python" ]]; then
-        echo "${REPO_ROOT}/.venv/bin/python"; return
-    fi
-
-    # 4. System python3
-    if command -v python3 &>/dev/null; then
-        echo "$(command -v python3)"; return
-    fi
-
-    echo ""
-}
-
-PYTHON="$(_find_python)"
-
-# ── Hermes agent discovery ────────────────────────────────────────────────────
-hdr "Discovering Hermes agent..."
-
-HERMES_HOME="${HERMES_HOME:-${HOME}/.hermes}"
-AGENT_DIR=""
-
-_find_agent() {
-    local candidates=(
-        "${HERMES_WEBUI_AGENT_DIR:-}"
-        "${HERMES_HOME}/hermes-agent"
-        "${REPO_ROOT}/../hermes-agent"
-        "${HOME}/.hermes/hermes-agent"
-        "${HOME}/hermes-agent"
-    )
-
-    for d in "${candidates[@]}"; do
-        [[ -z "$d" ]] && continue
-        d="$(cd "${d}" 2>/dev/null && pwd || true)"
-        if [[ -n "$d" && -f "${d}/run_agent.py" ]]; then
-            echo "$d"; return
-        fi
-    done
-    echo ""
-}
-
-AGENT_DIR="$(_find_agent)"
-
-if [[ -n "${AGENT_DIR}" ]]; then
-    ok "Hermes agent: ${AGENT_DIR}"
-    export HERMES_WEBUI_AGENT_DIR="${AGENT_DIR}"
-
-    # Now that we have agent dir, prefer its venv if we don't already have a python
-    if [[ -z "${HERMES_WEBUI_PYTHON:-}" && -x "${AGENT_DIR}/venv/bin/python" ]]; then
-        PYTHON="${AGENT_DIR}/venv/bin/python"
-    fi
-else
-    warn "Hermes agent not found. Agent features will not work."
-    warn "Fix with: export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent"
+if [[ -f "${REPO_ROOT}/.env" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  source "${REPO_ROOT}/.env"
+  set +a
 fi
 
-if [[ -n "${PYTHON}" ]]; then
-    ok "Python: ${PYTHON}  ($(${PYTHON} --version 2>&1))"
-else
-    warn "No Python found. Attempting to install..."
-    if command -v apt-get &>/dev/null; then
-        sudo apt-get install -y python3 python3-venv python3-pip
-    elif command -v brew &>/dev/null; then
-        brew install python3
-    else
-        die "Could not find or install Python. Please install Python 3.8+ and re-run."
-    fi
+PYTHON="${HERMES_WEBUI_PYTHON:-}"
+if [[ -z "${PYTHON}" ]]; then
+  if command -v python3 >/dev/null 2>&1; then
     PYTHON="$(command -v python3)"
-    ok "Python installed: ${PYTHON}"
+  elif command -v python >/dev/null 2>&1; then
+    PYTHON="$(command -v python)"
+  else
+    echo "[XX] Python 3 is required to run bootstrap.py" >&2
+    exit 1
+  fi
 fi
 
-# ── Minimum Python version check ─────────────────────────────────────────────
-PY_VER="$(${PYTHON} -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
-PY_MAJOR="$(echo "${PY_VER}" | cut -d. -f1)"
-PY_MINOR="$(echo "${PY_VER}" | cut -d. -f2)"
-if [[ "${PY_MAJOR}" -lt 3 || ( "${PY_MAJOR}" -eq 3 && "${PY_MINOR}" -lt 8 ) ]]; then
-    die "Python 3.8+ required. Found: ${PY_VER}"
-fi
-
-# ── Dependency check / local venv setup ──────────────────────────────────────
-hdr "Checking dependencies..."
-
-VENV_NEEDED=false
-VENV_PATH="${REPO_ROOT}/.venv"
-
-# If the chosen python is already the agent venv, its deps are already installed.
-# If it is a system python, check if we can import the webui deps, create a local
-# .venv if not.
-_check_deps() {
-    "${PYTHON}" -c "import yaml" 2>/dev/null
-}
-
-if ! _check_deps; then
-    info "PyYAML not found in ${PYTHON}. Creating local .venv..."
-
-    if [[ ! -d "${VENV_PATH}" ]]; then
-        "${PYTHON}" -m venv "${VENV_PATH}" || die "Failed to create virtualenv at ${VENV_PATH}"
-    fi
-
-    VENV_PY="${VENV_PATH}/bin/python"
-    "${VENV_PY}" -m pip install --quiet --upgrade pip
-
-    if [[ -f "${REPO_ROOT}/requirements.txt" ]]; then
-        info "Installing from requirements.txt..."
-        "${VENV_PY}" -m pip install --quiet -r "${REPO_ROOT}/requirements.txt"
-    else
-        info "Installing minimal deps (pyyaml)..."
-        "${VENV_PY}" -m pip install --quiet pyyaml
-    fi
-
-    PYTHON="${VENV_PY}"
-    ok "Local venv ready: ${VENV_PATH}"
-else
-    ok "Dependencies satisfied."
-fi
-
-# ── Kill any stale instance on the same port ─────────────────────────────────
-hdr "Checking for existing instances..."
-
-EXISTING=$(lsof -ti tcp:"${PORT}" 2>/dev/null || true)
-if [[ -n "${EXISTING}" ]]; then
-    warn "Killing existing process on port ${PORT} (PID ${EXISTING})"
-    kill "${EXISTING}" 2>/dev/null || true
-    sleep 0.5
-fi
-
-# Also kill any server.py process from this repo
-pkill -f "${REPO_ROOT}/server.py" 2>/dev/null || true
-
-# ── Set up working directory for Hermes imports ───────────────────────────────
-# server.py / api/config.py inject agent dir into sys.path at import time,
-# but we also cd into the agent dir so relative imports in run_agent work.
-if [[ -n "${AGENT_DIR}" ]]; then
-    WORKDIR="${AGENT_DIR}"
-else
-    WORKDIR="${REPO_ROOT}"
-fi
-
-# ── Launch ───────────────────────────────────────────────────────────────────
-hdr "Starting Hermes Web UI..."
-
-LOG="/tmp/hermes-webui-${PORT}.log"
-export HERMES_WEBUI_HOST="${HERMES_WEBUI_HOST:-127.0.0.1}"
-export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${HERMES_HOME}/webui}"
-
-nohup "${PYTHON}" "${REPO_ROOT}/server.py" \
-    > "${LOG}" 2>&1 &
-PID=$!
-
-echo -e "\n${CYAN}  PID ${PID} starting...${RESET}"
-sleep 1.5
-
-# ── Health check ─────────────────────────────────────────────────────────────
-HEALTH_URL="http://${HERMES_WEBUI_HOST:-127.0.0.1}:${PORT}/health"
-MAX_WAIT=15
-ELAPSED=0
-while [[ $ELAPSED -lt $MAX_WAIT ]]; do
-    if curl -sf "${HEALTH_URL}" | grep -q '"status"' 2>/dev/null; then
-        break
-    fi
-    sleep 0.5
-    ELAPSED=$((ELAPSED + 1))
-done
-
-if ! curl -sf "${HEALTH_URL}" | grep -q '"status"' 2>/dev/null; then
-    warn "Health check did not pass within ${MAX_WAIT}s. Check log:"
-    tail -20 "${LOG}"
-    echo ""
-    warn "Server may still be starting. Try: curl ${HEALTH_URL}"
-else
-    ok "Server is healthy."
-fi
-
-# ── Print access instructions ─────────────────────────────────────────────────
-BIND_HOST="${HERMES_WEBUI_HOST:-127.0.0.1}"
-
-echo ""
-echo -e "${BOLD}========================================${RESET}"
-echo -e "${GREEN}  Hermes Web UI is running${RESET}"
-echo -e "${BOLD}========================================${RESET}"
-echo ""
-
-if [[ "${BIND_HOST}" == "127.0.0.1" || "${BIND_HOST}" == "localhost" ]]; then
-    # Server is bound to loopback -- detect if we are on a remote machine
-    # by checking if $SSH_CLIENT or $SSH_TTY is set
-    if [[ -n "${SSH_CLIENT:-}" || -n "${SSH_TTY:-}" ]]; then
-        SERVER_IP="$(hostname -I 2>/dev/null | awk '{print $1}' || echo "<your-server-ip>")"
-        echo -e "  You are on a remote machine. To access from your local browser:"
-        echo ""
-        echo -e "  ${CYAN}ssh -N -L ${PORT}:127.0.0.1:${PORT} \$(whoami)@${SERVER_IP}${RESET}"
-        echo ""
-        echo -e "  Then open: ${BOLD}http://localhost:${PORT}${RESET}"
-    else
-        echo -e "  Open: ${BOLD}http://localhost:${PORT}${RESET}"
-    fi
-else
-    echo -e "  Open: ${BOLD}http://${BIND_HOST}:${PORT}${RESET}"
-fi
-
-echo ""
-echo -e "  Log:  ${LOG}"
-echo -e "  PID:  ${PID}"
-echo ""
+exec "${PYTHON}" "${REPO_ROOT}/bootstrap.py" --no-browser "$@"

static/favicon-512.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="96" fill="#1a1a1a"/>
+  <defs>
+    <linearGradient id="g" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#F5C542;stop-opacity:1"/>
+      <stop offset="100%" style="stop-color:#D4961C;stop-opacity:1"/>
+    </linearGradient>
+  </defs>
+  <rect x="240" y="80" width="32" height="368" rx="16" fill="url(#g)"/>
+  <path d="M240 144 C192 112, 112 112, 80 144 C112 128, 176 128, 224 160" fill="#F5C542" opacity="0.9"/>
+  <path d="M240 176 C208 152, 144 152, 112 176 C144 160, 192 160, 224 192" fill="#D4961C" opacity="0.8"/>
+  <path d="M272 144 C320 112, 400 112, 432 144 C400 128, 336 128, 288 160" fill="#F5C542" opacity="0.9"/>
+  <path d="M272 176 C304 152, 368 152, 400 176 C368 160, 320 160, 288 192" fill="#D4961C" opacity="0.8"/>
+  <path d="M256 384 C176 352, 160 304, 208 272 C160 288, 144 336, 192 368 C144 320, 176 240, 240 224 C192 256, 176 304, 224 336" fill="none" stroke="#F5C542" stroke-width="20" stroke-linecap="round"/>
+  <path d="M256 384 C336 352, 352 304, 304 272 C352 288, 368 336, 320 368 C368 320, 336 240, 272 224 C320 256, 336 304, 288 336" fill="none" stroke="#D4961C" stroke-width="20" stroke-linecap="round"/>
+  <circle cx="256" cy="80" r="32" fill="#F5C542"/>
+  <circle cx="256" cy="80" r="16" fill="#FFF8E1" opacity="0.7"/>
+</svg>

static/favicon.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="12" fill="#1a1a1a"/>
+  <defs>
+    <linearGradient id="g" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#F5C542;stop-opacity:1"/>
+      <stop offset="100%" style="stop-color:#D4961C;stop-opacity:1"/>
+    </linearGradient>
+  </defs>
+  <rect x="30" y="10" width="4" height="46" rx="2" fill="url(#g)"/>
+  <path d="M30 18 C24 14, 14 14, 10 18 C14 16, 22 16, 28 20" fill="#F5C542" opacity="0.9"/>
+  <path d="M30 22 C26 19, 18 19, 14 22 C18 20, 24 20, 28 24" fill="#D4961C" opacity="0.8"/>
+  <path d="M34 18 C40 14, 50 14, 54 18 C50 16, 42 16, 36 20" fill="#F5C542" opacity="0.9"/>
+  <path d="M34 22 C38 19, 46 19, 50 22 C46 20, 40 20, 36 24" fill="#D4961C" opacity="0.8"/>
+  <path d="M32 48 C22 44, 20 38, 26 34 C20 36, 18 42, 24 46 C18 40, 22 30, 30 28 C24 32, 22 38, 28 42"
+        fill="none" stroke="#F5C542" stroke-width="2.5" stroke-linecap="round"/>
+  <path d="M32 48 C42 44, 44 38, 38 34 C44 36, 46 42, 40 46 C46 40, 42 30, 34 28 C40 32, 42 38, 36 42"
+        fill="none" stroke="#D4961C" stroke-width="2.5" stroke-linecap="round"/>
+  <circle cx="32" cy="10" r="4" fill="#F5C542"/>
+  <circle cx="32" cy="10" r="2" fill="#FFF8E1" opacity="0.7"/>
+</svg>

static/icons.js

@@ -0,0 +1,90 @@
+// ── Lucide icon library (self-hosted SVG paths, no CDN dependency) ──────────
+// All icons are 24×24 viewBox, stroke-based, currentColor.
+// Usage: li('folder')  →  returns a ready-to-embed SVG string
+// The returned SVG uses display:inline-block + vertical-align so it sits
+// neatly beside text in both HTML templates and innerHTML assignments.
+
+const LI_PATHS = {
+  // Navigation tabs
+  'message-square':  '<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>',
+  'calendar':        '<rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/>',
+  'layers':          '<path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/>',
+  'lightbulb':       '<path d="M12 2a7 7 0 0 1 7 7c0 2.5-1.3 4.7-3.2 6H8.2C6.3 13.7 5 11.5 5 9a7 7 0 0 1 7-7z"/><line x1="9" y1="17" x2="15" y2="17"/><line x1="10" y1="20" x2="14" y2="20"/>',
+  'folder':          '<path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/>',
+  'list-todo':       '<rect x="3" y="5" width="6" height="6" rx="1"/><path d="m3 17 2 2 4-4"/><path d="M13 6h8"/><path d="M13 12h8"/><path d="M13 18h8"/>',
+  // Editing / actions
+  'pencil':          '<path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z"/>',
+  'save':            '<path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/>',
+  'chevron-down':    '<polyline points="6 9 12 15 18 9"/>',
+  'chevron-right':   '<polyline points="9 18 15 12 9 6"/>',
+  'download':        '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/>',
+  'upload':          '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/>',
+  'braces':          '<path d="M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1"/><path d="M16 3h1a2 2 0 0 1 2 2v5a2 2 0 0 0 2 2 2 2 0 0 0-2 2v5a2 2 0 0 1-2 2h-1"/>',
+  'trash-2':         '<path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/>',
+  'settings':        '<circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/>',
+  'alert-triangle':  '<path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/>',
+  'refresh-cw':      '<polyline points="23 4 23 10 17 10"/><polyline points="1 20 1 14 7 14"/><path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15"/>',
+  'undo':            '<path d="M9 14 4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 5.5 5.5v0a5.5 5.5 0 0 1-5.5 5.5H11"/>',
+  'check':           '<polyline points="20 6 9 17 4 12"/>',
+  'lock':            '<rect x="3" y="11" width="18" height="11" rx="2" ry="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/>',
+  'star':            '<polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>',
+  'x':               '<line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>',
+  'square':          '<rect x="3" y="3" width="18" height="18" rx="2" ry="2"/>',
+  'plus':            '<line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/>',
+  'arrow-up':        '<line x1="12" y1="19" x2="12" y2="5"/><polyline points="5 12 12 5 19 12"/>',
+  'arrow-right':     '<line x1="5" y1="12" x2="19" y2="12"/><polyline points="12 5 19 12 12 19"/>',
+  'loader':          '<line x1="12" y1="2" x2="12" y2="6"/><line x1="12" y1="18" x2="12" y2="22"/><line x1="4.93" y1="4.93" x2="7.76" y2="7.76"/><line x1="16.24" y1="16.24" x2="19.07" y2="19.07"/><line x1="2" y1="12" x2="6" y2="12"/><line x1="18" y1="12" x2="22" y2="12"/><line x1="4.93" y1="19.07" x2="7.76" y2="16.24"/><line x1="16.24" y1="7.76" x2="19.07" y2="4.93"/>',
+  'pause':           '<rect x="6" y="4" width="4" height="16" rx="1"/><rect x="14" y="4" width="4" height="16" rx="1"/>',
+  // Tool icons
+  'terminal':        '<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>',
+  'file-text':       '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/>',
+  'file-pen':        '<path d="M12 22h6a2 2 0 0 0 2-2V7l-5-5H6a2 2 0 0 0-2 2v10"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M10.4 19.4 14 16l-4-1 .4 4.4z"/><path d="m14 16 1.5-1.5a2.12 2.12 0 0 1 3 3L17 19"/>',
+  'search':          '<circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/>',
+  'globe':           '<circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/>',
+  'play':            '<polygon points="5 3 19 12 5 21 5 3"/>',
+  'wrench':          '<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/>',
+  'brain':           '<path d="M9.5 2A2.5 2.5 0 0 1 12 4.5v15a2.5 2.5 0 0 1-4.96-.44 2.5 2.5 0 0 1-2.96-3.08 3 3 0 0 1-.34-5.58 2.5 2.5 0 0 1 1.32-4.24 2.5 2.5 0 0 1 1.98-3A2.5 2.5 0 0 1 9.5 2z"/><path d="M14.5 2A2.5 2.5 0 0 0 12 4.5v15a2.5 2.5 0 0 0 4.96-.44 2.5 2.5 0 0 0 2.96-3.08 3 3 0 0 0 .34-5.58 2.5 2.5 0 0 0-1.32-4.24 2.5 2.5 0 0 0-1.98-3A2.5 2.5 0 0 0 14.5 2z"/>',
+  'book-open':       '<path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"/><path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"/>',
+  'grip-vertical':   '<circle cx="9" cy="5" r="1"/><circle cx="9" cy="12" r="1"/><circle cx="9" cy="19" r="1"/><circle cx="15" cy="5" r="1"/><circle cx="15" cy="12" r="1"/><circle cx="15" cy="19" r="1"/>',
+  'clock':           '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
+  'bot':             '<rect x="3" y="11" width="18" height="10" rx="2"/><circle cx="12" cy="5" r="2"/><path d="M12 7v4"/><line x1="8" y1="16" x2="8" y2="16"/><line x1="16" y1="16" x2="16" y2="16"/>',
+  'eye':             '<path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/>',
+  'shuffle':         '<polyline points="16 3 21 3 21 8"/><line x1="4" y1="20" x2="21" y2="3"/><polyline points="21 16 21 21 16 21"/><line x1="15" y1="15" x2="21" y2="21"/><line x1="4" y1="4" x2="9" y2="9"/>',
+  'paperclip':       '<path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.82-2.82l8.48-8.48"/>',
+  'copy':            '<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>',
+  'rotate-ccw':      '<path d="M3 2v6h6"/><path d="M3 8a9 9 0 1 0 2.64-4.36L3 8"/>',
+  'user':            '<path d="M20 21a8 8 0 0 0-16 0"/><circle cx="12" cy="7" r="4"/>',
+  // File-type icons
+  'image':           '<rect x="3" y="3" width="18" height="18" rx="2" ry="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/>',
+  'file-code':       '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><polyline points="10 13 8 15 10 17"/><polyline points="14 13 16 15 14 17"/>',
+  'zap':             '<polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"/>',
+  // Suggestion buttons
+  'clipboard-list':  '<path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><rect x="8" y="2" width="8" height="4" rx="1" ry="1"/><line x1="9" y1="12" x2="15" y2="12"/><line x1="9" y1="16" x2="12" y2="16"/>',
+  'map':             '<polygon points="1 6 1 22 8 18 16 22 23 18 23 2 16 6 8 2 1 6"/><line x1="8" y1="2" x2="8" y2="18"/><line x1="16" y1="6" x2="16" y2="22"/>',
+  'git-branch':      '<line x1="6" y1="3" x2="6" y2="15"/><circle cx="18" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/>',
+  // Audio / TTS
+  'volume-2':        '<polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"/><path d="M19.07 4.93a10 10 0 0 1 0 14.14"/><path d="M15.54 8.46a5 5 0 0 1 0 7.07"/>',
+  // Voice-mode button — universal "two-way voice conversation" glyph (matches ChatGPT/Gemini)
+  'audio-lines':     '<path d="M2 10v4"/><path d="M6 6v12"/><path d="M10 3v18"/><path d="M14 8v8"/><path d="M18 5v14"/><path d="M22 10v4"/>',
+  // Queue pill chevron (ui.js queue indicator)
+  'chevron-up':      '<polyline points="18 15 12 9 6 15"/>',
+  // Insights panel stat cards (panels.js)
+  'hash':            '<line x1="4" y1="9" x2="20" y2="9"/><line x1="4" y1="15" x2="20" y2="15"/><line x1="10" y1="3" x2="8" y2="21"/><line x1="16" y1="3" x2="14" y2="21"/>',
+  'cpu':             '<rect x="4" y="4" width="16" height="16" rx="2" ry="2"/><rect x="9" y="9" width="6" height="6"/><line x1="9" y1="1" x2="9" y2="4"/><line x1="15" y1="1" x2="15" y2="4"/><line x1="9" y1="20" x2="9" y2="23"/><line x1="15" y1="20" x2="15" y2="23"/><line x1="20" y1="9" x2="23" y2="9"/><line x1="20" y1="14" x2="23" y2="14"/><line x1="1" y1="9" x2="4" y2="9"/><line x1="1" y1="14" x2="4" y2="14"/>',
+  'dollar-sign':     '<line x1="12" y1="1" x2="12" y2="23"/><path d="M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6"/>',
+};
+
+/**
+ * Returns a Lucide SVG string for the given icon name.
+ * @param {string} name  – key in LI_PATHS (e.g. 'folder', 'trash-2')
+ * @param {number} size  – width/height in px (default 16)
+ * @returns {string} SVG element string ready for innerHTML
+ */
+function li(name, size = 16) {
+  const p = LI_PATHS[name];
+  if (!p) { console.warn('li(): unknown icon', name); return ''; }
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" `
+       + `stroke="currentColor" stroke-width="2" stroke-linecap="round" `
+       + `stroke-linejoin="round" aria-hidden="true" `
+       + `style="display:inline-block;vertical-align:-0.15em;flex-shrink:0">${p}</svg>`;
+}

static/login.js

@@ -0,0 +1,110 @@
+/* Login page — external script, no inline handlers.
+ * Loaded by the /login route. Reads data attributes from the form for
+ * i18n strings so the server does not need to inject JS literals.
+ */
+document.addEventListener('DOMContentLoaded', function () {
+  var form = document.getElementById('login-form');
+  var input = document.getElementById('pw');
+
+  if (!form || !input) return;
+
+  var invalidPw = form.getAttribute('data-invalid-pw') || 'Invalid password';
+  var connFailed = form.getAttribute('data-conn-failed') || 'Connection failed';
+
+  function showErr(msg) {
+    var err = document.getElementById('err');
+    if (err) { err.textContent = msg; err.style.display = 'block'; }
+  }
+
+  function hideErr() {
+    var err = document.getElementById('err');
+    if (err) { err.style.display = 'none'; }
+  }
+
+  // Return the ?next= redirect path if present and safe, otherwise './'
+  // Guards against open-redirect: rejects protocol-relative (//evil.com),
+  // absolute URLs, backslash variants, and control characters.
+  function _safeNextPath() {
+    try {
+      var raw = new URL(window.location.href).searchParams.get('next');
+      if (!raw) return './';
+      if (raw.charAt(0) !== '/') return './';             // must be path-absolute
+      if (raw.charAt(1) === '/' || raw.charAt(1) === '\\') return './'; // reject // and \\
+      if (/[\x00-\x1f\x7f\s]/.test(raw)) return './';  // reject control chars / whitespace
+      return raw;
+    } catch (_) { return './'; }
+  }
+
+  async function doLogin(e) {
+    e.preventDefault();
+    var pw = input.value;
+    hideErr();
+    try {
+      var res = await fetch('api/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ password: pw }),
+        credentials: 'include',
+      });
+      var data = {};
+      try { data = await res.json(); } catch (_) {}
+      if (res.ok && data.ok) {
+        window.location.href = _safeNextPath();
+      } else {
+        showErr(data.error || invalidPw);
+      }
+    } catch (ex) {
+      showErr(connFailed);
+    }
+  }
+
+  form.addEventListener('submit', doLogin);
+
+  input.addEventListener('keydown', function (e) {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      doLogin(e);
+    }
+  });
+
+  // On page load, probe the server so we can distinguish "can't reach server"
+  // (Tailscale off, wrong network) from "session expired / need to log in".
+  // Uses /health — a public endpoint, no auth required.
+  // If unreachable, retries every 3 s and auto-reloads once the server is back.
+  (function checkConnectivity() {
+    var retryTimer = null;
+
+    function setFormDisabled(disabled) {
+      if (input) input.disabled = disabled;
+      var btn = form.querySelector('button');
+      if (btn) btn.disabled = disabled;
+    }
+
+    function probe() {
+      fetch('health', { method: 'GET', credentials: 'omit' })
+        .then(function (r) {
+          if (r.ok) {
+            // Server is reachable — if we were in retry mode, reload so the
+            // page reflects the correct auth state (expired session, etc.).
+            if (retryTimer !== null) {
+              clearTimeout(retryTimer);
+              retryTimer = null;
+              window.location.reload();
+            }
+          } else {
+            showErr(connFailed + ' (server error ' + r.status + ')');
+          }
+        })
+        .catch(function () {
+          showErr('Cannot reach server — check your VPN / Tailscale connection.');
+          setFormDisabled(true);
+          // Keep retrying so the page auto-recovers once the network is back.
+          if (retryTimer === null) {
+            retryTimer = setInterval(probe, 3000);
+          }
+        });
+    }
+
+    probe();
+  })();
+});

static/manifest.json

@@ -0,0 +1,34 @@
+{
+  "name": "Hermes",
+  "short_name": "Hermes",
+  "description": "Hermes AI Agent Web UI",
+  "start_url": "./",
+  "display": "standalone",
+  "background_color": "#1a1a1a",
+  "theme_color": "#1a1a1a",
+  "orientation": "portrait-primary",
+  "icons": [
+    {
+      "src": "static/favicon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "static/favicon-32.png",
+      "sizes": "32x32",
+      "type": "image/png"
+    },
+    {
+      "src": "static/favicon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "static/favicon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ]
+}

static/onboarding.js

@@ -0,0 +1,635 @@
+const ONBOARDING={status:null,step:0,steps:['system','setup','workspace','password','finish'],form:{provider:'openrouter',workspace:'',model:'',password:'',apiKey:'',baseUrl:''},active:false,probe:{status:'idle',error:null,detail:'',models:null,probedKey:''}};
+
+// ── Onboarding base-URL probe (#1499) ───────────────────────────────────────
+// Probes <base_url>/models so the wizard can validate the configured endpoint
+// before persisting AND populate the model dropdown from the live catalog.
+// Probe state lives on ONBOARDING.probe; the dropdown render and the
+// nextOnboardingStep gate both consult it.
+
+let _onboardingProbeTimer=null;
+
+function _onboardingProbeKey(provider,baseUrl,apiKey){
+  return `${provider||''}|${(baseUrl||'').trim().replace(/\/+$/,'')}|${apiKey||''}`;
+}
+
+function _setOnboardingProbeState(patch){
+  ONBOARDING.probe={...ONBOARDING.probe,...patch};
+  // Re-render body so probe status / model dropdown reflect new state.
+  _renderOnboardingBody();
+}
+
+async function _runOnboardingProbe({force=false}={}){
+  const provider=ONBOARDING.form.provider;
+  const cat=_getOnboardingSetupProvider(provider);
+  if(!cat||!cat.requires_base_url){
+    _setOnboardingProbeState({status:'idle',error:null,detail:'',models:null,probedKey:''});
+    return ONBOARDING.probe;
+  }
+  const baseUrl=(ONBOARDING.form.baseUrl||'').trim();
+  if(!baseUrl){
+    _setOnboardingProbeState({status:'idle',error:null,detail:'',models:null,probedKey:''});
+    return ONBOARDING.probe;
+  }
+  const apiKey=(ONBOARDING.form.apiKey||'').trim();
+  const key=_onboardingProbeKey(provider,baseUrl,apiKey);
+  if(!force&&ONBOARDING.probe.probedKey===key&&ONBOARDING.probe.status!=='probing'){
+    return ONBOARDING.probe;
+  }
+  _setOnboardingProbeState({status:'probing',error:null,detail:'',probedKey:key});
+  try{
+    const res=await api('/api/onboarding/probe',{method:'POST',body:JSON.stringify({provider,base_url:baseUrl,api_key:apiKey||undefined})});
+    if(res&&res.ok){
+      _setOnboardingProbeState({status:'ok',error:null,detail:'',models:Array.isArray(res.models)?res.models:[],probedKey:key});
+      // If the user hasn't picked a model yet (or their pick is no longer in
+      // the list), default to the first probed model so Continue isn't blocked
+      // on an empty selection.
+      const stillPresent=ONBOARDING.form.model&&(res.models||[]).some(m=>m.id===ONBOARDING.form.model);
+      if(!stillPresent&&(res.models||[]).length>0){
+        ONBOARDING.form.model=res.models[0].id;
+        _renderOnboardingBody();
+      }
+    }else{
+      const err=(res&&res.error)||'unreachable';
+      const detail=(res&&res.detail)||'';
+      _setOnboardingProbeState({status:'error',error:err,detail,models:null,probedKey:key});
+    }
+  }catch(e){
+    _setOnboardingProbeState({status:'error',error:'unreachable',detail:(e&&e.message)||String(e),models:null,probedKey:key});
+  }
+  return ONBOARDING.probe;
+}
+
+function _scheduleOnboardingProbe(){
+  if(_onboardingProbeTimer)clearTimeout(_onboardingProbeTimer);
+  _onboardingProbeTimer=setTimeout(()=>{_runOnboardingProbe();},400);
+}
+
+function _onboardingProbeMessage(probe){
+  if(!probe||probe.status==='idle')return '';
+  if(probe.status==='probing')return t('onboarding_probe_probing')||'Testing connection…';
+  if(probe.status==='ok'){
+    const n=(probe.models||[]).length;
+    const tmpl=t('onboarding_probe_ok')||'Connected. {n} model(s) available.';
+    return tmpl.replace('{n}',String(n));
+  }
+  // status === 'error'
+  const errKey='onboarding_probe_error_'+probe.error;
+  const localized=t(errKey);
+  // i18n.js's `t()` returns the key itself when missing — fall back to a generic message.
+  const heading=(localized&&localized!==errKey)?localized:(t('onboarding_probe_error_generic')||'Could not reach the configured base URL.');
+  const detail=probe.detail?` (${probe.detail})`:'';
+  return heading+detail;
+}
+
+function _getOnboardingSetupProviders(){
+  return (((ONBOARDING.status||{}).setup||{}).providers)||[];
+}
+
+function _getOnboardingSetupProvider(id){
+  return _getOnboardingSetupProviders().find(p=>p.id===id)||null;
+}
+
+function _getOnboardingSetupCategories(){
+  return (((ONBOARDING.status||{}).setup||{}).categories)||[];
+}
+
+/** Render the provider <select> with <optgroup> per category. */
+function _renderProviderSelectOptions(selectedId){
+  const providers=_getOnboardingSetupProviders();
+  const categories=_getOnboardingSetupCategories();
+  const provMap={};
+  providers.forEach(p=>{provMap[p.id]=p;});
+  if(!categories.length){
+    // Fallback: flat list when no categories are available.
+    return providers.map(p=>`<option value="${esc(p.id)}">${esc(p.label)}${p.quick?' — '+esc(t('onboarding_quick_setup_badge')):''}</option>`).join('');
+  }
+  return categories.map(cat=>{
+    const opts=cat.providers.map(pid=>{
+      const p=provMap[pid];
+      if(!p)return '';
+      return `<option value="${esc(p.id)}"${p.id===selectedId?' selected':''}>${esc(p.label)}${p.quick?' — '+esc(t('onboarding_quick_setup_badge')):''}</option>`;
+    }).join('');
+    return `<optgroup label="${esc(t('provider_category_'+cat.id)||cat.label)}">${opts}</optgroup>`;
+  }).join('');
+}
+
+function _getOnboardingCurrentSetup(){
+  return (((ONBOARDING.status||{}).setup||{}).current)||{};
+}
+
+function _onboardingStepMeta(key){
+  return ({
+    system:{title:t('onboarding_step_system_title'),desc:t('onboarding_step_system_desc')},
+    setup:{title:t('onboarding_step_setup_title'),desc:t('onboarding_step_setup_desc')},
+    workspace:{title:t('onboarding_step_workspace_title'),desc:t('onboarding_step_workspace_desc')},
+    password:{title:t('onboarding_step_password_title'),desc:t('onboarding_step_password_desc')},
+    finish:{title:t('onboarding_step_finish_title'),desc:t('onboarding_step_finish_desc')}
+  })[key];
+}
+
+function _renderOnboardingSteps(){
+  const wrap=$('onboardingSteps');
+  if(!wrap)return;
+  wrap.innerHTML='';
+  ONBOARDING.steps.forEach((key,idx)=>{
+    const meta=_onboardingStepMeta(key);
+    const item=document.createElement('div');
+    item.className='onboarding-step'+(idx===ONBOARDING.step?' active':idx<ONBOARDING.step?' done':'');
+    item.innerHTML=`<div class="onboarding-step-index">${idx+1}</div><div><div class="onboarding-step-title">${meta.title}</div><div class="onboarding-step-desc">${meta.desc}</div></div>`;
+    wrap.appendChild(item);
+  });
+}
+
+function _setOnboardingNotice(msg,kind='info'){
+  const el=$('onboardingNotice');
+  if(!el)return;
+  if(!msg){el.style.display='none';el.textContent='';el.className='onboarding-status';return;}
+  el.style.display='block';
+  el.className='onboarding-status '+kind;
+  el.textContent=msg;
+}
+
+function _getOnboardingWorkspaceChoices(){
+  const items=((ONBOARDING.status||{}).workspaces||{}).items||[];
+  return items.length?items:[{name:'Home',path:ONBOARDING.form.workspace||''}];
+}
+
+function _getOnboardingProviderModelChoices(){
+  const provider=_getOnboardingSetupProvider(ONBOARDING.form.provider);
+  // Probe-discovered models (#1499) take precedence over the static catalog
+  // for providers with requires_base_url=True.  The catalog ships an empty
+  // list for self-hosted providers (lmstudio, ollama, custom) — without the
+  // probe the user had nothing to pick from.
+  if(provider&&provider.requires_base_url&&ONBOARDING.probe&&ONBOARDING.probe.status==='ok'&&Array.isArray(ONBOARDING.probe.models)&&ONBOARDING.probe.models.length){
+    return ONBOARDING.probe.models;
+  }
+  return provider?(provider.models||[]):[];
+}
+
+function _renderOnboardingBaseUrlField(showBaseUrl){
+  // Renders the base_url input PLUS the probe status banner / Test button
+  // when the active provider has requires_base_url=True (#1499).  Returns
+  // the empty string when the active provider does not require a base URL,
+  // so the existing call sites can continue to template-interpolate this in
+  // place of the previous inline `<label …>` snippet.
+  if(!showBaseUrl)return '';
+  const probe=ONBOARDING.probe||{status:'idle'};
+  const msg=_onboardingProbeMessage(probe);
+  let banner='';
+  if(msg){
+    const cls={ok:'onboarding-probe-ok',probing:'onboarding-probe-probing',error:'onboarding-probe-error'}[probe.status]||'';
+    banner=`<p class="onboarding-copy onboarding-probe-banner ${cls}">${esc(msg)}</p>`;
+  }
+  const testBtnLabel=t('onboarding_probe_test_button')||'Test connection';
+  const testBtnDisabled=(probe.status==='probing')?'disabled':'';
+  return `<label class="onboarding-field"><span>${t('onboarding_base_url_label')}</span><input id="onboardingBaseUrlInput" value="${esc(ONBOARDING.form.baseUrl||'')}" placeholder="${t('onboarding_base_url_placeholder')}" oninput="ONBOARDING.form.baseUrl=this.value;_scheduleOnboardingProbe()" onblur="_runOnboardingProbe()"></label><div class="onboarding-probe-row"><button type="button" class="onboarding-probe-btn" ${testBtnDisabled} onclick="_runOnboardingProbe({force:true})">${esc(testBtnLabel)}</button></div>${banner}`;
+}
+
+function _renderOnboardingApiKeyField(){
+  // Renders the API-key input.  For providers flagged `key_optional` in the
+  // setup catalog (lmstudio, ollama, custom — typically self-hosted servers
+  // that run keyless by default), the field shows an "(optional)" hint and
+  // empty input is accepted on Continue.  Pre-#1499-third-sub-bug-fix the
+  // wizard required a non-empty string here even for keyless installs, which
+  // forced users to type random gibberish to clear onboarding.
+  const provider=_getOnboardingSetupProvider(ONBOARDING.form.provider);
+  const keyOptional=!!(provider&&provider.key_optional);
+  const labelKey=keyOptional?'onboarding_api_key_label_optional':'onboarding_api_key_label';
+  const placeholderKey=keyOptional?'onboarding_api_key_placeholder_optional':'onboarding_api_key_placeholder';
+  const helpHtml=keyOptional?`<p class="onboarding-copy onboarding-api-key-help">${esc(t('onboarding_api_key_help_keyless')||'')}</p>`:'';
+  return `<label class="onboarding-field" id="onboardingApiKeyField"><span>${t(labelKey)}</span><input id="onboardingApiKeyInput" type="password" value="${esc(ONBOARDING.form.apiKey||'')}" placeholder="${t(placeholderKey)}" oninput="ONBOARDING.form.apiKey=this.value" onblur="_runOnboardingProbe()"></label>${helpHtml}`;
+}
+
+function _getOnboardingSelectedModel(){
+  return ONBOARDING.form.model||'';
+}
+
+function _renderOnboardingModelField(){
+  const choices=_getOnboardingProviderModelChoices();
+  if(ONBOARDING.form.provider==='custom'){
+    return `<label class="onboarding-field"><span>${t('onboarding_model_label')}</span><input id="onboardingModelInput" value="${esc(_getOnboardingSelectedModel())}" placeholder="${t('onboarding_custom_model_placeholder')}" oninput="ONBOARDING.form.model=this.value"></label><p class="onboarding-copy">${t('onboarding_custom_model_help')}</p>`;
+  }
+  const options=choices.map(m=>`<option value="${esc(m.id)}">${esc(m.label)}</option>`).join('');
+  return `<label class="onboarding-field"><span>${t('onboarding_model_label')}</span><select id="onboardingModelSelect" onchange="ONBOARDING.form.model=this.value">${options}</select></label><p class="onboarding-copy">${t('onboarding_workspace_help')}</p>`;
+}
+
+function _providerStatusLabel(system){
+  if(system.chat_ready) return t('onboarding_check_provider_ready');
+  if(system.provider_configured) return t('onboarding_check_provider_partial');
+  return t('onboarding_check_provider_pending');
+}
+
+function _renderOnboardingBody(){
+  const body=$('onboardingBody');
+  if(!body||!ONBOARDING.status)return;
+  const key=ONBOARDING.steps[ONBOARDING.step];
+  const system=ONBOARDING.status.system||{};
+  const settings=ONBOARDING.status.settings||{};
+  const setup=ONBOARDING.status.setup||{};
+  const nextBtn=$('onboardingNextBtn');
+  const backBtn=$('onboardingBackBtn');
+  if(backBtn) backBtn.style.display=ONBOARDING.step>0?'':'none';
+  if(nextBtn) nextBtn.textContent=key==='finish'?t('onboarding_open'):t('onboarding_continue');
+
+  if(key==='system'){
+    const hermesOk=system.hermes_found&&system.imports_ok;
+    const setupOk=!!system.chat_ready;
+    _setOnboardingNotice(system.provider_note|| (setupOk?t('onboarding_notice_system_ready'):t('onboarding_notice_system_unavailable')),setupOk?'success':(hermesOk?'info':'warn'));
+    body.innerHTML=`
+      <div class="onboarding-panel-grid">
+        <div class="onboarding-check ${hermesOk?'ok':'warn'}"><strong>${t('onboarding_check_agent')}</strong><span>${hermesOk?t('onboarding_check_agent_ready'):t('onboarding_check_agent_missing')}</span></div>
+        <div class="onboarding-check ${(setupOk?'ok':system.provider_configured?'warn':'muted')}"><strong>${t('onboarding_check_provider')}</strong><span>${_providerStatusLabel(system)}</span></div>
+        <div class="onboarding-check ${(settings.password_enabled?'ok':'muted')}"><strong>${t('onboarding_check_password')}</strong><span>${settings.password_enabled?t('onboarding_check_password_enabled'):t('onboarding_check_password_disabled')}</span></div>
+      </div>
+      <div class="onboarding-copy">
+        <p><strong>${t('onboarding_config_file')}</strong> ${esc(system.config_path||t('onboarding_unknown'))}</p>
+        <p><strong>${t('onboarding_env_file')}</strong> ${esc(system.env_path||t('onboarding_unknown'))}</p>
+        <p>${esc(system.provider_note||'')}</p>
+        ${system.current_provider?`<p><strong>${t('onboarding_current_provider')}</strong> ${esc(system.current_provider)}${system.current_model?` — ${esc(system.current_model)}`:''}</p>`:''}
+        ${system.current_base_url?`<p><strong>${t('onboarding_base_url_label')}</strong> ${esc(system.current_base_url)}</p>`:''}
+        ${system.missing_modules&&system.missing_modules.length?`<p><strong>${t('onboarding_missing_imports')}</strong> ${esc(system.missing_modules.join(', '))}</p>`:''}
+      </div>`;
+    return;
+  }
+
+  if(key==='setup'){
+    const selectedId=ONBOARDING.form.provider;
+    const groupedOptions=_renderProviderSelectOptions(selectedId);
+    const provider=_getOnboardingSetupProvider(selectedId)||_getOnboardingSetupProviders()[0]||null;
+    const showBaseUrl=provider&&provider.requires_base_url;
+    const keyHelp=provider?`${t('onboarding_api_key_help_prefix')} ${esc(provider.env_var)}.`:'';
+
+    // OAuth provider path: configured via CLI, no API key input needed.
+    const currentIsOauth=!!(ONBOARDING.status.setup||{}).current_is_oauth;
+    const currentProviderName=((ONBOARDING.status.setup||{}).current||{}).provider||'';
+    if(currentIsOauth){
+      const isReady=!!(ONBOARDING.status.system||{}).chat_ready;
+      const providerLabel=esc(currentProviderName);
+      if(isReady){
+        _setOnboardingNotice(t('onboarding_notice_setup_already_ready'),'success');
+        body.innerHTML=`
+          <div class="onboarding-oauth-card onboarding-oauth-ready">
+            <div class="onboarding-oauth-icon">✓</div>
+            <div>
+              <strong>${t('onboarding_oauth_provider_ready_title')}</strong>
+              <p>${t('onboarding_oauth_provider_ready_body').replace('{provider}',providerLabel)}</p>
+            </div>
+          </div>
+          <p class="onboarding-copy" style="margin-top:20px">${t('onboarding_oauth_switch_hint')}</p>
+          <label class="onboarding-field">
+            <span>${t('onboarding_provider_label')}</span>
+            <select id="onboardingProviderSelect" onchange="syncOnboardingProvider(this.value)">${groupedOptions}</select>
+          </label>
+          ${_renderOnboardingApiKeyField()}
+          ${_renderOnboardingBaseUrlField(showBaseUrl)}
+          <p class="onboarding-copy">${keyHelp}</p>`;
+      } else {
+        _setOnboardingNotice(t('onboarding_notice_setup_required'),'warn');
+        body.innerHTML=`
+          <div class="onboarding-oauth-card onboarding-oauth-pending">
+            <div class="onboarding-oauth-icon">⚠</div>
+            <div>
+              <strong>${t('onboarding_oauth_provider_not_ready_title')}</strong>
+              <p>${t('onboarding_oauth_provider_not_ready_body').replace('{provider}',providerLabel)}</p>
+            </div>
+          </div>
+          <p class="onboarding-copy" style="margin-top:20px">${t('onboarding_oauth_switch_hint')}</p>
+          <label class="onboarding-field">
+            <span>${t('onboarding_provider_label')}</span>
+            <select id="onboardingProviderSelect" onchange="syncOnboardingProvider(this.value)">${groupedOptions}</select>
+          </label>
+          ${_renderOnboardingApiKeyField()}
+          ${_renderOnboardingBaseUrlField(showBaseUrl)}
+          <p class="onboarding-copy">${keyHelp}</p>`;
+      }
+      return;
+    }
+
+    _setOnboardingNotice(system.chat_ready?t('onboarding_notice_setup_already_ready'):t('onboarding_notice_setup_required'),system.chat_ready?'success':'info');
+    body.innerHTML=`
+      <label class="onboarding-field">
+        <span>${t('onboarding_provider_label')}</span>
+        <select id="onboardingProviderSelect" onchange="syncOnboardingProvider(this.value)">${groupedOptions}</select>
+      </label>
+      ${_renderOnboardingApiKeyField()}
+      ${_renderOnboardingBaseUrlField(showBaseUrl)}
+      <p class="onboarding-copy">${keyHelp}</p>
+      <div class="onboarding-oauth-card" id="codexOAuthCard">
+        <div class="onboarding-oauth-icon">🔑</div>
+        <div style="flex:1">
+          <strong>${t('oauth_login_codex')}</strong>
+          <p style="margin:6px 0 0;font-size:13px;color:var(--muted);line-height:1.5">
+            ${t('onboarding_oauth_switch_hint')}
+          </p>
+        </div>
+        <button class="sm-btn" id="codexOAuthBtn" onclick="startCodexOAuth()" style="margin-left:auto;flex-shrink:0">${t('oauth_login_codex')}</button>
+      </div>
+      <div id="codexOAuthFlow" style="display:none;margin-top:12px"></div>
+      ${showBaseUrl?`<p class="onboarding-copy">${t('onboarding_base_url_help')}</p>`:''}
+      <p class="onboarding-copy">${esc(setup.unsupported_note||'')||''}</p>`;
+    return;
+  }
+
+  if(key==='workspace'){
+    const workspaceOptions=_getOnboardingWorkspaceChoices().map(ws=>`<option value="${esc(ws.path)}">${esc(ws.name||ws.path)} — ${esc(ws.path)}</option>`).join('');
+    _setOnboardingNotice(t('onboarding_notice_workspace'), 'info');
+    body.innerHTML=`
+      <label class="onboarding-field">
+        <span>${t('onboarding_workspace_label')}</span>
+        <select id="onboardingWorkspaceSelect" onchange="syncOnboardingWorkspaceSelect(this.value)">${workspaceOptions}</select>
+      </label>
+      <label class="onboarding-field">
+        <span>${t('onboarding_workspace_or_path')}</span>
+        <input id="onboardingWorkspaceInput" value="${esc(ONBOARDING.form.workspace||'')}" placeholder="${t('onboarding_workspace_placeholder')}" oninput="ONBOARDING.form.workspace=this.value">
+      </label>
+      ${_renderOnboardingModelField()}`;
+    const wsSel=$('onboardingWorkspaceSelect');
+    if(wsSel && ONBOARDING.form.workspace) wsSel.value=ONBOARDING.form.workspace;
+    const modelSel=$('onboardingModelSelect');
+    if(modelSel && ONBOARDING.form.model) modelSel.value=ONBOARDING.form.model;
+    return;
+  }
+
+  if(key==='password'){
+    _setOnboardingNotice(settings.password_enabled?t('onboarding_notice_password_enabled'):t('onboarding_notice_password_recommended'), settings.password_enabled?'success':'info');
+    body.innerHTML=`
+      <label class="onboarding-field">
+        <span>${t('onboarding_password_label')}</span>
+        <input id="onboardingPasswordInput" type="password" value="${esc(ONBOARDING.form.password||'')}" placeholder="${t('onboarding_password_placeholder')}" oninput="ONBOARDING.form.password=this.value">
+      </label>
+      <p class="onboarding-copy">${t('onboarding_password_help')}</p>`;
+    return;
+  }
+
+  const provider=_getOnboardingSetupProvider(ONBOARDING.form.provider);
+  _setOnboardingNotice(t('onboarding_notice_finish'), 'success');
+  body.innerHTML=`
+    <div class="onboarding-summary">
+      <div><strong>${t('onboarding_provider_label')}</strong><span>${esc((provider&&provider.label)||ONBOARDING.form.provider||t('onboarding_not_set'))}</span></div>
+      <div><strong>${t('onboarding_model_label')}</strong><span>${esc(_getOnboardingSelectedModel()||t('onboarding_not_set'))}</span></div>
+      <div><strong>${t('onboarding_workspace_label')}</strong><span>${esc(ONBOARDING.form.workspace||t('onboarding_not_set'))}</span></div>
+      <div><strong>${t('onboarding_check_password')}</strong><span>${t(_getOnboardingPasswordSummaryKey(settings))}</span></div>
+    </div>
+    ${ONBOARDING.form.baseUrl?`<p class="onboarding-copy"><strong>${t('onboarding_base_url_label')}</strong> ${esc(ONBOARDING.form.baseUrl)}</p>`:''}
+    <p class="onboarding-copy">${t('onboarding_finish_help')}</p>`;
+}
+
+function _getOnboardingPasswordSummaryKey(settings){
+  const hasExistingPassword=!!(settings&&settings.password_enabled);
+  const hasNewPassword=!!((ONBOARDING.form.password||'').trim());
+  if(hasNewPassword) return hasExistingPassword?'onboarding_password_will_replace':'onboarding_password_will_enable';
+  return hasExistingPassword?'onboarding_password_keep_existing':'onboarding_password_remains_disabled';
+}
+
+function syncOnboardingWorkspaceSelect(value){
+  ONBOARDING.form.workspace=value;
+  const input=$('onboardingWorkspaceInput');
+  if(input) input.value=value;
+}
+
+function syncOnboardingProvider(value){
+  const provider=_getOnboardingSetupProvider(value);
+  ONBOARDING.form.provider=value;
+  if(provider){
+    if(!ONBOARDING.form.model || !_getOnboardingProviderModelChoices().some(m=>m.id===ONBOARDING.form.model) || value==='custom'){
+      ONBOARDING.form.model=provider.default_model||'';
+    }
+    if(provider.requires_base_url){
+      ONBOARDING.form.baseUrl=ONBOARDING.form.baseUrl||provider.default_base_url||'';
+    }else{
+      ONBOARDING.form.baseUrl=provider.default_base_url||'';
+    }
+  }
+  _renderOnboardingBody();
+}
+
+async function loadOnboardingWizard(){
+  try{
+    const status=await api('/api/onboarding/status');
+    ONBOARDING.status=status;
+    const current=((status.setup||{}).current)||{};
+    ONBOARDING.form.provider=current.provider||'openrouter';
+    ONBOARDING.form.workspace=(status.workspaces&&status.workspaces.last)||status.settings.default_workspace||'';
+    ONBOARDING.form.model=status.settings.default_model||current.model||'';
+    ONBOARDING.form.password='';
+    ONBOARDING.form.apiKey='';
+    ONBOARDING.form.baseUrl=current.base_url||'';
+    ONBOARDING.active=!status.completed;
+    if(!ONBOARDING.active) return false;
+    $('onboardingOverlay').style.display='flex';
+    _renderOnboardingSteps();
+    _renderOnboardingBody();
+    return true;
+  }catch(e){
+    console.warn('onboarding status failed',e);
+    return false;
+  }
+}
+
+function prevOnboardingStep(){
+  if(ONBOARDING.step===0)return;
+  ONBOARDING.step--;
+  _renderOnboardingSteps();
+  _renderOnboardingBody();
+}
+
+async function _saveOnboardingProviderSetup(){
+  const provider=(ONBOARDING.form.provider||'').trim();
+  const model=(ONBOARDING.form.model||'').trim();
+  const apiKey=(ONBOARDING.form.apiKey||'').trim();
+  const baseUrl=(ONBOARDING.form.baseUrl||'').trim();
+  const current=_getOnboardingCurrentSetup();
+  const isUnchanged=current.provider===provider&&((current.model||'')===model)&&((current.base_url||'')===baseUrl);
+  // Skip the POST when nothing changed.  We also skip when the provider is
+  // unsupported/OAuth-based and already working — chat_ready may be false for
+  // providers not in the quick-setup list (e.g. minimax-cn) even though they are
+  // fully configured.  Posting in that case would either be a no-op (the server
+  // just marks complete for unsupported providers) or could silently overwrite
+  // config.yaml if the user accidentally changed the provider dropdown.
+  const currentIsOauth=!!(ONBOARDING.status&&ONBOARDING.status.setup&&ONBOARDING.status.setup.current_is_oauth);
+  if(isUnchanged && !apiKey && ((ONBOARDING.status.system||{}).chat_ready || currentIsOauth)) return;
+  const body={provider,model};
+  if(apiKey) body.api_key=apiKey;
+  if(baseUrl) body.base_url=baseUrl;
+  const status=await api('/api/onboarding/setup',{method:'POST',body:JSON.stringify(body)});
+  ONBOARDING.status=status;
+}
+
+async function _saveOnboardingDefaults(){
+  const workspace=(ONBOARDING.form.workspace||'').trim();
+  const model=(ONBOARDING.form.model||'').trim();
+  const password=(ONBOARDING.form.password||'').trim();
+  if(!workspace) throw new Error(t('onboarding_error_choose_workspace'));
+  if(!model) throw new Error(t('onboarding_error_choose_model'));
+  const known=_getOnboardingWorkspaceChoices().some(ws=>ws.path===workspace);
+  if(!known){
+    await api('/api/workspaces/add',{method:'POST',body:JSON.stringify({path:workspace})});
+  }
+  // Model persisted by /api/onboarding/setup — no /api/default-model call needed here
+  const body={default_workspace:workspace};
+  if(password) body._set_password=password;
+  const saved=await api('/api/settings',{method:'POST',body:JSON.stringify(body)});
+  if(ONBOARDING.status){
+    ONBOARDING.status.settings={...(ONBOARDING.status.settings||{}),password_enabled:!!saved.auth_enabled};
+  }
+  localStorage.setItem('hermes-webui-model',model);
+  if($('modelSelect')) _applyModelToDropdown(model,$('modelSelect'));
+}
+
+async function _finishOnboarding(){
+  await _saveOnboardingProviderSetup();
+  await _saveOnboardingDefaults();
+  const done=await api('/api/onboarding/complete',{method:'POST',body:'{}'});
+  ONBOARDING.status=done;
+  ONBOARDING.active=false;
+  $('onboardingOverlay').style.display='none';
+  showToast(t('onboarding_complete'));
+  await loadWorkspaceList();
+  if(typeof renderSessionList==='function') await renderSessionList();
+  if(!S.session && typeof newSession==='function'){
+    await newSession(true);
+    await renderSessionList();
+  }
+}
+
+async function skipOnboarding(){
+  try{
+    // Mark onboarding completed server-side without changing any config
+    await api('/api/onboarding/complete',{method:'POST',body:'{}'});
+    ONBOARDING.active=false;
+    $('onboardingOverlay').style.display='none';
+    showToast(t('onboarding_skipped')||'Setup skipped');
+  }catch(e){
+    _setOnboardingNotice((e.message||String(e)),'warn');
+  }
+}
+
+async function nextOnboardingStep(){
+  try{
+    if(ONBOARDING.steps[ONBOARDING.step]==='setup'){
+      ONBOARDING.form.provider=(($('onboardingProviderSelect')||{}).value||ONBOARDING.form.provider||'').trim();
+      ONBOARDING.form.apiKey=(($('onboardingApiKeyInput')||{}).value||'').trim();
+      ONBOARDING.form.baseUrl=(($('onboardingBaseUrlInput')||{}).value||ONBOARDING.form.baseUrl||'').trim();
+      if(!ONBOARDING.form.provider) throw new Error(t('onboarding_error_provider_required'));
+      if(ONBOARDING.form.provider==='custom' && !ONBOARDING.form.baseUrl) throw new Error(t('onboarding_error_base_url_required'));
+      // For self-hosted providers (requires_base_url=True), gate Continue on a
+      // successful probe of <base_url>/models — otherwise the wizard would
+      // happily persist an unreachable URL and finish in 200ms with no
+      // outbound HTTP, exactly the bug in #1499.  Run the probe synchronously
+      // here, then check status; the probe is idempotent & cached on
+      // (provider, baseUrl, apiKey) so this rarely triggers a second network
+      // call when the user already saw a green banner.
+      const cat=_getOnboardingSetupProvider(ONBOARDING.form.provider);
+      if(cat&&cat.requires_base_url){
+        if(!ONBOARDING.form.baseUrl) throw new Error(t('onboarding_error_base_url_required'));
+        await _runOnboardingProbe();
+        if(ONBOARDING.probe.status!=='ok'){
+          // Surface the same localized error string the inline banner shows.
+          const msg=_onboardingProbeMessage(ONBOARDING.probe)||t('onboarding_error_probe_failed')||'Could not reach the configured base URL.';
+          throw new Error(msg);
+        }
+      }
+    }
+    if(ONBOARDING.steps[ONBOARDING.step]==='workspace'){
+      ONBOARDING.form.workspace=(($('onboardingWorkspaceInput')||{}).value||ONBOARDING.form.workspace||'').trim();
+      ONBOARDING.form.model=(($('onboardingModelInput')||{}).value||($('onboardingModelSelect')||{}).value||ONBOARDING.form.model||'').trim();
+      if(!ONBOARDING.form.workspace) throw new Error(t('onboarding_error_workspace_required'));
+      if(!ONBOARDING.form.model) throw new Error(t('onboarding_error_model_required'));
+    }
+    if(ONBOARDING.steps[ONBOARDING.step]==='password'){
+      ONBOARDING.form.password=(($('onboardingPasswordInput')||{}).value||'').trim();
+    }
+    if(ONBOARDING.step===ONBOARDING.steps.length-1){
+      await _finishOnboarding();
+      return;
+    }
+    ONBOARDING.step++;
+    _renderOnboardingSteps();
+    _renderOnboardingBody();
+  }catch(e){
+    _setOnboardingNotice(e.message||String(e),'warn');
+  }
+}
+
+/* ── Codex OAuth device-code flow ── */
+let _codexOAuthSSE=null;
+
+async function startCodexOAuth(){
+  const flowDiv=$('codexOAuthFlow');
+  const btn=$('codexOAuthBtn');
+  if(!flowDiv)return;
+  if(btn){btn.disabled=true;btn.textContent='...';}
+  flowDiv.style.display='block';
+  flowDiv.innerHTML=`<div class="onboarding-oauth-card onboarding-oauth-pending"><div class="onboarding-oauth-icon">⏳</div><div><strong>${t('oauth_codex_polling')}</strong><p>Starting device-code flow…</p></div></div>`;
+  try{
+    const resp=await api('/api/oauth/codex/start',{method:'POST'});
+    if(resp.error) throw new Error(resp.error);
+    const{device_code,user_code,verification_uri}=resp;
+    if(!device_code||!user_code||!verification_uri) throw new Error('Invalid OAuth response');
+    // Open verification URI in new tab
+    window.open(verification_uri,'_blank');
+    // Show user code prominently
+    flowDiv.innerHTML=`
+      <div class="onboarding-oauth-card onboarding-oauth-pending">
+        <div class="onboarding-oauth-icon">📋</div>
+        <div style="flex:1">
+          <strong>${t('oauth_codex_step1')}</strong>
+          <p><a href="${esc(verification_uri)}" target="_blank" rel="noopener" style="color:var(--accent);word-break:break-all">${esc(verification_uri)}</a></p>
+          <p style="margin-top:8px"><strong>${t('oauth_codex_step2')}</strong></p>
+          <code style="display:inline-block;font-size:18px;letter-spacing:0.1em;background:rgba(255,255,255,.08);padding:6px 14px;border-radius:8px;margin-top:4px;user-select:all">${esc(user_code)}</code>
+          <p style="margin-top:8px;color:var(--muted);font-size:13px">${t('oauth_codex_polling')}</p>
+        </div>
+      </div>`;
+    // Connect to SSE poll endpoint
+    const pollUrl=new URL('api/oauth/codex/poll?device_code='+encodeURIComponent(device_code),location.href);
+    if(_codexOAuthSSE){_codexOAuthSSE.close();_codexOAuthSSE=null;}
+    _codexOAuthSSE=new EventSource(pollUrl.href);
+    _codexOAuthSSE.onmessage=function(ev){
+      let data;
+      try{data=JSON.parse(ev.data);}catch(e){return;}
+      if(data.status==='success'){
+        if(_codexOAuthSSE){_codexOAuthSSE.close();_codexOAuthSSE=null;}
+        flowDiv.innerHTML=`
+          <div class="onboarding-oauth-card onboarding-oauth-ready">
+            <div class="onboarding-oauth-icon">✅</div>
+            <div><strong>${t('oauth_codex_success')}</strong>
+            <p>Token saved to credential pool. You can now use Codex as a provider.</p></div>
+          </div>`;
+        if(btn){btn.disabled=false;btn.textContent=t('oauth_login_codex');}
+        showToast(t('oauth_codex_success'));
+        // Refresh onboarding status in background
+        loadOnboardingWizard().catch(()=>{});
+      }else if(data.status==='error'){
+        if(_codexOAuthSSE){_codexOAuthSSE.close();_codexOAuthSSE=null;}
+        const isExpired=(data.error||'').includes('expired');
+        flowDiv.innerHTML=`
+          <div class="onboarding-oauth-card" style="border-color:var(--error,#e55)">
+            <div class="onboarding-oauth-icon">❌</div>
+            <div><strong>${isExpired?t('oauth_codex_expired'):t('oauth_codex_error')}</strong>
+            <p>${esc(data.error||'Unknown error')}</p></div>
+          </div>`;
+        if(btn){btn.disabled=false;btn.textContent=t('oauth_login_codex');}
+      }
+      // 'polling' status — keep waiting
+    };
+    _codexOAuthSSE.onerror=function(){
+      if(_codexOAuthSSE){_codexOAuthSSE.close();_codexOAuthSSE=null;}
+      if(btn){btn.disabled=false;btn.textContent=t('oauth_login_codex');}
+      // Don't overwrite if already showing success/error
+      if(!flowDiv.querySelector('.onboarding-oauth-ready')&&!flowDiv.querySelector('[style*="error"]')){
+        flowDiv.innerHTML=`
+          <div class="onboarding-oauth-card" style="border-color:var(--error,#e55)">
+            <div class="onboarding-oauth-icon">❌</div>
+            <div><strong>${t('oauth_codex_error')}</strong><p>Connection lost. Please try again.</p></div>
+          </div>`;
+      }
+    };
+  }catch(e){
+    flowDiv.innerHTML=`
+      <div class="onboarding-oauth-card" style="border-color:var(--error,#e55)">
+        <div class="onboarding-oauth-icon">❌</div>
+        <div><strong>${t('oauth_codex_error')}</strong><p>${esc(e.message||String(e))}</p></div>
+      </div>`;
+    if(btn){btn.disabled=false;btn.textContent=t('oauth_login_codex');}
+  }
+}

static/sw.js

@@ -0,0 +1,124 @@
+/**
+ * Hermes WebUI Service Worker
+ * Minimal PWA service worker — enables "Add to Home Screen".
+ * No offline caching of API responses (the UI requires a live backend).
+ * Caches only static shell assets so the app shell loads fast on repeat visits.
+ */
+
+// Cache version is injected by the server at request time (routes.py /sw.js handler).
+// Bumps automatically whenever the git commit changes — no manual edits needed.
+const CACHE_NAME = 'hermes-shell-__WEBUI_VERSION__';
+
+// Static assets that form the app shell.
+//
+// Versioned assets (CSS + JS) include `?v=__WEBUI_VERSION__` to match the
+// query string the page sends — see index.html. Without the version query
+// here, every cache lookup against `?v=...` URLs would miss and fall through
+// to network, defeating the pre-cache.
+//
+// Unversioned assets (`./`, manifest.json, favicons) are referenced from
+// index.html without a cache-bust query, so they stay unversioned here too.
+const VQ = '?v=__WEBUI_VERSION__';
+const SHELL_ASSETS = [
+  './',
+  './static/style.css' + VQ,
+  './static/boot.js' + VQ,
+  './static/ui.js' + VQ,
+  './static/messages.js' + VQ,
+  './static/sessions.js' + VQ,
+  './static/panels.js' + VQ,
+  './static/commands.js' + VQ,
+  './static/icons.js' + VQ,
+  './static/i18n.js' + VQ,
+  './static/workspace.js' + VQ,
+  './static/terminal.js' + VQ,
+  './static/onboarding.js' + VQ,
+  './static/favicon.svg',
+  './static/favicon-32.png',
+  './manifest.json',
+];
+
+// Install: pre-cache the app shell
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => {
+      return cache.addAll(SHELL_ASSETS).catch((err) => {
+        // Non-fatal: if any asset fails, still activate
+        console.warn('[sw] Shell pre-cache partial failure:', err);
+      });
+    })
+  );
+  self.skipWaiting();
+});
+
+// Activate: clean up old caches
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(
+        keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k))
+      )
+    )
+  );
+  self.clients.claim();
+});
+
+// Fetch strategy:
+// - API calls (/api/*, /stream) → always network (never cache)
+// - Shell assets → cache-first with network fallback
+// - Everything else → network-first, fall back to offline page
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+
+  // Never intercept cross-origin requests
+  if (url.origin !== self.location.origin) return;
+
+  // Never intercept the service worker script itself. Returning a cached sw.js
+  // prevents the browser from seeing a new cache version after local patches.
+  if (url.pathname.endsWith('/sw.js')) return;
+
+  // API and streaming endpoints — always go to network.
+  // The WebUI may be mounted under a subpath such as /hermes/, so API
+  // requests can look like /hermes/api/sessions rather than /api/sessions.
+  if (
+    url.pathname.startsWith('/api/') ||
+    url.pathname.includes('/api/') ||
+    url.pathname.includes('/stream') ||
+    url.pathname.startsWith('/health') ||
+    url.pathname.includes('/health')
+  ) {
+    return; // let browser handle normally
+  }
+
+  // Shell assets: cache-first
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        // Cache successful GET responses for shell assets
+        if (
+          event.request.method === 'GET' &&
+          response.status === 200
+        ) {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
+        }
+        return response;
+      }).catch(() => {
+        // Offline fallback for navigation requests.
+        // Note: caches.match() returns a Promise (always truthy in a `||` check),
+        // so we must await/then to unwrap it — otherwise the `new Response(...)`
+        // branch is dead code and the browser falls back to its default offline page.
+        if (event.request.mode === 'navigate') {
+          return caches.match('./').then((cached) => cached || new Response(
+            '<html><body style="font-family:sans-serif;padding:2rem;background:#1a1a1a;color:#ccc">' +
+            '<h2>You are offline</h2>' +
+            '<p>Hermes requires a server connection. Please check your network and try again.</p>' +
+            '</body></html>',
+            { headers: { 'Content-Type': 'text/html' } }
+          ));
+        }
+      });
+    })
+  );
+});

static/terminal.js

@@ -0,0 +1,632 @@
+const TERMINAL_UI={
+  open:false,
+  collapsed:false,
+  sessionId:null,
+  workspace:null,
+  source:null,
+  term:null,
+  fitAddon:null,
+  resizeObserver:null,
+  resizeTimer:null,
+  closeTimer:null,
+  typedLine:'',
+  height:null,
+  resizeHandleReady:false,
+  resizing:false,
+  resizeStartY:0,
+  resizeStartHeight:0,
+};
+
+const TERMINAL_HEIGHT_DEFAULT=260;
+const TERMINAL_HEIGHT_MIN=180;
+const TERMINAL_HEIGHT_MAX=520;
+const TERMINAL_MOBILE_HEIGHT_DEFAULT=190;
+const TERMINAL_MOBILE_HEIGHT_MIN=140;
+const TERMINAL_MOBILE_HEIGHT_MAX=300;
+
+function _terminalEls(){
+  return {
+    panel:$('composerTerminalPanel'),
+    inner:$('composerTerminalPanel')&&$('composerTerminalPanel').querySelector('.composer-terminal-inner'),
+    dock:$('composerTerminalDock'),
+    viewport:$('terminalViewport'),
+    surface:$('terminalSurface'),
+    toggle:$('btnTerminalToggle'),
+    workspace:$('terminalWorkspaceLabel'),
+    dockWorkspace:$('terminalDockWorkspaceLabel'),
+    handle:$('terminalResizeHandle'),
+  };
+}
+
+function _terminalSessionId(){
+  return S.session&&S.session.session_id;
+}
+
+function _terminalWorkspaceName(){
+  const ws=S.session&&S.session.workspace;
+  if(!ws)return '';
+  const parts=String(ws).split(/[\\/]+/).filter(Boolean);
+  return parts[parts.length-1]||ws;
+}
+
+function _isTerminalCloseCommand(value){
+  return ['exit','quit','logout','close'].includes(String(value||'').trim().toLowerCase());
+}
+
+function _trackTerminalInput(data){
+  if(data==='\r'||data==='\n'){
+    const command=TERMINAL_UI.typedLine;
+    TERMINAL_UI.typedLine='';
+    return command;
+  }
+  if(data==='\u0003'){
+    TERMINAL_UI.typedLine='';
+    return null;
+  }
+  if(data==='\u007f'||data==='\b'){
+    TERMINAL_UI.typedLine=TERMINAL_UI.typedLine.slice(0,-1);
+    return null;
+  }
+  if(data.length===1&&data>=' '){
+    TERMINAL_UI.typedLine+=data;
+  }else if(data.length>1&&/^[\x20-\x7e]+$/.test(data)){
+    TERMINAL_UI.typedLine+=data;
+  }
+  return null;
+}
+
+function _terminalCssVar(name,fallback){
+  const value=getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+  return value||fallback;
+}
+
+function _terminalTheme(){
+  const isDark=document.documentElement.classList.contains('dark');
+  const background=_terminalCssVar('--code-bg',isDark?'#1A1A2E':'#F5F0E5');
+  const foreground=_terminalCssVar('--pre-text',_terminalCssVar('--text',isDark?'#E2E8F0':'#1A1610'));
+  const muted=_terminalCssVar('--muted',isDark?'#C0C0C0':'#5C5344');
+  const accent=_terminalCssVar('--accent-text',_terminalCssVar('--accent',isDark?'#FFD700':'#8B6508'));
+  const error=_terminalCssVar('--error',isDark?'#EF5350':'#C62828');
+  const success=_terminalCssVar('--success',isDark?'#4CAF50':'#3D8B40');
+  const warning=_terminalCssVar('--warning',isDark?'#FFA726':'#E68A00');
+  const info=_terminalCssVar('--info',isDark?'#4DD0E1':'#0288A8');
+  return {
+    background,
+    foreground,
+    cursor:accent,
+    selectionBackground:_terminalCssVar('--accent-bg-strong',isDark?'rgba(255,215,0,.18)':'rgba(184,134,11,.18)'),
+    black:isDark?'#0D0D1A':'#1A1610',
+    red:error,
+    green:success,
+    yellow:warning,
+    blue:info,
+    magenta:accent,
+    cyan:info,
+    white:foreground,
+    brightBlack:muted,
+    brightRed:error,
+    brightGreen:success,
+    brightYellow:accent,
+    brightBlue:info,
+    brightMagenta:accent,
+    brightCyan:info,
+    brightWhite:isDark?'#FFFFFF':'#0F0D08',
+  };
+}
+
+function syncComposerTerminalTheme(){
+  if(TERMINAL_UI.term)TERMINAL_UI.term.options.theme=_terminalTheme();
+}
+
+function _xtermReady(){
+  return typeof window.Terminal==='function';
+}
+
+function _ensureXterm(){
+  const {surface}= _terminalEls();
+  if(!surface)return null;
+  if(TERMINAL_UI.term)return TERMINAL_UI.term;
+  if(!_xtermReady()){
+    surface.textContent='Terminal library failed to load. Check network access to cdn.jsdelivr.net.';
+    return null;
+  }
+  const term=new window.Terminal({
+    cursorBlink:true,
+    fontSize:13,
+    fontFamily:'Menlo, Monaco, Consolas, "Liberation Mono", monospace',
+    scrollback:1000,
+    convertEol:false,
+    theme:_terminalTheme(),
+  });
+  let fitAddon=null;
+  if(window.FitAddon&&typeof window.FitAddon.FitAddon==='function'){
+    fitAddon=new window.FitAddon.FitAddon();
+    term.loadAddon(fitAddon);
+  }
+  if(window.WebLinksAddon&&typeof window.WebLinksAddon.WebLinksAddon==='function'){
+    term.loadAddon(new window.WebLinksAddon.WebLinksAddon());
+  }
+  term.open(surface);
+  term.onData(data=>{
+    const completedCommand=_trackTerminalInput(data);
+    if(completedCommand!==null&&_isTerminalCloseCommand(completedCommand)){
+      closeComposerTerminal();
+      return;
+    }
+    const sid=TERMINAL_UI.sessionId||_terminalSessionId();
+    if(!sid)return;
+    api('/api/terminal/input',{method:'POST',body:JSON.stringify({
+      session_id:sid,
+      data,
+    })}).catch(e=>showToast(t('terminal_input_failed')+e.message,2600,'error'));
+  });
+  TERMINAL_UI.term=term;
+  TERMINAL_UI.fitAddon=fitAddon;
+  _fitTerminal();
+  return term;
+}
+
+function _terminalDimensions(){
+  const term=TERMINAL_UI.term;
+  if(term&&term.cols&&term.rows)return {rows:term.rows,cols:term.cols};
+  return {rows:18,cols:80};
+}
+
+function _terminalHeightBounds(){
+  const mobile=window.matchMedia&&window.matchMedia('(max-width: 700px)').matches;
+  const min=mobile?TERMINAL_MOBILE_HEIGHT_MIN:TERMINAL_HEIGHT_MIN;
+  const maxByViewport=Math.floor(window.innerHeight*(mobile?0.44:0.5));
+  const hardMax=mobile?TERMINAL_MOBILE_HEIGHT_MAX:TERMINAL_HEIGHT_MAX;
+  return {
+    min,
+    max:Math.max(min,Math.min(hardMax,maxByViewport)),
+    defaultHeight:mobile?TERMINAL_MOBILE_HEIGHT_DEFAULT:TERMINAL_HEIGHT_DEFAULT,
+  };
+}
+
+function _clampTerminalHeight(height){
+  const bounds=_terminalHeightBounds();
+  const n=Number(height);
+  const fallback=TERMINAL_UI.height||bounds.defaultHeight;
+  return Math.max(bounds.min,Math.min(bounds.max,Number.isFinite(n)?n:fallback));
+}
+
+function _applyTerminalHeight(height){
+  const {inner,handle}= _terminalEls();
+  const next=_clampTerminalHeight(height);
+  TERMINAL_UI.height=next;
+  if(inner)inner.style.setProperty('--composer-terminal-height',next+'px');
+  if(handle){
+    const bounds=_terminalHeightBounds();
+    handle.setAttribute('aria-valuemin',String(bounds.min));
+    handle.setAttribute('aria-valuemax',String(bounds.max));
+    handle.setAttribute('aria-valuenow',String(next));
+  }
+  if(TERMINAL_UI.open&&!TERMINAL_UI.collapsed){
+    _fitTerminal();
+    _syncTerminalTranscriptSpace(true);
+  }
+  return next;
+}
+
+function _resetTerminalHeightForViewport(){
+  const bounds=_terminalHeightBounds();
+  _applyTerminalHeight(TERMINAL_UI.height||bounds.defaultHeight);
+}
+
+function _startTerminalHeightResize(ev){
+  if(ev.pointerType==='touch')return;
+  const {inner,handle}= _terminalEls();
+  if(!inner||!handle)return;
+  ev.preventDefault();
+  TERMINAL_UI.resizing=true;
+  TERMINAL_UI.resizeStartY=ev.clientY;
+  TERMINAL_UI.resizeStartHeight=TERMINAL_UI.height||inner.getBoundingClientRect().height||_terminalHeightBounds().defaultHeight;
+  inner.classList.add('is-resizing');
+  try{handle.setPointerCapture(ev.pointerId);}catch(_){}
+}
+
+function _moveTerminalHeightResize(ev){
+  if(!TERMINAL_UI.resizing)return;
+  ev.preventDefault();
+  _applyTerminalHeight(TERMINAL_UI.resizeStartHeight+(TERMINAL_UI.resizeStartY-ev.clientY));
+}
+
+function _endTerminalHeightResize(ev){
+  if(!TERMINAL_UI.resizing)return;
+  TERMINAL_UI.resizing=false;
+  const {inner,handle}= _terminalEls();
+  if(inner)inner.classList.remove('is-resizing');
+  if(handle&&ev&&ev.pointerId!==undefined)try{handle.releasePointerCapture(ev.pointerId);}catch(_){}
+  _fitTerminal();
+}
+
+function _handleTerminalResizeKey(ev){
+  let delta=0;
+  if(ev.key==='ArrowUp')delta=16;
+  else if(ev.key==='ArrowDown')delta=-16;
+  else if(ev.key==='PageUp')delta=64;
+  else if(ev.key==='PageDown')delta=-64;
+  else if(ev.key==='Home'){
+    ev.preventDefault();
+    return _applyTerminalHeight(_terminalHeightBounds().min);
+  }
+  else if(ev.key==='End'){
+    ev.preventDefault();
+    return _applyTerminalHeight(_terminalHeightBounds().max);
+  }
+  else return;
+  ev.preventDefault();
+  _applyTerminalHeight((TERMINAL_UI.height||_terminalHeightBounds().defaultHeight)+delta);
+}
+
+function _initTerminalResizeHandle(){
+  if(TERMINAL_UI.resizeHandleReady)return;
+  const {handle}= _terminalEls();
+  if(!handle)return;
+  TERMINAL_UI.resizeHandleReady=true;
+  handle.addEventListener('pointerdown',_startTerminalHeightResize);
+  handle.addEventListener('pointermove',_moveTerminalHeightResize);
+  handle.addEventListener('pointerup',_endTerminalHeightResize);
+  handle.addEventListener('pointercancel',_endTerminalHeightResize);
+  handle.addEventListener('keydown',_handleTerminalResizeKey);
+}
+
+function _terminalMessagesEl(){
+  return document.getElementById('messages');
+}
+
+function _terminalIsMessagesNearBottom(el){
+  if(!el)return false;
+  return el.scrollHeight-el.scrollTop-el.clientHeight<150;
+}
+
+function _syncTerminalTranscriptSpace(open,opts){
+  opts=opts||{};
+  const messages=_terminalMessagesEl();
+  if(!messages)return;
+  const wasNearBottom=_terminalIsMessagesNearBottom(messages);
+  if(!open){
+    messages.classList.remove('terminal-open');
+    messages.classList.remove('terminal-collapsed');
+    messages.classList.remove('terminal-expanding-from-dock');
+    messages.style.removeProperty('--terminal-card-height');
+    messages.style.removeProperty('--terminal-dock-height');
+    if(wasNearBottom&&typeof scrollToBottom==='function')requestAnimationFrame(scrollToBottom);
+    return;
+  }
+  if(open==='collapsed'){
+    messages.classList.remove('terminal-open');
+    messages.classList.add('terminal-collapsed');
+  }else{
+    messages.classList.add('terminal-open');
+    messages.classList.remove('terminal-collapsed');
+  }
+  const measure=()=>{
+    if(!TERMINAL_UI.open)return;
+    const {panel,inner,dock}= _terminalEls();
+    const target=open==='collapsed'?(dock||panel):(inner||panel);
+    const h=target&&target.getBoundingClientRect().height;
+    if(h>0){
+      if(open==='collapsed')messages.style.setProperty('--terminal-dock-height',Math.ceil(h+24)+'px');
+      else messages.style.setProperty('--terminal-card-height',Math.ceil(h+24)+'px');
+    }
+    if(wasNearBottom&&typeof scrollToBottom==='function')scrollToBottom();
+  };
+  if(opts.immediate)measure();
+  requestAnimationFrame(measure);
+  setTimeout(measure,420);
+}
+
+function _fitTerminal(){
+  const term=TERMINAL_UI.term;
+  if(!term)return;
+  if(TERMINAL_UI.collapsed)return;
+  try{
+    if(TERMINAL_UI.fitAddon)TERMINAL_UI.fitAddon.fit();
+  }catch(_){}
+  _syncTerminalTranscriptSpace(true);
+  _scheduleTerminalResize();
+}
+
+function _setTerminalChromeState(state){
+  const {panel,inner,dock,workspace,dockWorkspace}= _terminalEls();
+  const composerWrap=$('composerWrap');
+  if(!panel)return;
+  const collapsed=state==='collapsed';
+  const expanded=state==='expanded';
+  if(composerWrap)composerWrap.classList.toggle('terminal-dock-visible',collapsed);
+  panel.hidden=!(collapsed||expanded);
+  panel.classList.toggle('is-open',expanded);
+  panel.classList.toggle('is-collapsed',collapsed);
+  if(inner)inner.setAttribute('aria-hidden',collapsed?'true':'false');
+  if(dock)dock.hidden=!collapsed;
+  const label=_terminalWorkspaceName();
+  if(workspace)workspace.textContent=label;
+  if(dockWorkspace)dockWorkspace.textContent=label;
+}
+
+function syncTerminalButton(){
+  const {toggle}= _terminalEls();
+  const currentSid=_terminalSessionId();
+  const currentWorkspace=S.session&&S.session.workspace;
+  if(TERMINAL_UI.open&&TERMINAL_UI.sessionId&&(currentSid!==TERMINAL_UI.sessionId||currentWorkspace!==TERMINAL_UI.workspace)){
+    closeComposerTerminal(TERMINAL_UI.sessionId);
+  }
+  if(!toggle)return;
+  const hasWorkspace=!!(S.session&&S.session.workspace);
+  toggle.disabled=!hasWorkspace;
+  toggle.classList.toggle('active',TERMINAL_UI.open);
+  toggle.setAttribute('aria-pressed',TERMINAL_UI.open?'true':'false');
+  toggle.title=hasWorkspace?(TERMINAL_UI.collapsed?t('terminal_expand'):t('terminal_open_title')):t('terminal_no_workspace_title');
+  toggle.setAttribute('aria-label',toggle.title);
+}
+
+function focusComposerTerminalInput(){
+  if(TERMINAL_UI.term)TERMINAL_UI.term.focus();
+}
+
+function _connectTerminalOutput(){
+  const sid=_terminalSessionId();
+  if(!sid)return;
+  if(TERMINAL_UI.source){
+    try{TERMINAL_UI.source.close();}catch(_){}
+    TERMINAL_UI.source=null;
+  }
+  const url=new URL('api/terminal/output',document.baseURI||location.href);
+  url.searchParams.set('session_id',sid);
+  const source=new EventSource(url.href,{withCredentials:true});
+  TERMINAL_UI.source=source;
+  source.addEventListener('output',ev=>{
+    if(TERMINAL_UI.source!==source)return;
+    let text='';
+    try{text=(JSON.parse(ev.data)||{}).text||'';}
+    catch(_){text=ev.data||'';}
+    if(TERMINAL_UI.term&&text)TERMINAL_UI.term.write(text);
+  });
+  source.addEventListener('terminal_closed',()=>{
+    if(TERMINAL_UI.source!==source)return;
+    if(TERMINAL_UI.term)TERMINAL_UI.term.writeln('\r\n[terminal closed]\r\n');
+    try{source.close();}catch(_){}
+    TERMINAL_UI.source=null;
+    setTimeout(()=>closeComposerTerminal(null,{skipApi:true}),260);
+  });
+  source.addEventListener('terminal_error',ev=>{
+    if(TERMINAL_UI.source!==source)return;
+    let msg=t('terminal_error');
+    try{msg=(JSON.parse(ev.data)||{}).error||msg;}catch(_){}
+    if(TERMINAL_UI.term)TERMINAL_UI.term.writeln('\r\n[terminal error] '+msg+'\r\n');
+    try{source.close();}catch(_){}
+    TERMINAL_UI.source=null;
+  });
+}
+
+async function _startComposerTerminal(restart=false){
+  const sid=_terminalSessionId();
+  if(!sid||!(S.session&&S.session.workspace)){
+    showToast(t('terminal_no_workspace_title'),2600,'warning');
+    syncTerminalButton();
+    return;
+  }
+  const term=_ensureXterm();
+  if(!term)return;
+  _fitTerminal();
+  const dims=_terminalDimensions();
+  await api('/api/terminal/start',{method:'POST',body:JSON.stringify({
+    session_id:sid,
+    rows:dims.rows,
+    cols:dims.cols,
+    restart:!!restart,
+  })});
+  TERMINAL_UI.sessionId=sid;
+  TERMINAL_UI.workspace=S.session&&S.session.workspace||null;
+  TERMINAL_UI.typedLine='';
+  _connectTerminalOutput();
+  _resizeComposerTerminal();
+}
+
+async function toggleComposerTerminal(force){
+  const next=typeof force==='boolean'?force:!TERMINAL_UI.open;
+  if(next){
+    if(TERMINAL_UI.open){
+      if(TERMINAL_UI.collapsed)expandComposerTerminal();
+      else focusComposerTerminalInput();
+      return;
+    }
+    const {panel,inner}= _terminalEls();
+    const messages=_terminalMessagesEl();
+    if(!panel)return;
+    clearTimeout(TERMINAL_UI.closeTimer);
+    _initTerminalResizeHandle();
+    _resetTerminalHeightForViewport();
+    if(messages)messages.classList.add('terminal-expanding-from-dock');
+    _setTerminalChromeState('expanded');
+    TERMINAL_UI.open=true;
+    TERMINAL_UI.collapsed=false;
+    _syncTerminalTranscriptSpace(true,{immediate:true});
+    if(messages)void messages.offsetHeight;
+    requestAnimationFrame(()=>{
+      panel.classList.add('is-open');
+      window.setTimeout(_fitTerminal,80);
+      setTimeout(()=>{
+        if(messages)messages.classList.remove('terminal-expanding-from-dock');
+      },120);
+    });
+    syncTerminalButton();
+    if(!TERMINAL_UI.resizeObserver&&window.ResizeObserver){
+      TERMINAL_UI.resizeObserver=new ResizeObserver(()=>_fitTerminal());
+      TERMINAL_UI.resizeObserver.observe(inner||panel);
+    }
+    try{
+      await _startComposerTerminal(false);
+      focusComposerTerminalInput();
+    }catch(e){
+      showToast(t('terminal_start_failed')+e.message,3200,'error');
+    }
+  }else{
+    await closeComposerTerminal();
+  }
+}
+
+function collapseComposerTerminal(){
+  if(!TERMINAL_UI.open||TERMINAL_UI.collapsed)return;
+  TERMINAL_UI.collapsed=true;
+  _setTerminalChromeState('collapsed');
+  _syncTerminalTranscriptSpace('collapsed');
+  syncTerminalButton();
+}
+
+function expandComposerTerminal(){
+  if(!TERMINAL_UI.open)return;
+  const {panel}= _terminalEls();
+  const messages=_terminalMessagesEl();
+  TERMINAL_UI.collapsed=false;
+  clearTimeout(TERMINAL_UI.closeTimer);
+  if(panel)panel.classList.add('is-expanding-from-dock');
+  if(messages)messages.classList.add('terminal-expanding-from-dock');
+  _syncTerminalTranscriptSpace(true,{immediate:true});
+  if(messages)void messages.offsetHeight;
+  _setTerminalChromeState('expanded');
+  _resetTerminalHeightForViewport();
+  requestAnimationFrame(()=>{
+    _fitTerminal();
+    focusComposerTerminalInput();
+    setTimeout(()=>{
+      if(panel)panel.classList.remove('is-expanding-from-dock');
+      if(messages)messages.classList.remove('terminal-expanding-from-dock');
+    },120);
+  });
+  syncTerminalButton();
+}
+
+function _disposeXterm(){
+  if(TERMINAL_UI.term){
+    try{TERMINAL_UI.term.dispose();}catch(_){}
+  }
+  TERMINAL_UI.term=null;
+  TERMINAL_UI.fitAddon=null;
+  TERMINAL_UI.typedLine='';
+  const {surface}= _terminalEls();
+  if(surface)surface.textContent='';
+}
+
+async function closeComposerTerminal(sessionId,opts){
+  opts=opts||{};
+  const sid=sessionId||TERMINAL_UI.sessionId||_terminalSessionId();
+  if(TERMINAL_UI.source){
+    try{TERMINAL_UI.source.close();}catch(_){}
+    TERMINAL_UI.source=null;
+  }
+  if(sid&&!opts.skipApi){
+    api('/api/terminal/close',{method:'POST',body:JSON.stringify({session_id:sid})}).catch(()=>{});
+  }
+  const {panel}= _terminalEls();
+  if(panel){
+    panel.classList.remove('is-open','is-collapsed','is-expanding-from-dock');
+    _syncTerminalTranscriptSpace(false);
+    clearTimeout(TERMINAL_UI.closeTimer);
+    TERMINAL_UI.closeTimer=setTimeout(()=>{
+      if(!TERMINAL_UI.open)panel.hidden=true;
+      _disposeXterm();
+    },280);
+  }else{
+    _syncTerminalTranscriptSpace(false);
+    _disposeXterm();
+  }
+  TERMINAL_UI.open=false;
+  TERMINAL_UI.collapsed=false;
+  const composerWrap=$('composerWrap');
+  if(composerWrap)composerWrap.classList.remove('terminal-dock-visible');
+  TERMINAL_UI.sessionId=null;
+  TERMINAL_UI.workspace=null;
+  syncTerminalButton();
+}
+
+async function restartComposerTerminal(){
+  if(!TERMINAL_UI.open||TERMINAL_UI.collapsed)return;
+  if(TERMINAL_UI.source){
+    try{TERMINAL_UI.source.close();}catch(_){}
+    TERMINAL_UI.source=null;
+  }
+  if(TERMINAL_UI.term)TERMINAL_UI.term.reset();
+  try{await _startComposerTerminal(true);}
+  catch(e){showToast(t('terminal_start_failed')+e.message,3200,'error');}
+}
+
+function clearComposerTerminal(){
+  if(TERMINAL_UI.term)TERMINAL_UI.term.clear();
+}
+
+function _terminalBufferText(){
+  const term=TERMINAL_UI.term;
+  if(!term||!term.buffer)return '';
+  const buffer=term.buffer.active;
+  const lines=[];
+  for(let i=0;i<buffer.length;i++){
+    const line=buffer.getLine(i);
+    if(line)lines.push(line.translateToString(true));
+  }
+  return lines.join('\n').trim();
+}
+
+async function copyComposerTerminalOutput(){
+  try{
+    const selection=TERMINAL_UI.term&&TERMINAL_UI.term.getSelection?TERMINAL_UI.term.getSelection():'';
+    await navigator.clipboard.writeText(selection||_terminalBufferText());
+    showToast(t('copied'));
+  }catch(e){
+    showToast(t('terminal_copy_failed')+e.message,2600,'error');
+  }
+}
+
+async function submitComposerTerminalInput(ev){
+  if(ev)ev.preventDefault();
+}
+
+function _scheduleTerminalResize(){
+  clearTimeout(TERMINAL_UI.resizeTimer);
+  TERMINAL_UI.resizeTimer=setTimeout(_resizeComposerTerminal,120);
+}
+
+async function _resizeComposerTerminal(){
+  if(!TERMINAL_UI.open||TERMINAL_UI.collapsed)return;
+  const sid=TERMINAL_UI.sessionId||_terminalSessionId();
+  if(!sid)return;
+  const dims=_terminalDimensions();
+  try{
+    await api('/api/terminal/resize',{method:'POST',body:JSON.stringify({
+      session_id:sid,
+      rows:dims.rows,
+      cols:dims.cols,
+    })});
+  }catch(_){}
+}
+
+window.addEventListener('beforeunload',()=>{
+  if(TERMINAL_UI.source)try{TERMINAL_UI.source.close();}catch(_){}
+  if(TERMINAL_UI.sessionId){
+    const url=new URL('api/terminal/close',document.baseURI||location.href).href;
+    const body=JSON.stringify({session_id:TERMINAL_UI.sessionId});
+    try{
+      navigator.sendBeacon(url,new Blob([body],{type:'application/json'}));
+    }catch(_){
+      try{fetch(url,{method:'POST',credentials:'include',headers:{'Content-Type':'application/json'},body,keepalive:true});}catch(__){}
+    }
+  }
+});
+
+window.addEventListener('resize',()=>{
+  if(!TERMINAL_UI.open)return;
+  if(TERMINAL_UI.collapsed){
+    _syncTerminalTranscriptSpace('collapsed');
+    return;
+  }
+  _resetTerminalHeightForViewport();
+});
+
+if(window.MutationObserver){
+  new MutationObserver(syncComposerTerminalTheme).observe(document.documentElement,{
+    attributes:true,
+    attributeFilter:['class','data-skin'],
+  });
+}

static/vendor/smd.min.js

@@ -0,0 +1,29 @@
+var D=2,C=3,h=4,b=5,B=6,U=7,G=8,S=9,x=10,m=11,H=12,K=13,M=14,Q=15,w=16,q=17,W=18,P=19,Y=20,y=21,F=22,$=23,v=24,X=25,j=26,z=27,J=28,V=29,Z=30,p=31;var I=1,k=2,L=4,T=8,f=16;function ee(e){switch(e){case I:return"href";case k:return"src";case L:return"class";case T:return"checked";case f:return"start"}}var ne=e=>{switch(e){case 1:return 3;case 2:return 4;case 3:return 5;case 4:return 6;case 5:return 7;default:return 8}},te=ne;var O=24;function ae(e){let c=new Uint32Array(O);return c[0]=1,{renderer:e,text:"",pending:"",tokens:c,len:0,token:1,fence_end:0,blockquote_idx:0,hr_char:"",hr_chars:0,fence_start:0,spaces:new Uint8Array(O),indent:"",indent_len:0,table_state:0}}function ce(e){e.pending.length>0&&o(e,`
+`)}function a(e){e.text.length!==0&&(e.renderer.add_text(e.renderer.data,e.text),e.text="")}function _(e){e.len-=1,e.token=e.tokens[e.len],e.renderer.end_token(e.renderer.data)}function i(e,c){(e.tokens[e.len]===24||e.tokens[e.len]===23)&&c!==25&&_(e),e.len+=1,e.tokens[e.len]=c,e.token=c,e.renderer.add_token(e.renderer.data,c)}function re(e,c,n){for(;n<=e.len;){if(e.tokens[n]===c)return n;n+=1}return-1}function l(e,c){for(e.fence_start=0;e.len>c;)_(e)}function u(e,c){let n=0;for(let t=0;t<=e.len&&(c-=e.spaces[t],!(c<0));t+=1)switch(e.tokens[t]){case 9:case 10:case 20:case 25:n=t;break}for(;e.len>n;)_(e);return c}function A(e,c){let n=-1,t=-1;for(let s=e.blockquote_idx+1;s<=e.len;s+=1)if(e.tokens[s]===25){if(e.indent_len<e.spaces[s]){t=-1;break}t=s}else e.tokens[s]===c&&(n=s);return t===-1?n===-1?(l(e,e.blockquote_idx),i(e,c),!0):(l(e,n),!1):(l(e,t),i(e,c),!0)}function g(e,c){i(e,25),e.spaces[e.len]=e.indent_len+c,E(e),e.token=103}function E(e){e.indent="",e.indent_len=0,e.pending=""}function N(e){switch(e){case 48:case 49:case 50:case 51:case 52:case 53:case 54:case 55:case 56:case 57:return!0;default:return!1}}function ie(e){switch(e){case 32:case 58:case 59:case 41:case 44:case 33:case 46:case 63:case 93:case 10:return!0;default:return!1}}function se(e){return N(e)||ie(e)}function o(e,c){for(let n of c){if(e.token===101){switch(n){case" ":e.indent_len+=1;continue;case"	":e.indent_len+=4;continue}let s=u(e,e.indent_len);e.indent_len=0,e.token=e.tokens[e.len],s>0&&o(e," ".repeat(s))}let t=e.pending+n;switch(e.token){case 21:case 1:case 20:case 24:case 23:switch(e.pending[0]){case void 0:e.pending=n;continue;case" ":e.pending=n,e.indent+=" ",e.indent_len+=1;continue;case"	":e.pending=n,e.indent+="	",e.indent_len+=4;continue;case`
+`:if(e.tokens[e.len]===25&&e.token===21){_(e),E(e),e.pending=n;continue}l(e,e.blockquote_idx),E(e),e.blockquote_idx=0,e.fence_start=0,e.pending=n;continue;case"#":switch(n){case"#":if(e.pending.length<6){e.pending=t;continue}break;case" ":u(e,e.indent_len),i(e,te(e.pending.length)),E(e);continue}break;case">":{let r=re(e,20,e.blockquote_idx+1);r===-1?(l(e,e.blockquote_idx),e.blockquote_idx+=1,e.fence_start=0,i(e,20)):e.blockquote_idx=r,E(e),e.pending=n;continue}case"-":case"*":case"_":if(e.hr_chars===0&&(e.hr_chars=1,e.hr_char=e.pending),e.hr_chars>0){switch(n){case e.hr_char:e.hr_chars+=1,e.pending=t;continue;case" ":e.pending=t;continue;case`
+`:if(e.hr_chars<3)break;u(e,e.indent_len),e.renderer.add_token(e.renderer.data,22),e.renderer.end_token(e.renderer.data),E(e),e.hr_chars=0;continue}e.hr_chars=0}if(e.pending[0]!=="_"&&e.pending[1]===" "){A(e,23),g(e,2),o(e,t.slice(2));continue}break;case"`":if(e.pending.length<3){if(n==="`"){e.pending=t,e.fence_start=t.length;continue}e.fence_start=0;break}switch(n){case"`":e.pending.length===e.fence_start?(e.pending=t,e.fence_start=t.length):(i(e,2),E(e),e.fence_start=0,o(e,t));continue;case`
+`:{u(e,e.indent_len),i(e,10),e.pending.length>e.fence_start&&e.renderer.set_attr(e.renderer.data,L,e.pending.slice(e.fence_start)),E(e),e.token=101;continue}default:e.pending=t;continue}case"+":if(n!==" ")break;A(e,23),g(e,2);continue;case"0":case"1":case"2":case"3":case"4":case"5":case"6":case"7":case"8":case"9":if(e.pending[e.pending.length-1]==="."){if(n!==" ")break;A(e,24)&&e.pending!=="1."&&e.renderer.set_attr(e.renderer.data,f,e.pending.slice(0,-1)),g(e,e.pending.length+1);continue}else{let r=n.charCodeAt(0);if(r===46||N(r)){e.pending=t;continue}}break;case"|":l(e,e.blockquote_idx),i(e,27),i(e,28),e.pending="",o(e,n);continue}let s=t;if(e.token===21)e.token=e.tokens[e.len],e.renderer.add_token(e.renderer.data,21),e.renderer.end_token(e.renderer.data);else if(e.indent_len>=4){let r=0;for(;r<4;r+=1)if(e.indent[r]==="	"){r=r+1;break}s=e.indent.slice(r)+t,i(e,9)}else i(e,2);E(e),o(e,s);continue;case 27:if(e.table_state===1)switch(n){case"-":case" ":case"|":case":":e.pending=t;continue;case`
+`:e.table_state=2,e.pending="";continue;default:_(e),e.table_state=0;break}else switch(e.pending){case"|":i(e,28),e.pending="",o(e,n);continue;case`
+`:_(e),e.pending="",e.table_state=0,o(e,n);continue}break;case 28:switch(e.pending){case"":break;case"|":i(e,29),_(e),e.pending="",o(e,n);continue;case`
+`:_(e),e.table_state=Math.min(e.table_state+1,2),e.pending="",o(e,n);continue;default:i(e,29),o(e,n);continue}break;case 29:if(e.pending==="|"){a(e),_(e),e.pending="",o(e,n);continue}break;case 9:switch(t){case`
+    `:case`
+   	`:case`
+  	`:case`
+ 	`:case`
+	`:e.text+=`
+`,e.pending="";continue;case`
+`:case`
+ `:case`
+  `:case`
+   `:e.pending=t;continue;default:e.pending.length!==0?(a(e),_(e),e.pending=n):e.text+=n;continue}case 10:switch(n){case"`":e.pending=t;continue;case`
+`:if(t.length===e.fence_start+e.fence_end+1){a(e),_(e),e.pending="",e.fence_start=0,e.fence_end=0,e.token=101;continue}e.token=101;break;case" ":if(e.pending[0]===`
+`){e.pending=t,e.fence_end+=1;continue}break}e.text+=e.pending,e.pending=n,e.fence_end=1;continue;case 11:switch(n){case"`":t.length===e.fence_start+ +(e.pending[0]===" ")?(a(e),_(e),e.pending="",e.fence_start=0):e.pending=t;continue;case`
+`:e.text+=e.pending,e.pending="",e.token=21,e.blockquote_idx=0,a(e);continue;case" ":e.text+=e.pending,e.pending=n;continue;default:e.text+=t,e.pending="";continue}case 103:switch(e.pending.length){case 0:if(n!=="[")break;e.pending=t;continue;case 1:if(n!==" "&&n!=="x")break;e.pending=t;continue;case 2:if(n!=="]")break;e.pending=t;continue;case 3:if(n!==" ")break;e.renderer.add_token(e.renderer.data,26),e.pending[1]==="x"&&e.renderer.set_attr(e.renderer.data,T,""),e.renderer.end_token(e.renderer.data),e.pending=" ";continue}e.token=e.tokens[e.len],e.pending="",o(e,t);continue;case 14:case 15:{let r="*",d=12;if(e.token===15&&(r="_",d=13),r===e.pending){if(a(e),r===n){_(e),e.pending="";continue}i(e,d),e.pending=n;continue}break}case 12:case 13:{let r="*",d=14;switch(e.token===13&&(r="_",d=15),e.pending){case r:r===n?e.tokens[e.len-1]===d?e.pending=t:(a(e),i(e,d),e.pending=""):(a(e),_(e),e.pending=n);continue;case r+r:let R=e.token;a(e),_(e),_(e),r!==n?(i(e,R),e.pending=n):e.pending="";continue}break}case 16:if(t==="~~"){a(e),_(e),e.pending="";continue}break;case 105:n===`
+`?(a(e),i(e,30),e.pending=""):(e.token=e.tokens[e.len],e.pending[0]==="\\"?e.text+="[":e.text+="$$",e.pending="",o(e,n));continue;case 30:if(t==="\\]"||t==="$$"){a(e),_(e),e.pending="";continue}break;case 31:if(t==="\\)"||e.pending[0]==="$"){a(e),_(e),n===")"?e.pending="":e.pending=n;continue}break;case 102:t==="http://"||t==="https://"?(a(e),i(e,18),e.pending=t,e.text=t):"http:/"[e.pending.length]===n||"https:/"[e.pending.length]===n?e.pending=t:(e.token=e.tokens[e.len],o(e,n));continue;case 17:case 19:if(e.pending==="]"){a(e),n==="("?e.pending=t:(_(e),e.pending=n);continue}if(e.pending[0]==="]"&&e.pending[1]==="("){if(n===")"){let r=e.token===17?I:k,d=e.pending.slice(2);e.renderer.set_attr(e.renderer.data,r,d),_(e),e.pending=""}else e.pending+=n;continue}break;case 18:n===" "||n===`
+`||n==="\\"?(e.renderer.set_attr(e.renderer.data,I,e.pending),a(e),_(e),e.pending=n):(e.text+=n,e.pending=t);continue;case 104:if(t.startsWith("<br")){if(t.length===3||n===" "||n==="/"&&(t.length===4||e.pending[e.pending.length-1]===" ")){e.pending=t;continue}if(n===">"){a(e),e.token=e.tokens[e.len],e.renderer.add_token(e.renderer.data,21),e.renderer.end_token(e.renderer.data),e.pending="";continue}}e.token=e.tokens[e.len],e.text+="<",e.pending=e.pending.slice(1),o(e,n);continue}switch(e.pending[0]){case"\\":if(e.token===19||e.token===30||e.token===31)break;switch(n){case"(":a(e),i(e,31),e.pending="";continue;case"[":e.token=105,e.pending=t;continue;case`
+`:e.pending=n;continue;default:let s=n.charCodeAt(0);e.pending="",e.text+=N(s)||s>=65&&s<=90||s>=97&&s<=122?t:n;continue}case`
+`:switch(e.token){case 19:case 30:case 31:break;case 3:case 4:case 5:case 6:case 7:case 8:a(e),l(e,e.blockquote_idx),e.blockquote_idx=0,e.pending=n;continue;default:a(e),e.pending=n,e.token=21,e.blockquote_idx=0;continue}break;case"<":if(e.token!==19&&e.token!==30&&e.token!==31){a(e),e.pending=t,e.token=104;continue}break;case"`":if(e.token===19)break;n==="`"?(e.fence_start+=1,e.pending=t):(e.fence_start+=1,a(e),i(e,11),e.text=n===" "||n===`
+`?"":n,e.pending="");continue;case"_":case"*":{if(e.token===19||e.token===30||e.token===31||e.token===14)break;let s=12,r=14,d=e.pending[0];if(d==="_"&&(s=13,r=15),e.pending.length===1){if(d===n){e.pending=t;continue}if(n!==" "&&n!==`
+`){a(e),i(e,s),e.pending=n;continue}}else{if(d===n){a(e),i(e,r),i(e,s),e.pending="";continue}if(n!==" "&&n!==`
+`){a(e),i(e,r),e.pending=n;continue}}break}case"~":if(e.token!==19&&e.token!==16){if(e.pending==="~"){if(n==="~"){e.pending=t;continue}}else if(n!==" "&&n!==`
+`){a(e),i(e,16),e.pending=n;continue}}break;case"$":if(e.token!==19&&e.token!==16&&e.pending==="$")if(n==="$"){e.token=105,e.pending=t;continue}else{if(se(n.charCodeAt(0)))break;a(e),i(e,31),e.pending=n;continue}break;case"[":if(e.token!==19&&e.token!==17&&e.token!==30&&e.token!==31&&n!=="]"){a(e),i(e,17),e.pending=n;continue}break;case"!":if(e.token!==19&&n==="["){a(e),i(e,19),e.pending="";continue}break;case" ":if(e.pending.length===1&&n===" ")continue;break}if(e.token!==19&&e.token!==17&&e.token!==30&&e.token!==31&&n==="h"&&(e.pending===" "||e.pending==="")){e.text+=e.pending,e.pending=n,e.token=102;continue}e.text+=e.pending,e.pending=n}a(e)}function _e(e){return{add_token:oe,end_token:de,add_text:Ee,set_attr:le,data:{nodes:[e,,,,,],index:0}}}function oe(e,c){let n=e.nodes[e.index],t;switch(c){case 1:return;case 20:t=document.createElement("blockquote");break;case 2:t=document.createElement("p");break;case 21:t=document.createElement("br");break;case 22:t=document.createElement("hr");break;case 3:t=document.createElement("h1");break;case 4:t=document.createElement("h2");break;case 5:t=document.createElement("h3");break;case 6:t=document.createElement("h4");break;case 7:t=document.createElement("h5");break;case 8:t=document.createElement("h6");break;case 12:case 13:t=document.createElement("em");break;case 14:case 15:t=document.createElement("strong");break;case 16:t=document.createElement("s");break;case 11:t=document.createElement("code");break;case 18:case 17:t=document.createElement("a");break;case 19:t=document.createElement("img");break;case 23:t=document.createElement("ul");break;case 24:t=document.createElement("ol");break;case 25:t=document.createElement("li");break;case 26:let s=t=document.createElement("input");s.type="checkbox",s.disabled=!0;break;case 9:case 10:n=n.appendChild(document.createElement("pre")),t=document.createElement("code");break;case 27:t=document.createElement("table");break;case 28:switch(n.children.length){case 0:n=n.appendChild(document.createElement("thead"));break;case 1:n=n.appendChild(document.createElement("tbody"));break;default:n=n.children[1]}t=document.createElement("tr");break;case 29:t=document.createElement(n.parentElement?.tagName==="THEAD"?"th":"td");break;case 30:t=document.createElement("equation-block");break;case 31:t=document.createElement("equation-inline");break}e.nodes[++e.index]=n.appendChild(t)}function de(e){e.index-=1}function Ee(e,c){e.nodes[e.index].appendChild(document.createTextNode(c))}function le(e,c,n){e.nodes[e.index].setAttribute(ee(c),n)}export{Y as BLOCKQUOTE,j as CHECKBOX,T as CHECKED,S as CODE_BLOCK,x as CODE_FENCE,m as CODE_INLINE,Z as EQUATION_BLOCK,p as EQUATION_INLINE,C as HEADING_1,h as HEADING_2,b as HEADING_3,B as HEADING_4,U as HEADING_5,G as HEADING_6,I as HREF,P as IMAGE,H as ITALIC_AST,K as ITALIC_UND,L as LANG,y as LINE_BREAK,q as LINK,X as LIST_ITEM,v as LIST_ORDERED,$ as LIST_UNORDERED,D as PARAGRAPH,W as RAW_URL,F as RULE,k as SRC,f as START,w as STRIKE,M as STRONG_AST,Q as STRONG_UND,z as TABLE,V as TABLE_CELL,J as TABLE_ROW,_e as default_renderer,ae as parser,ce as parser_end,o as parser_write};

static/workspace.js

@@ -1,15 +1,43 @@
 async function api(path,opts={}){
-  const url=new URL(path,location.origin);
-  const res=await fetch(url.href,{credentials:'include',headers:{'Content-Type':'application/json'},...opts});
-  if(!res.ok){
-    const text=await res.text();
-    // Parse JSON error body and surface the human-readable message,
-    // rather than showing raw JSON like {"error":"Profile 'x' does not exist."}
-    try{const j=JSON.parse(text);throw new Error(j.error||j.message||text);}
-    catch(e){if(e instanceof SyntaxError)throw new Error(text);throw e;}
+  // Strip leading slash so URL resolves relative to location.href (supports subpath mounts)
+  const rel = path.startsWith('/') ? path.slice(1) : path;
+  const url=new URL(rel,document.baseURI||location.href);
+  // Retry up to 2 times on network errors (e.g. stale keep-alive after long idle).
+  // Server errors (4xx/5xx) are NOT retried — only connection failures.
+  let lastErr;
+  for(let attempt=0;attempt<3;attempt++){
+    try{
+      const res=await fetch(url.href,{credentials:'include',headers:{'Content-Type':'application/json'},...opts});
+      if(!res.ok){
+        // 401 means the auth session expired. Redirect to /login so the user can
+        // re-authenticate. This is especially important for iOS PWA (standalone mode)
+        // where a server-side 302 → /login opens in Safari instead of within the PWA.
+        if(res.status===401){window.location.href='/login?next='+encodeURIComponent(window.location.pathname+window.location.search);return;}
+        const text=await res.text();
+        // Parse JSON error body and surface the human-readable message,
+        // rather than showing raw JSON like {"error":"Profile 'x' does not exist."}
+        let message=text;
+        try{const j=JSON.parse(text);message=j.error||j.message||text;}catch(e){}
+        // Attach the raw HTTP context so callers can branch on status (404 stale-session
+        // cleanup, 401 redirect, 503 retry, etc.) without re-parsing the message string.
+        const err=new Error(message);
+        err.status=res.status;
+        err.statusText=res.statusText;
+        err.body=text;
+        throw err;
+      }
+      const ct=res.headers.get('content-type')||'';
+      return ct.includes('application/json')?res.json():res.text();
+    }catch(e){
+      lastErr=e;
+      // Only retry on network errors (TypeError from fetch), not on HTTP errors
+      // that were already thrown above. Re-throw 401 redirects immediately.
+      if(e.message&&/401/.test(e.message)) throw e;
+      if(attempt<2 && e instanceof TypeError) continue;
+      throw e;
+    }
   }
-  const ct=res.headers.get('content-type')||'';
-  return ct.includes('application/json')?res.json():res.text();
+  throw lastErr;
 }
 
 // Persist/restore expanded directory state per workspace in localStorage
@@ -41,20 +69,23 @@ async function loadDir(path){
     const data=await api(`/api/list?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}`);
     S.entries=data.entries||[];renderBreadcrumb();renderFileTree();
     // Pre-fetch contents of restored expanded dirs so they render without a second click
+    // (parallelized — avoids serial waterfall when multiple dirs are expanded)
     if(!path||path==='.'){
-      for(const dirPath of (S._expandedDirs||[])){
-        if(!S._dirCache[dirPath]){
-          try{
-            const dc=await api(`/api/list?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(dirPath)}`);
-            S._dirCache[dirPath]=dc.entries||[];
-          }catch(e2){S._dirCache[dirPath]=[];}
-        }
+      const expanded=S._expandedDirs||new Set();
+      const pending=[...expanded].filter(dirPath=>!S._dirCache[dirPath]);
+      if(pending.length){
+        const results=await Promise.all(pending.map(dirPath=>
+          api(`/api/list?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(dirPath)}`)
+            .then(dc=>({dirPath,entries:dc.entries||[]}))
+            .catch(()=>({dirPath,entries:[]}))
+        ));
+        for(const {dirPath,entries} of results) S._dirCache[dirPath]=entries;
       }
-      if(S._expandedDirs&&S._expandedDirs.size>0)renderFileTree();
+      if(expanded.size>0)renderFileTree();
     }
     if(typeof clearPreview==='function'){
       if(typeof _previewDirty!=='undefined'&&_previewDirty){
-        if(confirm('You have unsaved changes in the preview. Discard and navigate?'))clearPreview();
+        showConfirmDialog({title:t('unsaved_confirm'),message:'',confirmLabel:'Discard',danger:true,focusCancel:true}).then(ok=>{if(ok)clearPreview();});
       }else{
         clearPreview();
       }
@@ -95,11 +126,14 @@ function navigateUp(){
 // File extension sets for preview routing (must match server-side sets)
 const IMAGE_EXTS  = new Set(['.png','.jpg','.jpeg','.gif','.svg','.webp','.ico','.bmp']);
 const MD_EXTS     = new Set(['.md','.markdown','.mdown']);
+const HTML_EXTS   = new Set(['.html','.htm']);
+const PDF_EXTS    = new Set(['.pdf']);
+const AUDIO_EXTS  = new Set(['.mp3','.wav','.m4a','.aac','.ogg','.oga','.opus','.flac']);
+const VIDEO_EXTS  = new Set(['.mp4','.mov','.m4v','.webm','.ogv','.avi','.mkv']);
 // Binary formats that should download rather than preview
 const DOWNLOAD_EXTS = new Set([
   '.docx','.doc','.xlsx','.xls','.pptx','.ppt','.odt','.ods','.odp',
-  '.pdf','.zip','.tar','.gz','.bz2','.7z','.rar',
-  '.mp3','.mp4','.wav','.m4a','.ogg','.flac','.mov','.avi','.mkv','.webm',
+  '.zip','.tar','.gz','.bz2','.7z','.rar',
   '.exe','.dmg','.pkg','.deb','.rpm',
   '.woff','.woff2','.ttf','.otf','.eot',
   '.bin','.dat','.db','.sqlite','.pyc','.class','.so','.dylib','.dll',
@@ -108,21 +142,27 @@ const DOWNLOAD_EXTS = new Set([
 function fileExt(p){ const i=p.lastIndexOf('.'); return i>=0?p.slice(i).toLowerCase():''; }
 
 let _previewCurrentPath = '';  // relative path of currently previewed file
-let _previewCurrentMode = '';  // 'code' | 'md' | 'image'
+let _previewCurrentMode = '';  // 'code' | 'md' | 'image' | 'html' | 'pdf' | 'audio' | 'video'
 let _previewDirty = false;     // true when edits are unsaved
 
 function showPreview(mode){
-  // mode: 'code' | 'image' | 'md'
+  // mode: 'code' | 'image' | 'md' | 'html' | 'pdf' | 'audio' | 'video'
   $('previewCode').style.display     = mode==='code'  ? '' : 'none';
   $('previewImgWrap').style.display  = mode==='image' ? '' : 'none';
+  const mediaWrap=$('previewMediaWrap'); if(mediaWrap) mediaWrap.style.display = (mode==='audio'||mode==='video') ? '' : 'none';
+  const pdfWrap=$('previewPdfWrap'); if(pdfWrap) pdfWrap.style.display = mode==='pdf' ? '' : 'none';
   $('previewMd').style.display       = mode==='md'    ? '' : 'none';
+  $('previewHtmlWrap').style.display = mode==='html'  ? '' : 'none';
   $('previewEditArea').style.display = 'none';  // start in read-only
   const badge=$('previewBadge');
   badge.className='preview-badge '+mode;
-  badge.textContent = mode==='image'?'image':mode==='md'?'md':fileExt($('previewPathText').textContent)||'text';
+  badge.textContent = mode==='image'?'image':mode==='audio'?'audio':mode==='video'?'video':mode==='pdf'?'pdf':mode==='md'?'md':mode==='html'?'html':fileExt($('previewPathText').textContent)||'text';
   _previewCurrentMode = mode;
   _previewDirty = false;
   updateEditBtn();
+  // Show "Open in browser" button for iframe-backed document previews
+  const openBtn=$('btnOpenInBrowser');
+  if(openBtn) openBtn.style.display = (mode==='html'||mode==='pdf')?'inline-flex':'none';
 }
 
 function updateEditBtn(){
@@ -131,8 +171,8 @@ function updateEditBtn(){
   const editable = _previewCurrentMode==='code'||_previewCurrentMode==='md';
   btn.style.display = editable?'':'none';
   const editing = $('previewEditArea').style.display!=='none';
-  btn.innerHTML = editing ? '&#128190; Save' : '&#9998; Edit';
-  btn.title = editing ? 'Save changes' : 'Edit this file';
+  btn.innerHTML = editing ? `&#128190; ${t('save')}` : `&#9998; ${t('edit')}`;
+  btn.title = editing ? t('save_title') : t('edit_title');
   btn.style.color = editing ? 'var(--blue)' : '';
   if(_previewDirty) btn.innerHTML = '&#128190; Save*';
 }
@@ -150,12 +190,12 @@ async function toggleEditMode(){
       _previewDirty=false;
       // Update read-only views
       if(_previewCurrentMode==='code') $('previewCode').textContent=content;
-      else $('previewMd').innerHTML=renderMd(content);
+      else { $('previewMd').innerHTML=renderMd(content); requestAnimationFrame(()=>{if(typeof renderKatexBlocks==='function')renderKatexBlocks();}); }
       $('previewEditArea').style.display='none';
       if(_previewCurrentMode==='code') $('previewCode').style.display='';
       else $('previewMd').style.display='';
-      showToast('Saved');
-    }catch(e){setStatus('Save failed: '+e.message);}
+      showToast(t('saved'));
+    }catch(e){setStatus(t('save_failed')+e.message);}
   }else{
     // Enter edit mode: populate textarea with current content
     const currentText = _previewCurrentMode==='code'
@@ -200,13 +240,34 @@ async function openFile(path){
   $('fileTree').style.display='none';
 
   _previewCurrentPath = path;
+  renderFileBreadcrumb(path);
   if(IMAGE_EXTS.has(ext)){
     // Image: load via raw endpoint, show as <img>
     showPreview('image');
-    const url=`/api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}`;
+    const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}`;
     $('previewImg').alt=path;
     $('previewImg').src=url;
-    $('previewImg').onerror=()=>setStatus('Could not load image');
+    $('previewImg').onerror=()=>setStatus(t('image_load_failed'));
+  } else if(AUDIO_EXTS.has(ext)||VIDEO_EXTS.has(ext)){
+    const mode=VIDEO_EXTS.has(ext)?'video':'audio';
+    showPreview(mode);
+    const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}&inline=1`;
+    const wrap=$('previewMediaWrap');
+    if(wrap){
+      wrap.innerHTML=(typeof _mediaPlayerHtml==='function')
+        ? _mediaPlayerHtml(mode,url,path.split('/').pop()||path)
+        : `<${mode} src="${url.replace(/"/g,'%22')}" controls preload="metadata"></${mode}>`;
+      if(typeof _applyMediaPlaybackPreferences==='function') _applyMediaPlaybackPreferences(wrap);
+    }
+  } else if(PDF_EXTS.has(ext)){
+    showPreview('pdf');
+    const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}&inline=1`;
+    const frame=$('previewPdfFrame');
+    if(frame){
+      frame.src=''; // clear first to avoid stale content
+      frame.src=url;
+      frame.title=`PDF preview: ${path.split('/').pop()||path}`;
+    }
   } else if(MD_EXTS.has(ext)){
     // Markdown: fetch text, render with renderMd, display as formatted HTML
     try{
@@ -214,7 +275,24 @@ async function openFile(path){
       showPreview('md');
       _previewRawContent = data.content;
       $('previewMd').innerHTML=renderMd(data.content);
-    }catch(e){setStatus('Could not open file');}
+      requestAnimationFrame(()=>{if(typeof renderKatexBlocks==='function')renderKatexBlocks();});
+    }catch(e){setStatus(t('file_open_failed'));}
+  } else if(HTML_EXTS.has(ext)){
+    // HTML: render in sandboxed iframe via raw endpoint.
+    // SECURITY TRADEOFF: We use sandbox="allow-scripts" which lets inline JS run
+    // but prevents access to the parent frame (origin isolation). This is a
+    // deliberate choice — the user is previewing their own workspace files, so
+    // blocking scripts entirely would break most HTML documents. The sandbox
+    // still prevents the preview from navigating the parent, accessing cookies,
+    // or reading other origin data. If a stricter mode is needed, remove
+    // allow-scripts (or add sandbox="") to disable all JS execution.
+    showPreview('html');
+    const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}&inline=1`;
+    const iframe=$('previewHtmlIframe');
+    if(iframe){
+      iframe.src=''; // clear first to avoid stale content
+      iframe.src=url;
+    }
   } else {
     // Plain code / text -- but fall back to download if server signals binary
     try{
@@ -236,12 +314,56 @@ async function openFile(path){
 function downloadFile(path){
   if(!S.session)return;
   // Trigger browser download via the raw file endpoint with content-disposition attachment
-  const url=`/api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}&download=1`;
+  const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(path)}&download=1`;
   const filename=path.split('/').pop();
   const a=document.createElement('a');
   a.href=url;a.download=filename;
   document.body.appendChild(a);a.click();
   setTimeout(()=>document.body.removeChild(a),100);
-  showToast(`Downloading ${filename}\u2026`,2000);
+  showToast(t('downloading',filename),2000);
 }
 
+
+// ── Render breadcrumb for file preview mode ──────────────────────────────────
+function renderFileBreadcrumb(filePath) {
+  const bar = $('breadcrumbBar');
+  if (!bar) return;
+  bar.style.display = 'flex';
+  const upBtn = $('btnUpDir');
+  if (upBtn) upBtn.style.display = '';
+
+  bar.innerHTML = '';
+  // Root
+  const root = document.createElement('span');
+  root.className = 'breadcrumb-seg breadcrumb-link';
+  root.textContent = '~';
+  root.onclick = () => { clearPreview(); loadDir('.'); };
+  bar.appendChild(root);
+
+  const parts = filePath.split('/');
+  let accumulated = '';
+  for (let i = 0; i < parts.length; i++) {
+    const sep = document.createElement('span');
+    sep.className = 'breadcrumb-sep';
+    sep.textContent = '/';
+    bar.appendChild(sep);
+
+    accumulated += (accumulated ? '/' : '') + parts[i];
+    const seg = document.createElement('span');
+    seg.textContent = parts[i];
+    if (i < parts.length - 1) {
+      seg.className = 'breadcrumb-seg breadcrumb-link';
+      const target = accumulated;
+      seg.onclick = () => { clearPreview(); loadDir(target); };
+    } else {
+      seg.className = 'breadcrumb-seg breadcrumb-current';
+    }
+    bar.appendChild(seg);
+  }
+}
+
+function openInBrowser(){
+  if(!_previewCurrentPath||!S.session) return;
+  const url=`api/file/raw?session_id=${encodeURIComponent(S.session.session_id)}&path=${encodeURIComponent(_previewCurrentPath)}`;
+  window.open(url,'_blank');
+}

tests/_pytest_port.py

@@ -0,0 +1,46 @@
+"""
+Shared test server constants for use in individual test files.
+
+Instead of hardcoding ``BASE = "http://127.0.0.1:8788"`` in every test file,
+import from here so the port and state dir are always consistent with
+what conftest.py computed for this worktree.
+
+Usage::
+
+    from tests._pytest_port import BASE
+
+conftest.py publishes ``HERMES_WEBUI_TEST_PORT`` and
+``HERMES_WEBUI_TEST_STATE_DIR`` to ``os.environ`` at module level
+(before any test file is imported), so this module always reads the
+correct values.  The auto-derivation fallback matches conftest's logic
+exactly, so standalone imports also work correctly.
+"""
+import hashlib
+import os
+import pathlib
+
+def _auto_test_port(repo_root: pathlib.Path) -> int:
+    h = int(hashlib.md5(str(repo_root).encode()).hexdigest(), 16)
+    return 20000 + (h % 10000)
+
+def _auto_state_dir_name(repo_root: pathlib.Path) -> str:
+    h = hashlib.md5(str(repo_root).encode()).hexdigest()[:8]
+    return f"webui-test-{h}"
+
+_TESTS_DIR   = pathlib.Path(__file__).parent.resolve()
+_REPO_ROOT   = _TESTS_DIR.parent.resolve()
+_HERMES_HOME = pathlib.Path(os.getenv('HERMES_HOME',
+                             str(pathlib.Path.home() / '.hermes')))
+
+TEST_PORT = int(os.environ.get('HERMES_WEBUI_TEST_PORT',
+                               str(_auto_test_port(_REPO_ROOT))))
+BASE = f"http://127.0.0.1:{TEST_PORT}"
+
+TEST_STATE_DIR = pathlib.Path(os.environ.get(
+    'HERMES_WEBUI_TEST_STATE_DIR',
+    str(_HERMES_HOME / _auto_state_dir_name(_REPO_ROOT))
+))
+
+# Default model injected by conftest — tests that mutate the default model
+# must restore to this value so later tests see a consistent baseline.
+TEST_DEFAULT_MODEL = os.environ.get('HERMES_WEBUI_DEFAULT_MODEL', 'openai/gpt-5.4-mini')

tests/conftest.py

@@ -31,14 +31,45 @@ HOME       = pathlib.Path.home()
 HERMES_HOME = pathlib.Path(os.getenv('HERMES_HOME', str(HOME / '.hermes')))
 
 # ── Test server config ────────────────────────────────────────────────────
-TEST_PORT      = int(os.getenv('HERMES_WEBUI_TEST_PORT', '8788'))
+# Port and state dir auto-derive from the repo path when no env var is set,
+# giving every worktree its own isolated port (8800-8899) and state directory.
+# Override with HERMES_WEBUI_TEST_PORT / HERMES_WEBUI_TEST_STATE_DIR to pin.
+
+def _auto_test_port(repo_root) -> int:
+    """Map repo path to a unique port in 20000-29999 (10k range = near-zero collisions).
+    Far from system port ranges and Linux ephemeral ports (32768+).
+    Override with HERMES_WEBUI_TEST_PORT to use a specific port."""
+    import hashlib
+    h = int(hashlib.md5(str(repo_root).encode()).hexdigest(), 16)
+    return 20000 + (h % 10000)
+
+def _auto_state_dir_name(repo_root) -> str:
+    import hashlib
+    h = hashlib.md5(str(repo_root).encode()).hexdigest()[:8]
+    return f"webui-test-{h}"
+
+TEST_PORT      = int(os.getenv('HERMES_WEBUI_TEST_PORT',
+                               str(_auto_test_port(REPO_ROOT))))
 TEST_BASE      = f"http://127.0.0.1:{TEST_PORT}"
 TEST_STATE_DIR = pathlib.Path(os.getenv(
     'HERMES_WEBUI_TEST_STATE_DIR',
-    str(HERMES_HOME / 'webui-mvp-test')
+    str(HERMES_HOME / _auto_state_dir_name(REPO_ROOT))
 ))
 TEST_WORKSPACE = TEST_STATE_DIR / 'test-workspace'
 
+# Publish at module level so api.config, _pytest_port.py, and any test module
+# importing stateful API code during collection see the isolated test paths.
+#
+# Direct assignment is intentional for production-risk paths: tests that import
+# api.config/api.models in the pytest process must never inherit the real
+# ~/.hermes state tree before the server subprocess fixture starts.
+os.environ['HERMES_WEBUI_TEST_PORT'] = str(TEST_PORT)
+os.environ['HERMES_WEBUI_TEST_STATE_DIR'] = str(TEST_STATE_DIR)
+os.environ['HERMES_WEBUI_STATE_DIR'] = str(TEST_STATE_DIR)
+os.environ['HERMES_WEBUI_DEFAULT_WORKSPACE'] = str(TEST_WORKSPACE)
+os.environ['HERMES_HOME'] = str(TEST_STATE_DIR)
+os.environ['HERMES_BASE_HOME'] = str(TEST_STATE_DIR)
+
 # ── Server script: always relative to repo root ───────────────────────────
 SERVER_SCRIPT = REPO_ROOT / 'server.py'
 if not SERVER_SCRIPT.exists():
@@ -153,6 +184,8 @@ def pytest_collection_modifyitems(config, items):
         # Agent backend (need running AIAgent)
         'test_chat_stream_opens_successfully',
         'test_approval_submit_and_respond',
+        # Security redaction (flaky — session state varies across test ordering)
+        'test_api_sessions_list_redacts_titles',
         # Workspace path (macOS /tmp -> /private/tmp symlink)
         'test_new_session_inherits_workspace',
         'test_workspace_add_valid',
@@ -170,7 +203,7 @@ def pytest_collection_modifyitems(config, items):
             skipped += 1
 
     if skipped:
-        print(f"\n⚠️  hermes-agent not found — {skipped} agent-dependent tests will be skipped\n")
+        print(f"\nWARNING: hermes-agent not found; {skipped} agent-dependent tests will be skipped\n")
 
 
 # ── Helpers ──────────────────────────────────────────────────────────────────
@@ -210,6 +243,18 @@ def test_server():
     Start an isolated test server on TEST_PORT with a clean state directory.
     Paths are discovered dynamically -- no hardcoded absolute path assumptions.
     """
+    # Kill any leftover process on the test port before starting.
+    # Stale servers from QA harness runs or prior test sessions cause
+    # conftest to think the server is already up, producing false failures.
+    try:
+        import subprocess as _sp
+        _sp.run(['fuser', '-k', f'{TEST_PORT}/tcp'],
+                capture_output=True, timeout=5)
+    except Exception:
+        pass
+    import time as _time
+    _time.sleep(0.5)  # brief pause to let the port release
+
     # Clean slate
     if TEST_STATE_DIR.exists():
         shutil.rmtree(TEST_STATE_DIR)
@@ -226,7 +271,25 @@ def test_server():
     # Isolated cron state
     (TEST_STATE_DIR / 'cron').mkdir(parents=True, exist_ok=True)
 
+    # Expose TEST_STATE_DIR to the test process itself so that tests which write
+    # directly to state.db (e.g. test_gateway_sync.py) always use the same path
+    # as the server.  Other test files (test_auth_sessions.py) may override
+    # HERMES_WEBUI_STATE_DIR for their own purposes, but HERMES_WEBUI_TEST_STATE_DIR
+    # is reserved for this mapping and is never overridden by individual test files.
+    # Export both port and state-dir as env vars so individual test files
+    # can read them without importing conftest (avoids circular imports).
+    os.environ.setdefault('HERMES_WEBUI_TEST_PORT', str(TEST_PORT))
+    # os.environ already set at module level above; no-op here.
+
     env = os.environ.copy()
+    # Strip real provider keys so test subprocess never inherits production credentials.
+    # The test server uses a mock/isolated config — no real API calls are made.
+    for _k in list(env):
+        if any(_k.startswith(p) for p in (
+            'OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY',
+            'GOOGLE_API_KEY', 'DEEPSEEK_API_KEY',
+        )):
+            del env[_k]
     env.update({
         "HERMES_WEBUI_PORT":              str(TEST_PORT),
         "HERMES_WEBUI_HOST":              "127.0.0.1",
@@ -234,6 +297,15 @@ def test_server():
         "HERMES_WEBUI_DEFAULT_WORKSPACE": str(TEST_WORKSPACE),
         "HERMES_WEBUI_DEFAULT_MODEL":     "openai/gpt-5.4-mini",
         "HERMES_HOME":                    str(TEST_STATE_DIR),
+        # Belt-and-suspenders: HERMES_BASE_HOME hard-locks _DEFAULT_HERMES_HOME
+        # in api/profiles.py to the test state dir regardless of profile switching
+        # or any os.environ mutation that happens inside the server process.
+        # Without this, a profile switch or active_profile file in the real
+        # ~/.hermes can redirect _get_active_hermes_home() out of the sandbox,
+        # causing onboarding writes (config.yaml, .env) to land in the production
+        # ~/.hermes/profiles/webui/ and overwrite real API keys.
+        "HERMES_BASE_HOME":               str(TEST_STATE_DIR),
+        "HERMES_WEBUI_PASSWORD":          "",
     })
 
     # Pass agent dir if discovered so server.py doesn't have to re-discover
@@ -279,6 +351,33 @@ def base_url():
     return TEST_BASE
 
 
+# ── Per-test model cache invalidation ────────────────────────────────────────
+# The TTL cache for get_available_models() persists across tests within the
+# same process. Tests that modify cfg in-memory won't trigger the mtime path,
+# so the cache must be explicitly invalidated after each test that exercises
+# provider/model detection.
+
+@pytest.fixture(autouse=True)
+def _invalidate_models_cache_after_test():
+    """Force the TTL cache to be cleared before and after every test.
+
+    This prevents state bleed where a test that calls get_available_models()
+    populates the cache with a particular config, and the next test sees stale
+    results even though it has mutated _cfg_cache in-memory.
+    """
+    try:
+        from api.config import invalidate_models_cache
+        invalidate_models_cache()
+    except Exception:
+        pass
+    yield
+    try:
+        from api.config import invalidate_models_cache
+        invalidate_models_cache()
+    except Exception:
+        pass
+
+
 # ── Per-test session cleanup ──────────────────────────────────────────────────
 
 @pytest.fixture(autouse=True)

tests/test_1003_appearance_autosave.py

@@ -0,0 +1,138 @@
+"""Regression checks for Issue #1003: Appearance settings autosave.
+
+Focus:
+- Theme/Skin/Font size should autosave immediately and only show inline status.
+- Appearance changes should not participate in the global unsaved-changes guard.
+- Full-save flow should still include font_size.
+- /api/settings should accept appearance-only payloads and preserve untouched fields.
+"""
+import json
+import re
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from tests._pytest_port import BASE
+
+
+BOOT_JS = (Path(__file__).parent.parent / "static" / "boot.js").read_text(encoding="utf-8")
+PANELS_JS = (Path(__file__).parent.parent / "static" / "panels.js").read_text(encoding="utf-8")
+INDEX_HTML = (Path(__file__).parent.parent / "static" / "index.html").read_text(encoding="utf-8")
+I18N_JS = (Path(__file__).parent.parent / "static" / "i18n.js").read_text(encoding="utf-8")
+
+
+def _function_block(src: str, name: str) -> str:
+    marker = re.search(rf"(^|\n)(?:async\s+)?function\s+{re.escape(name)}\(", src)
+    assert marker is not None, f"{name}() not found"
+    start = marker.start()
+    next_marker = re.search(r"\n(?:function\s+\w+\(|async\s+function\s+\w+\()", src[start + 1 :])
+    if next_marker:
+        end = start + 1 + next_marker.start()
+    else:
+        end = len(src)
+    return src[start:end]
+
+
+def _post(path, body):
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        BASE + path,
+        data=data,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return json.loads(r.read()), r.status
+    except urllib.error.HTTPError as e:
+        payload = e.read()
+        return json.loads(payload or b"{}"), e.code
+
+
+def _get(path):
+    with urllib.request.urlopen(BASE + path, timeout=10) as r:
+        return json.loads(r.read()), r.status
+
+
+def test_appearance_pickers_schedule_autosave_and_do_not_mark_dirty():
+    for fn in ("_pickTheme", "_pickSkin", "_pickFontSize"):
+        block = _function_block(BOOT_JS, fn)
+        assert "_scheduleAppearanceAutosave()" in block, (
+            f"{fn}() should invoke _scheduleAppearanceAutosave()"
+        )
+        assert "_markSettingsDirty()" not in block, (
+            f"{fn}() should not call _markSettingsDirty()"
+        )
+
+
+def test_appearance_revert_preview_no_longer_rolls_back_theme_skin_font():
+    block = _function_block(PANELS_JS, "_revertSettingsPreview")
+    assert "hermes-theme" not in block
+    assert "hermes-skin" not in block
+    assert "hermes-font-size" not in block
+    assert "_markSettingsDirty()" not in block
+
+
+def test_appearance_autosave_payload_is_theme_skin_font_only():
+    block = _function_block(PANELS_JS, "_appearancePayloadFromUi")
+    assert "theme:" in block
+    assert "skin:" in block
+    assert "font_size:" in block
+    assert "language:" not in block
+    assert "workspace" not in block
+    assert "show_token_usage" not in block
+    status_block = _function_block(PANELS_JS, "_setAppearanceAutosaveStatus")
+    assert "settings_autosave_saving" in status_block
+    assert "settings_autosave_saved" in status_block
+    assert "settings_autosave_failed" in status_block
+    assert "settings_autosave_retry" in status_block
+
+
+def test_appearance_autosave_status_line_and_i18n_keys_exist():
+    assert 'id="settingsAppearanceAutosaveStatus"' in INDEX_HTML
+    required_keys = [
+        "settings_autosave_saving",
+        "settings_autosave_saved",
+        "settings_autosave_failed",
+        "settings_autosave_retry",
+    ]
+    for key in required_keys:
+        assert I18N_JS.count(f"{key}:") >= 8, (
+            f"{key} must be defined in all LOCALES blocks (found {I18N_JS.count(f'{key}:')})"
+        )
+
+
+def test_full_save_settings_still_includes_font_size():
+    block = _function_block(PANELS_JS, "saveSettings")
+    compact = block.replace(" ", "")
+    assert "body.theme=theme;" in compact
+    assert "body.skin=skin;" in compact
+    assert "body.font_size=fontSize;" in compact
+
+
+def test_settings_api_accepts_appearance_only_payload_without_overwriting_other_fields():
+    original, status = _get("/api/settings")
+    assert status == 200
+    snapshot = {
+        "theme": original.get("theme"),
+        "skin": original.get("skin"),
+        "font_size": original.get("font_size", "default"),
+        "show_token_usage": original.get("show_token_usage"),
+        "show_cli_sessions": original.get("show_cli_sessions"),
+        "check_for_updates": original.get("check_for_updates"),
+    }
+    try:
+        d, status = _post("/api/settings", {"theme": "system", "skin": "charizard", "font_size": "large"})
+        assert status == 200
+        assert d.get("theme") == "system"
+        assert d.get("skin") == "charizard"
+        assert d.get("font_size") == "large"
+        reloaded, _ = _get("/api/settings")
+        assert reloaded.get("show_token_usage") == snapshot["show_token_usage"]
+        assert reloaded.get("show_cli_sessions") == snapshot["show_cli_sessions"]
+        assert reloaded.get("check_for_updates") == snapshot["check_for_updates"]
+    finally:
+        _post("/api/settings", {
+            "theme": snapshot["theme"],
+            "skin": snapshot["skin"],
+            "font_size": snapshot["font_size"],
+        })

tests/test_1003_preferences_autosave.py

@@ -0,0 +1,178 @@
+"""Regression checks for Issue #1003 Phase 2: Preferences settings autosave (PR #1369).
+
+Mirrors the structure of test_1003_appearance_autosave.py to verify the
+preferences-panel autosave pattern is wired correctly:
+
+- All 13 preference fields use _schedulePreferencesAutosave (not _markSettingsDirty)
+- Password field MUST still call _markSettingsDirty (security: never autosave)
+- _preferencesPayloadFromUi covers all 13 fields
+- _setPreferencesAutosaveStatus uses the shared i18n keys
+- Status div exists in static/index.html
+- _autosavePreferencesSettings clears the dirty flag and hides the unsaved bar
+"""
+import re
+from pathlib import Path
+
+PANELS_JS = (Path(__file__).parent.parent / "static" / "panels.js").read_text(encoding="utf-8")
+INDEX_HTML = (Path(__file__).parent.parent / "static" / "index.html").read_text(encoding="utf-8")
+I18N_JS = (Path(__file__).parent.parent / "static" / "i18n.js").read_text(encoding="utf-8")
+
+
+def _function_block(src: str, name: str) -> str:
+    marker = re.search(rf"(^|\n)(?:async\s+)?function\s+{re.escape(name)}\(", src)
+    assert marker is not None, f"{name}() not found"
+    start = marker.start()
+    next_marker = re.search(r"\n(?:function\s+\w+\(|async\s+function\s+\w+\()", src[start + 1:])
+    end = start + 1 + next_marker.start() if next_marker else len(src)
+    return src[start:end]
+
+
+def _load_settings_panel_block() -> str:
+    return _function_block(PANELS_JS, "loadSettingsPanel")
+
+
+# ── Field-by-field autosave wiring ───────────────────────────────────────
+
+PREFERENCE_FIELDS_AUTOSAVE = [
+    # (DOM id, field name in _preferencesPayloadFromUi)
+    ("settingsSendKey", "send_key"),
+    ("settingsLanguage", "language"),
+    ("settingsShowTokenUsage", "show_token_usage"),
+    ("settingsSimplifiedToolCalling", "simplified_tool_calling"),
+    ("settingsShowCliSessions", "show_cli_sessions"),
+    ("settingsSyncInsights", "sync_to_insights"),
+    ("settingsCheckUpdates", "check_for_updates"),
+    ("settingsSoundEnabled", "sound_enabled"),
+    ("settingsNotificationsEnabled", "notifications_enabled"),
+    ("settingsSidebarDensity", "sidebar_density"),
+    ("settingsAutoTitleRefresh", "auto_title_refresh_every"),
+    ("settingsBusyInputMode", "busy_input_mode"),
+    ("settingsBotName", "bot_name"),
+]
+
+
+def test_all_13_preference_fields_have_autosave_payload_entries():
+    """_preferencesPayloadFromUi must include all 13 preference fields."""
+    block = _function_block(PANELS_JS, "_preferencesPayloadFromUi")
+    for dom_id, field in PREFERENCE_FIELDS_AUTOSAVE:
+        assert f"$('{dom_id}')" in block, \
+            f"_preferencesPayloadFromUi missing reference to {dom_id}"
+        assert f"payload.{field}=" in block, \
+            f"_preferencesPayloadFromUi missing payload assignment for {field}"
+
+
+def test_preference_fields_use_schedule_autosave_not_mark_dirty():
+    """All 12 listener attachments (excluding bot_name's debounce wrapper) must
+    use _schedulePreferencesAutosave. bot_name uses a wrapper but still
+    eventually calls _schedulePreferencesAutosave."""
+    panel = _load_settings_panel_block()
+    # Each field should have at least one addEventListener call wired to the autosave
+    # path. We check that for each non-password/non-model field, the dirty marker
+    # has been replaced.
+    for dom_id, _field in PREFERENCE_FIELDS_AUTOSAVE:
+        if dom_id == "settingsBotName":
+            # Bot name uses a 500ms wrapper that calls _schedulePreferencesAutosave
+            # via setTimeout. The wrapper itself is in the loadSettingsPanel block.
+            assert "_schedulePreferencesAutosave" in panel, \
+                "_schedulePreferencesAutosave must be referenced for bot_name flow"
+            continue
+        # For other fields: search the field's block for the addEventListener call
+        # and verify it points to _schedulePreferencesAutosave.
+        # We use a context window around the dom_id to find the listener.
+        idx = panel.find(f"$('{dom_id}')")
+        assert idx != -1, f"{dom_id} not loaded in loadSettingsPanel"
+        # Window of next ~600 chars covers the .addEventListener call
+        window = panel[idx:idx + 600]
+        assert "addEventListener" in window, f"{dom_id} has no addEventListener"
+        assert "_schedulePreferencesAutosave" in window, \
+            f"{dom_id} listener should call _schedulePreferencesAutosave (Phase 2 #1003)"
+        assert "_markSettingsDirty" not in window, \
+            f"{dom_id} should not call _markSettingsDirty (Phase 2 autosaves it)"
+
+
+def test_password_still_uses_mark_dirty():
+    """SECURITY INVARIANT: password field must NEVER autosave; it must still
+    call _markSettingsDirty so user explicitly clicks Save Settings."""
+    panel = _load_settings_panel_block()
+    idx = panel.find("$('settingsPassword')")
+    assert idx != -1, "settingsPassword field not loaded"
+    window = panel[idx:idx + 400]
+    assert "_markSettingsDirty" in window, \
+        "Password field MUST call _markSettingsDirty (security: never autosave passwords)"
+    assert "_schedulePreferencesAutosave" not in window, \
+        "Password field MUST NOT call _schedulePreferencesAutosave (security)"
+
+
+def test_autosave_clears_dirty_flag_and_hides_unsaved_bar():
+    """_autosavePreferencesSettings must clear the dirty flag and hide the
+    unsaved-changes bar on success — but ONLY when password and model are
+    not pending. Q1 from Opus pre-release review of v0.50.250."""
+    block = _function_block(PANELS_JS, "_autosavePreferencesSettings")
+    # Must check pwField/modelSel state before clearing dirty + hiding bar
+    assert "settingsPassword" in block, (
+        "_autosavePreferencesSettings must check the password field before "
+        "clearing _settingsDirty (Opus SHOULD-FIX Q1: autosave was clobbering "
+        "pending password edits)"
+    )
+    assert "settingsModel" in block, (
+        "_autosavePreferencesSettings must check the model selector before "
+        "clearing _settingsDirty (autosave was clobbering pending model changes)"
+    )
+    assert "_settingsHermesDefaultModelOnOpen" in block, (
+        "_autosavePreferencesSettings must compare the model selector value "
+        "against the on-open snapshot to detect a pending change"
+    )
+    # The clear-and-hide block must be conditional, not unconditional
+    compact = block.replace(" ", "").replace("\n", "")
+    assert "if(!pwDirty&&!modelDirty)" in compact or "if(pwDirty||modelDirty)" in compact, (
+        "_autosavePreferencesSettings must guard the dirty-clear and bar-hide "
+        "with a condition that defers when a manual field has pending edits"
+    )
+
+
+def test_status_div_exists_in_index_html():
+    """The status div must be present in index.html for status feedback."""
+    assert 'id="settingsPreferencesAutosaveStatus"' in INDEX_HTML
+
+
+def test_set_status_uses_shared_i18n_keys():
+    """_setPreferencesAutosaveStatus must use the shared i18n keys from Phase 1."""
+    block = _function_block(PANELS_JS, "_setPreferencesAutosaveStatus")
+    for key in [
+        "settings_autosave_saving",
+        "settings_autosave_saved",
+        "settings_autosave_failed",
+        "settings_autosave_retry",
+    ]:
+        assert key in block, f"_setPreferencesAutosaveStatus must use '{key}'"
+
+
+def test_retry_function_exists_and_falls_back_gracefully():
+    """_retryPreferencesAutosave must exist and use the saved retry payload (or
+    rebuild from UI if unavailable)."""
+    block = _function_block(PANELS_JS, "_retryPreferencesAutosave")
+    assert "_settingsPreferencesAutosaveRetryPayload" in block, \
+        "Retry must reference the stored payload"
+    assert "_preferencesPayloadFromUi" in block, \
+        "Retry must fall back to rebuilding from UI when no stored payload"
+    assert "_autosavePreferencesSettings" in block, \
+        "Retry must invoke _autosavePreferencesSettings"
+
+
+def test_debounce_cancels_pending_timer_on_rapid_input():
+    """_schedulePreferencesAutosave must clear any in-flight timer before
+    setting a new one — otherwise rapid changes queue up multiple POSTs."""
+    block = _function_block(PANELS_JS, "_schedulePreferencesAutosave")
+    assert "clearTimeout(_settingsPreferencesAutosaveTimer)" in block, \
+        "_schedulePreferencesAutosave must clearTimeout the prior timer"
+    assert "350" in block, \
+        "_schedulePreferencesAutosave must use 350ms debounce (matching Phase 1)"
+
+
+def test_phase1_appearance_autosave_still_passes():
+    """Sanity: Phase 2 must not break Phase 1's pattern. The Appearance autosave
+    functions and i18n keys must still exist."""
+    assert "function _appearancePayloadFromUi" in PANELS_JS
+    assert "function _autosaveAppearanceSettings" in PANELS_JS
+    assert "function _scheduleAppearanceAutosave" in PANELS_JS
+    assert 'id="settingsAppearanceAutosaveStatus"' in INDEX_HTML

tests/test_1038_pwa_auth_redirect.py

@@ -0,0 +1,112 @@
+"""
+Tests for issue #1038 — iOS PWA auth-expiry redirect.
+
+When a 401 is returned by any API endpoint, the client-side JS should redirect
+to /login rather than showing a raw error toast. On iOS PWA standalone mode a
+server-side 302→/login breaks out of the PWA shell into Safari, so the fix is
+client-side: workspace.js api() intercepts 401 before throwing and calls
+window.location.href = '/login'.
+
+These are static regression tests that verify the JS source contains the
+correct guard patterns.
+"""
+
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def _workspace_js() -> str:
+    return (ROOT / "static" / "workspace.js").read_text(encoding="utf-8")
+
+
+def _ui_js() -> str:
+    return (ROOT / "static" / "ui.js").read_text(encoding="utf-8")
+
+
+class TestPWAAuthRedirect:
+    def test_workspace_js_has_401_redirect(self):
+        """api() in workspace.js must redirect to /login on 401."""
+        src = _workspace_js()
+        # Guard must appear inside the !res.ok block, before throwing
+        assert "res.status===401" in src, \
+            "workspace.js api() must check res.status===401"
+        assert "window.location.href='/login" in src or 'window.location.href="/login' in src, \
+            "workspace.js api() must redirect to /login on 401"
+
+    def test_workspace_js_401_before_throw(self):
+        """The 401 redirect must come before any error throw."""
+        src = _workspace_js()
+        idx_401 = src.find("res.status===401")
+        # api() may throw via `throw new Error(...)` or via the structured
+        # `const err=new Error(...); ... throw err;` pattern that attaches HTTP
+        # context for callers. Either is fine — what matters is the 401 redirect
+        # short-circuits before the generic throw.
+        idx_throw = src.find("throw new Error")
+        if idx_throw == -1:
+            idx_throw = src.find("throw err")
+        assert idx_401 != -1, "401 guard not found in workspace.js"
+        assert idx_throw != -1, "no error throw found in workspace.js"
+        assert idx_401 < idx_throw, \
+            "401 redirect must appear before the generic throw in workspace.js"
+
+    def test_ui_js_has_redirect_helper(self):
+        """ui.js must define _redirectIfUnauth helper."""
+        src = _ui_js()
+        assert "_redirectIfUnauth" in src, \
+            "ui.js must define _redirectIfUnauth helper function"
+
+    def test_ui_js_models_fetch_uses_redirect(self):
+        """populateModelDropdown() must call _redirectIfUnauth on the api/models response."""
+        src = _ui_js()
+        # The helper must be called after the api/models fetch
+        assert "_redirectIfUnauth(_modelsRes)" in src, \
+            "populateModelDropdown() must check 401 on api/models fetch"
+
+    def test_ui_js_live_models_fetch_uses_redirect(self):
+        """loadLiveModels() must call _redirectIfUnauth on the api/models/live response."""
+        src = _ui_js()
+        assert "_redirectIfUnauth(_liveRes)" in src, \
+            "loadLiveModels() must check 401 on api/models/live fetch"
+
+    def test_ui_js_upload_fetch_uses_redirect(self):
+        """File upload must call _redirectIfUnauth on the api/upload response."""
+        src = _ui_js()
+        assert "_redirectIfUnauth(res)" in src, \
+            "upload fetch must call _redirectIfUnauth"
+
+
+class TestLoginJsSafeNextPath:
+    """login.js _safeNextPath() must honor ?next= but reject open-redirect payloads."""
+
+    @staticmethod
+    def _login_js():
+        return (Path(__file__).parent.parent / "static" / "login.js").read_text(encoding="utf-8")
+
+    def test_safe_next_path_function_exists(self):
+        """login.js must define _safeNextPath() to honor the ?next= redirect."""
+        assert "_safeNextPath" in self._login_js(), (
+            "login.js must define _safeNextPath() to use the ?next= redirect after login"
+        )
+
+    def test_login_uses_safe_next_path(self):
+        """doLogin success handler must redirect to _safeNextPath(), not hardcoded './'."""
+        src = self._login_js()
+        assert "_safeNextPath()" in src, (
+            "doLogin must call _safeNextPath() instead of hardcoding './'"
+        )
+
+    def test_safe_next_path_rejects_protocol_relative(self):
+        """_safeNextPath guard must reject '//' prefix (protocol-relative open-redirect)."""
+        src = self._login_js()
+        assert "charAt(1) === '/'" in src or "startsWith('//')" in src, (
+            "_safeNextPath must reject protocol-relative paths like //evil.com"
+        )
+
+    def test_safe_next_path_rejects_non_path_absolute(self):
+        """_safeNextPath guard must require path starts with '/'."""
+        src = self._login_js()
+        assert "charAt(0) !== '/'" in src or "startsWith('/')" in src, (
+            "_safeNextPath must reject non-path-absolute inputs (e.g. 'http://...')"
+        )

tests/test_1044_mermaid_csp_font.py

@@ -0,0 +1,51 @@
+"""
+Tests for issue #1044 — Mermaid CSP font violation.
+
+Mermaid's built-in themes inject an @import for Google Fonts (Manrope) at
+render time, which is blocked by the CSP's style-src directive. Fix: pass
+fontFamily:'inherit' in themeVariables so Mermaid never requests an external
+font URL.
+"""
+
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def _ui_js() -> str:
+    return (ROOT / "static" / "ui.js").read_text(encoding="utf-8")
+
+
+class TestMermaidCSPFont:
+    def test_mermaid_init_has_font_family_inherit(self):
+        """themeVariables in mermaid.initialize() must set fontFamily to 'inherit'."""
+        src = _ui_js()
+        assert "fontFamily:'inherit'" in src, (
+            "mermaid.initialize() themeVariables must set fontFamily:'inherit' "
+            "to suppress the Google Fonts (Manrope) import that violates CSP"
+        )
+
+    def test_mermaid_init_no_google_fonts_url(self):
+        """ui.js must not contain a hardcoded fonts.googleapis.com URL."""
+        src = _ui_js()
+        assert "fonts.googleapis.com" not in src, (
+            "ui.js must not reference fonts.googleapis.com — use fontFamily:'inherit'"
+        )
+
+    def test_mermaid_font_family_inside_theme_variables_block(self):
+        """fontFamily:'inherit' must be inside the themeVariables block of mermaid.initialize()."""
+        src = _ui_js()
+        init_idx = src.find("mermaid.initialize(")
+        assert init_idx != -1, "mermaid.initialize() call not found in ui.js"
+        # Find the themeVariables block after the initialize call
+        tv_idx = src.find("themeVariables", init_idx)
+        assert tv_idx != -1, "themeVariables not found inside mermaid.initialize()"
+        font_idx = src.find("fontFamily:'inherit'", tv_idx)
+        assert font_idx != -1, (
+            "fontFamily:'inherit' must appear inside themeVariables in mermaid.initialize()"
+        )
+        # The closing brace of themeVariables should come after fontFamily
+        close_brace = src.find("})", tv_idx)
+        assert font_idx < close_brace, (
+            "fontFamily:'inherit' must be inside the themeVariables block (before })"
+        )

tests/test_1045_bfcache_layout_restore.py

@@ -0,0 +1,124 @@
+"""
+Tests for issue #1045 — bfcache layout broken on tab restore.
+
+When the browser restores a page from bfcache (event.persisted === true),
+the async boot IIFE does not re-run. The existing pageshow handler (added for
+#822) only cleared the session search field and re-rendered the session list.
+This left the rail, topbar, workspace panel, and resize handles in the stale
+bfcache DOM state, producing a broken layout.
+
+Fix: extend the pageshow handler to also call syncTopbar, syncWorkspacePanelState,
+_initResizePanels, and startGatewaySSE — all guarded so missing helpers degrade.
+"""
+
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def _boot_js() -> str:
+    return (ROOT / "static" / "boot.js").read_text(encoding="utf-8")
+
+
+def _pageshow_handler(src: str) -> str:
+    marker = "window.addEventListener('pageshow'"
+    ps_idx = src.find(marker)
+    assert ps_idx != -1, "pageshow listener not found in boot.js"
+    brace = src.find("=> {", ps_idx)
+    assert brace != -1, "pageshow listener body not found"
+    brace = src.find("{", brace)
+    depth = 1
+    i = brace + 1
+    while i < len(src) and depth:
+        if src[i] == "{":
+            depth += 1
+        elif src[i] == "}":
+            depth -= 1
+        i += 1
+    assert depth == 0, "pageshow listener body did not close"
+    return src[brace + 1 : i - 1]
+
+
+class TestBfcacheLayoutRestore:
+    def test_pageshow_calls_sync_topbar(self):
+        """pageshow handler must call syncTopbar() on bfcache restore."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "syncTopbar" in handler_body, (
+            "pageshow handler must call syncTopbar() to restore topbar state after bfcache"
+        )
+
+    def test_pageshow_calls_sync_workspace_panel_state(self):
+        """pageshow handler must call syncWorkspacePanelState()."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "syncWorkspacePanelState" in handler_body, (
+            "pageshow handler must call syncWorkspacePanelState() on bfcache restore"
+        )
+
+
+    def test_pageshow_calls_start_gateway_sse(self):
+        """pageshow handler must call startGatewaySSE() to reconnect the dead SSE connection."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "startGatewaySSE" in handler_body, (
+            "pageshow handler must restart gateway SSE (bfcache-persisted connections are dead)"
+        )
+
+    def test_pageshow_still_clears_session_search(self):
+        """pageshow handler must still clear #sessionSearch (original #822 fix preserved)."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "sessionSearch" in handler_body, (
+            "pageshow handler must still clear #sessionSearch (regression: #822 fix must be preserved)"
+        )
+
+    def test_pageshow_still_calls_render_session_list_from_cache(self):
+        """pageshow handler must still call renderSessionListFromCache()."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "renderSessionListFromCache" in handler_body, (
+            "pageshow handler must still call renderSessionListFromCache() (regression: #822 fix)"
+        )
+
+    def test_pageshow_does_not_call_init_resize_panels(self):
+        """pageshow handler must NOT call _initResizePanels() — bfcache
+        preserves event listeners so re-attaching them stacks duplicates."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        assert "_initResizePanels" not in handler_body, (
+            "pageshow handler must not call _initResizePanels() — it stacks "
+            "duplicate mousedown listeners on every bfcache restore"
+        )
+
+    def test_new_calls_are_guarded_with_typeof(self):
+        """New calls in the pageshow handler must be typeof-guarded for safe degradation."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        # Each of the new calls must be guarded
+        for fn in ("syncTopbar", "syncWorkspacePanelState", "startGatewaySSE",
+                   "closeModelDropdown", "closeReasoningDropdown", "closeWsDropdown", "closeProfileDropdown"):
+            assert f"typeof {fn} === 'function'" in handler_body, (
+                f"{fn}() call in pageshow handler must be guarded with typeof === 'function'"
+            )
+
+    def test_pageshow_closes_all_dropdowns(self):
+        """pageshow handler must close all known dropdowns to reset frozen bfcache popover state."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        for fn in ("closeModelDropdown", "closeReasoningDropdown", "closeWsDropdown", "closeProfileDropdown"):
+            assert fn in handler_body, (
+                f"pageshow handler must call {fn}() to dismiss any dropdown left open by bfcache"
+            )
+
+    def test_dropdowns_closed_before_layout_sync(self):
+        """Dropdown closes must come before layout sync calls (clean state first)."""
+        src = _boot_js()
+        handler_body = _pageshow_handler(src)
+        close_idx = handler_body.find("closeModelDropdown")
+        sync_idx = handler_body.find("syncTopbar")
+        assert close_idx != -1 and sync_idx != -1, "Both close and sync calls must be present"
+        assert close_idx < sync_idx, (
+            "Dropdown close calls must appear before layout sync calls in the pageshow handler"
+        )
+

tests/test_1058_adaptive_title_refresh.py

@@ -0,0 +1,382 @@
+"""Tests for adaptive session title refresh helpers (PR #1058).
+
+Covers all five new functions added to api/streaming.py:
+  - _count_exchanges
+  - _latest_exchange_snippets
+  - _get_title_refresh_interval
+  - _run_background_title_refresh
+  - _maybe_schedule_title_refresh
+"""
+import sys
+import os
+import threading
+import types
+import unittest
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# Ensure the project root is on sys.path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from api.streaming import (
+    _count_exchanges,
+    _latest_exchange_snippets,
+    _get_title_refresh_interval,
+    _run_background_title_refresh,
+    _maybe_schedule_title_refresh,
+)
+
+
+@pytest.fixture(autouse=True)
+def _restore_auth_sessions():
+    """Snapshot and restore api.auth._sessions around each test.
+
+    Importing api.streaming can trigger api.config.load_settings() which may
+    call into api.auth and create a real session token.  Without this fixture,
+    that stale token leaks into test_auth_session_persistence.py tests (which
+    assume _sessions starts empty) when our file runs first alphabetically.
+    """
+    import api.auth as _auth
+    snapshot = dict(_auth._sessions)
+    yield
+    _auth._sessions.clear()
+    _auth._sessions.update(snapshot)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _user_msg(text):
+    return {'role': 'user', 'content': text}
+
+
+def _asst_msg(text, tool_calls=None):
+    msg = {'role': 'assistant', 'content': text}
+    if tool_calls is not None:
+        msg['tool_calls'] = tool_calls
+    return msg
+
+
+def _tool_only_asst():
+    """Assistant message that only has tool_calls, no real text."""
+    return {'role': 'assistant', 'content': '', 'tool_calls': [{'id': 't1', 'type': 'function'}]}
+
+
+def _make_session(title='My Title', llm_title_generated=True, messages=None, session_id='sid1'):
+    s = MagicMock()
+    s.title = title
+    s.llm_title_generated = llm_title_generated
+    s.messages = messages or []
+    s.session_id = session_id
+    s.save = MagicMock()
+    return s
+
+
+# ---------------------------------------------------------------------------
+# _count_exchanges
+# ---------------------------------------------------------------------------
+
+class TestCountExchanges:
+    def test_empty_messages_returns_zero(self):
+        assert _count_exchanges([]) == 0
+
+    def test_none_messages_returns_zero(self):
+        assert _count_exchanges(None) == 0
+
+    def test_counts_only_user_messages(self):
+        msgs = [_user_msg('hello'), _asst_msg('hi'), _user_msg('world')]
+        assert _count_exchanges(msgs) == 2
+
+    def test_skips_empty_user_messages(self):
+        msgs = [_user_msg(''), _user_msg('   '), _user_msg('real question')]
+        assert _count_exchanges(msgs) == 1
+
+    def test_counts_list_content_user_messages(self):
+        msgs = [
+            {'role': 'user', 'content': [{'type': 'text', 'text': 'list question'}]},
+        ]
+        assert _count_exchanges(msgs) == 1
+
+    def test_skips_empty_list_content(self):
+        msgs = [
+            {'role': 'user', 'content': [{'type': 'text', 'text': '   '}]},
+        ]
+        assert _count_exchanges(msgs) == 0
+
+    def test_ignores_non_user_roles(self):
+        msgs = [_asst_msg('response'), {'role': 'system', 'content': 'system prompt'}]
+        assert _count_exchanges(msgs) == 0
+
+    def test_ignores_non_dict_entries(self):
+        msgs = ['not a dict', _user_msg('real'), None]
+        assert _count_exchanges(msgs) == 1
+
+    def test_five_exchanges(self):
+        msgs = []
+        for i in range(5):
+            msgs.append(_user_msg(f'question {i}'))
+            msgs.append(_asst_msg(f'answer {i}'))
+        assert _count_exchanges(msgs) == 5
+
+
+# ---------------------------------------------------------------------------
+# _latest_exchange_snippets
+# ---------------------------------------------------------------------------
+
+class TestLatestExchangeSnippets:
+    def test_empty_returns_empty_strings(self):
+        u, a = _latest_exchange_snippets([])
+        assert u == '' and a == ''
+
+    def test_none_returns_empty_strings(self):
+        u, a = _latest_exchange_snippets(None)
+        assert u == '' and a == ''
+
+    def test_basic_pair(self):
+        msgs = [_user_msg('first q'), _asst_msg('first a'),
+                _user_msg('second q'), _asst_msg('second a')]
+        u, a = _latest_exchange_snippets(msgs)
+        assert u == 'second q'
+        assert a == 'second a'
+
+    def test_returns_latest_not_first(self):
+        msgs = [_user_msg('old q'), _asst_msg('old a'),
+                _user_msg('new q'), _asst_msg('new a')]
+        u, a = _latest_exchange_snippets(msgs)
+        assert u == 'new q'
+
+    def test_skips_tool_call_only_assistant(self):
+        """An assistant msg with tool_calls and no real text should be skipped."""
+        msgs = [_user_msg('q'), _asst_msg('real answer'),
+                _user_msg('q2'), _tool_only_asst()]
+        u, a = _latest_exchange_snippets(msgs)
+        # _tool_only_asst should be skipped; fall back to previous real assistant
+        assert a == 'real answer'
+        assert u == 'q2'
+
+    def test_truncates_long_content(self):
+        long_text = 'x' * 600
+        msgs = [_user_msg(long_text), _asst_msg(long_text)]
+        u, a = _latest_exchange_snippets(msgs)
+        assert len(u) == 500
+        assert len(a) == 500
+
+    def test_no_assistant_message(self):
+        msgs = [_user_msg('q')]
+        u, a = _latest_exchange_snippets(msgs)
+        assert u == 'q'
+        assert a == ''
+
+    def test_no_user_message(self):
+        msgs = [_asst_msg('a')]
+        u, a = _latest_exchange_snippets(msgs)
+        assert u == ''
+        assert a == 'a'
+
+    def test_ignores_non_dict_entries(self):
+        msgs = ['noise', _user_msg('q'), None, _asst_msg('a')]
+        u, a = _latest_exchange_snippets(msgs)
+        assert u == 'q'
+        assert a == 'a'
+
+
+# ---------------------------------------------------------------------------
+# _get_title_refresh_interval
+# ---------------------------------------------------------------------------
+
+class TestGetTitleRefreshInterval:
+    def test_returns_int_for_valid_setting(self):
+        # _get_title_refresh_interval does a local import: `from api.config import load_settings`
+        # so patch the source module, not api.streaming
+        with patch('api.config.load_settings', return_value={'auto_title_refresh_every': '5'}):
+            assert _get_title_refresh_interval() == 5
+
+    def test_returns_zero_for_off_setting(self):
+        with patch('api.config.load_settings', return_value={'auto_title_refresh_every': '0'}):
+            assert _get_title_refresh_interval() == 0
+
+    def test_returns_zero_when_key_absent(self):
+        with patch('api.config.load_settings', return_value={}):
+            assert _get_title_refresh_interval() == 0
+
+    def test_returns_zero_on_exception(self):
+        with patch('api.config.load_settings', side_effect=Exception('boom')):
+            assert _get_title_refresh_interval() == 0
+
+    def test_valid_values_10_and_20(self):
+        for val in ('10', '20'):
+            with patch('api.config.load_settings', return_value={'auto_title_refresh_every': val}):
+                assert _get_title_refresh_interval() == int(val)
+
+
+# ---------------------------------------------------------------------------
+# _run_background_title_refresh
+# ---------------------------------------------------------------------------
+
+class TestRunBackgroundTitleRefresh:
+    def _make_put_event(self):
+        events = []
+        def put(name, data):
+            events.append((name, data))
+        return put, events
+
+    def _make_session_obj(self, title='Old Title'):
+        s = MagicMock()
+        s.title = title
+        s.llm_title_generated = True
+        s.save = MagicMock()
+        return s
+
+    def test_skips_when_title_changed_before_call(self):
+        """If the title has changed (manual rename) since the refresh was scheduled, skip."""
+        put, events = self._make_put_event()
+        with patch('api.streaming.get_session') as mock_get, \
+             patch('api.streaming.SESSIONS', {}), \
+             patch('api.streaming.LOCK', threading.Lock()):
+            s = self._make_session_obj(title='Different Title')
+            mock_get.return_value = s
+            _run_background_title_refresh(
+                'sid', 'user', 'asst', 'Old Title', put, agent=None
+            )
+        # No 'title' event should have been emitted
+        assert not any(name == 'title' for name, _ in events)
+
+    def test_skips_if_session_not_found(self):
+        put, events = self._make_put_event()
+        with patch('api.streaming.get_session', side_effect=KeyError('not found')):
+            _run_background_title_refresh('sid', 'u', 'a', 'title', put)
+        assert events == []
+
+    def test_skips_when_title_is_untitled(self):
+        put, events = self._make_put_event()
+        with patch('api.streaming.get_session') as mock_get:
+            s = self._make_session_obj(title='Untitled')
+            mock_get.return_value = s
+            _run_background_title_refresh('sid', 'u', 'a', 'Untitled', put)
+        assert not any(name == 'title' for name, _ in events)
+
+    def test_skips_same_title(self):
+        """If the LLM generates a title identical to the current one, no event is emitted."""
+        put, events = self._make_put_event()
+        with patch('api.streaming.get_session') as mock_get, \
+             patch('api.streaming._aux_title_configured', return_value=True), \
+             patch('api.streaming._generate_llm_session_title_via_aux',
+                   return_value=('Old Title', 'llm_ok', 'raw')), \
+             patch('api.streaming.SESSIONS', {}), \
+             patch('api.streaming.LOCK', threading.Lock()):
+            s = self._make_session_obj(title='Old Title')
+            mock_get.return_value = s
+            _run_background_title_refresh('sid', 'u', 'a', 'Old Title', put)
+        assert not any(name == 'title' for name, _ in events)
+
+    def test_emits_title_event_on_new_title(self):
+        put, events = self._make_put_event()
+        s = self._make_session_obj(title='Old Title')
+        # Use a real dict for SESSIONS so .get() works, pre-populated with our session
+        fake_sessions = {'sid': s}
+        with patch('api.streaming.get_session', return_value=s), \
+             patch('api.streaming._aux_title_configured', return_value=True), \
+             patch('api.streaming._generate_llm_session_title_via_aux',
+                   return_value=('New Refreshed Title', 'llm_ok', 'raw')), \
+             patch('api.streaming.SESSIONS', fake_sessions), \
+             patch('api.streaming.LOCK', threading.Lock()):
+            _run_background_title_refresh('sid', 'u', 'a', 'Old Title', put)
+        title_events = [(n, d) for n, d in events if n == 'title']
+        assert len(title_events) == 1
+        assert title_events[0][1]['title'] == 'New Refreshed Title'
+
+    def test_exceptions_are_silently_swallowed(self):
+        """Any unexpected error inside must not propagate — it's a background daemon."""
+        put, events = self._make_put_event()
+        with patch('api.streaming.get_session', side_effect=RuntimeError('oops')):
+            # Should not raise
+            _run_background_title_refresh('sid', 'u', 'a', 'title', put)
+        assert events == []
+
+
+# ---------------------------------------------------------------------------
+# _maybe_schedule_title_refresh
+# ---------------------------------------------------------------------------
+
+class TestMaybeScheduleTitleRefresh:
+    def _noop_put(self, name, data):
+        pass
+
+    def test_does_nothing_when_disabled(self):
+        with patch('api.streaming._get_title_refresh_interval', return_value=0):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                session = _make_session(messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []
+
+    def test_does_nothing_when_title_is_empty(self):
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                session = _make_session(title='', messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []
+
+    def test_does_nothing_for_untitled(self):
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                session = _make_session(title='Untitled', messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []
+
+    def test_does_nothing_when_title_not_llm_generated(self):
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                session = _make_session(llm_title_generated=False,
+                                        messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []
+
+    def test_does_nothing_when_exchange_count_not_at_interval(self):
+        """Refresh only fires when exchange_count % interval == 0 (and > 0)."""
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                # 4 exchanges — not a multiple of 5
+                session = _make_session(messages=[_user_msg('q'), _asst_msg('a')] * 4)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []
+
+    def test_spawns_thread_at_exact_interval(self):
+        """Refresh fires when exchange_count == refresh_interval."""
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            spawned = []
+            with patch('threading.Thread') as mock_thread_cls:
+                mock_thread = MagicMock()
+                mock_thread_cls.return_value = mock_thread
+                # 5 user messages = 5 exchanges
+                session = _make_session(messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+                assert mock_thread_cls.called
+                assert mock_thread.start.called
+
+    def test_spawns_thread_at_multiple_of_interval(self):
+        """Refresh fires at 10 exchanges when interval is 5."""
+        with patch('api.streaming._get_title_refresh_interval', return_value=5):
+            with patch('threading.Thread') as mock_thread_cls:
+                mock_thread = MagicMock()
+                mock_thread_cls.return_value = mock_thread
+                # 10 exchanges
+                session = _make_session(messages=[_user_msg('q'), _asst_msg('a')] * 10)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+                assert mock_thread_cls.called
+
+    def test_does_nothing_when_no_exchange_content(self):
+        """Even at interval, if both snippets are empty, don't spawn."""
+        with patch('api.streaming._get_title_refresh_interval', return_value=5), \
+             patch('api.streaming._latest_exchange_snippets', return_value=('', '')):
+            spawned = []
+            with patch('threading.Thread', side_effect=lambda **kw: spawned.append(kw) or MagicMock()):
+                session = _make_session(messages=[_user_msg('q'), _asst_msg('a')] * 5)
+                _maybe_schedule_title_refresh(session, self._noop_put, None)
+        assert spawned == []

tests/test_1059_settings_picker_active_state.py

@@ -0,0 +1,84 @@
+"""Regression tests for settings picker active-state highlighting.
+
+The theme, skin, and font-size pickers in the Appearance settings tab must show
+the currently-selected option with a visible accent border. This was broken because
+the CSS rule used !important on border-color:var(--border) which overrode the inline
+style that _syncThemePicker/etc. set. Fixed by moving to .active CSS class + !important
+override on the active state.
+
+Issue: #1059 (settings picker active state)
+"""
+from pathlib import Path
+
+BOOT_JS = (Path(__file__).parent.parent / "static" / "boot.js").read_text(encoding="utf-8")
+STYLE_CSS = (Path(__file__).parent.parent / "static" / "style.css").read_text(encoding="utf-8")
+
+
+class TestSettingsPickerActiveState:
+    """The selected picker card must be visually distinct via the .active class."""
+
+    def test_theme_picker_uses_active_class(self):
+        """_syncThemePicker must toggle .active class, not set inline borderColor."""
+        idx = BOOT_JS.find("function _syncThemePicker(")
+        assert idx >= 0, "_syncThemePicker function not found in boot.js"
+        body = BOOT_JS[idx:idx + 300]
+        assert "classList.toggle" in body, (
+            "_syncThemePicker must use classList.toggle('active', ...) — "
+            "inline style.borderColor is overridden by !important CSS rules"
+        )
+        # Confirm no accent/border2 color values set inline (clearing with '' is OK)
+        assert "var(--accent)" not in body and "var(--border2)" not in body, (
+            "_syncThemePicker must not set var(--accent) or var(--border2) inline — "
+            "those are overridden by !important CSS rules"
+        )
+
+    def test_font_size_picker_uses_active_class(self):
+        """_syncFontSizePicker must toggle .active class."""
+        idx = BOOT_JS.find("function _syncFontSizePicker(")
+        assert idx >= 0, "_syncFontSizePicker function not found in boot.js"
+        body = BOOT_JS[idx:idx + 300]
+        assert "classList.toggle" in body, (
+            "_syncFontSizePicker must use classList.toggle('active', ...)"
+        )
+        assert "var(--accent)" not in body and "var(--border2)" not in body, (
+            "_syncFontSizePicker must not set var(--accent) or var(--border2) inline"
+        )
+
+    def test_skin_picker_uses_active_class(self):
+        """_syncSkinPicker must toggle .active class."""
+        idx = BOOT_JS.find("function _syncSkinPicker(")
+        assert idx >= 0, "_syncSkinPicker function not found in boot.js"
+        body = BOOT_JS[idx:idx + 300]
+        assert "classList.toggle" in body, (
+            "_syncSkinPicker must use classList.toggle('active', ...)"
+        )
+        assert "var(--accent)" not in body and "var(--border2)" not in body, (
+            "_syncSkinPicker must not set var(--accent) or var(--border2) inline"
+        )
+
+    def test_css_active_rule_beats_base_rule(self):
+        """CSS must have a .active rule with !important that overrides the base border-color rule."""
+        assert ".theme-pick-btn.active" in STYLE_CSS, (
+            "style.css must have a .theme-pick-btn.active rule"
+        )
+        assert ".font-size-pick-btn.active" in STYLE_CSS, (
+            "style.css must have a .font-size-pick-btn.active rule"
+        )
+        assert ".skin-pick-btn.active" in STYLE_CSS, (
+            "style.css must have a .skin-pick-btn.active rule"
+        )
+        # The active rule must use !important to beat the base !important rule
+        idx = STYLE_CSS.find(".theme-pick-btn.active")
+        rule = STYLE_CSS[idx:idx + 200]
+        assert "!important" in rule, (
+            ".theme-pick-btn.active must use !important to override "
+            "the base border-color:var(--border)!important rule"
+        )
+
+    def test_active_rule_uses_accent_color(self):
+        """The .active rule must apply the accent color to make selection visible."""
+        idx = STYLE_CSS.find(".theme-pick-btn.active")
+        rule = STYLE_CSS[idx:idx + 200]
+        assert "var(--accent)" in rule, (
+            ".theme-pick-btn.active must set border-color to var(--accent)"
+        )

tests/test_1062_busy_input_modes.py

@@ -0,0 +1,375 @@
+"""Regression tests for busy_input_mode (PR #1062, closes #720).
+
+Pins the wiring for the three modes (queue / interrupt / steer):
+- The setting key + default + enum validation in api/config.py
+- Three slash commands registered in static/commands.js
+- send()'s busy branch reads window._busyInputMode and dispatches
+- Boot initializes window._busyInputMode from settings
+- 17 new i18n keys present in all 6 locale blocks
+
+Issue: #720 (configurable busy-input behaviour)
+"""
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+CONFIG_PY = (ROOT / "api" / "config.py").read_text(encoding="utf-8")
+COMMANDS_JS = (ROOT / "static" / "commands.js").read_text(encoding="utf-8")
+MESSAGES_JS = (ROOT / "static" / "messages.js").read_text(encoding="utf-8")
+UI_JS = (ROOT / "static" / "ui.js").read_text(encoding="utf-8")
+BOOT_JS = (ROOT / "static" / "boot.js").read_text(encoding="utf-8")
+PANELS_JS = (ROOT / "static" / "panels.js").read_text(encoding="utf-8")
+INDEX_HTML = (ROOT / "static" / "index.html").read_text(encoding="utf-8")
+I18N_JS = (ROOT / "static" / "i18n.js").read_text(encoding="utf-8")
+
+
+# ── Backend: setting registration + enum validation ─────────────────────
+
+class TestBusyInputModeSetting:
+    """The new setting key must be registered with a default and enum validator."""
+
+    def test_default_is_queue(self):
+        """Default value preserves existing queue behaviour for users who don't touch the setting."""
+        assert '"busy_input_mode": "queue"' in CONFIG_PY, (
+            "_DEFAULT_SETTINGS must include busy_input_mode='queue' so existing users see no change"
+        )
+
+    def test_enum_validator_present(self):
+        """_SETTINGS_ENUM_KEYS must validate busy_input_mode against {queue, interrupt, steer}."""
+        # Find the entry inside the enum dict (a set literal as the value)
+        idx = CONFIG_PY.find('"busy_input_mode": {')
+        assert idx >= 0, "busy_input_mode entry missing from _SETTINGS_ENUM_KEYS"
+        block = CONFIG_PY[idx:idx + 200]
+        assert '"queue"' in block and '"interrupt"' in block and '"steer"' in block, (
+            "busy_input_mode enum must contain {queue, interrupt, steer}"
+        )
+
+
+# ── Frontend: slash commands ─────────────────────────────────────────────
+
+class TestSlashCommandRegistration:
+    """The three new slash commands must be registered in COMMANDS array."""
+
+    def test_queue_command_registered(self):
+        assert "name:'queue'" in COMMANDS_JS and "fn:cmdQueue" in COMMANDS_JS
+
+    def test_interrupt_command_registered(self):
+        assert "name:'interrupt'" in COMMANDS_JS and "fn:cmdInterrupt" in COMMANDS_JS
+
+    def test_steer_command_registered(self):
+        assert "name:'steer'" in COMMANDS_JS and "fn:cmdSteer" in COMMANDS_JS
+
+    def test_all_three_busy_commands_are_no_echo(self):
+        """All three busy commands must set noEcho:true so the slash invocation
+        is not echoed as a visible user bubble.  Without noEcho, /queue causes a
+        double-bubble: the raw slash text appears, then the queued message appears
+        again when the drain fires.
+        """
+        for name in ("queue", "interrupt", "steer"):
+            idx = COMMANDS_JS.find(f"name:'{name}'")
+            assert idx >= 0, f"{name} not registered"
+            block = COMMANDS_JS[idx:idx + 250]
+            assert "noEcho:true" in block, (
+                f"/{name} registration must set noEcho:true — "
+                "without it the command text is echoed as a user bubble, causing duplicates"
+            )
+
+
+class TestSlashCommandHandlers:
+    """The three handler functions must guard properly and call cancelStream where appropriate."""
+
+    def test_cmd_queue_handles_idle_state(self):
+        """/queue when idle now sends the message normally instead of showing an
+        error toast.  The if(!S.busy) guard must still exist — it routes to the
+        idle-send path rather than the queue path."""
+        idx = COMMANDS_JS.find("async function cmdQueue(")
+        assert idx >= 0
+        body = COMMANDS_JS[idx:idx + 600]
+        assert "if(!S.busy)" in body, "/queue must have an if(!S.busy) guard that routes to send()"
+
+    def test_cmd_interrupt_calls_cancel_stream(self):
+        idx = COMMANDS_JS.find("async function cmdInterrupt(")
+        assert idx >= 0
+        body = COMMANDS_JS[idx:idx + 1300]  # expanded: idle-fallback block added before the busy path
+        assert "queueSessionMessage" in body, "/interrupt must queue the new message before cancelling"
+        assert "cancelStream" in body, "/interrupt must call cancelStream() so the drain re-sends"
+
+    def test_cmd_steer_delegates_to_try_steer(self):
+        """/steer delegates to _trySteer which calls /api/chat/steer with
+        a queue+cancel fallback. The fallback path is exercised by tests
+        in test_real_steer.py — this test just pins the delegation."""
+        idx = COMMANDS_JS.find("async function cmdSteer(")
+        assert idx >= 0
+        body = COMMANDS_JS[idx:idx + 800]
+        # cmdSteer now delegates to _trySteer; the fallback (queueSessionMessage
+        # + cancelStream) lives inside _trySteer.
+        assert "_trySteer" in body, "cmdSteer must call _trySteer to use the real /api/chat/steer endpoint"
+        # The shared helper must contain the fallback path
+        helper_idx = COMMANDS_JS.find("async function _trySteer(")
+        assert helper_idx >= 0, "_trySteer helper must exist"
+        helper_body = COMMANDS_JS[helper_idx:helper_idx + 1500]
+        assert "queueSessionMessage" in helper_body
+        assert "cancelStream" in helper_body
+        # Toast should differ from interrupt to signal it's the steer path
+        assert "cmd_steer_fallback" in helper_body or "steer_fallback" in helper_body
+
+
+# ── send() busy branch ───────────────────────────────────────────────────
+
+    def test_slash_commands_clear_pending_files(self):
+        """All three busy command handlers must clear S.pendingFiles (directly
+        or via _trySteer) after enqueuing, so staged files are not duplicated.
+
+        cmdQueue and cmdInterrupt call queueSessionMessage themselves and clear
+        S.pendingFiles directly.  cmdSteer delegates to _trySteer.  The fallback/interrupt path clears
+        S.pendingFiles inside _trySteer; the success path returns early and
+        send() handles the post-await clear.  Either way files are not
+        duplicated — we verify by checking _trySteer body for the clearing.
+        """
+        # cmdQueue and cmdInterrupt clear pendingFiles directly
+        for fn_name in ("cmdQueue", "cmdInterrupt"):
+            idx = COMMANDS_JS.find(f"function {fn_name}(")
+            assert idx >= 0, f"{fn_name} not found"
+            body = COMMANDS_JS[idx:idx + 800]
+            assert "S.pendingFiles=[]" in body, (
+                f"{fn_name} must clear S.pendingFiles after queueSessionMessage"
+            )
+            assert "renderTray()" in body, (
+                f"{fn_name} must call renderTray() after clearing pendingFiles"
+            )
+        # cmdSteer delegates to _trySteer; that helper clears pendingFiles
+        idx_try = COMMANDS_JS.find("function _trySteer(")
+        assert idx_try >= 0, "_trySteer not found"
+        try_body = COMMANDS_JS[idx_try:idx_try + 1200]
+        assert "S.pendingFiles=[]" in try_body, (
+            "_trySteer must clear S.pendingFiles in its fallback path — "
+            "without this, files are lost on steer→interrupt fallback"
+        )
+        assert "renderTray()" in try_body, (
+            "_trySteer must call renderTray() after clearing pendingFiles"
+        )
+
+
+class TestBusySendButton:
+    """The composer send button must remain usable for busy-input actions."""
+
+    def test_update_send_btn_uses_single_primary_action_button(self):
+        idx = UI_JS.find("function updateSendBtn()")
+        assert idx >= 0, "updateSendBtn() not found"
+        body = UI_JS[idx:UI_JS.find("function setBusy", idx)]
+        assert "getComposerPrimaryAction()" in body, (
+            "updateSendBtn must derive icon/color/enabled state from one composer-primary action helper"
+        )
+        assert "btn.dataset.action=action" in body, (
+            "btnSend should expose its current action for CSS, tests, and accessibility"
+        )
+        assert "btn.classList.toggle('stop',action==='stop')" in body, (
+            "busy/no-draft state should turn the single primary button into the red stop action"
+        )
+        assert "btn.style.display=''" in body, (
+            "the single primary button should remain visible while busy; it becomes Stop when there is no draft"
+        )
+
+    def test_composer_primary_action_accounts_for_all_busy_input_modes(self):
+        idx = UI_JS.find("function getComposerPrimaryAction()")
+        assert idx >= 0, "getComposerPrimaryAction() not found"
+        body = UI_JS[idx:UI_JS.find("function _setComposerPrimaryButtonIcon", idx)]
+        assert "return 'stop'" in body, "busy/no-draft + active stream must map to stop"
+        assert "return 'queue'" in body, "queue mode and unavailable steer/interrupt fallbacks must map to queue"
+        assert "return 'interrupt'" in body, "interrupt mode with an active stream must map to interrupt"
+        assert "return 'steer'" in body, "steer mode with active stream support must map to steer"
+        assert "window._busyInputMode||'queue'" in body, "helper must respect the Busy input mode setting"
+        assert "_getExplicitBusyCommandAction(msg&&msg.value)" in body, (
+            "explicit /queue, /interrupt, and /steer drafts must override the Busy input mode for button visuals"
+        )
+
+    def test_explicit_busy_commands_override_button_visual_action(self):
+        idx = UI_JS.find("function _getExplicitBusyCommandAction(")
+        assert idx >= 0, "_getExplicitBusyCommandAction() not found"
+        body = UI_JS[idx:UI_JS.find("function getComposerPrimaryAction", idx)]
+        assert "name==='queue'" in body and "return 'queue'" in body, (
+            "typing /queue <message> should show the queue/list-end button even in another busy mode"
+        )
+        assert "name==='steer'" in body and "return 'steer'" in body, (
+            "typing /steer <message> should show the steer/compass button even when the global mode is queue"
+        )
+        assert "name==='interrupt'" in body and "return 'interrupt'" in body, (
+            "typing /interrupt <message> should show the interrupt/skip-forward button even in another busy mode"
+        )
+        assert "if(!args) return null" in body, (
+            "partial slash commands without a payload should not override the primary button while the user is still typing"
+        )
+
+    def test_send_button_click_uses_primary_action_handler(self):
+        assert "function handleComposerPrimaryAction()" in UI_JS, (
+            "btnSend click should route through a primary action handler so Stop can cancel instead of sending"
+        )
+        assert "handleComposerPrimaryAction" in BOOT_JS, (
+            "boot.js should wire btnSend to handleComposerPrimaryAction(), not directly to send()"
+        )
+
+
+class TestSendBusyBranchDispatch:
+    """send()'s busy block must read window._busyInputMode and branch accordingly."""
+
+    def test_send_reads_busy_input_mode(self):
+        # The send() function should read window._busyInputMode in the busy block
+        send_idx = MESSAGES_JS.find("async function send(")
+        assert send_idx >= 0
+        # Look in the first ~3000 chars of send() for the busy mode read
+        send_body = MESSAGES_JS[send_idx:send_idx + 3000]
+        assert "_busyInputMode" in send_body, (
+            "send() must read window._busyInputMode in the S.busy branch"
+        )
+
+    def test_send_calls_cancel_stream_on_interrupt(self):
+        send_idx = MESSAGES_JS.find("async function send(")
+        send_body = MESSAGES_JS[send_idx:send_idx + 3000]
+        # The interrupt branch must call cancelStream
+        assert "cancelStream" in send_body
+        # And queue before cancel (otherwise the drain has nothing to pick up)
+        # Verify the order textually: queueSessionMessage appears before cancelStream
+        # within the busy block's interrupt branch
+        cancel_idx = send_body.find("cancelStream")
+        queue_idx = send_body.find("queueSessionMessage")
+        assert queue_idx >= 0 and cancel_idx >= 0
+        assert queue_idx < cancel_idx, (
+            "queueSessionMessage must run before cancelStream so the drain "
+            "after setBusy(false) picks up the queued message"
+        )
+
+
+    def test_slash_commands_intercepted_before_busymode_routing(self):
+        """The three busy-control slash commands (/steer /interrupt /queue) must be
+        intercepted at the TOP of the busy block — before the busyMode routing — so
+        they execute immediately while the agent is running.
+
+        Without this intercept, typing /steer while busy queues the text as a plain
+        message.  When it drains after the turn ends there is no active stream, so
+        cmdSteer says "No active task to stop." and the steer is lost entirely.
+        """
+        send_idx = MESSAGES_JS.find("async function send(")
+        assert send_idx >= 0, "send() not found"
+        # Look in the first 500 chars of the busy block for the intercept
+        busy_start = MESSAGES_JS.find("S.busy||compressionRunning", send_idx)
+        assert busy_start >= 0, "busy block not found"
+        # The intercept must appear BEFORE the busyMode assignment
+        intercept_idx = MESSAGES_JS.find("'steer','interrupt','queue'", busy_start)
+        busymode_idx = MESSAGES_JS.find("_busyInputMode||'queue'", busy_start)
+        assert intercept_idx >= 0, (
+            "send() must intercept /steer /interrupt /queue before the busyMode "
+            "routing block — otherwise they queue instead of executing immediately"
+        )
+        assert intercept_idx < busymode_idx, (
+            "The slash-command intercept must come BEFORE the busyMode routing "
+            "so /steer executes while the agent is running, not after the turn ends"
+        )
+
+    def test_steer_intercept_calls_handler_directly(self):
+        """The busy-intercept must dispatch via _bc.fn(_pc.args), not queue the text."""
+        send_idx = MESSAGES_JS.find("async function send(")
+        busy_start = MESSAGES_JS.find("S.busy||compressionRunning", send_idx)
+        intercept_idx = MESSAGES_JS.find("'steer','interrupt','queue'", busy_start)
+        assert intercept_idx >= 0
+        # Get the intercept block (up to the next busyMode assignment)
+        busymode_idx = MESSAGES_JS.find("_busyInputMode||'queue'", busy_start)
+        intercept_block = MESSAGES_JS[intercept_idx:busymode_idx]
+        assert "_bc.fn(_pc.args)" in intercept_block, (
+            "The intercept must call the command handler directly via _bc.fn(_pc.args)"
+        )
+        assert "return;" in intercept_block, (
+            "The intercept must return after dispatching so send() does not also queue"
+        )
+
+    def test_steer_intercept_clears_input_before_await(self):
+        """The intercept must clear $('msg').value BEFORE awaiting the handler.
+
+        Without the sync clear, the input field still shows '/steer foo' after
+        the steer fires. If the user presses Enter again (a common reflex while
+        waiting for the toast), send() re-runs and either re-fires the command
+        or — once the turn ended — drops a confusing 'No active task to stop.'
+        """
+        send_idx = MESSAGES_JS.find("async function send(")
+        busy_start = MESSAGES_JS.find("S.busy||compressionRunning", send_idx)
+        intercept_idx = MESSAGES_JS.find("'steer','interrupt','queue'", busy_start)
+        busymode_idx = MESSAGES_JS.find("_busyInputMode||'queue'", busy_start)
+        intercept_block = MESSAGES_JS[intercept_idx:busymode_idx]
+        clear_idx = intercept_block.find("$('msg').value=''")
+        await_idx = intercept_block.find("await _bc.fn")
+        assert clear_idx >= 0, (
+            "The intercept must clear $('msg').value (so the field doesn't keep "
+            "showing /steer foo after the command fires)"
+        )
+        assert await_idx >= 0, "await _bc.fn(...) must be present in the intercept"
+        assert clear_idx < await_idx, (
+            "$('msg').value='' must be cleared BEFORE awaiting the handler — "
+            "otherwise a reflexive Enter press during the await re-fires the command"
+        )
+
+
+# ── Boot init + settings panel wiring ───────────────────────────────────
+
+class TestBootAndPanelsWiring:
+    def test_boot_init_default_path(self):
+        """Boot success path initialises window._busyInputMode from settings."""
+        assert "window._busyInputMode=(s.busy_input_mode||'queue')" in BOOT_JS
+
+    def test_boot_init_fallback_path(self):
+        """Boot fallback path (settings load failed) initialises to safe default."""
+        # The fallback should set window._busyInputMode='queue'
+        assert "window._busyInputMode='queue'" in BOOT_JS
+
+    def test_panels_load_save_apply(self):
+        assert "settingsBusyInputMode" in PANELS_JS, "panels.js must load the setting"
+        assert "body.busy_input_mode" in PANELS_JS, "saveSettings must include busy_input_mode in body"
+        assert "window._busyInputMode=body.busy_input_mode" in PANELS_JS, (
+            "_applySavedSettingsUi must propagate busy_input_mode to the global"
+        )
+
+    def test_index_html_dropdown_has_three_options(self):
+        idx = INDEX_HTML.find('id="settingsBusyInputMode"')
+        assert idx >= 0
+        block = INDEX_HTML[idx:idx + 800]
+        assert 'value="queue"' in block
+        assert 'value="interrupt"' in block
+        assert 'value="steer"' in block
+
+
+# ── i18n locale coverage ─────────────────────────────────────────────────
+
+class TestI18nKeys:
+    """All 17 new keys must appear in each of the 6 locale blocks."""
+
+    REQUIRED_KEYS = [
+        "cmd_queue",
+        "cmd_interrupt",
+        "cmd_steer",
+        "cmd_queue_no_msg",
+        "cmd_queue_not_busy",
+        "cmd_queue_confirm",
+        "cmd_interrupt_no_msg",
+        "cmd_interrupt_confirm",
+        "cmd_steer_no_msg",
+        "cmd_steer_fallback",
+        "busy_steer_fallback",
+        "busy_interrupt_confirm",
+        "settings_label_busy_input_mode",
+        "settings_desc_busy_input_mode",
+        "settings_busy_input_mode_queue",
+        "settings_busy_input_mode_interrupt",
+        "settings_busy_input_mode_steer",
+    ]
+
+    def test_each_key_appears_at_least_six_times(self):
+        """Each key should appear once per locale (en, ru, es, de, zh, zh-Hant) = 6 occurrences minimum."""
+        for key in self.REQUIRED_KEYS:
+            count = I18N_JS.count(f"{key}:")
+            assert count >= 6, (
+                f"i18n key {key!r} appears {count} times; expected ≥6 (one per locale block)"
+            )
+
+    def test_key_count_total(self):
+        """17 keys × 6 locales = 102 minimum occurrences across the file."""
+        total = sum(I18N_JS.count(f"{key}:") for key in self.REQUIRED_KEYS)
+        assert total >= 17 * 6, (
+            f"Total i18n occurrences = {total}; expected ≥ {17*6}"
+        )

tests/test_1079_cron_session_project.py

@@ -0,0 +1,94 @@
+"""Tests for #1079: Auto-assign cron job sessions to dedicated 'Cron Jobs' project."""
+
+import json
+import pathlib
+import shutil
+import tempfile
+
+import pytest
+
+from tests.conftest import TEST_STATE_DIR, _post, TEST_BASE
+
+pytestmark = pytest.mark.usefixtures("test_server")
+
+
+def _get_projects(base_url):
+    """Fetch the project list from the API."""
+    import urllib.request
+    with urllib.request.urlopen(base_url + "/api/projects", timeout=5) as r:
+        return json.loads(r.read())
+
+
+def test_ensure_cron_project_creates_project():
+    """ensure_cron_project() should create a 'Cron Jobs' project if none exists."""
+    from api.models import ensure_cron_project, load_projects, save_projects
+
+    # Remove any existing Cron Jobs project to test creation
+    projects = load_projects()
+    original = [p for p in projects if p.get('name') != 'Cron Jobs']
+    save_projects(original)
+
+    pid = ensure_cron_project()
+
+    # Should now exist
+    projects = load_projects()
+    cron_projects = [p for p in projects if p.get('name') == 'Cron Jobs']
+    assert len(cron_projects) == 1
+    assert cron_projects[0]['project_id'] == pid
+    assert cron_projects[0]['color'] == '#6366f1'
+    assert len(pid) == 12
+
+    # Restore
+    save_projects(projects)
+
+
+def test_ensure_cron_project_idempotent():
+    """Calling ensure_cron_project() twice should return the same ID."""
+    from api.models import ensure_cron_project, load_projects, save_projects
+
+    projects = load_projects()
+    save_projects([p for p in projects if p.get('name') != 'Cron Jobs'])
+
+    pid1 = ensure_cron_project()
+    pid2 = ensure_cron_project()
+    assert pid1 == pid2
+
+
+def test_is_cron_session():
+    """is_cron_session should detect cron sessions by source_tag or ID prefix."""
+    from api.models import is_cron_session
+
+    # By source_tag
+    assert is_cron_session("any_id", source_tag="cron") is True
+    assert is_cron_session("any_id", source_tag="cli") is False
+
+    # By session ID prefix
+    assert is_cron_session("cron_abc123") is True
+    assert is_cron_session("cron_") is True
+    assert is_cron_session("regular_session") is False
+    assert is_cron_session(None) is False
+    assert is_cron_session("") is False
+
+
+def test_cron_jobs_project_i18n_key_exists():
+    """Every shipped locale must have the cron_jobs_project i18n key.
+
+    Test was originally written for 8 locales; v0.50.264 added Japanese,
+    bringing the count to 9. Use >= so future locale additions don't
+    require touching this test.
+    """
+    i18n_path = pathlib.Path(__file__).resolve().parent.parent / "static" / "i18n.js"
+    content = i18n_path.read_text(encoding="utf-8")
+
+    # Count occurrences of cron_jobs_project
+    count = content.count("cron_jobs_project:")
+    assert count >= 9, f"Expected >= 9 locale entries for cron_jobs_project, found {count}"
+
+
+def test_cron_session_gets_project_id_in_cli_list():
+    """get_cli_sessions() should assign project_id for cron sessions."""
+    from api.models import get_cli_sessions
+    # Just verify the function is callable and returns a list
+    # The actual project assignment is tested indirectly via integration
+    sessions = get_cli_sessions()
+    assert isinstance(sessions, list)

tests/test_1325_user_fenced_code.py

@@ -0,0 +1,123 @@
+"""Tests for issue #1325 — fenced code blocks in user message bubbles."""
+import os
+import subprocess
+import tempfile
+
+UI_JS = os.path.join(os.path.dirname(__file__), '..', 'static', 'ui.js')
+
+
+def _extract_js_functions():
+    """Extract esc and _renderUserFencedBlocks from ui.js by line numbers."""
+    lines = open(UI_JS).read().split('\n')
+    # esc is on line 52 (0-indexed: 51)
+    esc_def = lines[51]
+    # _renderUserFencedBlocks starts at line 61 (0-indexed: 60)
+    # Find the end by matching closing brace at column 0
+    fn_lines = []
+    i = 60  # 0-indexed
+    depth = 0
+    while i < len(lines):
+        fn_lines.append(lines[i])
+        depth += lines[i].count('{') - lines[i].count('}')
+        if depth <= 0:
+            break
+        i += 1
+    fn_def = '\n'.join(fn_lines)
+    return esc_def, fn_def
+
+
+def _run_user_render(text_input):
+    """Return the HTML output of _renderUserFencedBlocks for the given input text."""
+    import json
+    esc_def, fn_def = _extract_js_functions()
+    js_code = esc_def + '\n' + fn_def + '\n'
+    js_code += 'var input = JSON.parse(process.argv[2]);\n'
+    js_code += 'process.stdout.write(_renderUserFencedBlocks(input));\n'
+    tf = tempfile.NamedTemporaryFile(mode='w', suffix='.js', delete=False, encoding='utf-8')
+    tf.write(js_code)
+    tf.close()
+    try:
+        result = subprocess.run(
+            ['node', tf.name, json.dumps(text_input)],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"node error: {result.stderr}")
+        return result.stdout
+    finally:
+        os.unlink(tf.name)
+
+
+class TestUserFencedBlocks:
+    """Fenced code blocks in user messages should render as <pre><code>."""
+
+    def test_simple_fenced_block(self):
+        out = _run_user_render("hello\n```python\nprint(1)\n```\nworld")
+        assert '<pre><code class="language-python">' in out
+        assert 'print(1)' in out
+        # Newlines around the fenced block become <br> (same as original plain-text path)
+        assert 'hello<br>' in out
+        assert '<br>world' in out
+
+    def test_fenced_block_escaped_html(self):
+        """HTML in code blocks should be escaped."""
+        out = _run_user_render("```html\n<div>hi</div>\n```")
+        assert '&lt;div&gt;' in out
+        # No raw <div> in code content
+        assert '<div>' not in out.replace('&lt;div&gt;', '').replace('&gt;', '')
+
+    def test_plain_text_not_interpreted_as_markdown(self):
+        """Bold/italic/links in non-fenced text should stay escaped."""
+        out = _run_user_render("**bold** and *italic* and <script>alert(1)</script>")
+        assert '**bold**' in out
+        assert '*italic*' in out
+        assert '&lt;script&gt;' in out
+        assert '<strong>' not in out
+
+    def test_language_header_shown(self):
+        out = _run_user_render("```javascript\nconst x = 1;\n```")
+        assert 'class="pre-header"' in out
+        assert 'javascript' in out
+
+    def test_no_language_no_header(self):
+        out = _run_user_render("```\nsome code\n```")
+        assert 'class="pre-header"' not in out
+        assert '<pre><code>' in out
+        assert 'some code' in out
+
+    def test_diff_block_colored(self):
+        out = _run_user_render("```diff\n+added\n-removed\n```")
+        assert 'diff-block' in out
+        assert 'diff-plus' in out
+        assert 'diff-minus' in out
+
+    def test_multiple_fenced_blocks(self):
+        out = _run_user_render("first\n```python\n1\n```\nmiddle\n```js\n2\n```\nlast")
+        assert 'language-python' in out
+        assert 'language-js' in out
+        assert 'first<br>' in out
+        assert '<br>last' in out
+
+    def test_fenced_block_with_ampersand(self):
+        out = _run_user_render("```python\nx & y\n```")
+        assert 'x &amp; y' in out
+
+    def test_empty_code_block(self):
+        out = _run_user_render("```\n```")
+        assert '<pre><code>' in out
+
+    def test_special_chars_outside_blocks_escaped(self):
+        out = _run_user_render("a < b > c & d")
+        assert 'a &lt; b &gt; c &amp; d' in out
+
+    def test_links_not_rendered_in_plain_text(self):
+        """URLs in plain text should NOT become clickable links."""
+        out = _run_user_render("Check https://example.com for details")
+        assert '<a ' not in out
+        assert 'https://example.com' in out
+
+    def test_inline_backticks_not_touched(self):
+        """Inline backticks (single backtick, not fenced block) should remain escaped as text."""
+        out = _run_user_render("use `var x = 1` here")
+        assert '`var x = 1`' in out
+        assert '<code>' not in out

tests/test_1432_newchat_and_1423_profile_input.py

@@ -0,0 +1,122 @@
+"""
+Regression tests for #1432 (new-chat empty-session guard ignores in-flight streams)
+and #1423 (profile name input lacks autocapitalize/spellcheck attrs).
+
+Both bugs ship as static-asset diffs verified by reading the JS files.
+"""
+import os
+import re
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), '..', 'static')
+
+
+def _read(filename):
+    return open(os.path.join(STATIC_DIR, filename), encoding='utf-8').read()
+
+
+class TestIssue1432NewChatGuardInFlight:
+    """`+` button and Cmd/Ctrl+K must create a new chat even while the current
+    session is still streaming. The empty-session guard from #1171 was checking
+    `message_count===0` only, which is true the entire time the first user
+    message is in flight (server-side count not yet updated). The guard now
+    also requires `!S.busy && !S.session.active_stream_id &&
+    !S.session.pending_user_message` — same in-flight signal used at
+    `static/messages.js:_restoreSettledSession()`.
+    """
+
+    def test_btnNewChat_handler_checks_in_flight_state(self):
+        src = _read('boot.js')
+        # Locate the btnNewChat onclick handler
+        m = re.search(
+            r"\$\('btnNewChat'\)\.onclick=async\(\)=>\{(.*?)\};",
+            src, re.DOTALL,
+        )
+        assert m, "btnNewChat onclick handler not found in boot.js"
+        body = m.group(1)
+        # The empty-session guard must check all three in-flight signals
+        assert 'message_count' in body, \
+            "btnNewChat guard missing message_count check"
+        assert 'S.busy' in body, \
+            "btnNewChat guard missing S.busy check (#1432)"
+        assert 'active_stream_id' in body, \
+            "btnNewChat guard missing active_stream_id check (#1432)"
+        assert 'pending_user_message' in body, \
+            "btnNewChat guard missing pending_user_message check (#1432)"
+
+    def test_cmdK_handler_checks_in_flight_state(self):
+        src = _read('boot.js')
+        # Locate the Cmd/Ctrl+K branch — it sits inside a keydown listener
+        idx = src.find("(e.metaKey||e.ctrlKey)&&e.key==='k'")
+        assert idx >= 0, "Cmd/Ctrl+K handler not found in boot.js"
+        # Read the next ~1500 chars (handler body)
+        body = src[idx:idx + 1500]
+        assert 'message_count' in body, \
+            "Cmd/Ctrl+K guard missing message_count check"
+        assert 'S.busy' in body, \
+            "Cmd/Ctrl+K guard missing S.busy check (#1432)"
+        assert 'active_stream_id' in body, \
+            "Cmd/Ctrl+K guard missing active_stream_id check (#1432)"
+        assert 'pending_user_message' in body, \
+            "Cmd/Ctrl+K guard missing pending_user_message check (#1432)"
+
+    def test_in_flight_signal_matches_restoreSettledSession(self):
+        """The new in-flight check uses the same signal as the canonical
+        'session is in flight' detector at messages.js:_restoreSettledSession.
+        Verifying both files use the same shape so future refactors don't
+        diverge."""
+        msgs_src = _read('messages.js')
+        # The canonical detector
+        assert 'session.active_stream_id||session.pending_user_message' in msgs_src, \
+            "Canonical in-flight detector at _restoreSettledSession changed shape — " \
+            "boot.js #1432 fix uses the same signals; keep them aligned"
+
+
+class TestIssue1423ProfileFormAutocapitalize:
+    """Profile name and base-url inputs must suppress browser
+    auto-capitalization, autocorrect, and spell-check. Without these
+    attributes, mobile keyboards (iOS/Android) capitalize the first letter
+    and desktop spellcheck can rewrite the typed value on blur — even though
+    the placeholder/hint says lowercase only. The form lowercases on submit
+    so stored data is correct; the bug is purely a misleading display."""
+
+    def _profile_input_html(self, input_id):
+        src = _read('panels.js')
+        # Match the input element — pull the full opening tag
+        m = re.search(
+            rf'<input\s+[^>]*id="{re.escape(input_id)}"[^>]*>',
+            src,
+        )
+        return m.group(0) if m else None
+
+    def test_profile_name_has_autocapitalize_none(self):
+        html = self._profile_input_html('profileFormName')
+        assert html, "profileFormName input not found in panels.js"
+        assert 'autocapitalize="none"' in html, \
+            f"profileFormName missing autocapitalize=\"none\" (#1423): {html}"
+
+    def test_profile_name_has_spellcheck_false(self):
+        html = self._profile_input_html('profileFormName')
+        assert html, "profileFormName input not found"
+        assert 'spellcheck="false"' in html, \
+            f"profileFormName missing spellcheck=\"false\" (#1423): {html}"
+
+    def test_profile_name_has_autocorrect_off(self):
+        html = self._profile_input_html('profileFormName')
+        assert html, "profileFormName input not found"
+        assert 'autocorrect="off"' in html, \
+            f"profileFormName missing autocorrect=\"off\" (#1423): {html}"
+
+    def test_profile_name_keeps_required(self):
+        """Regression guard: required must still be present."""
+        html = self._profile_input_html('profileFormName')
+        assert ' required' in html, \
+            f"profileFormName lost required attribute: {html}"
+
+    def test_profile_baseurl_has_autocapitalize_none(self):
+        """Base URL inputs are equally bad targets for autocapitalize."""
+        html = self._profile_input_html('profileFormBaseUrl')
+        assert html, "profileFormBaseUrl input not found"
+        assert 'autocapitalize="none"' in html, \
+            f"profileFormBaseUrl missing autocapitalize=\"none\" (#1423)"
+        assert 'spellcheck="false"' in html, \
+            f"profileFormBaseUrl missing spellcheck=\"false\" (#1423)"

tests/test_1466_bfcache_inflight_reattach.py

@@ -0,0 +1,66 @@
+"""Regression coverage for BFCache restore of an in-flight session (#1466).
+
+A browser `pageshow` restore from BFCache does not re-run the boot IIFE. After
+#1473, normal reload restores in-flight sessions through `loadSession()` and
+`checkInflightOnBoot()`. BFCache restore should align with that path for the
+currently viewed session instead of only refreshing layout chrome/sidebar cache.
+"""
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parent.parent
+BOOT_JS = (REPO_ROOT / "static" / "boot.js").read_text(encoding="utf-8")
+
+
+def _pageshow_handler() -> str:
+    marker = "window.addEventListener('pageshow'"
+    start = BOOT_JS.find(marker)
+    assert start != -1, "pageshow listener not found in boot.js"
+    brace = BOOT_JS.find("=> {", start)
+    assert brace != -1, "pageshow listener body not found"
+    brace = BOOT_JS.find("{", brace)
+    depth = 1
+    i = brace + 1
+    while i < len(BOOT_JS) and depth:
+        if BOOT_JS[i] == "{":
+            depth += 1
+        elif BOOT_JS[i] == "}":
+            depth -= 1
+        i += 1
+    assert depth == 0, "pageshow listener body did not close"
+    return BOOT_JS[brace + 1 : i - 1]
+
+
+def test_pageshow_restores_active_inflight_session_through_load_session():
+    """BFCache restore should refresh active session metadata and reattach stream.
+
+    The normal boot/reload path now calls loadSession(saved), which handles
+    active_stream_id / pending_user_message and reattaches via attachLiveStream().
+    The BFCache pageshow path must call the same loadSession path for the current
+    active session because the boot IIFE does not run again.
+    """
+    body = _pageshow_handler()
+    assert "S.session" in body and "S.session.session_id" in body
+    assert "loadSession(S.session.session_id" in body
+
+
+def test_pageshow_checks_persisted_inflight_marker_after_restoring_session():
+    """BFCache restore should preserve the reload recovery marker behavior.
+
+    If localStorage still has an inflight marker, the pageshow path should reuse
+    checkInflightOnBoot() after restoring the active session, matching the normal
+    reload path without adding new server-side persistence behavior.
+    """
+    body = _pageshow_handler()
+    load_pos = body.find("loadSession(S.session.session_id")
+    check_pos = body.find("checkInflightOnBoot(S.session.session_id")
+    assert load_pos != -1
+    assert check_pos != -1
+    assert load_pos < check_pos
+
+
+def test_pageshow_active_session_restore_is_guarded_and_non_blocking():
+    """pageshow handler must degrade safely when optional helpers are absent."""
+    body = _pageshow_handler()
+    assert "typeof loadSession === 'function'" in body
+    assert "typeof checkInflightOnBoot === 'function'" in body
+    assert "catch" in body[body.find("loadSession(S.session.session_id") : body.find("startGatewaySSE")]

tests/test_1466_sidebar_cancel_clarify.py

@@ -0,0 +1,54 @@
+"""Regression coverage for issue #1466 sidebar cancel ownership.
+
+The active pane is only a projection; running state belongs to the session that
+owns the stream. Cancelling a running session from the sidebar context menu must
+address that session's stream id and must only clear approval/clarify UI owned by
+that session.
+"""
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+BOOT_JS = (ROOT / "static" / "boot.js").read_text(encoding="utf-8")
+SESSIONS_JS = (ROOT / "static" / "sessions.js").read_text(encoding="utf-8")
+
+
+def _function_body(src: str, name: str, window: int = 1800) -> str:
+    idx = src.find(f"function {name}(")
+    assert idx >= 0, f"{name} not found"
+    return src[idx : idx + window]
+
+
+class TestSidebarCancelAction:
+    def test_running_sidebar_sessions_get_stop_action(self):
+        """Running sessions need a context-menu cancel action even when not active pane."""
+        body = _function_body(SESSIONS_JS, "_openSessionActionMenu", 3200)
+        assert "session.active_stream_id" in body, (
+            "sidebar action menu must detect per-session active_stream_id instead of S.activeStreamId"
+        )
+        assert "cancelSessionStream(session)" in body, (
+            "running sidebar sessions must expose a stop action that cancels that session"
+        )
+        assert body.find("cancelSessionStream(session)") < body.find("deleteSession(session.session_id)"), (
+            "stop action should appear before destructive delete action"
+        )
+
+    def test_cancel_session_stream_uses_session_owned_stream_id(self):
+        """Cancel-from-sidebar must call /api/chat/cancel with the row's stream id."""
+        body = _function_body(BOOT_JS, "cancelSessionStream")
+        assert "session&&session.active_stream_id" in body or "session && session.active_stream_id" in body
+        assert "stream_id=${encodeURIComponent(streamId)}" in body
+        assert "S.activeStreamId" not in body.split("const streamId", 1)[1].split("fetch", 1)[0], (
+            "sidebar cancel must not derive the stream id from the active pane global"
+        )
+
+    def test_cancel_session_stream_clears_only_owned_clarify_and_approval_cards(self):
+        """Cancelling A from sidebar must not blanket-clear B's clarify/approval cards."""
+        body = _function_body(BOOT_JS, "cancelSessionStream")
+        assert "_clarifySessionId===sid" in body, (
+            "clarify card cleanup must be gated to the cancelled session id"
+        )
+        assert "_approvalSessionId===sid" in body, (
+            "approval card cleanup must be gated to the cancelled session id"
+        )
+        assert "hideClarifyCard(true" in body
+        assert "hideApprovalCard(true" in body

tests/test_465_session_branching.py

@@ -0,0 +1,273 @@
+"""Tests for issue #465 — session branching (/branch).
+
+Verifies:
+  1. Backend endpoint POST /api/session/branch exists in routes.py
+  2. Session model supports parent_session_id field
+  3. Frontend /branch slash command is registered
+  4. forkFromMessage function exists in commands.js
+  5. Fork button (git-branch icon) is rendered in ui.js message actions
+  6. Parent session indicator (⑂) is rendered in sessions.js sidebar
+  7. i18n keys exist for all branch-related strings
+  8. git-branch icon exists in icons.js
+"""
+import re
+
+
+# ── Backend ────────────────────────────────────────────────────────────────────
+
+def test_branch_endpoint_exists():
+    """Verify the POST /api/session/branch route handler exists."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    assert '"POST /api/session/branch"' in src or '"/api/session/branch"' in src, \
+        "Missing /api/session/branch route"
+
+
+def test_branch_endpoint_validates_session_id():
+    """Verify the branch endpoint requires session_id."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    # Find the branch block
+    branch_match = re.search(
+        r'parsed\.path == "/api/session/branch"(.*?)(?=\n    if parsed\.path|$)',
+        src, re.DOTALL
+    )
+    assert branch_match, "Could not find /api/session/branch handler block"
+    block = branch_match.group(1)
+    assert 'require(body, "session_id")' in block, \
+        "Branch handler should validate session_id"
+
+
+def test_branch_endpoint_returns_new_session_id():
+    """Verify the branch endpoint returns session_id and title."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    branch_match = re.search(
+        r'parsed\.path == "/api/session/branch"(.*?)(?=\n    if parsed\.path|$)',
+        src, re.DOTALL
+    )
+    assert branch_match
+    block = branch_match.group(1)
+    assert '"session_id"' in block, "Branch handler should return session_id"
+    assert '"title"' in block, "Branch handler should return title"
+    assert '"parent_session_id"' in block, \
+        "Branch handler should return parent_session_id"
+
+
+def test_branch_creates_session_with_parent():
+    """Verify the branch creates a Session with parent_session_id set."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    branch_match = re.search(
+        r'parsed\.path == "/api/session/branch"(.*?)(?=\n    if parsed\.path|$)',
+        src, re.DOTALL
+    )
+    assert branch_match
+    block = branch_match.group(1)
+    assert 'parent_session_id=source.session_id' in block, \
+        "Branch handler should set parent_session_id to source session"
+
+
+def test_branch_keep_count_support():
+    """Verify the branch endpoint supports keep_count parameter."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    branch_match = re.search(
+        r'parsed\.path == "/api/session/branch"(.*?)(?=\n    if parsed\.path|$)',
+        src, re.DOTALL
+    )
+    assert branch_match
+    block = branch_match.group(1)
+    assert 'keep_count' in block, "Branch handler should support keep_count"
+    assert 'forked_messages = source_messages[:keep_count]' in block, \
+        "Branch handler should slice messages by keep_count"
+
+
+def test_branch_auto_title():
+    """Verify fork title defaults to '<original> (fork)'."""
+    with open('api/routes.py') as f:
+        src = f.read()
+    branch_match = re.search(
+        r'parsed\.path == "/api/session/branch"(.*?)(?=\n    if parsed\.path|$)',
+        src, re.DOTALL
+    )
+    assert branch_match
+    block = branch_match.group(1)
+    assert '(fork)' in block, "Branch handler should auto-title as '(fork)'"
+
+
+# ── Session model ──────────────────────────────────────────────────────────────
+
+def test_session_model_parent_session_id():
+    """Verify Session model supports parent_session_id."""
+    with open('api/models.py') as f:
+        src = f.read()
+    assert 'parent_session_id' in src, "Session model should have parent_session_id"
+    # Check __init__ parameter
+    assert 'parent_session_id: str=None' in src, \
+        "Session.__init__ should accept parent_session_id parameter"
+    # Check it's set on self
+    assert 'self.parent_session_id = parent_session_id' in src, \
+        "Session.__init__ should assign parent_session_id"
+
+
+def test_session_compact_includes_parent():
+    """Verify compact() includes parent_session_id."""
+    with open('api/models.py') as f:
+        src = f.read()
+    # Use simpler search - find the compact method and check for parent_session_id after it
+    compact_def_match = re.search(r"def compact\(self", src)
+    assert compact_def_match, "Could not find compact() method"
+    # Check the next 1000 chars after def compact for parent_session_id
+    snippet = src[compact_def_match.start():compact_def_match.start() + 1500]
+    assert "'parent_session_id'" in snippet, \
+        "compact() should include parent_session_id"
+
+
+def test_session_metadata_fields_includes_parent():
+    """Verify parent_session_id is in METADATA_FIELDS for persistence."""
+    with open('api/models.py') as f:
+        src = f.read()
+    assert "'parent_session_id'" in src, \
+        "METADATA_FIELDS should include parent_session_id"
+
+
+# ── Frontend: slash command ────────────────────────────────────────────────────
+
+def test_branch_slash_command_registered():
+    """Verify /branch is registered as a slash command."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    assert "name:'branch'" in src, "/branch should be registered as a command"
+    assert 'cmdBranch' in src, "cmdBranch handler should be defined"
+
+
+def test_cmdBranch_function_exists():
+    """Verify cmdBranch function is defined."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    assert 'async function cmdBranch(' in src, \
+        "cmdBranch should be an async function"
+
+
+def test_cmdBranch_calls_branch_endpoint():
+    """Verify cmdBranch calls the /api/session/branch endpoint."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    branch_fn = re.search(r'async function cmdBranch\(.*?\n\}', src, re.DOTALL)
+    assert branch_fn, "Could not find cmdBranch function"
+    block = branch_fn.group(0)
+    assert "'/api/session/branch'" in block, \
+        "cmdBranch should call /api/session/branch"
+
+
+def test_cmdBranch_switches_session():
+    """Verify cmdBranch calls loadSession after branching."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    branch_fn = re.search(r'async function cmdBranch\(.*?\n\}', src, re.DOTALL)
+    assert branch_fn
+    block = branch_fn.group(0)
+    assert 'loadSession(' in block, \
+        "cmdBranch should switch to the new session via loadSession"
+
+
+# ── Frontend: forkFromMessage ─────────────────────────────────────────────────
+
+def test_forkFromMessage_function_exists():
+    """Verify forkFromMessage function exists."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    assert 'async function forkFromMessage(' in src, \
+        "forkFromMessage should be defined"
+
+
+def test_forkFromMessage_passes_keep_count():
+    """Verify forkFromMessage passes keep_count to the endpoint."""
+    with open('static/commands.js') as f:
+        src = f.read()
+    fn = re.search(r'async function forkFromMessage\(.*?\n\}', src, re.DOTALL)
+    assert fn
+    block = fn.group(0)
+    assert 'keep_count' in block, \
+        "forkFromMessage should pass keep_count to /api/session/branch"
+
+
+# ── Frontend: fork button in messages ──────────────────────────────────────────
+
+def test_fork_button_rendered_in_ui():
+    """Verify fork button is rendered in message actions."""
+    with open('static/ui.js') as f:
+        src = f.read()
+    assert "forkBtn" in src, "forkBtn variable should exist in ui.js"
+    assert "fork_from_here" in src, \
+        "fork_from_here i18n key should be referenced for tooltip"
+    assert "forkFromMessage(" in src, \
+        "forkFromMessage should be called from the button"
+
+
+def test_fork_button_in_message_actions():
+    """Verify fork button is included in the msg-actions span."""
+    with open('static/ui.js') as f:
+        src = f.read()
+    # The footHtml template should include forkBtn
+    assert '${forkBtn}' in src, \
+        "forkBtn should be included in message actions template"
+
+
+# ── Frontend: sidebar parent indicator ────────────────────────────────────────
+
+def test_sidebar_parent_indicator():
+    """Verify parent session indicator is rendered in session list."""
+    with open('static/sessions.js') as f:
+        src = f.read()
+    assert 'parent_session_id' in src, \
+        "sessions.js should check parent_session_id"
+    assert 'session-branch-indicator' in src, \
+        "Should have session-branch-indicator class"
+    assert '\\u2442' in src, \
+        "Should use ⑂ character for parent indicator"
+
+
+def test_parent_indicator_clickable():
+    """Verify parent indicator navigates to parent session on click."""
+    with open('static/sessions.js') as f:
+        src = f.read()
+    # Find the parent indicator block
+    parent_block = re.search(
+        r'branch-indicator[\s\S]*?parent_session_id[\s\S]*?titleRow\.appendChild',
+        src
+    )
+    assert parent_block, "Could not find parent indicator block"
+    block = parent_block.group(0)
+    assert 'loadSession(' in block, \
+        "Parent indicator should call loadSession on click"
+
+
+# ── Frontend: i18n keys ────────────────────────────────────────────────────────
+
+def test_i18n_branch_keys():
+    """Verify all branch-related i18n keys exist in English locale."""
+    with open('static/i18n.js') as f:
+        src = f.read()
+    required_keys = [
+        'cmd_branch',
+        'cmd_branch_usage',
+        'branch_forked',
+        'branch_failed',
+        'fork_from_here',
+        'forked_from',
+    ]
+    for key in required_keys:
+        assert f"{key}:" in src or f"{key} :" in src, \
+            f"Missing i18n key: {key}"
+
+
+# ── Frontend: icon ─────────────────────────────────────────────────────────────
+
+def test_git_branch_icon_exists():
+    """Verify git-branch icon is defined in icons.js."""
+    with open('static/icons.js') as f:
+        src = f.read()
+    assert "'git-branch'" in src, \
+        "git-branch icon should be defined in LI_PATHS"

tests/test_499_tts_playback.py

@@ -0,0 +1,249 @@
+"""
+Tests for #499: TTS playback of agent responses via Web Speech API.
+
+Verifies that TTS utility functions, speaker button rendering, and
+settings controls are present in the WebUI codebase.
+"""
+import os
+import re
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), '..', 'static')
+
+
+def _read(filename):
+    return open(os.path.join(STATIC_DIR, filename), encoding='utf-8').read()
+
+
+class TestTtsUtilityFunctions:
+    """TTS core functions exist in ui.js."""
+
+    def test_strip_for_tts_exists(self):
+        src = _read('ui.js')
+        assert 'function _stripForTTS(' in src, \
+            "_stripForTTS function not found in ui.js"
+
+    def test_speak_message_exists(self):
+        src = _read('ui.js')
+        assert 'function speakMessage(' in src, \
+            "speakMessage function not found in ui.js"
+
+    def test_stop_tts_exists(self):
+        src = _read('ui.js')
+        assert 'function stopTTS(' in src, \
+            "stopTTS function not found in ui.js"
+
+    def test_auto_read_exists(self):
+        src = _read('ui.js')
+        assert 'function autoReadLastAssistant(' in src, \
+            "autoReadLastAssistant function not found in ui.js"
+
+    def test_strip_code_blocks(self):
+        """_stripForTTS must remove ``` code blocks."""
+        src = _read('ui.js')
+        assert re.search(r'_stripForTTS.*```', src, re.DOTALL), \
+            "_stripForTTS must handle fenced code blocks"
+
+    def test_strip_media_paths(self):
+        """_stripForTTS must replace MEDIA: paths."""
+        src = _read('ui.js')
+        assert 'MEDIA:' in src and 'a file' in src, \
+            "_stripForTTS must replace MEDIA: paths"
+
+    def test_uses_speech_synthesis(self):
+        """speakMessage must use window.speechSynthesis."""
+        src = _read('ui.js')
+        assert 'SpeechSynthesisUtterance' in src, \
+            "speakMessage must create SpeechSynthesisUtterance"
+        assert 'speechSynthesis.speak' in src, \
+            "speakMessage must call speechSynthesis.speak"
+
+
+class TestTtsSpeakerButton:
+    """Speaker button is rendered on assistant messages."""
+
+    def test_tts_button_rendered(self):
+        """ttsBtn must be generated for non-user messages."""
+        src = _read('ui.js')
+        assert 'msg-tts-btn' in src, \
+            "TTS button class not found in ui.js"
+
+    def test_tts_button_not_on_user_messages(self):
+        """ttsBtn must only be added for non-user (assistant) messages."""
+        src = _read('ui.js')
+        # Find the ttsBtn definition — it should have !isUser guard
+        tts_line = [l for l in src.splitlines() if 'msg-tts-btn' in l][0]
+        assert '!isUser' in tts_line or 'isUser' in tts_line, \
+            "TTS button should have user-check guard"
+
+    def test_tts_button_in_footer(self):
+        """ttsBtn must be included in the msg-actions span."""
+        src = _read('ui.js')
+        # The footHtml line should include ttsBtn
+        foot_lines = [l for l in src.splitlines() if 'footHtml' in l and 'msg-actions' in l]
+        assert any('ttsBtn' in l for l in foot_lines), \
+            "ttsBtn not included in footHtml msg-actions"
+
+    def test_tts_button_uses_volume_icon(self):
+        """Speaker button should use volume-2 icon."""
+        src = _read('ui.js')
+        tts_line = [l for l in src.splitlines() if 'msg-tts-btn' in l][0]
+        assert 'volume-2' in tts_line, \
+            "TTS button should use volume-2 icon"
+
+
+class TestTtsSettings:
+    """TTS settings controls exist in the HTML and are wired in panels.js."""
+
+    def test_tts_enabled_checkbox(self):
+        src = _read('index.html')
+        assert 'settingsTtsEnabled' in src, \
+            "TTS enabled checkbox not found in index.html"
+
+    def test_tts_auto_read_checkbox(self):
+        src = _read('index.html')
+        assert 'settingsTtsAutoRead' in src, \
+            "TTS auto-read checkbox not found in index.html"
+
+    def test_tts_voice_selector(self):
+        src = _read('index.html')
+        assert 'settingsTtsVoice' in src, \
+            "TTS voice selector not found in index.html"
+
+    def test_tts_rate_slider(self):
+        src = _read('index.html')
+        assert 'settingsTtsRate' in src, \
+            "TTS rate slider not found in index.html"
+
+    def test_tts_pitch_slider(self):
+        src = _read('index.html')
+        assert 'settingsTtsPitch' in src, \
+            "TTS pitch slider not found in index.html"
+
+    def test_tts_settings_wired_in_panels(self):
+        """TTS settings must be initialized in loadSettingsPanel."""
+        src = _read('panels.js')
+        assert 'settingsTtsEnabled' in src, \
+            "TTS enabled setting not wired in panels.js"
+        assert '_applyTtsEnabled' in src, \
+            "_applyTtsEnabled not called in panels.js"
+
+    def test_apply_tts_enabled_function(self):
+        """_applyTtsEnabled must toggle msg-tts-btn display."""
+        src = _read('panels.js')
+        assert 'function _applyTtsEnabled(' in src, \
+            "_applyTtsEnabled function not found in panels.js"
+
+
+class TestTtsI18n:
+    """TTS i18n keys exist in the English locale."""
+
+    def test_tts_listen_key(self):
+        src = _read('i18n.js')
+        assert "tts_listen:" in src, \
+            "tts_listen key not found in i18n.js"
+
+    def test_tts_not_supported_key(self):
+        src = _read('i18n.js')
+        assert "tts_not_supported:" in src, \
+            "tts_not_supported key not found in i18n.js"
+
+    def test_tts_settings_keys(self):
+        src = _read('i18n.js')
+        for key in ['settings_label_tts', 'settings_label_tts_auto_read',
+                     'settings_label_tts_voice', 'settings_label_tts_rate',
+                     'settings_label_tts_pitch']:
+            assert f"{key}:" in src, f"{key} not found in i18n.js"
+
+
+class TestTtsAutoRead:
+    """Auto-read is triggered after SSE done event."""
+
+    def test_auto_read_called_in_messages(self):
+        src = _read('messages.js')
+        assert 'autoReadLastAssistant' in src, \
+            "autoReadLastAssistant not called in messages.js"
+
+    def test_tts_pause_on_composer_focus(self):
+        """Speech should pause when user focuses the composer."""
+        src = _read('messages.js')
+        assert 'speechSynthesis.pause' in src, \
+            "speechSynthesis.pause not called in messages.js"
+        assert 'speechSynthesis.resume' in src, \
+            "speechSynthesis.resume not called in messages.js"
+
+
+class TestTtsBoot:
+    """TTS enabled state is applied on page load."""
+
+    def test_apply_tts_on_boot(self):
+        src = _read('boot.js')
+        assert '_applyTtsEnabled' in src, \
+            "_applyTtsEnabled not called in boot.js"
+
+
+class TestTtsStyles:
+    """TTS CSS styles exist."""
+
+    def test_tts_button_hidden_default(self):
+        src = _read('style.css')
+        assert '.msg-tts-btn' in src, \
+            ".msg-tts-btn CSS class not found in style.css"
+
+    def test_tts_pulse_animation(self):
+        src = _read('style.css')
+        assert 'tts-pulse' in src, \
+            "tts-pulse animation not found in style.css"
+
+
+class TestIssue1409TtsToggleBodyClass:
+    """Regression: #1409 — TTS toggle had no effect because of CSS specificity collision.
+
+    Original bug: ``_applyTtsEnabled`` set ``btn.style.display=enabled?'':'none'``.
+    The empty-string branch removes the inline override, after which the
+    ``.msg-tts-btn { display:none; }`` rule from style.css applies — so both
+    "enabled" and "disabled" states left the button hidden.
+
+    Fix: toggle a body-level class (``body.tts-enabled``) and gate the speaker
+    icon on a compound selector ``body.tts-enabled .msg-tts-btn``. This bypasses
+    the inline-style cascade collision and survives ``renderMd()`` re-renders.
+    """
+
+    def test_apply_tts_enabled_uses_body_class(self):
+        """_applyTtsEnabled must toggle the document body's `tts-enabled` class."""
+        src = _read('panels.js')
+        # The new shape: toggle body class instead of writing inline display
+        assert "document.body.classList.toggle('tts-enabled'" in src, (
+            "_applyTtsEnabled must toggle the body.tts-enabled class — see #1409. "
+            "Reverting to inline `style.display` will silently break the toggle "
+            "again because of the .msg-action-btn / .msg-tts-btn cascade."
+        )
+
+    def test_apply_tts_enabled_does_not_use_inline_display(self):
+        """_applyTtsEnabled must NOT set inline `style.display` on .msg-tts-btn."""
+        src = _read('panels.js')
+        # Find the function body and check it doesn't set inline display
+        # on individual buttons (the broken pattern).
+        m = re.search(
+            r'function _applyTtsEnabled\([^)]*\)\s*\{(?P<body>[^}]*)\}',
+            src,
+        )
+        assert m, "_applyTtsEnabled function body not found in panels.js"
+        body = m.group('body')
+        assert '.style.display' not in body, (
+            "_applyTtsEnabled body must not set inline style.display — that's "
+            "the #1409 bug. Use body.classList.toggle('tts-enabled') instead."
+        )
+
+    def test_body_class_selector_in_css(self):
+        """style.css must show .msg-tts-btn only when body.tts-enabled is set."""
+        src = _read('style.css')
+        assert 'body.tts-enabled .msg-tts-btn' in src, (
+            "Missing `body.tts-enabled .msg-tts-btn` selector in style.css — "
+            "without this rule the body class has no visual effect (#1409)."
+        )
+        # The default-hidden rule must still be present (so no body class = no icon).
+        assert '.msg-tts-btn{display:none;}' in src or \
+               re.search(r'\.msg-tts-btn\s*\{[^}]*display\s*:\s*none', src), (
+            "Default `.msg-tts-btn{display:none;}` rule must remain so the "
+            "icon is hidden by default (#1409)."
+        )