Merge pull request #2019 from nesquena/stage-330

Release L — v0.51.36 — Locale + provider + cross-cutting (6 PRs)

.dockerignore

@@ -0,0 +1,7 @@
+.git
+.pytest_cache
+__pycache__
+*.pyc
+*.pyo
+tests/
+.env*

.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

@@ -0,0 +1,57 @@
+name: Release & Docker
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # required: create GitHub Release
+      packages: write   # required: push to ghcr.io
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # Create GitHub Release from tag with auto-generated notes
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+      # Set up multi-arch build (QEMU + Buildx)
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      # Log in to GitHub Container Registry
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract tags from the git ref (supports vX.Y and vX.Y.Z formats)
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=match,pattern=v(\d+\.\d+(?:\.\d+)?),group=1
+            type=raw,value=latest
+
+      # Build and push multi-arch image (amd64 + arm64)
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          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,37 @@
+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 pytest-asyncio
+          # Install the `mcp` package so tests/test_mcp_server.py runs in CI.
+          # The package is an optional runtime dep of mcp_server.py — users
+          # who run the MCP integration install it themselves; CI installs
+          # it so test coverage exists. If mcp install fails (Python 3.13
+          # wheel not yet available, etc.), tests/test_mcp_server.py uses
+          # importorskip and the matrix stays green.
+          pip install mcp || echo "mcp install failed — test_mcp_server.py will importorskip"
+
+      - name: Run tests
+        run: pytest tests/ -v --timeout=60

.gitignore

@@ -12,16 +12,41 @@ __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
+!docs/troubleshooting.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,57 +7,84 @@
 >
 > 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 six vanilla JS modules loaded from static/.
+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
 
     <repo>/
-    server.py              Thin routing shell + HTTP Handler. ~76 lines. Pure Python.
+    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
     api/
       __init__.py          Package marker
-      routes.py            All GET + POST route handlers (~1016 lines)
-      config.py            Shared configuration, constants, global state, model discovery (~640 lines)
-      helpers.py           HTTP helpers: j(), bad(), require(), safe_resolve() (~57 lines)
-      models.py            Session model + CRUD (~132 lines)
+      auth.py              Optional password authentication, signed cookies (~149 lines)
+      config.py            Discovery, globals, model detection, reloadable config (~701 lines)
+      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)
-      upload.py            Multipart parser, file upload handler (~77 lines)
-      streaming.py         SSE engine, run_agent integration, cancel support (~222 lines)
     static/
-      index.html           HTML template (served from disk)
-      style.css            All CSS
-      ui.js                DOM helpers, renderMd, tool cards, model dropdown (~846 lines)
-      workspace.js         File tree, preview, file ops (~169 lines)
-      sessions.js          Session CRUD, list rendering, search, SVG icons, overlay actions (~532 lines)
-      messages.js          send(), SSE event handlers, approval, transcript (~293 lines)
-      panels.js            Cron, skills, memory, workspace, todo, switchPanel (~771 lines)
-      boot.js              Event wiring + boot IIFE (~175 lines)
+      index.html           HTML template (~364 lines)
+      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, 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)
+      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_sprint1-16.py   Feature tests per sprint (14 files, Sprints 1-11 + 16)
-      test_regressions.py  Permanent regression gate
+      test_sprint{1-20b}.py Feature tests per sprint (21 files, 415 test functions)
+      test_regressions.py  Permanent regression gate (23 tests)
     AGENTS.md              Instruction file for agents working in this directory.
     ROADMAP.md             Feature and product roadmap document.
     SPRINTS.md             Forward sprint plan with CLI + Claude parity targets.
     ARCHITECTURE.md        THIS FILE.
     TESTING.md             Manual browser test plan and automated coverage reference.
     CHANGELOG.md           Release notes per sprint.
-    PORTABILITY.md         Portability design spec for download-and-run installs.
+    BUGS.md                Bug backlog and fixed items tracker.
     requirements.txt       Python dependencies.
     .env.example           Sample environment variable overrides.
 
@@ -67,7 +94,8 @@ State directory (runtime data, separate from source):
     sessions/          One JSON file per session: {session_id}.json
     workspaces.json    Registered workspaces list
     last_workspace.txt Last-used workspace path
-    settings.json      (future) User settings
+    settings.json      User settings (default model, workspace, send key, password hash)
+    projects.json      Session project groups (name, color, id)
 
 Log file:
 
@@ -91,6 +119,8 @@ Environment variables controlling behavior:
     HERMES_WEBUI_STATE_DIR         Where sessions/ folder lives
     HERMES_CONFIG_PATH             Path to ~/.hermes/config.yaml
     HERMES_WEBUI_DEFAULT_MODEL     Default LLM model string
+    HERMES_WEBUI_PASSWORD          Optional: enable password auth (off by default)
+    HERMES_HOME                    Base directory for Hermes state (~/.hermes by default)
 
 Test isolation environment variables (set by conftest.py):
 
@@ -109,6 +139,8 @@ Per-request environment variables (set by chat handler, restored after):
     HERMES_EXEC_ASK      Set to "1" to enable approval gate for dangerous commands.
     HERMES_SESSION_KEY   Set to session_id. The approval tool keys pending entries
                          by this value, enabling per-session approval state.
+    HERMES_HOME          Set to the active profile's directory before running agent.
+                         Saved and restored around each agent run.
 
 WARNING: These env vars are process-global. Two concurrent chat requests will clobber
 each other. This is safe only for single-user, single-concurrent-request use.
@@ -336,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
@@ -347,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 = {
@@ -395,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
@@ -452,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:
 
@@ -463,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)
 
@@ -1084,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.
@@ -1575,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 unless the user has explicitly opened that Activity row before. Persist open/closed disclosure state per chat and per turn, so switching away from a chat and coming back preserves the mode the user left it in. Summary line uses one disclosure for internals and stays intentionally terse, e.g. `Activity: 4 tools`. It should not repeat the always-present thinking area, list individual tool names, or add a second trailing count badge. 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

@@ -0,0 +1,89 @@
+FROM python:3.12-slim
+
+LABEL maintainer="nesquena"
+LABEL description="Hermes Web UI — browser interface for Hermes Agent"
+
+# Install system packages
+ENV DEBIAN_FRONTEND=noninteractive
+
+# 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
+
+RUN apt-get update -y --fix-missing --no-install-recommends \
+    && apt-get install -y --no-install-recommends \
+    apt-utils \
+    locales \
+    ca-certificates \
+    curl \
+    rsync \
+    openssh-client \
+    git \
+    xz-utils \
+    && 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
+
+# Create the unprivileged runtime user. The entrypoint starts as root only for
+# UID/GID alignment and filesystem preparation, then execs the server as this user.
+RUN groupadd -g 1024 hermeswebui \
+    && useradd -u 1024 -d /home/hermeswebui -g hermeswebui -G users -s /bin/bash -m hermeswebui \
+    && mkdir -p /app /uv_cache \
+    && chown -R hermeswebui:hermeswebui /home/hermeswebui /app /uv_cache
+
+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
+
+COPY --chown=root:root . /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
+
+EXPOSE 8787
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8787/health || exit 1
+
+# docker_init.bash performs root-only bind-mount setup, then drops to hermeswebui
+# before starting the WebUI server. The production image does not ship sudo.
+USER root
+CMD ["/hermeswebui_init.bash"]
+

HERMES.md

@@ -0,0 +1,489 @@
+# Why Hermes
+
+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 real problem: most tools are excellent in the moment and weak over time
+
+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 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.
+
+```
+Session-scoped:   You -> [Tool] -> Answer -> Done
+                  (some tools now carry memory, but the execution is stateless)
+
+Persistent agent: You <-> [Hermes] <-> (memory, skills, schedule, tools, surfaces)
+                  (runs on your server, accumulates context, acts on your behalf offline)
+```
+
+---
+
+## A note on convergence
+
+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.
+
+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.
+
+---
+
+## 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. You never configure
+this manually — it happens in the background as a side effect of normal use.
+
+### 2. Autonomous scheduling
+
+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 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
+
+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 across all of them.
+
+---
+
+## How AI tools are layered today
+
+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:
+
+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."
+
+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.
+
+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.
+
+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.
+
+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
+
+### vs. OpenClaw
+
+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) 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 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.
+
+Two practical differences worth knowing directly:
+
+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 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: 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 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 (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; 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 |
+| Orchestrates Claude Code / Codex | No | Yes |
+| 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 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.
+
+What Claude Code has that's worth knowing:
+
+- 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; 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
+
+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.
+
+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 + 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 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) | 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 (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). 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 Automations; CLI has none) | Yes |
+| Messaging app access | No | Yes |
+| 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 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.
+
+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 | 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 / 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
+
+Cursor has changed substantially. The "no memory, no scheduling, no messaging" description was
+accurate in 2024 and is wrong now.
+
+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 (Supermaven) | Excellent (Cascade) | Excellent | No |
+| Inline diff / refactor | Yes | Yes | Yes | Via shell |
+| 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 |
+| 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 and ChatGPT
+
+These are no longer simple chat tools. The description of "no memory, no scheduling, no
+messaging" is inaccurate for both.
+
+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.
+
+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
+
+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 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 — 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
+
+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 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.
+
+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.
+
+---
+
+## What Hermes is not
+
+Hermes is not the best in-editor autocomplete tool. Cursor and Windsurf do that job better.
+Use one alongside Hermes.
+
+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 at it more useful
+over time. The models do the reasoning; Hermes makes sure that reasoning accumulates into
+something durable.
+
+---
+
+## Security and control
+
+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.
+
+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,37 +1,227 @@
 # 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 width="1392" height="854" alt="image" src="https://github.com/user-attachments/assets/79cd3c0d-3167-42ed-9434-447a742c25c3" />
+<img width="2448" height="1748" alt="Hermes Web UI — three-panel layout" src="https://github.com/user-attachments/assets/6bf8af4c-209d-441e-8b92-6515d7a0c369" />
 
-This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI leverages your existing Hermes agent, existing models, without requiring any setup.
+<table>
+  <tr>
+    <td width="50%" align="center">
+      <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, 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>
+
+<table>
+  <tr>
+    <td width="50%" align="center">
+      <img alt="Workspace file browser with inline preview" src="docs/images/ui-workspace.png" />
+      <br /><sub>Workspace file browser with inline preview</sub>
+    </td>
+    <td width="50%" align="center">
+      <img alt="Session projects, tags, and tool call cards" src="docs/images/ui-sessions.png" />
+      <br /><sub>Session projects, tags, and tool call cards</sub>
+    </td>
+  </tr>
+</table>
+
+This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI uses your existing Hermes agent and existing models, without requiring any additional setup.
+
+---
+
+## Why Hermes
+
+Most AI tools reset every session. They don't know who you are, what you worked on, or what
+conventions your project follows. You re-explain yourself every time.
+
+Hermes retains context across sessions, runs scheduled jobs while you're offline, and gets
+smarter about your environment the longer it runs. It uses your existing Hermes agent setup,
+your existing models, and requires no additional configuration to start.
+
+What makes it different from other agentic tools:
+
+- **Persistent memory** — user profile, agent notes, and a skills system that saves reusable
+  procedures; Hermes learns your environment and does not have to relearn it
+- **Self-hosted scheduling** — cron jobs that fire while you're offline and deliver results to
+  Telegram, Discord, Slack, Signal, email, and more
+- **10+ messaging platforms** — the same agent available in the terminal is reachable from your phone
+- **Self-improving skills** — Hermes writes and saves its own skills automatically from experience;
+  no marketplace to browse, no plugins to install
+- **Provider-agnostic** — OpenAI, Anthropic, Google, DeepSeek, OpenRouter, and more
+- **Orchestrates other agents** — can spawn Claude Code or Codex for heavy coding tasks and bring
+  the results back into its own memory
+- **Self-hosted** — your conversations, your memory, your hardware
+
+**vs. the field** *(landscape is actively shifting — see [HERMES.md](HERMES.md) for the full breakdown)*:
+
+| | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
+|---|---|---|---|---|---|
+| Persistent memory (auto) | Yes | Partial† | Partial | Partial | Yes |
+| Scheduled jobs (self-hosted) | Yes | No‡ | No | No | Yes |
+| Messaging app access | Yes (15+ platforms) | Partial (Telegram/Discord preview) | No | No | Yes (10+) |
+| Web UI (self-hosted) | Dashboard only | No | No | Yes | Yes |
+| Self-improving skills | Partial | No | No | No | Yes |
+| Python / ML ecosystem | No (Node.js) | No | No | No | Yes |
+| Provider-agnostic | Yes | No (Claude only) | Yes | Yes | Yes |
+| Open source | Yes (MIT) | No | Yes | Yes | Yes |
+
+† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall  
+‡ Claude Code has cloud-managed scheduling (Anthropic infrastructure) and session-scoped `/loop`; no self-hosted cron
+
+**The closest competitor is OpenClaw** — both are always-on, self-hosted, open-source agents
+with memory, cron, and messaging. The key differences: Hermes writes and saves its own skills
+automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
+Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
+has had security incidents involving malicious skills); and Hermes runs natively in the Python
+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:
+For self-hosted VM or homelab installs, `ctl.sh` wraps the common daemon lifecycle commands without requiring `fuser` or `pkill`:
 
-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).
+```bash
+./ctl.sh start              # background daemon, PID at ~/.hermes/webui.pid
+./ctl.sh status             # PID, uptime, bound host/port, log path, /health
+./ctl.sh logs --lines 100   # tail ~/.hermes/webui.log
+./ctl.sh restart
+./ctl.sh stop
+```
+
+`ctl.sh start` runs the bootstrap in foreground/no-browser mode behind the daemon wrapper, writes logs to `~/.hermes/webui.log`, and respects `.env` plus inline overrides such as `HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start`.
+
+The bootstrap will:
+
+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.
+> For Windows / WSL auto-start at login, see [`docs/wsl-autostart.md`](docs/wsl-autostart.md).
+
+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.
+
+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 \
+  -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
+```
+
+### Build locally
+
+```bash
+docker build -t 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
+```
+
+### Multi-container setups
+
+If you want the agent and WebUI in separate containers (for isolation, or because you're already running an agent gateway elsewhere):
+
+```bash
+# 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
+```
+
+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`
+> and set `HERMES_WEBUI_PASSWORD` to enable authentication.
 
 ---
 
@@ -55,6 +245,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
 ```
 
@@ -70,12 +261,16 @@ Full list of environment variables:
 |---|---|---|
 | `HERMES_WEBUI_AGENT_DIR` | auto-discovered | Path to the hermes-agent checkout |
 | `HERMES_WEBUI_PYTHON` | auto-discovered | Python executable |
-| `HERMES_WEBUI_HOST` | `127.0.0.1` | Bind address |
+| `HERMES_WEBUI_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for all IPv4, `::` for all IPv6, `::1` for IPv6 loopback) |
 | `HERMES_WEBUI_PORT` | `8787` | Port |
 | `HERMES_WEBUI_STATE_DIR` | `~/.hermes/webui-mvp` | Where sessions and state are stored |
 | `HERMES_WEBUI_DEFAULT_WORKSPACE` | `~/workspace` | Default workspace |
 | `HERMES_WEBUI_DEFAULT_MODEL` | `openai/gpt-5.4-mini` | Default model |
-| `HERMES_HOME` | `~/.hermes` | Base directory for Hermes state (affects all paths above) |
+| `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 |
 
 ---
@@ -102,6 +297,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:
@@ -127,17 +356,18 @@ Tests discover the repo and the Hermes agent dynamically -- no hardcoded paths.
 
 ```bash
 cd hermes-webui
-python -m pytest tests/ -v
+pytest tests/ -v --timeout=60
 ```
 
 Or using the agent venv explicitly:
 
 ```bash
-/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v   # or any Python with deps installed
+/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v
 ```
 
 Tests run against an isolated server on port 8788 with a separate state directory.
-Production data and real cron jobs are never touched.
+Production data and real cron jobs are never touched. Current count: **3309 tests**
+across 100+ test files.
 
 ---
 
@@ -145,88 +375,299 @@ Production data and real cron jobs are never touched.
 
 ### Chat and agent
 - Streaming responses via SSE (tokens appear as they are generated)
-- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter); dynamic model dropdown populated from configured keys
+- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Z.AI); dynamic model dropdown populated from configured keys
 - 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
-- Tool call cards inline -- each shows the tool name, args, and result snippet
+- 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)
+- Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
 - Approval card for dangerous shell commands (allow once / session / always / deny)
 - SSE auto-reconnect on network blips (SSH tunnel resilience)
 - File attachments persist across page reloads
 - Message timestamps (HH:MM next to each message, full date on hover)
+- Code block copy button with "Copied!" feedback
+- Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
+- Safe HTML rendering in AI responses (bold, italic, code converted to markdown)
+- rAF-throttled token streaming for smoother rendering during long responses
+- Context usage indicator in composer footer -- token count, cost, and fill bar (model-aware)
 
 ### Sessions
 - Create, rename, duplicate, delete, search by title and message content
-- Pin/star sessions to the top of the sidebar
+- 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
 - Session tags -- add #tag to titles for colored chips and click-to-filter
-- Grouped by Today / Yesterday / Earlier in the sidebar
+- Grouped by Today / Yesterday / Earlier in the sidebar (collapsible date groups)
 - Download as Markdown transcript, full JSON export, or import from JSON
 - Sessions persist across page reloads and SSH tunnel reconnects
 - Browser tab title reflects the active session name
+- CLI session bridge -- CLI sessions from hermes-agent's SQLite store appear in the sidebar with a gold "cli" badge; click to import with full history and reply normally
+- Token/cost display -- input tokens, output tokens, estimated cost shown per conversation (toggle in Settings or `/usage` command)
 
 ### Workspace file browser
-- Browse directory tree with type icons
+- Directory tree with expand/collapse (single-click toggles, double-click navigates)
+- Breadcrumb navigation with clickable path segments
 - Preview text, code, Markdown (rendered), and images inline
 - Edit, create, delete, and rename files; create folders
+- Binary file download (auto-detected from server)
+- File preview auto-closes on directory navigation (with unsaved-edit guard)
+- Git detection -- branch name and dirty file count badge in workspace header
 - Right panel is drag-resizable
 - Syntax highlighted code preview (Prism.js)
 
+### Voice input
+- Microphone button in the composer (Web Speech API)
+- Tap to record, tap again or send to stop
+- Live interim transcription appears in the textarea
+- Auto-stops after ~2s of silence
+- Appends to existing textarea content (doesn't replace)
+- Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)
+
+### 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)
+
+### Authentication and security
+- Optional password auth -- off by default, zero friction for localhost
+- Enable via `HERMES_WEBUI_PASSWORD` env var or Settings panel
+- Signed HMAC HTTP-only cookie with 24h TTL
+- Minimal dark-themed login page at `/login`
+- Security headers on all responses (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
+- 20MB POST body size limit
+- CDN resources pinned with SRI integrity hashes
+
+### Themes
+- 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 in topbar) -- persist default model and default workspace server-side
+- **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`, `/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
+
 ### Panels
-- **Chat** -- session list, search, pin, archive, new conversation
-- **Tasks** -- view, create, edit, run, pause/resume, delete cron jobs; completion alerts
-- **Skills** -- list all skills by category, search, preview, create/edit/delete
+- **Chat** -- session list, search, pin, archive, projects, new conversation
+- **Tasks** -- view, create, edit, run, pause/resume, delete cron jobs; run history; completion alerts
+- **Skills** -- list all skills by category, search, preview, create/edit/delete; linked files viewer
 - **Memory** -- view and edit MEMORY.md and USER.md inline
+- **Profiles** -- create, switch, delete agent profiles; clone config
 - **Todos** -- live task list from the current session
 - **Spaces** -- add, rename, remove workspaces; quick-switch from topbar
 
+### Mobile responsive
+- Hamburger sidebar -- slide-in overlay on mobile (<640px)
+- 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
+- Full-height chat/composer on phones without bottom-nav spacing
+- Desktop layout completely unchanged
+
 ---
 
 ## Architecture
 
 ```
-server.py               HTTP routing shell (~76 lines)
+server.py               HTTP routing shell + auth middleware (~154 lines)
 api/
-  routes.py             All GET + POST route handlers
-  config.py             Discovery + globals + model provider detection
-  helpers.py            HTTP helpers: j(), bad(), require(), safe_resolve()
-  models.py             Session model + CRUD
-  workspace.py          File ops: list_dir, read_file_content, workspace helpers
-  upload.py             Multipart parser, file upload handler
-  streaming.py          SSE engine, run_agent integration, cancel support
+  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
-  style.css             All CSS
-  ui.js                 DOM helpers, renderMd, Mermaid, tool cards, file tree
-  workspace.js          File tree, preview, file ops
-  sessions.js           Session CRUD, list rendering, search, tags, archive
-  messages.js           send(), SSE event handlers, approval, transcript
-  panels.js             Cron, skills, memory, workspace, todo, switchPanel, alerts
-  boot.js               Event wiring + boot IIFE
+  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, separate HERMES_HOME)
-  test_sprint1-14.py    Feature tests per sprint
-  test_regressions.py   Permanent regression gate
+  conftest.py           Isolated test server (port 8788)
+  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
 ```
 
 State lives outside the repo at `~/.hermes/webui-mvp/` by default
-(sessions, workspaces, settings, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`.
+(sessions, workspaces, settings, projects, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`.
 
 ---
 
 ## Docs
 
+- `HERMES.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
 - `ROADMAP.md` -- feature roadmap and sprint history
 - `ARCHITECTURE.md` -- system design, all API endpoints, implementation notes
 - `TESTING.md` -- manual browser test plan and automated coverage reference
-- `CHANGELOG.md` -- release notes
+- `CHANGELOG.md` -- release notes per sprint
+- `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets
+- `THEMES.md` -- theme system documentation, custom theme guide
+- `docs/troubleshooting.md` -- diagnostic flows for common failures (e.g. "AIAgent not available")
+
+## 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,336 +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: Sprint 17 / v0.19 (April 3, 2026)
-> Tests: 294 passing
-> Source: <repo>/
+> Last updated: v0.51.31 (May 9, 2026) — 5028 tests collected — Release H 12-PR contributor batch (image-mode fix + race fixes + composer drafts + locale parity + custom-provider dedup + TTL config + heartbeat polish)
+> 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, custom model discovery, GLM-5.1 | 237 |
-| Sprint 17 | Workspace polish + slash commands + settings | Breadcrumb navigation, slash command autocomplete, send key setting (#26) | 294 |
+| 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 (~76 lines) + api/ modules (~2145 lines) | Thin shell + business logic in api/ |
-| HTML template | <repo>/static/index.html | Served from disk |
-| CSS | <repo>/static/style.css (~560 lines) | Served from disk |
-| JavaScript | <repo>/static/{ui,workspace,sessions,messages,panels,boot,commands}.js | 7 modules, ~2990 lines total |
-| 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)
-- [ ] Token/cost estimate per message (Wave 3)
-
-### 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)
-- [ ] Skill picker in cron create form (Wave 3)
+### 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
-- [ ] View skill linked files (Wave 3)
+- [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
+- [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 (#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
 
 ### Configuration
-- [x] Settings panel (default model, default workspace) (Sprint 12)
-- [ ] Enable/disable toolsets per session (deferred)
+- [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 (Sprint 13)
-- [x] Background agent error alerts (Sprint 13)
+- [x] Cron job completion alerts
+- [x] Background agent error banner
+- [x] Approval pending badge
+- [x] Provider / model mismatch toast warning
 
-### Advanced / Future
-- [ ] Voice input via Whisper (Wave 6)
-- [ ] TTS playback of responses (Wave 6)
-- [ ] Subagent delegation cards (Wave 6)
-- [x] Background task cancel (activity bar Cancel button)
-- [ ] Code execution cell (Wave 6)
-- [ ] Password authentication (Wave 7)
-- [ ] HTTPS / reverse proxy (Wave 7)
-- [ ] Mobile responsive layout (Wave 7)
-- [ ] Virtual scroll for large lists (Wave 7)
+### Slash commands
+- [x] Command registry + autocomplete dropdown
+- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/goal`, `/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
+- [x] LLM Gateway routing metadata display — assistant turns and session metadata show the served model/provider, failover path, and model-switch warnings when response metadata includes `used_provider`, `used_model`, or `routing` (#732)
+
+### 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)
+- **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 |
 
 ---
 
-## Wave 3: Power Features and Developer Experience
+## Versioning conventions
 
-### Sprint 3.1: Tool Call Visibility Inline
-Show tool calls as collapsible cards in the conversation.
-Collapsed: tool name badge + one-line preview. Expanded: full args + result.
+- **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
 
-### Sprint 3.2: Multi-Model Expansion
-Add more models. Group by provider. Model info tooltip on hover.
-(Partially done: 10 models in dropdown from Sprint 1.)
-
-### Sprint 3.2b: Resizable Panel Widths (COMPLETE Sprint 6)
-Both sidebar and workspace panel are drag-resizable with localStorage persistence.
-
-### Sprint 3.3: Workspace File Actions
-- [x] Rename file (inline, double-click) (Sprint 14)
-- [x] Create folder (Sprint 14)
-- [x] Syntax highlighted code preview (Prism.js)
-
-### Sprint 3.4: Conversation Controls
-- [x] Copy message (Sprint 5)
-- [x] Edit last user message + regenerate
-- [x] Regenerate last assistant response
-- [x] Clear conversation (wipe messages, keep session)
-
----
-
-## Wave 4: Settings, Configuration, Notifications
-
-### Sprint 4.1: Settings Panel
-Full settings overlay: default model, default workspace, enabled toolsets, config viewer.
-
-### Sprint 4.2: Notification Panel
-Bell icon with unread count. SSE endpoint for cron completions and errors. Toast pop-ups.
-
-### Sprint 4.3: Delivery Target Config
-Configure and test-ping delivery targets (Discord, Telegram, Slack, email) for cron jobs.
-
----
-
-## Wave 5: Honcho Integration and Long-term Memory
-
-### Sprint 5.1: Honcho Memory Panel
-User representation panel, cross-session context, Honcho search, memory write.
-
-### Sprint 5.2: Session Continuity Features
-"What were we working on?" button, session tags, session archive.
-
----
-
-## Wave 6: Realtime and Agentic Features
-
-### Sprint 6.1: Background Task Monitor
-Live list of running agent threads. Cancel button. Queue visibility.
-
-### Sprint 6.2: Subagent Delegation Cards
-When delegate_task fires, show subagent progress inline in chat.
-
-### Sprint 6.3: Code Execution Panel
-Jupyter-style inline code cell. Stateful kernel per session.
-
-### Sprint 6.4: Voice Mode
-Push-to-talk mic button. Whisper transcription. Optional TTS playback.
-
----
-
-## Wave 7: Production Hardening and Mobile
-
-### Sprint 7.1: Authentication
-HERMES_WEBUI_PASSWORD env var gate. Signed cookie. Login page.
-
-### Sprint 7.2: HTTPS and Reverse Proxy
-Nginx + Let's Encrypt. CORS headers for external domain.
-
-### Sprint 7.3: Mobile Responsive Layout
-Collapsible sidebar hamburger. Touch-friendly controls. Swipe gestures.
-
-### Sprint 7.4: Performance and Scale
-Virtual scroll for session/message lists. Incremental message loading.
-
----
-
-## User Requested Features
-
-Community-requested enhancements tracked from GitHub issues.
-
-| Feature | Issue | Description | Complexity |
-|---------|-------|-------------|-----------|
-| Workspace tree view | #22 | Accordion/tree view for workspace file browser instead of flat list. Lazy-load subdirectories on expand, no backend changes needed. | Medium |
-| Docker container | #7 | Docker Compose setup with separate hermes-agent and hermes-webui containers, multi-arch (amd64 + arm64), volume mounts for config. | Medium-High |
-| Authentication | #23 | Password gate via `HERMES_WEBUI_PASSWORD` env var, login page, signed cookie. Already planned in Sprint 7.1. | Low-Medium |
-| Send key / personalization | #26 | Toggle send key (Enter vs Ctrl/Cmd+Enter) and queue vs interrupt mode as global settings. | Low |
-| Multi-profile support | #28 | Profile management UI: create, delete, switch, configure agent profiles. | Medium |
-| Mobile responsive UI | #21 | Hamburger menu, slide-out sidebar drawer, touch-friendly controls. Already planned in Sprint 7.3. | Medium-High |
+Per-version detail and contributor attribution live in [CHANGELOG.md](./CHANGELOG.md).

SPRINTS.md

@@ -1,508 +1,147 @@
-# Hermes Web UI -- Forward Sprint Plan
+# Hermes Web UI — Sprint Planning
 
-> Current state: v0.20 | 318 tests | Daily driver ready
-> This document plans the path from here to two targets:
+> Forward-looking sprint plan and active queue.
 >
-> Target A: 1:1 feature parity with the Hermes CLI (everything you can do from the
->           terminal, you can do from the browser)
+> Current state: v0.50.281 | 3995 tests | port 8787
+> Target A (CLI parity): ✅ Complete
+> Target B (Claude parity): ~95% — full subagent transparency UI and code-execution cells remain
 >
-> Target B: 1:1 parity with Claude's reproducible features (the full Claude
->           browser UI experience, minus things only Anthropic can build)
->
-> Sprints are ordered by impact. Each builds on the one before.
-> Past sprint history lives in CHANGELOG.md.
+> Per-version detail: [CHANGELOG.md](./CHANGELOG.md)
+> Sprint history (chronology): [ROADMAP.md](./ROADMAP.md)
 
 ---
 
-## Where we are now (v0.18)
+## How sprints work here
 
-**CLI parity: ~85% complete.** Core agent loop, all tools visible, workspace
-file ops, cron/skills/memory CRUD, session management, streaming, cancel,
-multi-provider models, custom endpoint discovery -- all solid. Gaps are
-subagent visibility, toolset control, and code execution.
+A sprint is a thematic batch — usually 3–8 PRs landed together as a release. Each sprint has:
 
-**Claude parity: ~65% complete.** Chat, streaming, file browser, session
-management, tool cards, syntax highlighting, model switching, projects,
-settings, Mermaid diagrams, mobile layout -- all present. Gaps are
-artifacts, voice, reasoning display, sharing.
+1. **Theme** — single-sentence framing of what changes
+2. **Items** — selected work, with tracking issue / PR
+3. **Out of scope** — what is explicitly deferred and why
+4. **Risks** — known sharp edges
+5. **Retro** — once shipped, what we learned
+
+External contributor PRs that don't fit a planned sprint get released individually as patch versions (`v0.50.X`). Sprints are reserved for coherent batches where the items reinforce each other.
 
 ---
 
-## Sprint 11 -- Multi-Provider Models + Streaming Smoothness (COMPLETED)
+## Active sprint candidates
 
-**Theme:** Use any Hermes-supported model provider from the UI, and make
-heavy agentic work feel fast and fluid.
+These are the issues currently labeled `sprint-candidate` — the inbox the next sprint plan draws from. Each item already has a confirmed root cause or design direction.
 
-**Why now:** Two high-impact gaps converge here. First, the model dropdown is
-hardcoded to ~10 OpenRouter model strings. If Hermes is configured with direct
-Anthropic, OpenAI, Google, or other API providers, the web UI can't use them.
-This means users who set up Hermes with native API keys are locked out of
-their own models in the browser. Second, the streaming render path rebuilds
-the entire message list on every tool event, causing visible flicker during
-heavy agentic work.
+| # | Title | Type | Sprint fit |
+|---|---|---|---|
+| #1458 | Persistent-host crashes — bootstrap fork pattern, state.db FD leak, HTTP-unhealthy wedge | bug, stability | Stability sprint candidate |
+| #1426 | OpenRouter free-tier `:free` variants invisible (tool-support filter) | bug + feat | Model picker sprint candidate |
+| #1362 | In-app OAuth login for Codex and Claude (currently terminal-only) | feat, ux | Onboarding sprint candidate |
+| #1360 | macOS desktop app — auto-scroll overrides user scroll (#677 regression) | bug, ux | Desktop app polish |
+| #1291 | GLM mutually exclusive between main agent and auxiliary title generation | bug | Auxiliary-route sprint |
 
-### Track A: Bugs
-- Tool card DOM thrash: renderMessages() rebuilds all cards on each tool event.
-  Switch to incremental append (append new card to existing group, no full rebuild).
-- Scroll position lost on re-render during streaming (messages jump).
-
-### Track B: Features
-- **Multi-provider model support:** Query Hermes agent's configured providers
-  and available models at startup via a new `GET /api/models` endpoint. The
-  model dropdown populates dynamically from whatever providers the user has
-  configured (OpenRouter, direct OpenAI, direct Anthropic, Google, DeepSeek,
-  etc.). Group by provider. Fall back to the current hardcoded list if the
-  agent query fails. This ensures the web UI can use any model the CLI can.
-- **Incremental tool card streaming:** Instead of renderMessages() on each
-  tool event, maintain a live card group element per turn and append/update
-  cards in place. The assistant text row below the cards also updates
-  incrementally (already does via assistantBody.innerHTML).
-- **Smooth scroll:** Pin scroll to bottom during streaming unless user has
-  manually scrolled up (read-back mode). Resume pinning when user scrolls
-  back to bottom.
-
-### Track C: Architecture
-- `api/routes.py`: extract the 49 if/elif route handlers from server.py's
-  Handler class into a dedicated routes module. server.py becomes a true
-  ~50-line shell: imports, Handler stub that delegates to routes, main().
-  Completes the server split started in Sprint 10.
-
-**Tests:** ~15 new. Total: ~205.
-**Hermes CLI parity impact:** High (model provider parity is a major CLI gap)
-**Claude parity impact:** Low (streaming smoothness)
+The active queue stays small — it's the next 1-2 sprints' worth of work. The broader backlog of feature requests lives in [ROADMAP.md → Forward Work](./ROADMAP.md#forward-work) and on the GitHub `enhancement` label.
 
 ---
 
-## Sprint 12 -- Settings Panel + Reliability + Session QoL
+## Planning principles
 
-**Theme:** Persist your preferences, survive network blips, and organize sessions.
+**Phase-0 fit assessment.** Every sprint candidate gets a marginal-benefit screen first: does this make the product noticeably better for real users, or does it add surface area that costs more to maintain than it earns? Five-question fit screen — need / shape / bloat / clutter / scope.
 
-**Why now:** Three daily-driver friction points converge. First, default model
-and workspace aren't persisted server-side -- every restart loses them. Second,
-SSH tunnel hiccups during long agent runs silently kill the response with no
-recovery. Third, after 50+ sessions the flat chronological list makes it hard
-to keep important conversations accessible.
+**Salvage over absorb.** When a contributor PR is partial or scoped wrong, prefer splicing the good parts into a maintainer-side PR with `Co-authored-by` attribution rather than asking for multiple rebase rounds. Only absorb whole when the PR is genuinely shippable as-is.
 
-### Track A: Bugs
-- Workspace validation on add doesn't check symlinks (shows as invalid when
-  it's actually a valid symlink to a directory).
+**Independent-review gate.** Self-built PRs need either (a) Opus advisor pass on the merged stage diff, or (b) independent review from a separate reviewer. High-risk batches (large LOC, security, locks, durability) get both.
 
-### Track B: Features
-- **Settings panel:** A gear icon in the topbar opens a slide-in settings panel.
-  Sections: Default Model, Default Workspace. Persisted server-side in
-  `~/.hermes/webui-mvp/settings.json`. Server reads settings on startup and
-  uses them as defaults. `GET /api/settings` + `POST /api/settings` endpoints.
-- **SSE auto-reconnect:** When the EventSource connection drops mid-stream
-  (network blip, SSH tunnel hiccup), auto-reconnect once using the same
-  `stream_id`. The server-side queue holds undelivered events. If reconnect
-  fails after 5s, show error banner. This is the #1 reliability gap for
-  remote VPS usage.
-- **Pin sessions:** A star icon on any session in the sidebar. Pinned sessions
-  float to the top of the list above date groups. Persisted on the session
-  JSON as `pinned: true`. Toggle on click. Simple and high quality-of-life.
-- **Import session from JSON:** Drag a `.json` export file into the sidebar
-  (or click an import button) to restore it as a new session. Mirrors the
-  existing JSON export. Useful for moving sessions between machines.
+**Per-PR release velocity.** When a single PR fixes a real bug and has a clean review, ship it as its own patch release the same day rather than waiting for a sprint batch. Friction-free is the goal — sprint batches exist for coherence, not for arbitrary grouping.
 
-### Track C: Architecture
-- Settings schema: `settings.json` with typed fields, validated on load, with
-  sane defaults. Served via `GET /api/settings`, written via `POST /api/settings`.
-- SSE reconnect: server keeps `STREAMS[stream_id]` alive for 60s after
-  client disconnect, allowing reconnect with the same stream_id.
+**No feature creep mid-PR.** If a contributor proposes a scope addition during review, file it as a separate PR and link from the original. The current PR keeps its original boundaries.
 
-**Tests:** ~15 new. Total: ~216.
-**Hermes CLI parity impact:** Medium (settings persistence, reliability)
-**Claude parity impact:** Medium (settings panel, pinned conversations)
+**Pre-release gate (mandatory).** Every release runs:
+1. `pytest tests/ -q --timeout=120` clean
+2. Browser sanity check (HTTP-level API tests against a test server)
+3. Opus advisor pass on the merged stage diff with a written brief
+4. CHANGELOG.md + ROADMAP.md + TESTING.md version stamp
+5. CI green on Python 3.11 / 3.12 / 3.13
+
+Skipping any of these requires a documented "I'm doing an override" from the maintainer.
 
 ---
 
-## Sprint 13 -- Alerts, Session QoL, Polish
+## Sprint shape
 
-**Theme:** Know what Hermes is doing, and small quality-of-life wins.
+A typical sprint runs 3-7 days end to end:
 
-**Why now:** Cron jobs run silently. Background errors surface nowhere. You have
-no way to know a long-running task finished (or failed) while you were on another
-tab. Meanwhile, a few small UX gaps (no session duplicate, no tab title) add up
-to daily friction.
+| Phase | Duration | Output |
+|---|---|---|
+| Triage | 0.5 day | Active queue → selected items + scope notes |
+| Design / spike | 0.5–1 day | Design notes for items needing them; deferrals documented |
+| Build | 2–4 days | Each item on its own branch + PR for independent review |
+| Review | 0.5–1 day | Maintainer + Opus advisor passes; SHOULD-FIX absorbed in-release |
+| Stage + ship | 0.5 day | Stage branch, full test suite, release PR, tag, deploy, verify live |
+| Hygiene | 0.5 day | Close PRs / issues, GitHub release notes, docs sync, retro |
 
-### Track A: Bugs
-- Symlink workspace validation — confirmed already fixed (`.resolve()` follows
-  symlinks before `is_dir()` check).
-
-### Track B: Features
-- **Cron completion alerts:** `GET /api/crons/recent?since=TIMESTAMP` endpoint.
-  UI polls every 30s (only when tab is focused). Toast notification on each
-  completion. Red badge count on Tasks nav tab, cleared when tab is opened.
-- **Background agent error alerts:** When a streaming session errors out and
-  the user is on a different session, show a persistent red banner above the
-  message area: "Session X encountered an error." Click "View" to navigate,
-  "Dismiss" to clear.
-- **Session duplicate:** Copy icon on each session in the sidebar (visible on
-  hover). Creates a new session with same workspace/model, titled "(copy)".
-- **Browser tab title:** `document.title` updates to show the active session
-  title (e.g. "My Task — Hermes"). Resets to "Hermes" when no session active.
-
-**Tests:** ~10 new. Total: ~221.
-**Hermes CLI parity impact:** Medium (cron visibility, error surfacing)
-**Claude parity impact:** Low
+Smaller sprints (1–2 PRs) compress to 1–2 days end to end. Single-PR releases skip the stage branch and ship via a release PR directly off the contributor's branch (or a maintainer-rebased copy if the fork doesn't grant write access).
 
 ---
 
-## Sprint 14 -- Visual Polish + Workspace Ops + Session Organization (COMPLETED)
+## Sprint history
 
-**Theme:** Polish the visual experience, close workspace file gaps, and
-organize sessions properly.
+Per-version detail is in [CHANGELOG.md](./CHANGELOG.md). High-level theme chronology is in [ROADMAP.md → Sprint History](./ROADMAP.md#sprint-history). A few notable sprints worth highlighting:
 
-### Track B: Features
-- **Mermaid diagram rendering:** Code blocks tagged `mermaid` render as
-  diagrams inline. Mermaid.js loaded lazily from CDN. Dark theme. Falls
-  back to code block on parse error.
-- **Message timestamps:** Subtle HH:MM time next to each role label. Full
-  date/time on hover. User messages tagged with `_ts` on send.
-- **Date grouping fix:** Session list uses `created_at` for groups instead
-  of `updated_at`. Prevents sessions jumping between groups on auto-title.
-- **File rename:** Double-click any filename in the workspace panel to
-  rename inline (same pattern as session rename). `POST /api/file/rename`.
-- **Folder create:** Folder icon button in workspace panel header.
-  `POST /api/file/create-dir`. Prompt for folder name.
-- **Session tags:** Add `#tag` to session titles. Tags extracted and shown
-  as colored chips in the sidebar. Click a tag to filter the session list.
-- **Session archive:** Archive button on each session (box icon). Archived
-  sessions hidden from sidebar by default. "Show N archived" toggle at top
-  of list. `POST /api/session/archive` endpoint.
-
-**Tests:** ~12 new. Total: ~233.
-**Hermes CLI parity impact:** Medium (file rename, folder create)
-**Claude parity impact:** Medium (Mermaid, tags, archive)
+- **Sprint 19** — auth + security hardening. First sprint that made the app safe to leave running beyond localhost.
+- **Sprint 21** — mobile responsive + Docker. Two-container compose enabled the first wave of self-host deployments.
+- **Sprint 22** — multi-profile support. Major CLI-parity unlock; profile switching is now seamless without server restart.
+- **Sprint 25** — macOS desktop application. Native Swift + WKWebView shell, universal Intel + Apple Silicon DMG, Sparkle 2 auto-update. Lives in the separate `hermes-webui/hermes-swift-mac` repo.
+- **Sprint 26** — pluggable themes. CSS-variable-driven 8-theme system that lets community contributors add themes as pure CSS.
+- **Sprint 34** — v0.50.0 UI overhaul. Composer-centric controls, Control Center modal, workspace state machine, rAF streaming throttle.
 
 ---
 
-## Sprint 15 -- Session Projects + Code Copy + Tool Card Toggle (COMPLETED)
+## Out of scope (across all sprints)
 
-**Theme:** Organize work the way you think, not just chronologically.
-Plus two quick UX wins for code and agentic workflows.
+These are intentionally not on the roadmap. Listing them here to save planning cycles.
 
-**Why now:** After 100+ sessions the sidebar is a flat chronological list.
-Finding sessions from 2 weeks ago, or keeping work separated by project,
-requires the search box. Session projects are the single biggest remaining
-organizational gap vs. Claude's project folders.
-
-### Track A: Bugs
-- None.
-
-### Track B: Features
-- **Session projects:** Named groups for organizing sessions. A project
-  filter bar (subtle chips) sits between the search input and the session
-  list. Each project has a name and color. Click a chip to filter sessions
-  to that project; "All" shows everything. Create projects inline (+
-  button), rename (double-click chip), delete (right-click). Assign
-  sessions via folder icon button (hover-reveal) with a dropdown picker.
-  Projects stored in `projects.json`. Session model gains `project_id`
-  field (null = unassigned). Fully backward-compatible with existing
-  sessions. Endpoints: `GET /api/projects`, `POST /api/projects/create`,
-  `POST /api/projects/rename`, `POST /api/projects/delete`,
-  `POST /api/session/move`.
-- **Code block copy button:** Every code block gets a "Copy" button.
-  Positioned in the language header bar (or top-right corner for plain
-  code blocks). Click copies code to clipboard, shows "Copied!" for 1.5s.
-- **Tool card expand/collapse:** When a message has 2+ tool cards, an
-  "Expand all / Collapse all" toggle appears above the card group.
-  Scoped per message group, not global.
-
-### Track C: Architecture
-- `projects.json` flat file storage for project list (same pattern as
-  `workspaces.json` and `settings.json`).
-- `project_id` field on Session model with backward-compatible null default.
-- `_index.json` includes `project_id` for fast client-side filtering.
-
-**Tests:** 13 new. Total: ~237.
-**Hermes CLI parity impact:** Low (CLI has no session organization)
-**Claude parity impact:** Very High (projects are a core Claude concept)
-
-### Candidates for later sprints
-- Artifacts + code execution (HTML/SVG preview, inline Python execution)
-- Voice input via Whisper
-- Subagent delegation cards (enhanced tool card rendering)
+- **Multi-user collaboration** — single-user assumption throughout the codebase. Refactoring would be a from-scratch architecture change.
+- **Sharing / public conversation URLs** — requires hosted backend with access control + CDN. Out of scope for self-hosted.
+- **Plugin marketplace** — Hermes skills already cover this surface.
+- **Anthropic / Claude proprietary features** — Projects AI memory, Claude artifacts sync. Not reproducible.
+- **Linux / Windows native app wrappers** — macOS done; demand on other platforms not yet established. Web UI works in any browser.
+- **App Store distribution** — sandboxing breaks the local-server model.
+- **Auto-update mechanism for the Python webapp** — Sparkle 2 covers the Mac app; the webapp updates via `git pull` + restart, which is the same as every other Python service.
 
 ---
 
-## Sprint 16 -- Session Sidebar Visual Polish (COMPLETED)
+## Templates
 
-**Theme:** Make the session list feel high-quality and delightful.
+When opening a new sprint plan, copy this structure:
 
-**Why now:** The session sidebar had two visible UX bugs: titles truncated
-unnecessarily because action icons reserved space even when hidden, and
-the project folder icon felt "sticky" and awkward. Emoji icons rendered
-inconsistently across platforms. These were the most common visual complaints.
+```markdown
+# Sprint NN — <theme>
 
-### Track A: Bugs (from BUGS.md)
-- **Session title truncation.** Action icons (pin, move, archive, dup, trash)
-  were always in the DOM with `flex-shrink:0`, reserving ~30px even when
-  invisible. Fix: wrapped all actions in a `.session-actions` overlay
-  container with `position:absolute`. Titles now use full available width.
-  Actions appear on hover with a gradient fade from the right edge.
-- **Folder button feels sticky.** Replaced `.has-project` persistent blue
-  button with a colored left border matching the project color. The folder
-  button now only appears in the hover overlay like all other actions.
+**Version target:** vX.Y.Z
+**Theme:** <single sentence>
+**Date started:** YYYY-MM-DD
+**Status:** PLANNED | IN PROGRESS | COMPLETED — vX.Y.Z
 
-### Track B: Features
-- **SVG action icons.** Replaced all emoji HTML entities (★, 📂, 📦, ⊕, 🗑)
-  with monochrome SVG line icons that inherit `currentColor`. Consistent
-  rendering across macOS, Linux, and Windows. Icons: pin (star), folder,
-  archive (box), duplicate (overlapping squares), trash (bin with lines).
-- **Pin indicator.** Small gold filled-star icon rendered inline before the
-  title only when the session is actually pinned. Unpinned sessions get
-  full title width with zero space reservation.
-- **Project border indicator.** Sessions assigned to a project show a
-  colored left border matching the project color, replacing the old
-  always-visible blue folder button.
-- **Hover overlay polish.** Actions container uses a gradient background
-  that fades from transparent to the sidebar color, creating a smooth
-  emergence effect. Overlay hides automatically during inline rename.
+## Items
+| # | Issue | Title | Complexity | Files | PR |
+|---|-------|-------|------------|-------|-----|
 
-### Deferred to Sprint 17
-- Slash commands (basic set with `commands.js` module)
-- Thinking/reasoning display for extended-thinking models
-- Slash command autocomplete popup
+## Rationale
+Why these items, why now.
 
-**Tests:** 74 new (test_sprint16.py: safe HTML rendering, XSS security, sidebar polish). Total: 289.
-**Hermes CLI parity impact:** Low
-**Claude parity impact:** Medium (sidebar polish matches Claude's quality bar)
+## Build approach
+Per-item branch + PR; or single combined branch if items are tightly coupled.
 
----
+## Out of scope
+What did NOT make this sprint and why.
 
-## Sprint 17 -- Workspace Polish + Slash Commands + Settings (COMPLETED)
+## Known risks
+Sharp edges to watch during review.
 
-**Theme:** Workspace polish, slash commands, and composer settings.
+## PR Status
+| Issue | PR | Status |
+|-------|-----|--------|
 
-**Why now:** Three things converge: @nothingmn filed Issue #22 requesting a
-tree/accordion workspace view (breadcrumb navigation is the foundation for
-that), slash commands were deferred from Sprint 16, and Issue #26 (send key
-personalization) fits naturally since we are already touching the keydown
-handler for slash command autocomplete.
+## Retro (post-ship)
+What worked, what we'd do differently.
+```
 
-### Track A: Workspace Breadcrumb Navigation
-- **Breadcrumb path bar.** When users click into subdirectories, a breadcrumb
-  bar appears showing the path (e.g. `~ / src / components`) with clickable
-  segments to navigate back. Hidden at root level for a clean UI.
-- **Up button.** Arrow-up button in the panel header navigates to the parent
-  directory. Hidden when already at workspace root.
-- **Current directory tracking.** `S.currentDir` state property tracks the
-  active directory. File operations (rename, delete, new file, new folder)
-  stay in the current directory instead of jumping back to root.
-- **New file/folder in subdirectories.** Creating files or folders now respects
-  the current directory, creating them in the viewed subdirectory.
-
-### Track B: Slash Commands Foundation
-- **commands.js module.** New 7th JS module with command registry, parser,
-  autocomplete dropdown, and built-in command handlers.
-- **Built-in commands:** `/help` (list commands), `/clear` (clear conversation),
-  `/model <name>` (switch model with fuzzy match), `/workspace <name>` (switch
-  workspace), `/new` (start new session).
-- **Autocomplete dropdown.** Typing `/` in the composer shows a filtered
-  dropdown. Arrow keys navigate, Tab/Enter select, Escape closes. Positioned
-  above the composer using the workspace dropdown CSS pattern.
-- **Transparent pass-through.** Unrecognized `/` commands pass through to the
-  agent normally (not intercepted).
-
-### Track C: Send Key Setting (Issue #26)
-- **`send_key` setting.** New setting in Settings panel: "Enter" (default) or
-  "Ctrl+Enter". Persisted to `settings.json`. Loaded on boot.
-- **Keydown handler rewrite.** Combined handler for autocomplete navigation
-  and send key preference. When `ctrl+enter` is selected, plain Enter inserts
-  a newline and Ctrl/Cmd+Enter sends.
-
-### Deferred to Sprint 18
-- Thinking/reasoning display for extended-thinking models
-- Voice input via Whisper
-- Workspace tree/accordion view (full implementation of Issue #22)
-
-**Tests:** 6 new (test_sprint17.py). Total: 318.
-**Hermes CLI parity impact:** Low (slash commands add convenience)
-**Claude parity impact:** Medium (workspace nav, slash commands match Claude UX)
-
----
-
-## Sprint 18 -- Voice + Multimodal Input
-
-**Theme:** Input beyond the keyboard.
-
-**Why now:** Voice is a meaningful quality-of-life feature for longer sessions
-and is achievable with Whisper. Image input closes the last modality gap with
-Claude (Claude accepts image paste natively -- we do too, but only as
-file uploads, not clipboard screenshots into the conversation directly).
-
-### Track A: Bugs
-- Image paste currently requires a click-to-attach flow. Direct paste into the
-  message textarea should embed the image inline (as a preview chip) and queue
-  it for upload on Send. (Partially works -- clean up edge cases.)
-- Large image uploads (>5MB) time out the upload step silently.
-
-### Track B: Features
-- **Voice input (Whisper):** A microphone icon in the composer. Hold to record,
-  release to transcribe via `POST /api/transcribe` (calls local Whisper or
-  OpenAI Whisper API). Transcribed text appears in the message input, editable
-  before send. Supports the full "voice -> text -> Hermes response" loop.
-- **TTS playback:** A speaker icon on assistant messages. Calls a TTS endpoint
-  (ElevenLabs or OpenAI TTS) and plays the audio. Toggle per-message. Optional
-  auto-play mode in settings.
-- **Vision input improvements:** Paste a screenshot directly from clipboard into
-  the conversation (not just the tray). Shows as an inline preview chip with
-  the image thumbnail. On Send, uploads and includes in the message.
-
-### Track C: Architecture
-- Audio pipeline: `POST /api/transcribe` streams audio bytes, returns transcript.
-  `GET /api/tts?text=...` returns audio/mpeg. Both use lazy import of Whisper
-  and TTS libraries to keep cold start fast.
-
-**Tests:** ~12 new. Total: ~271.
-**Hermes CLI parity impact:** Medium (voice not in CLI, but adds capability)
-**Claude parity impact:** High (Claude has native voice mode)
-
----
-
-## Sprint 18 -- Subagent Visibility + Agentic Transparency
-
-**Theme:** Watch Hermes think, not just respond.
-
-**Why now:** When Hermes delegates to subagents (delegate_task, spawns parallel
-workstreams), the UI shows nothing. On long multi-agent tasks you have no idea
-what's happening. This is the last major "CLI feels better" gap for power users.
-
-### Track A: Bugs
-- Tool cards for delegate_task show no information about what the subagent was
-  asked to do or what it returned.
-- The activity bar text truncates at 55 chars -- tool previews for long terminal
-  commands show nothing useful.
-
-### Track B: Features
-- **Subagent delegation cards:** When `delegate_task` fires, show an expandable
-  card with the subagent's goal, status (pending/running/done), and result
-  summary. Multiple subagents from one call appear as a card group. Uses the
-  existing tool card infrastructure.
-- **Background task monitor:** A "Tasks" indicator in the topbar (separate from
-  the cron Tasks panel). Shows count of active agent threads. Click opens a
-  popover listing all in-flight streams with session names and elapsed times.
-  Cancel any individual thread. This is the full job queue visibility the CLI
-  implicitly has via `ps aux`.
-- **Thinking/reasoning display:** When the model emits reasoning tokens (o3,
-  Claude extended thinking), show them in a collapsible "Reasoning" card above
-  the response. Collapsed by default. This matches Claude's reasoning display.
-
-### Track C: Architecture
-- Task registry: extend STREAMS to include session name, start time, and task
-  description. New `GET /api/tasks/active` endpoint returns all running streams
-  with metadata.
-
-**Tests:** ~14 new. Total: ~285.
-**Hermes CLI parity impact:** Very High (subagent and task visibility is the
-  last major CLI gap)
-**Claude parity impact:** High (Claude shows reasoning, tool use visibly)
-
----
-
-## Sprint 19 -- Auth, HTTPS, and Production Hardening
-
-**Theme:** Make this safe to leave running.
-
-**Why now:** Everything else is done. This is the sprint you run when you want
-to expose the UI beyond localhost -- to a team, a mobile device, or a public
-address.
-
-### Track A: Bugs
-- Server has no request size limit on non-upload endpoints (potential DoS).
-- Session JSON files have no size cap (a runaway agent could write GBs).
-
-### Track B: Features
-- **Password authentication:** A login page with a configurable password
-  (HERMES_WEBUI_PASSWORD env var). Signed cookie session (24h expiry).
-  Single-user model -- no accounts, no registration.
-- **HTTPS / reverse proxy guide:** A one-page `DEPLOY.md` with instructions
-  for running behind nginx + Let's Encrypt on a VPS. Configuration snippets
-  for systemd service, nginx config, certbot.
-- **Mobile responsive layout:** Collapsible sidebar (hamburger). Touch-friendly
-  session list (swipe to delete, tap to navigate). Composer expands on focus.
-  Right panel hidden by default on mobile, accessible via a Files tab.
-- **Rate limiting:** Simple per-IP token bucket on the chat/start endpoint
-  (configurable, default 10 req/min) to prevent accidental hammering.
-
-### Track C: Architecture
-- Helmet headers: X-Content-Type-Options, X-Frame-Options, HSTS (when served
-  over HTTPS). Simple middleware in the Handler.
-
-**Tests:** ~12 new. Total: ~297.
-**Hermes CLI parity impact:** Low (CLI has no auth/HTTPS concerns)
-**Claude parity impact:** Very High (Claude is authenticated, HTTPS only)
-
----
-
-## Feature Parity Summary
-
-### After Sprint 18 (Hermes CLI parity: complete)
-
-| CLI Feature | Status |
-|-------------|--------|
-| Chat / agent loop | Done (v0.3) |
-| Streaming responses | Done (v0.5) |
-| Tool call visibility | Done (v0.11) |
-| File ops (read/write/search/patch) | Done (v0.6) |
-| Terminal commands | Done via workspace |
-| Cron job management | Done (v0.9) |
-| Skills management | Done (v0.9) |
-| Memory read/write | Done (v0.9) |
-| Session history | Done (v0.3) |
-| Workspace switching | Done (v0.7) |
-| Model selection | Done (v0.3) |
-| Multi-provider model support | Done (Sprint 11) |
-| Toolset control | Sprint 12 |
-| Settings persistence | Done (Sprint 12) |
-| Subagent visibility | Sprint 18 |
-| Background task monitor | Sprint 18 |
-| Code execution (Jupyter) | Sprint 17+ |
-| Cron completion alerts | Done (Sprint 13) |
-| Virtual scroll (perf) | Deferred |
-
-### After Sprint 19 (Claude parity: ~90% complete)
-
-| Claude Feature | Status |
-|----------------|--------|
-| Dark theme, 3-panel layout | Done (v0.1) |
-| Streaming chat | Done (v0.5) |
-| Model switching | Done (v0.3) |
-| File attachments | Done (v0.6) |
-| Syntax highlighting | Done (v0.10) |
-| Tool use visibility | Done (v0.11) |
-| Edit/regenerate messages | Done (v0.10) |
-| Session management | Done (v0.6) |
-| Artifacts (HTML/SVG preview) | Sprint 17+ |
-| Code execution inline | Sprint 17+ |
-| Mermaid diagrams | Done (Sprint 14) |
-| Projects / folders | Done (Sprint 15) |
-| Pinned/starred sessions | Done (Sprint 12) |
-| Reasoning display | Sprint 18 |
-| Voice input | Sprint 17 |
-| TTS playback | Sprint 17 |
-| Notifications | Done (Sprint 13) |
-| Settings panel | Done (Sprint 12) |
-| Auth / login | Sprint 19 |
-| HTTPS | Sprint 19 |
-| Mobile layout | Done (v0.16.1) |
-| Sharing / public URLs | Not planned (requires server infra) |
-| Claude-specific features | Not replicable (Projects AI, artifacts sync) |
-
-### What is intentionally not planned
-
-- **Sharing / public conversation URLs:** Requires a hosted backend with access
-  control and CDN. Out of scope for a personal VPS deployment.
-- **Claude-specific model features:** Claude-native Projects memory, extended
-  artifacts sync, Anthropic's proprietary reasoning UI. These are Anthropic
-  infrastructure, not reproducible.
-- **Real-time collaboration:** Multiple users in the same session simultaneously.
-  Single-user assumption throughout.
-- **Plugin marketplace:** Hermes skills cover this use case already.
-
----
-
-*Last updated: April 3, 2026*
-*Current version: v0.19 | 318 tests*
-*Next sprint: Sprint 18 (Voice + Multimodal Input)*
+The maintainer's planning notes for each sprint live in the workspace repo (private), not in this file. This file is the public-facing planning shape.

TESTING.md

@@ -1,12 +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 every user-facing feature of the UI through Sprint 2.
+> 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 8787. Open http://localhost:8787 in browser.
 > Server health check: curl http://127.0.0.1:8787/health should return {"status":"ok"}.
+>
+> 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.
 
 ---
 
@@ -29,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.
@@ -70,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.
 
@@ -141,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
@@ -150,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.
 
 ---
 
@@ -221,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
@@ -260,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.
@@ -276,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:
@@ -374,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:
@@ -465,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.
@@ -828,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]"
@@ -839,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
@@ -848,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"
@@ -922,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"
@@ -978,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.
 
@@ -991,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"
@@ -1019,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:
@@ -1067,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
@@ -1191,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.
 
@@ -1222,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,
@@ -1286,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.
 
@@ -1294,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
@@ -1323,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.
 
@@ -1351,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.
 
@@ -1464,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
@@ -1482,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
@@ -1593,8 +1681,162 @@ FAIL: User message gone, blank chat, response lands in wrong session.
 
 ---
 
-*Last updated: Post-Sprint 10 concurrency sweeps, March 31, 2026*
-*Total automated tests: 190/190*
-*Regression gate: tests/test_regressions.py (23 tests, one per introduced bug)*
-*Run: python -m pytest tests/ -v*
+---
+
+## Sections Added Post-Sprint 10 (Sprints 11-19)
+
+The following features were added in Sprints 11-19 and need manual browser testing.
+Each has automated API-level tests in `tests/test_sprint{N}.py`.
+
+### Sprint 11: Multi-Provider Models
+- Open model dropdown. Verify models grouped by provider (OpenAI, Anthropic, Google, etc.)
+- If custom `base_url` configured in config.yaml, verify local models appear in dropdown.
+- Switch model. Send a message. Verify response uses selected model.
+
+### Sprint 12: Settings + Pin + Import
+- 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.
+
+### Sprint 13: Alerts + Session QoL
+- Duplicate a session (copy icon in hover overlay). Verify "(copy)" title.
+- Browser tab title updates to active session name. Switch sessions — title changes.
+
+### Sprint 14: Visual Polish + Workspace Ops
+- Create a mermaid code block in a response. Verify diagram renders inline.
+- Message timestamps visible next to role labels (hover for full date).
+- Double-click a file in workspace panel to rename. Enter saves, Escape cancels.
+- Create a folder via folder icon in workspace header.
+- Add `#tag` to session title. Verify tag chip appears in sidebar. Click to filter.
+- Archive a session. Verify it disappears. Toggle "Show archived" to see it.
+
+### Sprint 15: Session Projects
+- Click "+" in project bar to create a project. Type name, Enter.
+- Click a project chip to filter sessions.
+- Hover a session → click folder icon → assign to project via picker.
+- Verify colored left border appears on assigned session.
+- Double-click project chip to rename. Right-click to delete.
+- Code blocks have a "Copy" button. Click → "Copied!" feedback.
+- Messages with 2+ tool cards show "Expand all / Collapse all" toggle.
+
+### Sprint 16: Sidebar Visual Polish
+- Session titles use full sidebar width (no truncated space for hidden icons).
+- 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).
+- 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.
+- Up button in panel header navigates to parent. Hidden at root.
+- Type `/` in composer → autocomplete dropdown appears. Arrow keys navigate.
+- Type `/help` → lists all commands. `/clear` clears conversation. `/model` switches.
+- Settings panel: change send key to Ctrl+Enter. Verify Enter inserts newline.
+
+### Sprint 18: Thinking + Tree View + Preview Fix
+- View a file in workspace. Click a breadcrumb or folder → preview closes automatically.
+- 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.
+- Set `HERMES_WEBUI_PASSWORD=test` env var. Restart. All pages redirect to `/login`.
+- Login page: minimal card, password field, "Sign in" button.
+- Enter correct password → redirected to `/`. Cookie set (24h).
+- Enter wrong password → error message, stay on login page.
+- Settings panel: set password via "Access Password" field. Auth activates.
+- "Sign Out" button visible when auth active. Click → redirected to /login.
+- API calls without auth cookie → 401 JSON response.
+- Check response headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`.
+
+### Sprint 20: Voice Input + Send Button
+- Mic button visible in composer (Chrome/Edge). Hidden in Firefox.
+- Tap mic → button turns red with pulse, "Listening..." indicator appears.
+- Speak → live transcription appears in textarea.
+- Stop speaking → auto-stops after ~2s silence. Text stays editable.
+- Tap mic again or Send → stops recording, sends text.
+- Type text, then tap mic → spoken text appends to existing text (doesn't replace).
+- Send button hidden when textarea is empty. Appears with pop-in animation when typing.
+- Send button is icon-only circle (no "Send" text label). Blue with glow.
+- Attach a file with no text → send button appears.
+- Send message → button disappears after textarea clears.
+- While agent is responding → send button hidden.
+
+### Sprint 21: Mobile Responsive + Docker
+- 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.
+- 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 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).
+
+### Sprint 22: Multi-Profile Support
+- Profile chip in topbar (purple accent). Click → dropdown with all profiles.
+- Dropdown shows gateway status dots, model info, skill count per profile.
+- Click a profile → switches; model dropdown, skills, memory, cron refresh.
+- "Manage profiles" link opens Profiles sidebar panel.
+- Profiles panel: cards with name, model, provider, skill count, API key status.
+- "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 → 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.
+
+---
+
+## 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.51.31, May 9, 2026*
+*Total automated tests collected: 4977*
+*Regression gate: tests/test_regressions.py*
+*Run: pytest tests/ -v --timeout=60*
 *Source: <repo>/*

THEMES.md

@@ -0,0 +1,145 @@
+# Hermes Web UI — Themes
+
+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.
+
+---
+
+## Switching Themes
+
+**Settings panel:** Click the gear icon, select a theme from the dropdown. The
+preview is instant — the UI updates as you click through options.
+
+**Slash command:** Type `/theme dark` or `/theme light` in the composer.
+
+**Themes persist** across page reloads and server restarts (stored in
+`settings.json` server-side, with `localStorage` for flicker-free loading).
+
+---
+
+## Built-in Themes
+
+| Theme | Description |
+|-------|-------------|
+| **Dark** (default) | Deep navy/indigo with muted blue accents. Easy on the eyes for long sessions. |
+| **Light** | Warm off-white with dark text. High contrast for bright environments. |
+| **Slate** | Warm charcoal, lighter than Dark. Easier on the eyes for extended use. |
+| **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. |
+
+---
+
+## Creating a Custom Theme
+
+A theme is a CSS block that overrides the color variables. Add it to
+`static/style.css` (or a separate file that you link after the main stylesheet).
+
+### Step 1: Define your theme block
+
+Every color in the UI comes from these CSS variables:
+
+```css
+:root[data-theme="your-theme-name"] {
+  /* Core palette */
+  --bg: #1a1a2e;          /* Main background */
+  --sidebar: #16213e;      /* Sidebar background */
+  --border: rgba(255,255,255,0.08);   /* Subtle borders */
+  --border2: rgba(255,255,255,0.14);  /* Stronger borders */
+  --text: #e8e8f0;         /* Primary text color */
+  --muted: #8888aa;        /* Secondary/muted text */
+  --accent: #e94560;       /* Accent color (errors, warnings, delete) */
+  --blue: #7cb9ff;         /* Primary action color (links, active states) */
+  --gold: #c9a84c;         /* Secondary accent (pinned items, gold highlights) */
+  --code-bg: #0d1117;      /* Code block background */
+
+  /* Surface and chrome (required for full theme polish) */
+  --surface: #1a2535;      /* Dropdowns, popups, toast, approval card */
+  --topbar-bg: rgba(22,33,62,.98);   /* Topbar background */
+  --main-bg: rgba(26,26,46,0.5);    /* Main chat area background */
+  --input-bg: rgba(255,255,255,.04); /* Input/button subtle backgrounds */
+  --hover-bg: rgba(255,255,255,.06); /* Hover state backgrounds */
+  --focus-ring: rgba(124,185,255,.35); /* Focus border color */
+  --focus-glow: rgba(124,185,255,.08); /* Focus box-shadow glow */
+
+  /* Typography (required for readable text across themes) */
+  --strong: #fff;          /* Bold text in messages */
+  --em: #c9c9e8;           /* Italic text in messages */
+  --code-text: #f0c27f;    /* Inline code text color */
+  --code-inline-bg: rgba(0,0,0,.35); /* Inline code background */
+  --pre-text: #e2e8f0;     /* Code block text color */
+}
+```
+
+The **core palette** controls the overall mood. The **surface/chrome** and
+**typography** variables are part of the standard theme contract — define all
+of them for a complete theme.
+
+For **light themes**, you also need `:root[data-theme="name"]` overrides
+for elements that use `rgba(255,255,255,.XX)` hover/border effects (these
+are invisible on light backgrounds). See the built-in light theme for the
+full pattern — it overrides ~45 selectors for proper dark-on-light contrast
+on hover states, borders, chips, role labels, session items, and
+interactive elements.
+
+### Step 2: Add it to the theme picker (optional)
+
+To make your theme appear in the Settings dropdown, add an `<option>` to the
+theme `<select>` in `static/index.html`:
+
+```html
+<option value="your-theme-name">Your Theme Name</option>
+```
+
+And update the `/theme` command's valid theme list in `static/commands.js`.
+
+### Step 3: Test it
+
+Switch to your theme via `/theme your-theme-name` or the Settings panel.
+Check these areas:
+- Sidebar session list (hover states, active state, project borders)
+- Message bubbles (user vs assistant styling)
+- Code blocks (background contrast, copy button visibility)
+- Tool cards (running indicator, expand/collapse)
+- Settings panel and login page
+- Mobile layout (hamburger sidebar, bottom nav)
+
+### Tips
+
+- **Light themes** need scrollbar and selection overrides, plus the full
+  text/code set (`--strong`, `--em`, `--code-text`, `--code-inline-bg`,
+  `--pre-text`) or they will look broken.
+- The **logo gradient** uses `--accent` automatically, so it adapts to your
+  theme without extra work.
+- **Prism.js syntax highlighting** uses its own CDN stylesheet (Tomorrow theme).
+  It works well on dark themes; on light themes the contrast is acceptable but
+  not perfect. Custom Prism theme support is planned for a future update.
+- **No server changes needed.** The `theme` setting in `settings.json` accepts
+  any string — your custom theme name will persist without code changes.
+
+---
+
+## How Themes Work Internally
+
+1. Each theme is a `:root[data-theme="name"]` CSS block that overrides variables.
+2. Switching themes sets `document.documentElement.dataset.theme = name` in JS.
+3. A tiny inline `<script>` in `<head>` reads `localStorage` before the
+   stylesheet loads — this prevents a flash of the wrong theme on page load.
+4. The theme preference is saved server-side via `POST /api/settings` and
+   loaded on boot via `GET /api/settings`.
+5. The `/theme` command and Settings dropdown both update the DOM, localStorage,
+   and server settings simultaneously.
+
+---
+
+## Contributing a Theme
+
+To contribute a new built-in theme:
+
+1. Add your `:root[data-theme="name"]` block to `static/style.css`
+2. Add the `<option>` to the Settings panel in `static/index.html`
+3. Add the theme name to the valid list in `cmdTheme()` in `static/commands.js`
+4. Test on desktop and mobile
+5. Open a PR — themes are pure CSS additions with no backend changes needed

api/agent_health.py

@@ -0,0 +1,330 @@
+"""Hermes agent/gateway heartbeat payload helpers (#716, #1879).
+
+The WebUI process is not always paired with a long-running Hermes gateway. Some
+setups use WebUI only, while self-hosted messaging deployments run a separate
+Hermes gateway daemon that records runtime metadata in the Hermes Agent home.
+This module turns those existing safe runtime signals into a small UI-facing
+heartbeat without shelling out or adding psutil as a hard dependency.
+
+Cross-container note (#1879): ``gateway.status.get_running_pid()`` uses
+``fcntl.flock`` and ``os.kill(pid, 0)``, both of which require the caller to
+share a PID namespace with the gateway process. In multi-container deployments
+where the WebUI runs separately from ``hermes-agent`` and only a Hermes data
+volume is shared, those checks always return ``None`` and the dashboard
+incorrectly shows "Gateway not running". To stay accurate without forcing a
+``pid: "service:hermes-agent"`` compose workaround, we accept a recent
+``updated_at`` timestamp on ``gateway_state.json`` (combined with
+``gateway_state == "running"``) as an equivalent live-process signal — the
+gateway already writes that file on every tick.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_GATEWAY_PID_FILE = "gateway.pid"
+_GATEWAY_RUNTIME_STATUS_FILE = "gateway_state.json"
+
+
+# Two cron ticks (~60s each). Chosen to avoid false negatives during brief
+# gateway restarts while still surfacing a true outage within a couple of
+# minutes. Override is intentionally not exposed: keep the check deterministic
+# and identical across deployments so support diagnostics are reproducible.
+GATEWAY_FRESHNESS_THRESHOLD_S: float = 120.0
+
+
+def _checked_at() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _runtime_status_is_fresh(
+    runtime_status: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    threshold_s: float = GATEWAY_FRESHNESS_THRESHOLD_S,
+) -> bool:
+    """Return ``True`` when ``gateway_state.json`` looks freshly written.
+
+    "Fresh" means the gateway self-reported ``running`` and the ``updated_at``
+    ISO-8601 timestamp is no older than ``threshold_s`` seconds. This is the
+    cross-container liveness signal used when ``get_running_pid()`` returns
+    ``None`` purely because of PID-namespace isolation (#1879).
+
+    Any unparseable input is treated as "not fresh" — a stale or missing
+    timestamp must never report alive.
+    """
+    if not isinstance(runtime_status, dict):
+        return False
+    if runtime_status.get("gateway_state") != "running":
+        return False
+
+    raw_updated_at = runtime_status.get("updated_at")
+    if not isinstance(raw_updated_at, str) or not raw_updated_at:
+        return False
+
+    # ``datetime.fromisoformat`` accepts the exact format gateway/status.py
+    # writes (``datetime.now(timezone.utc).isoformat()``). We deliberately
+    # don't pull in dateutil — keeping this stdlib-only matches the rest of
+    # this module.
+    try:
+        updated_at = datetime.fromisoformat(raw_updated_at)
+    except (TypeError, ValueError):
+        return False
+
+    if updated_at.tzinfo is None:
+        # A naive timestamp could mean anything across containers / hosts.
+        # Refuse to interpret it rather than assume UTC.
+        return False
+
+    reference = now if now is not None else datetime.now(timezone.utc)
+    age_s = (reference - updated_at).total_seconds()
+    if age_s < 0:
+        # Clock skew between containers can produce small negatives. A future
+        # timestamp is still a "fresh" signal — the gateway clearly wrote it
+        # very recently — so accept it. A wildly-future timestamp (> threshold
+        # in the future) is rejected to avoid trusting a broken clock.
+        return -age_s <= threshold_s
+    return age_s <= threshold_s
+
+
+def _runtime_status_is_stale_stopped(
+    runtime_status: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    threshold_s: float = GATEWAY_FRESHNESS_THRESHOLD_S,
+) -> bool:
+    """Return ``True`` for an old clean-stop root gateway state.
+
+    A user may run only profile-scoped gateways while a root
+    ``gateway_state.json`` from an older, intentionally stopped gateway remains
+    on disk (#1944). Treat that stale stopped file like "no root gateway
+    configured" so the heartbeat banner does not keep warning about a service
+    the user is not running. Fresh stopped state still reports down.
+    """
+    if not isinstance(runtime_status, dict):
+        return False
+    if runtime_status.get("gateway_state") != "stopped":
+        return False
+
+    raw_updated_at = runtime_status.get("updated_at")
+    if not isinstance(raw_updated_at, str) or not raw_updated_at:
+        return False
+
+    try:
+        updated_at = datetime.fromisoformat(raw_updated_at)
+    except (TypeError, ValueError):
+        return False
+    if updated_at.tzinfo is None:
+        return False
+
+    reference = now if now is not None else datetime.now(timezone.utc)
+    age_s = (reference - updated_at).total_seconds()
+    return age_s > threshold_s
+
+
+def _gateway_status_module():
+    """Load gateway.status lazily so tests and WebUI-only installs stay isolated."""
+    return importlib.import_module("gateway.status")
+
+
+def _gateway_root_pid_path() -> Path | None:
+    """Return the root Hermes gateway PID path.
+
+    Gateway runtime files are root-level singletons.  A profile-scoped WebUI
+    process may have HERMES_HOME=<root>/profiles/<name>, but gateway.pid,
+    gateway.lock, and gateway_state.json still live under <root>.
+    """
+    try:
+        from hermes_constants import get_default_hermes_root
+        return get_default_hermes_root() / _GATEWAY_PID_FILE
+    except Exception:
+        return None
+
+
+def _read_runtime_status_path(path: Path) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if isinstance(payload, dict):
+        return payload
+    return None
+
+
+def _read_gateway_runtime_status(gateway_status: Any, pid_path: Path | None) -> dict[str, Any] | None:
+    read_runtime_status = gateway_status.read_runtime_status
+    if pid_path is not None:
+        try:
+            return read_runtime_status(pid_path=pid_path)
+        except TypeError:
+            try:
+                return read_runtime_status(pid_path)
+            except TypeError:
+                if getattr(gateway_status, "__name__", "") == "gateway.status" or hasattr(
+                    gateway_status,
+                    "_read_json_file",
+                ):
+                    runtime_status_file = str(
+                        getattr(gateway_status, "_RUNTIME_STATUS_FILE", _GATEWAY_RUNTIME_STATUS_FILE)
+                    )
+                    runtime_status = _read_runtime_status_path(pid_path.with_name(runtime_status_file))
+                    if runtime_status is not None:
+                        return runtime_status
+    return read_runtime_status()
+
+
+def _gateway_running_pid(gateway_status: Any, pid_path: Path | None) -> int | None:
+    get_running_pid = gateway_status.get_running_pid
+    if pid_path is not None:
+        try:
+            return get_running_pid(pid_path=pid_path, cleanup_stale=False)
+        except TypeError:
+            try:
+                return get_running_pid(pid_path, cleanup_stale=False)
+            except TypeError:
+                pass
+    try:
+        return get_running_pid(cleanup_stale=False)
+    except TypeError:
+        # Older agent versions may not expose cleanup_stale. Keep compatibility.
+        return get_running_pid()
+
+
+def _runtime_detail_subset(runtime_status: dict[str, Any] | None) -> dict[str, Any]:
+    """Return only non-sensitive runtime fields for the browser.
+
+    gateway.status records argv/PID metadata so the CLI can validate process
+    identity. The WebUI alert only needs health semantics, never raw command
+    lines, paths, environment, or tokens.
+    """
+    if not isinstance(runtime_status, dict):
+        return {}
+
+    details: dict[str, Any] = {}
+    gateway_state = runtime_status.get("gateway_state")
+    if isinstance(gateway_state, str) and gateway_state:
+        details["gateway_state"] = gateway_state
+
+    updated_at = runtime_status.get("updated_at")
+    if isinstance(updated_at, str) and updated_at:
+        details["updated_at"] = updated_at
+
+    try:
+        details["active_agents"] = max(0, int(runtime_status.get("active_agents") or 0))
+    except (TypeError, ValueError):
+        pass
+
+    platforms = runtime_status.get("platforms")
+    if isinstance(platforms, dict):
+        details["platform_count"] = len(platforms)
+        states: dict[str, int] = {}
+        for payload in platforms.values():
+            if not isinstance(payload, dict):
+                continue
+            state = payload.get("state")
+            if isinstance(state, str) and state:
+                states[state] = states.get(state, 0) + 1
+        if states:
+            details["platform_states"] = states
+
+    return details
+
+
+def build_agent_health_payload() -> dict[str, Any]:
+    """Return `{alive, checked_at, details}` for the Hermes gateway/agent.
+
+    `alive` is intentionally tri-state:
+      * True: a gateway runtime signal says the process is alive.
+      * False: gateway metadata exists, but no live gateway process owns it.
+      * None: no gateway metadata/status is available, so this WebUI setup is
+        probably not configured with a separate gateway process.
+    """
+    checked_at = _checked_at()
+    try:
+        gateway_status = _gateway_status_module()
+    except Exception as exc:
+        return {
+            "alive": None,
+            "checked_at": checked_at,
+            "details": {
+                "state": "unknown",
+                "reason": "gateway_status_unavailable",
+                "error": type(exc).__name__,
+            },
+        }
+
+    gateway_pid_path = _gateway_root_pid_path()
+
+    runtime_status = None
+    try:
+        runtime_status = _read_gateway_runtime_status(gateway_status, gateway_pid_path)
+    except Exception:
+        runtime_status = None
+
+    try:
+        running_pid = _gateway_running_pid(gateway_status, gateway_pid_path)
+    except Exception:
+        running_pid = None
+
+    safe_details = _runtime_detail_subset(runtime_status)
+    if running_pid is not None:
+        return {
+            "alive": True,
+            "checked_at": checked_at,
+            "details": {
+                "state": "alive",
+                **safe_details,
+            },
+        }
+
+    # Cross-container fallback (#1879): when ``get_running_pid()`` cannot see
+    # the gateway because we're in a different PID namespace, a recent
+    # ``updated_at`` on ``gateway_state.json`` is a reliable equivalent signal
+    # since the gateway writes it on every tick. We only trust this fallback
+    # when the gateway also self-reports ``gateway_state == "running"`` so
+    # crash-without-cleanup scenarios still surface as "down".
+    if _runtime_status_is_fresh(runtime_status):
+        return {
+            "alive": True,
+            "checked_at": checked_at,
+            "details": {
+                "state": "alive",
+                "reason": "cross_container_freshness",
+                **safe_details,
+            },
+        }
+
+    if _runtime_status_is_stale_stopped(runtime_status):
+        return {
+            "alive": None,
+            "checked_at": checked_at,
+            "details": {
+                "state": "unknown",
+                "reason": "gateway_stale_stopped_state",
+                **safe_details,
+            },
+        }
+
+    if isinstance(runtime_status, dict):
+        return {
+            "alive": False,
+            "checked_at": checked_at,
+            "details": {
+                "state": "down",
+                "reason": "gateway_not_running",
+                **safe_details,
+            },
+        }
+
+    return {
+        "alive": None,
+        "checked_at": checked_at,
+        "details": {
+            "state": "unknown",
+            "reason": "gateway_not_configured",
+        },
+    }

api/agent_sessions.py

@@ -0,0 +1,561 @@
+"""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',
+}
+
+CLI_MIN_UNTITLED_MESSAGE_COUNT = 6
+CLI_MIN_UNTITLED_USER_MESSAGE_COUNT = 2
+
+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 _safe_lower(value) -> str:
+    return str(value or "").strip().lower()
+
+
+def _normalize_source_name(value: object) -> str:
+    source = _safe_lower(value)
+    if not source:
+        return ""
+    if source.endswith(" session"):
+        source = source[:-len(" session")].strip()
+    return source
+
+
+def _looks_like_default_cli_title(row: dict) -> bool:
+    """Return True when a CLI row looks like framework-generated metadata."""
+    title = _safe_lower(row.get("title"))
+    if not title or title == "untitled":
+        return True
+    if title in {"cli", "cli session"}:
+        return True
+
+    source_candidates = {
+        _normalize_source_name(row.get("source")),
+        _normalize_source_name(row.get("session_source")),
+        _normalize_source_name(row.get("source_tag")),
+        _normalize_source_name(row.get("raw_source")),
+        _normalize_source_name(row.get("source_label")),
+    }
+    source_candidates.discard("")
+    source_candidates.add("cli")
+    return any(title == f"{candidate} session" for candidate in source_candidates)
+
+
+def _as_positive_int(value) -> int:
+    try:
+        return max(0, int(float(value)))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _count_user_turns(row: dict) -> int:
+    user_turns = row.get("actual_user_message_count")
+    if user_turns is None:
+        user_turns = row.get("user_message_count")
+    if user_turns is None:
+        messages = row.get("messages") or []
+        if isinstance(messages, list):
+            return sum(
+                1
+                for msg in messages
+                if _safe_lower(msg.get("role") if isinstance(msg, dict) else msg) == "user"
+            )
+        return 0
+    return _as_positive_int(user_turns)
+
+
+def _has_cli_lineage(row: dict) -> bool:
+    segment_count = _as_positive_int(row.get("_compression_segment_count"))
+    return segment_count > 1 or bool(row.get("_lineage_root_id"))
+
+
+def is_cli_session_row(row: dict) -> bool:
+    """Return True for rows that should be treated as CLI-imported sessions."""
+    if not isinstance(row, dict):
+        return False
+    source = _safe_lower(row.get("session_source"))
+    if source == "messaging":
+        return False
+    if source == "cli":
+        return True
+    source_tag = _safe_lower(row.get("source_tag"))
+    raw_source = _safe_lower(row.get("raw_source"))
+    source_name = _safe_lower(row.get("source"))
+    source_label = _safe_lower(row.get("source_label"))
+    if source_tag == "cli" or raw_source == "cli" or source_name == "cli" or source_label == "cli":
+        return True
+
+    # Legacy imported CLI rows may only be marked as CLI in sidebar metadata.
+    # Keep this conservative to avoid treating messaging sessions as CLI.
+    return bool(
+        row.get("is_cli_session")
+        and source not in MESSAGING_SOURCES
+        and source_tag not in MESSAGING_SOURCES
+        and raw_source not in MESSAGING_SOURCES
+        and source_name not in MESSAGING_SOURCES
+        and _looks_like_default_cli_title(row)
+    )
+
+
+def is_cli_session_row_visible(row: dict) -> bool:
+    """Return whether a CLI-related row should remain visible in the sidebar."""
+    if not isinstance(row, dict):
+        return False
+    if not is_cli_session_row(row):
+        return True
+
+    message_count = _as_positive_int(row.get("actual_message_count") or row.get("message_count"))
+    if message_count <= 0:
+        return False
+
+    if _has_cli_lineage(row):
+        return True
+
+    if not _looks_like_default_cli_title(row):
+        return True
+
+    return _count_user_turns(row) >= CLI_MIN_UNTITLED_USER_MESSAGE_COUNT
+
+
+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.
+
+    Do not collapse lineage across raw sources. A WebUI session that continues
+    from a Telegram/CLI/etc. parent must remain visible as its own surface-owned
+    conversation; otherwise the tip inherits the root's title/source metadata and
+    can disappear under messaging/sidebar policies.
+    """
+    if not parent or not child:
+        return False
+    parent_source = str(parent.get('source') or '').strip().lower()
+    child_source = str(child.get('source') or '').strip().lower()
+    if parent_source and child_source and parent_source != child_source:
+        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)
+        parent = rows_by_id.get(parent_id)
+        if _is_continuation_session(parent, row):
+            continuation_child_ids.add(row['id'])
+        else:
+            row['relationship_type'] = 'child_session'
+            row['parent_title'] = parent.get('title') if parent else None
+            row['parent_source'] = parent.get('source') if parent else None
+            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', 'actual_user_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()}
+        cur.execute("PRAGMA table_info(messages)")
+        message_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)
+        user_message_count_expr = (
+            "COUNT(CASE WHEN LOWER(m.role) = 'user' THEN 1 END)"
+            if 'role' in message_cols
+            else "COUNT(m.id)"
+        )
+
+        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,
+                   {user_message_count_expr} AS actual_user_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]
+        projected = [row for row in projected if is_cli_session_row_visible(row)]
+        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_source = str(parent_row.get('source') or '').strip().lower()
+                child_source = str(row.get('source') or '').strip().lower()
+                if parent_source and child_source and parent_source != child_source:
+                    entry['_cross_surface_child_session'] = True
+                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

@@ -0,0 +1,366 @@
+"""
+Hermes Web UI -- Optional password authentication.
+Off by default. Enable by setting HERMES_WEBUI_PASSWORD env var
+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__)
+
+
+# Default session TTL — 30 days. Kept as a module-level constant for backwards
+# compatibility with downstream code and regression tests that import it.
+# At runtime, prefer ``_resolve_session_ttl()`` which honours the env var and
+# settings.json overrides; this constant is the floor / fallback.
+SESSION_TTL = 86400 * 30  # 30 days
+
+
+def _resolve_session_ttl() -> int:
+    """Resolve session TTL from env > settings > default.
+
+    Priority mirrors get_password_hash(): HERMES_WEBUI_SESSION_TTL env var
+    first, then settings.json, falling back to ``SESSION_TTL`` (30 days).
+    Clamped to [60s, 1 year] to prevent runaway cookies or self-lockout.
+    """
+    env_v = os.getenv('HERMES_WEBUI_SESSION_TTL', '').strip()
+    if env_v.isdigit():
+        val = int(env_v)
+        if 60 <= val <= 86400 * 365:
+            return val
+    s = load_settings()
+    v = s.get('session_ttl_seconds')
+    if isinstance(v, int) and 60 <= v <= 86400 * 365:
+        return v
+    return SESSION_TTL
+
+
+# ── Public paths (no auth required) ─────────────────────────────────────────
+PUBLIC_PATHS = frozenset({
+    '/login', '/health', '/favicon.ico', '/sw.js',
+    '/api/auth/login', '/api/auth/status',
+    '/manifest.json', '/manifest.webmanifest',
+})
+
+COOKIE_NAME = 'hermes_session'
+
+_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_FILE = STATE_DIR / '.login_attempts.json'
+_LOGIN_MAX_ATTEMPTS = 5
+_LOGIN_WINDOW = 60  # seconds
+
+
+def _load_login_attempts() -> dict[str, list[float]]:
+    """Load persisted login attempts from STATE_DIR, pruning expired entries."""
+    try:
+        if _LOGIN_ATTEMPTS_FILE.exists():
+            data = json.loads(_LOGIN_ATTEMPTS_FILE.read_text(encoding='utf-8'))
+            if not isinstance(data, dict):
+                raise ValueError('malformed login-attempts file — expected dict')
+            now = time.time()
+            attempts: dict[str, list[float]] = {}
+            for ip, raw_times in data.items():
+                if not isinstance(ip, str) or not isinstance(raw_times, list):
+                    continue
+                fresh = [
+                    float(t)
+                    for t in raw_times
+                    if isinstance(t, (int, float)) and now - float(t) < _LOGIN_WINDOW
+                ]
+                if fresh:
+                    attempts[ip] = fresh
+            return attempts
+    except Exception as e:
+        logger.debug("Failed to load login attempts file, starting fresh: %s", e)
+    return {}
+
+
+def _save_login_attempts(attempts: dict[str, list[float]]) -> None:
+    """Atomically persist login attempts to STATE_DIR/.login_attempts.json (0600)."""
+    try:
+        _LOGIN_ATTEMPTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=_LOGIN_ATTEMPTS_FILE.parent, suffix='.login_attempts.tmp')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(attempts, f)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, _LOGIN_ATTEMPTS_FILE)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception as e:
+        logger.debug("Failed to persist login attempts: %s", e)
+
+
+_login_attempts = _load_login_attempts()  # ip -> [timestamp, ...]
+
+
+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]
+    if attempts:
+        _login_attempts[ip] = attempts
+    else:
+        _login_attempts.pop(ip, None)
+    _save_login_attempts(_login_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
+    _save_login_attempts(_login_attempts)
+
+
+def _signing_key():
+    """Return a random signing key, generating and persisting one on first call."""
+    key_file = STATE_DIR / '.signing_key'
+    try:
+        if key_file.exists():
+            raw = key_file.read_bytes()
+            if len(raw) >= 32:
+                return raw[:32]
+    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:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        key_file.write_bytes(key)
+        key_file.chmod(0o600)
+    except Exception:
+        logger.debug("Failed to persist signing key, using in-memory key only")
+    return key
+
+
+def _hash_password(password):
+    """PBKDF2-SHA256 with 600k iterations (OWASP recommendation).
+    Salt is the persisted random signing key, which is secret and unique per
+    installation. This keeps the stored hash format a plain hex string
+    (no format change to settings.json) while replacing the predictable
+    STATE_DIR-derived salt from the original implementation."""
+    salt = _signing_key()
+    dk = hashlib.pbkdf2_hmac('sha256', password.encode(), salt, 600_000)
+    return dk.hex()
+
+
+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()
+    if env_pw:
+        return _hash_password(env_pw)
+    settings = load_settings()
+    return settings.get('password_hash') or None
+
+
+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) -> bool:
+    """Verify a plaintext password against the stored hash."""
+    expected = get_password_hash()
+    if not expected:
+        return False
+    return hmac.compare_digest(_hash_password(plain), expected)
+
+
+def create_session() -> str:
+    """Create a new auth session. Returns signed cookie value."""
+    token = secrets.token_hex(32)
+    _sessions[token] = time.time() + _resolve_session_ttl()
+    _save_sessions(_sessions)
+    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
+    return f"{token}.{sig}"
+
+
+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()[:32]
+    if not hmac.compare_digest(sig, expected_sig):
+        return False
+    expiry = _sessions.get(token)
+    if not expiry or time.time() > expiry:
+        _sessions.pop(token, None)
+        return False
+    return True
+
+
+def invalidate_session(cookie_value) -> None:
+    """Remove a session token."""
+    if cookie_value and '.' in cookie_value:
+        token = cookie_value.rsplit('.', 1)[0]
+        if token in _sessions:
+            _sessions.pop(token, None)
+            _save_sessions(_sessions)
+
+
+def parse_cookie(handler) -> str | None:
+    """Extract the auth cookie from the request headers."""
+    cookie_header = handler.headers.get('Cookie', '')
+    if not cookie_header:
+        return None
+    cookie = http.cookies.SimpleCookie()
+    try:
+        cookie.load(cookie_header)
+    except http.cookies.CookieError:
+        return None
+    morsel = cookie.get(COOKIE_NAME)
+    return morsel.value if morsel else None
+
+
+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/') or parsed.path.startswith('/session/static/'):
+        return True
+    # Check session cookie
+    cookie_val = parse_cookie(handler)
+    if cookie_val and verify_session(cookie_val):
+        return True
+    # Not authorized
+    if parsed.path.startswith('/api/'):
+        handler.send_response(401)
+        handler.send_header('Content-Type', 'application/json')
+        handler.end_headers()
+        handler.wfile.write(b'{"error":"Authentication required"}')
+    else:
+        handler.send_response(302)
+        # 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) -> None:
+    """Set the auth cookie on the response."""
+    cookie = http.cookies.SimpleCookie()
+    cookie[COOKIE_NAME] = cookie_value
+    cookie[COOKIE_NAME]['httponly'] = True
+    cookie[COOKIE_NAME]['samesite'] = 'Lax'
+    cookie[COOKIE_NAME]['path'] = '/'
+    cookie[COOKIE_NAME]['max-age'] = str(_resolve_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) -> None:
+    """Clear the auth cookie on the response."""
+    cookie = http.cookies.SimpleCookie()
+    cookie[COOKIE_NAME] = ''
+    cookie[COOKIE_NAME]['httponly'] = True
+    cookie[COOKIE_NAME]['path'] = '/'
+    cookie[COOKIE_NAME]['max-age'] = '0'
+    handler.send_header('Set-Cookie', cookie[COOKIE_NAME].OutputString())

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/dashboard_probe.py

@@ -0,0 +1,211 @@
+"""Safe server-side probe for the official Hermes Agent dashboard.
+
+The official `hermes dashboard` binds to 127.0.0.1:9119 by default and exposes
+GET /api/status as a public, read-only identity/status endpoint.  Keep all
+probing server-side to avoid browser CORS/mixed-content failures, and only allow
+loopback targets so a user-controlled setting cannot become an SSRF primitive.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.request
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_DASHBOARD_PORT = 9119
+DEFAULT_DASHBOARD_TIMEOUT = 0.5
+DEFAULT_DASHBOARD_TARGETS = (("127.0.0.1", DEFAULT_DASHBOARD_PORT), ("localhost", DEFAULT_DASHBOARD_PORT))
+_DASHBOARD_ENABLED_VALUES = {"auto", "always", "never"}
+_LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+def _base_url(host: str, port: int, scheme: str = "http") -> str:
+    display_host = f"[{host}]" if ":" in host and not host.startswith("[") else host
+    return f"{scheme}://{display_host}:{port}"
+
+
+def normalize_dashboard_url(raw_url: str | None) -> tuple[str, int, str, str] | None:
+    """Return (host, port, scheme, base_url) for a safe loopback dashboard URL.
+
+    Overrides intentionally accept only scheme + loopback host + explicit port.
+    Paths, query strings, fragments, and credentials are rejected: the probe
+    appends the official `/api/status` fingerprint itself and must not become an
+    arbitrary local URL fetcher.
+    """
+    raw = str(raw_url or "").strip()
+    if not raw:
+        return None
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("invalid dashboard URL scheme")
+    if parsed.username or parsed.password:
+        raise ValueError("invalid dashboard URL credentials")
+    host = parsed.hostname or ""
+    normalized_host = host.strip().lower()
+    if normalized_host not in _LOOPBACK_HOSTS:
+        raise ValueError("invalid dashboard URL host")
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("invalid dashboard URL port") from exc
+    if not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError("invalid dashboard URL port")
+    path = parsed.path or ""
+    if path not in ("", "/") or parsed.params or parsed.query or parsed.fragment:
+        raise ValueError("invalid dashboard URL path")
+    base = _base_url(normalized_host, port, parsed.scheme)
+    return normalized_host, port, parsed.scheme, base
+
+
+def _looks_like_official_dashboard(payload: object) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    version = payload.get("version")
+    if not isinstance(version, str) or not version.strip():
+        return False
+    # Verified against current Hermes Agent `hermes_cli.web_server.get_status()`:
+    # /api/status returns version plus these Hermes-specific fields. Requiring at
+    # least one avoids treating any generic {version: ...} local service as the
+    # official dashboard.
+    return any(key in payload for key in ("release_date", "hermes_home", "config_path", "gateway_running"))
+
+
+def probe_official_dashboard(
+    host: str,
+    port: int,
+    timeout: float = DEFAULT_DASHBOARD_TIMEOUT,
+    scheme: str = "http",
+) -> dict:
+    """Best-effort check that `hermes dashboard` is running on host:port."""
+    try:
+        normalized_host = str(host or "").strip().lower()
+        if normalized_host not in _LOOPBACK_HOSTS:
+            raise ValueError("dashboard probe host must be loopback")
+        port = int(port)
+        if not (1 <= port <= 65535):
+            raise ValueError("dashboard probe port out of range")
+        if scheme not in {"http", "https"}:
+            raise ValueError("dashboard probe scheme must be http or https")
+        base = _base_url(normalized_host, port, scheme)
+        request = urllib.request.Request(
+            f"{base}/api/status",
+            headers={"Accept": "application/json", "User-Agent": "hermes-webui-dashboard-probe"},
+        )
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if getattr(response, "status", None) != 200:
+                return {"running": False}
+            payload = json.loads(response.read().decode("utf-8"))
+        if not _looks_like_official_dashboard(payload):
+            return {"running": False}
+        result = {"running": True, "host": normalized_host, "port": port, "url": base}
+        version = payload.get("version")
+        if isinstance(version, str) and version.strip():
+            result["version"] = version.strip()
+        return result
+    except Exception:
+        logger.debug("official Hermes dashboard probe failed", exc_info=True)
+        return {"running": False}
+
+
+def _dashboard_config(config_data: dict | None = None) -> dict:
+    if config_data is None:
+        try:
+            from api.config import get_config
+
+            config_data = get_config()
+        except Exception:
+            config_data = {}
+    webui_cfg = config_data.get("webui", {}) if isinstance(config_data, dict) else {}
+    dashboard_cfg = webui_cfg.get("dashboard", {}) if isinstance(webui_cfg, dict) else {}
+    return dashboard_cfg if isinstance(dashboard_cfg, dict) else {}
+
+
+def get_dashboard_config(config_data: dict | None = None) -> dict:
+    """Return normalized profile config for the Settings → System controls."""
+    dashboard_cfg = _dashboard_config(config_data)
+    enabled = str(dashboard_cfg.get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        enabled = "auto"
+    raw_url = str(dashboard_cfg.get("url") or "").strip()
+    if raw_url:
+        # Normalize before echoing so the UI never displays unsafe/stale values.
+        _host, _port, _scheme, raw_url = normalize_dashboard_url(raw_url)
+    return {"enabled": enabled, "url": raw_url}
+
+
+def save_dashboard_config(payload: dict) -> dict:
+    """Persist dashboard link settings under webui.dashboard in config.yaml."""
+    enabled = str((payload or {}).get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        raise ValueError("invalid dashboard enabled mode")
+    raw_url = str((payload or {}).get("url", "") or "").strip()
+    normalized_url = ""
+    if raw_url:
+        _host, _port, _scheme, normalized_url = normalize_dashboard_url(raw_url)
+
+    from api import config as webui_config
+
+    config_path = webui_config._get_config_path()
+    config_data = webui_config._load_yaml_config_file(config_path)
+    webui_section = config_data.get("webui")
+    if not isinstance(webui_section, dict):
+        webui_section = {}
+        config_data["webui"] = webui_section
+    dashboard_section = webui_section.get("dashboard")
+    if not isinstance(dashboard_section, dict):
+        dashboard_section = {}
+        webui_section["dashboard"] = dashboard_section
+    dashboard_section["enabled"] = enabled
+    if normalized_url:
+        dashboard_section["url"] = normalized_url
+    else:
+        dashboard_section.pop("url", None)
+    webui_config._save_yaml_config_file(config_path, config_data)
+    webui_config.reload_config()
+    return {"enabled": enabled, "url": normalized_url}
+
+
+def _webui_bind_host_allows_auto_probe() -> bool:
+    raw_host = str(os.environ.get("HERMES_WEBUI_HOST") or "127.0.0.1").strip().lower()
+    host = raw_host.replace("[", "").replace("]", "")
+    return host in _LOOPBACK_HOSTS
+
+
+def get_dashboard_status(config_data: dict | None = None) -> dict:
+    """Return the safe status payload consumed by GET /api/dashboard/status."""
+    dashboard_cfg = _dashboard_config(config_data)
+    enabled = str(dashboard_cfg.get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        enabled = "auto"
+    if enabled == "never":
+        return {"running": False, "enabled": "never"}
+
+    raw_url = dashboard_cfg.get("url") or dashboard_cfg.get("target") or ""
+    try:
+        override = normalize_dashboard_url(raw_url)
+    except ValueError:
+        return {"running": False, "enabled": enabled, "error": "invalid dashboard url"}
+
+    targets: list[tuple[str, int, str, str]]
+    if override:
+        targets = [override]
+    else:
+        targets = [(host, port, "http", _base_url(host, port)) for host, port in DEFAULT_DASHBOARD_TARGETS]
+
+    if enabled == "always":
+        host, port, scheme, base = targets[0]
+        return {"running": True, "enabled": enabled, "host": host, "port": port, "url": base}
+
+    if not _webui_bind_host_allows_auto_probe():
+        return {"running": False, "enabled": enabled}
+
+    for host, port, scheme, _base in targets:
+        result = probe_official_dashboard(host, port, timeout=DEFAULT_DASHBOARD_TIMEOUT, scheme=scheme)
+        if result.get("running"):
+            result["enabled"] = enabled
+            return result
+    return {"running": False, "enabled": enabled}

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/goals.py

@@ -0,0 +1,608 @@
+"""WebUI bridge for Hermes persistent session goals."""
+
+from __future__ import annotations
+
+import copy
+import logging
+import re
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+try:  # Exposed as a module attribute so tests can monkeypatch it directly.
+    from hermes_cli.goals import (  # type: ignore
+        CONTINUATION_PROMPT_TEMPLATE,
+        DEFAULT_MAX_TURNS,
+        GoalManager as _NativeGoalManager,
+        GoalState,
+        judge_goal,
+    )
+except Exception:  # pragma: no cover - depends on installed hermes-agent
+    CONTINUATION_PROMPT_TEMPLATE = ""  # type: ignore
+    DEFAULT_MAX_TURNS = 20  # type: ignore
+    _NativeGoalManager = None  # type: ignore
+    GoalState = None  # type: ignore
+    judge_goal = None  # type: ignore
+
+GoalManager = _NativeGoalManager  # type: ignore
+
+_DB_CACHE: dict[str, Any] = {}
+
+
+def _default_max_turns() -> int:
+    """Return the configured /goal turn budget, defaulting to Hermes' 20 turns."""
+    try:
+        from api import config as _config
+
+        cfg = getattr(_config, "cfg", {}) or {}
+        goals_cfg = cfg.get("goals", {}) if isinstance(cfg, dict) else {}
+        if not isinstance(goals_cfg, dict):
+            return int(DEFAULT_MAX_TURNS or 20)
+        return max(1, int(goals_cfg.get("max_turns", DEFAULT_MAX_TURNS or 20) or 20))
+    except Exception:
+        return int(DEFAULT_MAX_TURNS or 20)
+
+
+def _meta_key(session_id: str) -> str:
+    return f"goal:{session_id}"
+
+
+def _profile_db(profile_home: str | Path):
+    """Return a SessionDB pinned to *profile_home*, without reading HERMES_HOME.
+
+    The upstream Hermes GoalManager persists through hermes_cli.goals.load_goal(),
+    which resolves SessionDB from process-global HERMES_HOME. WebUI sessions are
+    profile-scoped and can run concurrently, so the WebUI bridge uses an explicit
+    state.db path whenever the caller provides the session's profile home.
+    """
+    home = Path(profile_home).expanduser().resolve()
+    key = str(home)
+    cached = _DB_CACHE.get(key)
+    if cached is not None:
+        return cached
+    try:
+        from hermes_state import SessionDB  # type: ignore
+
+        db = SessionDB(db_path=home / "state.db")
+    except Exception as exc:  # pragma: no cover - import/env dependent
+        logger.debug("GoalManager profile DB unavailable for %s: %s", home, exc)
+        return None
+    _DB_CACHE[key] = db
+    return db
+
+
+class _ProfileGoalManager:
+    """Small WebUI-local GoalManager adapter with explicit profile persistence."""
+
+    def __init__(self, session_id: str, *, profile_home: str | Path, default_max_turns: int = 20):
+        if GoalState is None:
+            raise RuntimeError("Hermes goal state unavailable")
+        self.session_id = session_id
+        self.profile_home = Path(profile_home).expanduser().resolve()
+        self.default_max_turns = int(default_max_turns or DEFAULT_MAX_TURNS or 20)
+        self._state = self._load()
+
+    @property
+    def state(self):
+        return self._state
+
+    def _load(self):
+        db = _profile_db(self.profile_home)
+        if db is None or not self.session_id:
+            return None
+        try:
+            raw = db.get_meta(_meta_key(self.session_id))
+        except Exception as exc:
+            logger.debug("GoalManager profile get_meta failed: %s", exc)
+            return None
+        if not raw:
+            return None
+        try:
+            return GoalState.from_json(raw)  # type: ignore[union-attr]
+        except Exception as exc:
+            logger.warning("GoalManager profile state parse failed for %s: %s", self.session_id, exc)
+            return None
+
+    def _save(self, state) -> None:
+        db = _profile_db(self.profile_home)
+        if db is None or not self.session_id or state is None:
+            return
+        try:
+            db.set_meta(_meta_key(self.session_id), state.to_json())
+        except Exception as exc:
+            logger.debug("GoalManager profile set_meta failed: %s", exc)
+
+    def is_active(self) -> bool:
+        return self._state is not None and self._state.status == "active"
+
+    def has_goal(self) -> bool:
+        return self._state is not None and self._state.status in ("active", "paused")
+
+    def status_line(self) -> str:
+        s = self._state
+        if s is None or s.status in ("cleared",):
+            return "No active goal. Set one with /goal <text>."
+        turns = f"{s.turns_used}/{s.max_turns} turns"
+        if s.status == "active":
+            return f"⊙ Goal (active, {turns}): {s.goal}"
+        if s.status == "paused":
+            extra = f" — {s.paused_reason}" if s.paused_reason else ""
+            return f"⏸ Goal (paused, {turns}{extra}): {s.goal}"
+        if s.status == "done":
+            return f"✓ Goal done ({turns}): {s.goal}"
+        return f"Goal ({s.status}, {turns}): {s.goal}"
+
+    def set(self, goal: str, *, max_turns: Optional[int] = None):
+        goal = (goal or "").strip()
+        if not goal:
+            raise ValueError("goal text is empty")
+        state = GoalState(  # type: ignore[operator]
+            goal=goal,
+            status="active",
+            turns_used=0,
+            max_turns=int(max_turns) if max_turns else self.default_max_turns,
+            created_at=time.time(),
+            last_turn_at=0.0,
+        )
+        self._state = state
+        self._save(state)
+        return state
+
+    def pause(self, reason: str = "user-paused"):
+        if not self._state:
+            return None
+        self._state.status = "paused"
+        self._state.paused_reason = reason
+        self._save(self._state)
+        return self._state
+
+    def resume(self, *, reset_budget: bool = True):
+        if not self._state:
+            return None
+        self._state.status = "active"
+        self._state.paused_reason = None
+        if reset_budget:
+            self._state.turns_used = 0
+        self._save(self._state)
+        return self._state
+
+    def clear(self) -> None:
+        if self._state is None:
+            return
+        self._state.status = "cleared"
+        self._save(self._state)
+        self._state = None
+
+    def evaluate_after_turn(self, last_response: str, *, user_initiated: bool = True) -> Dict[str, Any]:
+        state = self._state
+        if state is None or state.status != "active":
+            return {
+                "status": state.status if state else None,
+                "should_continue": False,
+                "continuation_prompt": None,
+                "verdict": "inactive",
+                "reason": "no active goal",
+                "message": "",
+            }
+
+        state.turns_used += 1
+        state.last_turn_at = time.time()
+
+        if judge_goal is None:
+            verdict, reason = "continue", "goal judge unavailable"
+        else:
+            verdict, reason = judge_goal(state.goal, str(last_response or ""))
+        state.last_verdict = verdict
+        state.last_reason = reason
+
+        if verdict == "done":
+            state.status = "done"
+            self._save(state)
+            return {
+                "status": "done",
+                "should_continue": False,
+                "continuation_prompt": None,
+                "verdict": "done",
+                "reason": reason,
+                "message": f"✓ Goal achieved: {reason}",
+            }
+
+        if state.turns_used >= state.max_turns:
+            state.status = "paused"
+            state.paused_reason = f"turn budget exhausted ({state.turns_used}/{state.max_turns})"
+            self._save(state)
+            return {
+                "status": "paused",
+                "should_continue": False,
+                "continuation_prompt": None,
+                "verdict": "continue",
+                "reason": reason,
+                "message": (
+                    f"⏸ Goal paused — {state.turns_used}/{state.max_turns} turns used. "
+                    "Use /goal resume to keep going, or /goal clear to stop."
+                ),
+            }
+
+        self._save(state)
+        return {
+            "status": "active",
+            "should_continue": True,
+            "continuation_prompt": self.next_continuation_prompt(),
+            "verdict": "continue",
+            "reason": reason,
+            "message": f"↻ Continuing toward goal ({state.turns_used}/{state.max_turns}): {reason}",
+        }
+
+    def next_continuation_prompt(self) -> Optional[str]:
+        if not self._state or self._state.status != "active":
+            return None
+        return CONTINUATION_PROMPT_TEMPLATE.format(goal=self._state.goal)
+
+
+def _manager(session_id: str, *, profile_home: str | Path | None = None):
+    if GoalManager is None:
+        return None
+    if profile_home and GoalManager is _NativeGoalManager and GoalState is not None:
+        try:
+            return _ProfileGoalManager(
+                session_id=session_id,
+                profile_home=profile_home,
+                default_max_turns=_default_max_turns(),
+            )
+        except Exception as exc:
+            logger.debug("Profile-scoped GoalManager unavailable: %s", exc)
+            return None
+    return GoalManager(session_id=session_id, default_max_turns=_default_max_turns())
+
+
+def _state_payload(state: Any) -> Optional[Dict[str, Any]]:
+    if state is None:
+        return None
+    return {
+        "goal": getattr(state, "goal", "") or "",
+        "status": getattr(state, "status", "") or "",
+        "turns_used": int(getattr(state, "turns_used", 0) or 0),
+        "max_turns": int(getattr(state, "max_turns", 0) or 0),
+        "last_verdict": getattr(state, "last_verdict", None),
+        "last_reason": getattr(state, "last_reason", None),
+        "paused_reason": getattr(state, "paused_reason", None),
+    }
+
+
+def _payload(
+    *,
+    ok: bool = True,
+    action: str,
+    message: str,
+    state: Any = None,
+    error: str | None = None,
+    kickoff_prompt: str | None = None,
+    decision: Dict[str, Any] | None = None,
+    message_key: str | None = None,
+    message_args: list[Any] | None = None,
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "ok": bool(ok),
+        "action": action,
+        "message": message,
+        "goal": _state_payload(state),
+    }
+    if error:
+        body["error"] = error
+    if kickoff_prompt:
+        body["kickoff_prompt"] = kickoff_prompt
+    if decision is not None:
+        body["decision"] = decision
+    if message_key:
+        body["message_key"] = message_key
+    if message_args is not None:
+        body["message_args"] = [a for a in message_args if a is not None]
+    return body
+
+
+def _goal_status_payload(state: Any, *, default_message: str | None = None) -> Dict[str, Any]:
+    """Build localized-status style payload fields from a goal state."""
+    if default_message is None:
+        default_message = "No active goal. Set one with /goal <text>."
+    if state is None:
+        return {"message": default_message, "message_key": "goal_status_none"}
+    status = str(getattr(state, "status", "") or "").strip()
+    if status in ("cleared",):
+        return {"message": default_message, "message_key": "goal_status_none"}
+    turns_used = int(getattr(state, "turns_used", 0) or 0)
+    max_turns = int(getattr(state, "max_turns", 0) or 0)
+    goal = str(getattr(state, "goal", "") or "")
+    if status == "active":
+        return {
+            "message": f"⊙ Goal (active, {turns_used}/{max_turns} turns): {goal}",
+            "message_key": "goal_status_active",
+            "message_args": [turns_used, max_turns, goal],
+        }
+    if status == "paused":
+        reason = str(getattr(state, "paused_reason", "") or "")
+        return {
+            "message": f"⏸ Goal (paused, {turns_used}/{max_turns}{' — ' + reason if reason else ''}): {goal}",
+            "message_key": "goal_status_paused",
+            "message_args": [turns_used, max_turns, reason, goal],
+        }
+    if status == "done":
+        return {
+            "message": f"✓ Goal done ({turns_used}/{max_turns}): {goal}",
+            "message_key": "goal_status_done",
+            "message_args": [turns_used, max_turns, goal],
+        }
+    return {
+        "message": f"Goal ({status}, {turns_used}/{max_turns}): {goal}",
+        "message_args": [status, turns_used, max_turns, goal],
+    }
+
+
+def _extract_goal_turns_from_message(message: str) -> tuple[int, int]:
+    """Best-effort extraction for continuation messages like '(1/20)'."""
+    if not message:
+        return 0, 0
+    match = re.search(r"\((\d+)\s*/\s*(\d+)\)", message)
+    if not match:
+        return 0, 0
+    try:
+        return int(match.group(1)), int(match.group(2))
+    except Exception:
+        return 0, 0
+
+
+def _goal_decision_payload(
+    decision: Dict[str, Any],
+    state: Any,
+) -> Dict[str, Any]:
+    """Attach goal message i18n key/args to an evaluation decision."""
+    if not isinstance(decision, dict):
+        return decision
+    status = str(decision.get("status") or "").strip()
+    reason = str(decision.get("reason") or "").strip()
+    turns_used = int(getattr(state, "turns_used", 0) or 0)
+    max_turns = int(getattr(state, "max_turns", 0) or 0)
+    if (turns_used, max_turns) == (0, 0):
+        turns_used, max_turns = _extract_goal_turns_from_message(str(decision.get("message") or ""))
+
+    if status == "done":
+        return {
+            **decision,
+            "message_key": "goal_achieved",
+            "message_args": [reason],
+        }
+    if status == "paused":
+        return {
+            **decision,
+            "message_key": "goal_paused_budget_exhausted",
+            "message_args": [turns_used, max_turns],
+        }
+    if decision.get("should_continue"):
+        return {
+            **decision,
+            "message_key": "goal_continuing",
+            "message_args": [turns_used, max_turns, reason],
+        }
+    return decision
+
+
+def goal_state_snapshot(session_id: str, *, profile_home: str | Path | None = None) -> Any:
+    """Return a deep copy of current goal state for rollback before kickoff."""
+    mgr = _manager(str(session_id or ""), profile_home=profile_home)
+    if mgr is None:
+        return None
+    return copy.deepcopy(getattr(mgr, "state", None))
+
+
+def restore_goal_state(session_id: str, snapshot: Any, *, profile_home: str | Path | None = None) -> None:
+    """Restore a prior goal state after kickoff stream creation fails."""
+    mgr = _manager(str(session_id or ""), profile_home=profile_home)
+    if mgr is None:
+        return
+    if snapshot is None:
+        try:
+            mgr.clear()
+        except Exception:
+            pass
+        return
+    if isinstance(mgr, _ProfileGoalManager):
+        mgr._state = snapshot
+        mgr._save(snapshot)
+        return
+    try:
+        from hermes_cli.goals import save_goal  # type: ignore
+
+        save_goal(str(session_id or ""), snapshot)
+    except Exception as exc:  # pragma: no cover - native fallback only
+        logger.debug("Goal state restore failed for %s: %s", session_id, exc)
+
+
+def goal_command_payload(
+    session_id: str,
+    args: str = "",
+    *,
+    stream_running: bool = False,
+    profile_home: str | Path | None = None,
+) -> Dict[str, Any]:
+    """Return the WebUI response payload for a /goal command.
+
+    Mirrors the gateway command semantics:
+    - /goal or /goal status shows status
+    - /goal pause pauses
+    - /goal resume resumes without auto-starting a turn
+    - /goal clear|stop|done clears
+    - /goal <text> sets a new active goal and returns kickoff_prompt so the
+      caller can start the first normal user-role turn immediately.
+    """
+    sid = str(session_id or "").strip()
+    if not sid:
+        return _payload(ok=False, action="error", error="missing_session", message="session_id required")
+
+    mgr = _manager(sid, profile_home=profile_home)
+    if mgr is None:
+        return _payload(ok=False, action="error", error="unavailable", message="Goals unavailable on this session.")
+
+    text = str(args or "").strip()
+    lower = text.lower()
+
+    if not text or lower == "status":
+        state = getattr(mgr, "state", None)
+        status_payload = _goal_status_payload(state)
+        return _payload(action="status", state=state, **status_payload)
+
+    if lower == "pause":
+        state = mgr.pause(reason="user-paused")
+        if state is None:
+            return _payload(
+                ok=False,
+                action="pause",
+                error="no_goal",
+                message="No goal set.",
+                message_key="goal_no_goal",
+            )
+        return _payload(
+            action="pause",
+            message=f"⏸ Goal paused: {state.goal}",
+            message_key="goal_paused",
+            message_args=[str(state.goal)],
+            state=state,
+        )
+
+    if lower == "resume":
+        state = mgr.resume()
+        if state is None:
+            return _payload(
+                ok=False,
+                action="resume",
+                error="no_goal",
+                message="No goal to resume.",
+                message_key="goal_no_goal",
+            )
+        return _payload(
+            action="resume",
+            message=(
+                f"▶ Goal resumed: {state.goal}\n"
+                "Send a new message, or type continue, to kick it off."
+            ),
+            message_key="goal_resumed",
+            message_args=[str(state.goal)],
+            state=state,
+        )
+
+    if lower in ("clear", "stop", "done"):
+        had = bool(mgr.has_goal())
+        mgr.clear()
+        return _payload(
+            action="clear",
+            message="Goal cleared." if had else "No active goal.",
+            message_key="goal_cleared" if had else "goal_no_goal",
+            state=getattr(mgr, "state", None),
+        )
+
+    if stream_running:
+        return _payload(
+            ok=False,
+            action="set",
+            error="agent_running",
+            message=(
+                "Agent is running — use /goal status / pause / clear mid-run, "
+                "or /stop before setting a new goal."
+            ),
+        )
+
+    try:
+        state = mgr.set(text)
+    except ValueError as exc:
+        return _payload(ok=False, action="set", error="invalid_goal", message=f"Invalid goal: {exc}")
+
+    return _payload(
+        action="set",
+        message=(
+            f"⊙ Goal set ({state.max_turns}-turn budget): {state.goal}\n"
+            "I'll keep working until the goal is done, you pause/clear it, or the budget is exhausted.\n"
+            "Controls: /goal status · /goal pause · /goal resume · /goal clear"
+        ),
+        message_key="goal_set",
+        message_args=[state.max_turns, state.goal],
+        state=state,
+        kickoff_prompt=state.goal,
+    )
+
+
+def has_active_goal(
+    session_id: str,
+    *,
+    profile_home: str | Path | None = None,
+) -> bool:
+    """Return True when the session has an active standing goal to evaluate."""
+    sid = str(session_id or "").strip()
+    if not sid:
+        return False
+    mgr = _manager(sid, profile_home=profile_home)
+    if mgr is None:
+        return False
+    try:
+        return bool(mgr.is_active())
+    except Exception as exc:
+        logger.debug("goal active-state check failed for session=%s: %s", sid, exc)
+        return False
+
+
+def evaluate_goal_after_turn(
+    session_id: str,
+    last_response: str,
+    *,
+    user_initiated: bool = True,
+    profile_home: str | Path | None = None,
+) -> Dict[str, Any]:
+    """Evaluate a completed turn against the standing goal, if any."""
+    sid = str(session_id or "").strip()
+    if not sid:
+        return {
+            "status": None,
+            "should_continue": False,
+            "continuation_prompt": None,
+            "verdict": "inactive",
+            "reason": "missing session_id",
+            "message": "",
+        }
+    mgr = _manager(sid, profile_home=profile_home)
+    if mgr is None:
+        return {
+            "status": None,
+            "should_continue": False,
+            "continuation_prompt": None,
+            "verdict": "inactive",
+            "reason": "goals unavailable",
+            "message": "",
+        }
+    try:
+        if not mgr.is_active():
+            return {
+                "status": getattr(getattr(mgr, "state", None), "status", None),
+                "should_continue": False,
+                "continuation_prompt": None,
+                "verdict": "inactive",
+                "reason": "no active goal",
+                "message": "",
+            }
+        decision = mgr.evaluate_after_turn(str(last_response or ""), user_initiated=user_initiated)
+    except Exception as exc:
+        logger.debug("goal evaluation failed for session=%s: %s", sid, exc)
+        return {
+            "status": None,
+            "should_continue": False,
+            "continuation_prompt": None,
+            "verdict": "error",
+            "reason": f"goal evaluation failed: {type(exc).__name__}",
+            "message": "",
+        }
+    if not isinstance(decision, dict):
+        decision = {}
+    decision.setdefault("should_continue", False)
+    decision.setdefault("continuation_prompt", None)
+    decision.setdefault("message", "")
+    decision = dict(decision)
+    decision = _goal_decision_payload(decision, getattr(mgr, "state", None))
+    return decision

api/helpers.py

@@ -2,22 +2,33 @@
 Hermes Web UI -- HTTP helper functions.
 """
 import json as _json
+import os
+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()
@@ -25,33 +36,267 @@ def safe_resolve(root: Path, requested: str) -> Path:
     return resolved
 
 
-def j(handler, payload, status=200):
-    """Send a JSON response."""
+def _security_headers(handler):
+    """Add security headers to every response."""
+    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' https://cdn.jsdelivr.net; "
+        "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 _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)
     handler.send_header('Content-Type', content_type)
     handler.send_header('Content-Length', str(len(body)))
     handler.send_header('Cache-Control', 'no-store')
+    _security_headers(handler)
     handler.end_headers()
     handler.wfile.write(body)
 
 
-def read_body(handler):
-    """Read and JSON-parse a POST request body."""
+MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
+
+
+# ── 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:
+        raise ValueError(f'Request body too large ({length} bytes, max {MAX_BODY_BYTES})')
     raw = handler.rfile.read(length) if length else b'{}'
     try:
         return _json.loads(raw)
     except Exception:
         return {}
+
+
+# ── Profile cookie helpers (issue #798) ─────────────────────────────────────
+
+PROFILE_COOKIE_NAME = 'hermes_profile'
+
+
+def get_profile_cookie_name() -> str:
+    """Return the cookie name used to persist the active WebUI profile."""
+    return os.getenv('WEBUI_PROFILE_COOKIE_NAME', PROFILE_COOKIE_NAME)
+
+
+def get_profile_cookie(handler) -> str | None:
+    """Extract the active-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
+    cookie_name = get_profile_cookie_name()
+    morsel = cookie.get(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 active-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_name = get_profile_cookie_name()
+    cookie[cookie_name] = name
+    cookie[cookie_name]['path'] = '/'
+    cookie[cookie_name]['httponly'] = True
+    cookie[cookie_name]['samesite'] = 'Lax'
+    return cookie[cookie_name].OutputString()

api/metering.py

@@ -0,0 +1,194 @@
+"""
+Hermes Web UI -- Streaming performance metering.
+
+Tracks Tokens Per Second (TPS) across active WebUI streams.  Metering data is
+emitted via SSE events so a streaming assistant message can update its own
+header while the turn is running.
+
+Architecture
+────────────
+Each streaming session is tracked independently.  TPS per stream is:
+
+    stream_tps = total_stream_deltas / (last_delta_ts - first_delta_ts)
+
+The global tps is the average of all currently active streams' 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 streams
+are actively receiving output deltas so message headers update 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_deltas)
+  meter().record_reasoning(stream_id, running_reasoning_deltas)
+
+The SSE `metering` event payload:
+  {
+    "tps": 47.3,              # omitted/null until a real reading exists
+    "tps_available": true,    # frontend must hide TPS when false
+    "estimated": false,       # never show byte/character-size estimates
+    "high": 52.1,
+    "low":  31.4,
+    "active": 1,
+  }
+"""
+
+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 | None:
+        if self.first_token_ts == 0.0 or self.last_token_ts <= self.first_token_ts:
+            return None
+        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 only streams with a real reading.  The
+            # UI hides TPS entirely when this is unavailable instead of showing
+            # placeholder/estimated values.
+            active = [s for s in self._sessions.values() if s.first_token_ts > 0]
+            active_tps = [v for s in active for v in [s.tps()] if v is not None and v > 0]
+            if active_tps:
+                global_tps = sum(active_tps) / len(active_tps)
+            else:
+                global_tps = None
+
+            # 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 is not None and 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) if global_tps is not None else None,
+                'tps_available': global_tps is not None,
+                'estimated': False,
+                'high': round(high, 1) if high else None,
+                'low': round(low, 1) if low else None,
+                'active': len(self._sessions),
+            }
+
+
+# ── Module-level singleton ─────────────────────────────────────────────────────
+
+_meter = GlobalMeter()
+
+
+def meter() -> GlobalMeter:
+    return _meter

api/oauth.py

@@ -0,0 +1,770 @@
+"""In-app OAuth flow implementations for onboarding.
+
+The browser receives only WebUI-local flow metadata (flow_id, user_code,
+verification_uri, high-level status). Provider device/auth codes and OAuth
+tokens stay server-side and are persisted to the active Hermes profile's
+``auth.json`` credential_pool.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import stat
+import threading
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Compatibility for older helper tests and self-heal code that import these.
+AUTH_JSON_PATH = Path.home() / ".hermes" / "auth.json"
+
+CODEX_ISSUER = "https://auth.openai.com"
+CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+CODEX_VERIFICATION_URI = f"{CODEX_ISSUER}/codex/device"
+CODEX_USER_CODE_URL = f"{CODEX_ISSUER}/api/accounts/deviceauth/usercode"
+CODEX_DEVICE_TOKEN_URL = f"{CODEX_ISSUER}/api/accounts/deviceauth/token"
+CODEX_TOKEN_URL = f"{CODEX_ISSUER}/oauth/token"
+CODEX_REDIRECT_URI = f"{CODEX_ISSUER}/deviceauth/callback"
+CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
+CODEX_FLOW_MAX_WAIT_SECONDS = 15 * 60
+
+_ALLOWED_ONBOARDING_OAUTH_PROVIDERS = {"openai-codex", "anthropic", "claude", "claude-code"}
+_ANTHROPIC_PROVIDER_ALIASES = {"anthropic", "claude", "claude-code"}
+_REJECTED_ONBOARDING_OAUTH_PROVIDERS = {
+    "nous",
+    "qwen-oauth",
+    "gemini-cli",
+    "google-gemini-cli",
+    "minimax",
+    "minimax-oauth",
+    "copilot",
+    "copilot-acp",
+}
+
+ANTHROPIC_CREDENTIAL_POLL_SECONDS = 5
+ANTHROPIC_FLOW_MAX_WAIT_SECONDS = 15 * 60
+ANTHROPIC_PUBLIC_LINK_ERROR = "Claude Code credential linking failed. Check server logs."
+
+_OAUTH_FLOWS: dict[str, dict[str, Any]] = {}
+_OAUTH_FLOWS_LOCK = threading.Lock()
+_ANTHROPIC_ENV_KEYS = ("ANTHROPIC_TOKEN", "ANTHROPIC_API_KEY")
+
+
+def _clear_process_anthropic_env_values() -> None:
+    """Clear Anthropic process env fallbacks under the streaming env lock."""
+    from api.streaming import _ENV_LOCK
+
+    with _ENV_LOCK:
+        for key in _ANTHROPIC_ENV_KEYS:
+            os.environ.pop(key, None)
+
+
+def resolve_runtime_provider_with_anthropic_env_lock(resolver, *args, **kwargs):
+    """Resolve runtime credentials under the Anthropic onboarding env lock.
+
+    Request paths must resolve Anthropic env fallbacks per outbound request,
+    not cache ANTHROPIC_TOKEN or ANTHROPIC_API_KEY across onboarding. Sharing
+    the process-env lock prevents a chat stream from observing one stale
+    Anthropic env value while onboarding has already cleared the other.
+    """
+    from api.streaming import _ENV_LOCK
+
+    with _ENV_LOCK:
+        return resolver(*args, **kwargs)
+
+
+def _normalize_onboarding_oauth_provider(provider: str) -> str:
+    provider = str(provider or "").strip().lower()
+    if provider in _ANTHROPIC_PROVIDER_ALIASES:
+        return "anthropic"
+    return provider or "openai-codex"
+
+
+def _get_active_hermes_home() -> Path:
+    try:
+        from api.profiles import get_active_hermes_home
+
+        return Path(get_active_hermes_home())
+    except Exception as exc:
+        # Per Opus advisor on stage-296: log the silent fallback so a corrupt
+        # profile state ending up writing tokens to ~/.hermes (instead of the
+        # active profile) is observable in logs rather than failing silently.
+        logger.warning(
+            "Falling back to ~/.hermes for OAuth credential storage: "
+            "active-profile resolution failed: %s",
+            exc,
+        )
+        return Path.home() / ".hermes"
+
+
+# ── legacy auth.json helpers ────────────────────────────────────────────────
+
+def _read_auth_json(auth_path: Path | None = None) -> dict[str, Any]:
+    """Read auth.json and return parsed dict, or an empty compatible store."""
+    path = auth_path or AUTH_JSON_PATH
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+            return loaded if isinstance(loaded, dict) else {}
+        except json.JSONDecodeError as exc:
+            logger.warning("Failed to parse %s: %s", path, exc)
+            return {}
+    return {}
+
+
+def read_auth_json():
+    """Public wrapper for streaming credential self-heal code."""
+    return _read_auth_json()
+
+
+def _write_auth_json(data: dict[str, Any], auth_path: Path | None = None) -> Path:
+    """Atomically write auth.json with owner-only permissions.
+
+    OAuth access/refresh tokens live in this file. The temp file is chmod 0600
+    before rename so the final path never inherits a permissive process umask.
+    """
+    path = auth_path or AUTH_JSON_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}")
+    try:
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        try:
+            tmp.chmod(0o600)
+        except OSError as exc:
+            logger.warning("Failed to chmod 0600 on %s: %s", tmp, exc)
+        tmp.replace(path)
+        try:
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+        return path
+    finally:
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _persist_codex_credentials(hermes_home: Path, token_data: dict[str, Any]) -> Path:
+    """Persist Codex OAuth credentials to active-profile auth.json."""
+    access_token = str(token_data.get("access_token") or "").strip()
+    refresh_token = str(token_data.get("refresh_token") or "").strip()
+    if not access_token:
+        raise RuntimeError("Codex token exchange did not return an access_token")
+
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    auth.setdefault("version", 1)
+    pool = auth.setdefault("credential_pool", {})
+    if not isinstance(pool, dict):
+        pool = {}
+        auth["credential_pool"] = pool
+    entries = pool.setdefault("openai-codex", [])
+    if not isinstance(entries, list):
+        entries = []
+        pool["openai-codex"] = entries
+
+    now = _now_iso()
+    entry = None
+    # Per Opus advisor on stage-296: also accept the legacy `source ==
+    # "oauth_device"` value so users with prior Codex OAuth credentials
+    # (written by older WebUI versions before this PR's source-key change)
+    # get their existing entry updated in-place rather than accumulating a
+    # stale duplicate pool entry.
+    _accept_sources = {"manual:device_code", "oauth_device"}
+    for candidate in entries:
+        if isinstance(candidate, dict) and candidate.get("source") in _accept_sources:
+            entry = candidate
+            break
+    if entry is None:
+        entry = {
+            "id": "codex-oauth-" + uuid.uuid4().hex[:12],
+            "label": "Codex OAuth",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "manual:device_code",
+            "base_url": CODEX_BASE_URL,
+            "created_at": now,
+        }
+        entries.insert(0, entry)
+
+    entry.update(
+        {
+            "label": "Codex OAuth",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "manual:device_code",
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "base_url": CODEX_BASE_URL,
+            "last_refresh": now,
+            "updated_at": now,
+        }
+    )
+    auth["updated_at"] = now
+    path = _write_auth_json(auth, auth_path)
+
+    try:
+        from api.config import invalidate_credential_pool_cache
+
+        invalidate_credential_pool_cache("openai-codex")
+    except Exception:
+        logger.debug("Failed to invalidate openai-codex credential cache", exc_info=True)
+
+    return path
+
+
+# Backward-compatible wrapper used by older code/tests.
+def _save_codex_credentials(token_data):
+    return _persist_codex_credentials(_get_active_hermes_home(), token_data)
+
+
+# ── Anthropic / Claude Code credential linking ─────────────────────────────
+
+def _read_claude_code_credentials() -> dict[str, Any] | None:
+    """Read Claude Code OAuth credentials from the host without exposing them.
+
+    Delegates to the agent adapter which knows about ~/.claude/.credentials.json
+    and macOS Keychain. Returns the credential dict or None.
+    """
+    try:
+        from agent.anthropic_adapter import (
+            is_claude_code_token_valid,
+            read_claude_code_credentials,
+        )
+
+        creds = read_claude_code_credentials()
+        if creds and (
+            is_claude_code_token_valid(creds) or bool(creds.get("refreshToken"))
+        ):
+            return creds
+    except Exception as exc:
+        logger.debug("Could not read Claude Code credentials: %s", exc)
+    return None
+
+
+def _clear_anthropic_env_values(hermes_home: Path) -> None:
+    """Clear Anthropic API/setup-token env values in the active profile only.
+
+    The .env write path already clears os.environ while holding the streaming
+    env lock. Keep a locked process-env clear here too so import/write failures
+    cannot leave or partially clear stale Anthropic fallbacks.
+    """
+    try:
+        from api.providers import _write_env_file
+
+        _write_env_file(
+            Path(hermes_home) / ".env",
+            {key: None for key in _ANTHROPIC_ENV_KEYS},
+        )
+    except Exception as exc:
+        logger.warning("Failed to clear Anthropic env values: %s", exc)
+    _clear_process_anthropic_env_values()
+
+
+def _link_anthropic_credentials(hermes_home: Path) -> None:
+    """Link Hermes to use Claude Code's credential store.
+
+    Clears ANTHROPIC_TOKEN and ANTHROPIC_API_KEY from the Hermes .env so
+    that resolve_anthropic_token() falls through to reading Claude Code's
+    ~/.claude/.credentials.json directly — the same thing the CLI's
+    ``use_anthropic_claude_code_credentials()`` does.
+
+    Also writes a marker entry in auth.json credential_pool so that
+    ``_provider_oauth_authenticated("anthropic", ...)`` can detect the
+    linked state without touching the actual credential files.
+    """
+    _clear_anthropic_env_values(hermes_home)
+
+    # Write a pool marker (no secrets) so onboarding status can detect linkage.
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    auth.setdefault("version", 1)
+    pool = auth.setdefault("credential_pool", {})
+    if not isinstance(pool, dict):
+        pool = {}
+        auth["credential_pool"] = pool
+    entries = pool.setdefault("anthropic", [])
+    if not isinstance(entries, list):
+        entries = []
+        pool["anthropic"] = entries
+
+    now = _now_iso()
+    entry = None
+    for candidate in entries:
+        if isinstance(candidate, dict) and candidate.get("source") == "claude_code_linked":
+            entry = candidate
+            break
+    if entry is None:
+        entry = {
+            "id": "anthropic-claude-code-" + uuid.uuid4().hex[:12],
+            "label": "Claude Code (linked)",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "claude_code_linked",
+            "created_at": now,
+        }
+        entries.insert(0, entry)
+
+    entry.update({
+        "label": "Claude Code (linked)",
+        "auth_type": "oauth",
+        "priority": 0,
+        "source": "claude_code_linked",
+        "updated_at": now,
+    })
+    auth["updated_at"] = now
+    _write_auth_json(auth, auth_path)
+
+    try:
+        from api.config import invalidate_credential_pool_cache
+        invalidate_credential_pool_cache("anthropic")
+    except Exception:
+        logger.debug("Failed to invalidate anthropic credential cache", exc_info=True)
+
+
+def _anthropic_public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": True,
+        "provider": "anthropic",
+        "flow_id": flow_id,
+        "status": flow.get("status", "pending"),
+        "poll_interval_seconds": flow.get("poll_interval_seconds", ANTHROPIC_CREDENTIAL_POLL_SECONDS),
+    }
+    if flow.get("status") == "pending":
+        payload["action_required"] = (
+            "Claude Code credentials were not found on this server. "
+            "Please run 'claude login' or 'claude setup-token' in a terminal "
+            "on the host, then return here — this page will detect the credentials automatically."
+        )
+    if flow.get("expires_at"):
+        payload["expires_at"] = flow["expires_at"]
+    return payload
+
+
+def _anthropic_public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": True,
+        "provider": "anthropic",
+        "flow_id": flow_id,
+        "status": flow.get("status", "error"),
+    }
+    if flow.get("status") == "error" and flow.get("error"):
+        payload["error"] = ANTHROPIC_PUBLIC_LINK_ERROR
+    return payload
+
+
+def _spawn_anthropic_credential_worker(flow_id: str) -> None:
+    worker = threading.Thread(
+        target=_run_anthropic_credential_worker, args=(flow_id,), daemon=True,
+    )
+    worker.start()
+
+
+def _run_anthropic_credential_worker(flow_id: str) -> None:
+    """Poll for Claude Code credential appearance until found, cancelled, or expired."""
+    while True:
+        with _OAUTH_FLOWS_LOCK:
+            flow = dict(_OAUTH_FLOWS.get(flow_id) or {})
+        if not flow:
+            return
+        if flow.get("status") != "pending":
+            return
+        if float(flow.get("expires_at") or 0) <= time.time():
+            _set_flow_status(flow_id, "expired")
+            return
+
+        time.sleep(max(1, int(flow.get("poll_interval_seconds") or ANTHROPIC_CREDENTIAL_POLL_SECONDS)))
+
+        # Re-check status under lock (cancel may have arrived during sleep)
+        with _OAUTH_FLOWS_LOCK:
+            live = _OAUTH_FLOWS.get(flow_id)
+            if not live or live.get("status") != "pending":
+                return
+
+        try:
+            creds = _read_claude_code_credentials()
+            if creds is None:
+                continue
+
+            # Re-check status under lock before linking — cancel must win
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if not current or current.get("status") != "pending":
+                    return
+
+            hermes_home = Path(flow["hermes_home"])
+            _link_anthropic_credentials(hermes_home)
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if not current or current.get("status") != "pending":
+                    cancelled = bool(current and current.get("status") == "cancelled")
+                else:
+                    current["status"] = "success"
+                    current["updated_at"] = time.time()
+                    _drop_sensitive_flow_fields(current)
+                    cancelled = False
+            if cancelled:
+                _remove_anthropic_link_marker(hermes_home)
+            return
+        except Exception as exc:
+            logger.warning("Anthropic credential polling failed: %s", exc)
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if current and current.get("status") == "pending":
+                    current["status"] = "error"
+                    current["updated_at"] = time.time()
+                    current["error"] = str(exc)
+                    _drop_sensitive_flow_fields(current)
+            return
+
+
+def _remove_anthropic_link_marker(hermes_home: Path) -> None:
+    """Remove the secret-free Claude Code linked marker after a cancelled race."""
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    pool = auth.get("credential_pool")
+    if not isinstance(pool, dict):
+        return
+    entries = pool.get("anthropic")
+    if not isinstance(entries, list):
+        return
+    kept = [entry for entry in entries if not (isinstance(entry, dict) and entry.get("source") == "claude_code_linked")]
+    if len(kept) == len(entries):
+        return
+    if kept:
+        pool["anthropic"] = kept
+    else:
+        pool.pop("anthropic", None)
+    auth["updated_at"] = _now_iso()
+    _write_auth_json(auth, auth_path)
+    try:
+        from api.config import invalidate_credential_pool_cache
+        invalidate_credential_pool_cache("anthropic")
+    except Exception:
+        logger.debug("Failed to invalidate anthropic credential cache", exc_info=True)
+
+
+# ── Codex protocol ──────────────────────────────────────────────────────────
+
+def _json_request(url: str, payload: dict[str, Any], *, form: bool = False) -> dict[str, Any]:
+    if form:
+        data = urllib.parse.urlencode(payload).encode("utf-8")
+        content_type = "application/x-www-form-urlencoded"
+    else:
+        data = json.dumps(payload).encode("utf-8")
+        content_type = "application/json"
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={"Content-Type": content_type, "Accept": "application/json"},
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _request_codex_user_code() -> dict[str, Any]:
+    return _json_request(CODEX_USER_CODE_URL, {"client_id": CODEX_CLIENT_ID})
+
+
+def _poll_codex_authorization(device_auth_id: str, user_code: str) -> dict[str, Any] | None:
+    try:
+        return _json_request(
+            CODEX_DEVICE_TOKEN_URL,
+            {"device_auth_id": device_auth_id, "user_code": user_code},
+        )
+    except urllib.error.HTTPError as exc:
+        if exc.code in (403, 404):
+            return None
+        raise
+
+
+def _exchange_codex_authorization(authorization_code: str, code_verifier: str) -> dict[str, Any]:
+    return _json_request(
+        CODEX_TOKEN_URL,
+        {
+            "grant_type": "authorization_code",
+            "code": authorization_code,
+            "redirect_uri": CODEX_REDIRECT_URI,
+            "client_id": CODEX_CLIENT_ID,
+            "code_verifier": code_verifier,
+        },
+        form=True,
+    )
+
+
+def _codex_public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "provider": "openai-codex",
+        "flow_id": flow_id,
+        "status": flow.get("status", "pending"),
+        "verification_uri": CODEX_VERIFICATION_URI,
+        "user_code": flow.get("user_code", ""),
+        "expires_at": flow.get("expires_at"),
+        "poll_interval_seconds": flow.get("poll_interval_seconds", 5),
+    }
+
+
+def _codex_public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    payload = {
+        "ok": True,
+        "provider": "openai-codex",
+        "flow_id": flow_id,
+        "status": flow.get("status", "error"),
+    }
+    if flow.get("status") == "error" and flow.get("error"):
+        payload["error"] = str(flow.get("error"))[:200]
+    return payload
+
+
+def _public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    provider = flow.get("provider", "openai-codex")
+    if provider == "anthropic":
+        return _anthropic_public_start_payload(flow_id, flow)
+    return _codex_public_start_payload(flow_id, flow)
+
+
+def _public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    provider = flow.get("provider", "openai-codex")
+    if provider == "anthropic":
+        return _anthropic_public_status_payload(flow_id, flow)
+    return _codex_public_status_payload(flow_id, flow)
+
+
+def _drop_sensitive_flow_fields(flow: dict[str, Any]) -> None:
+    for key in (
+        "device_auth_id",
+        "authorization_code",
+        "code_verifier",
+        "access_token",
+        "refresh_token",
+        "token_data",
+    ):
+        flow.pop(key, None)
+
+
+def _cleanup_oauth_flows(now: float | None = None) -> None:
+    now = now or time.time()
+    cutoff = now - 300
+    with _OAUTH_FLOWS_LOCK:
+        for fid, flow in list(_OAUTH_FLOWS.items()):
+            status = flow.get("status")
+            if status == "pending" and float(flow.get("expires_at") or 0) <= now:
+                flow["status"] = "expired"
+                _drop_sensitive_flow_fields(flow)
+            if status in {"success", "expired", "cancelled", "error"} and float(flow.get("updated_at") or 0) < cutoff:
+                _OAUTH_FLOWS.pop(fid, None)
+
+
+def _spawn_codex_oauth_worker(flow_id: str) -> None:
+    worker = threading.Thread(target=_run_codex_oauth_worker, args=(flow_id,), daemon=True)
+    worker.start()
+
+
+def _set_flow_status(flow_id: str, status: str, **fields: Any) -> None:
+    with _OAUTH_FLOWS_LOCK:
+        flow = _OAUTH_FLOWS.get(flow_id)
+        if not flow:
+            return
+        flow["status"] = status
+        flow["updated_at"] = time.time()
+        flow.update(fields)
+        if status in {"success", "expired", "cancelled", "error"}:
+            _drop_sensitive_flow_fields(flow)
+
+
+def _run_codex_oauth_worker(flow_id: str) -> None:
+    while True:
+        with _OAUTH_FLOWS_LOCK:
+            flow = dict(_OAUTH_FLOWS.get(flow_id) or {})
+        if not flow:
+            return
+        status = flow.get("status")
+        if status != "pending":
+            return
+        if float(flow.get("expires_at") or 0) <= time.time():
+            _set_flow_status(flow_id, "expired")
+            return
+
+        time.sleep(max(1, int(flow.get("poll_interval_seconds") or 5)))
+
+        with _OAUTH_FLOWS_LOCK:
+            live = dict(_OAUTH_FLOWS.get(flow_id) or {})
+        if live.get("status") != "pending":
+            return
+        try:
+            code_resp = _poll_codex_authorization(
+                str(live.get("device_auth_id") or ""),
+                str(live.get("user_code") or ""),
+            )
+            if code_resp is None:
+                continue
+            authorization_code = str(code_resp.get("authorization_code") or "").strip()
+            code_verifier = str(code_resp.get("code_verifier") or "").strip()
+            if not authorization_code or not code_verifier:
+                raise RuntimeError("Device auth response missing authorization_code or code_verifier")
+            tokens = _exchange_codex_authorization(authorization_code, code_verifier)
+            # Re-check status under lock before persisting: a cancel/expire that
+            # raced with the device-token + token-exchange network calls must
+            # win, so we don't persist credentials the user explicitly aborted.
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if not current or current.get("status") != "pending":
+                    return
+            _persist_codex_credentials(Path(live["hermes_home"]), tokens)
+            _set_flow_status(flow_id, "success")
+            return
+        except Exception as exc:
+            logger.warning("Codex OAuth onboarding flow failed: %s", exc)
+            _set_flow_status(flow_id, "error", error=str(exc))
+            return
+
+
+def _start_anthropic_flow(hermes_home: Path) -> dict[str, Any]:
+    """Start or immediately complete the Anthropic credential-linking flow."""
+    creds = _read_claude_code_credentials()
+    flow_id = uuid.uuid4().hex
+
+    if creds:
+        # Credentials already exist — link and return success immediately.
+        _link_anthropic_credentials(hermes_home)
+        flow = {
+            "provider": "anthropic",
+            "status": "success",
+            "hermes_home": str(hermes_home),
+            "created_at": time.time(),
+            "updated_at": time.time(),
+        }
+        with _OAUTH_FLOWS_LOCK:
+            _OAUTH_FLOWS[flow_id] = flow
+        return _public_start_payload(flow_id, flow)
+
+    # No credentials found — create a pending flow that polls for them.
+    expires_at = time.time() + ANTHROPIC_FLOW_MAX_WAIT_SECONDS
+    flow = {
+        "provider": "anthropic",
+        "status": "pending",
+        "expires_at": expires_at,
+        "poll_interval_seconds": ANTHROPIC_CREDENTIAL_POLL_SECONDS,
+        "hermes_home": str(hermes_home),
+        "created_at": time.time(),
+        "updated_at": time.time(),
+    }
+    with _OAUTH_FLOWS_LOCK:
+        _OAUTH_FLOWS[flow_id] = flow
+    _spawn_anthropic_credential_worker(flow_id)
+    return _public_start_payload(flow_id, flow)
+
+
+def start_onboarding_oauth_flow(body: dict[str, Any] | None) -> dict[str, Any]:
+    """Start the supported onboarding OAuth flow.
+
+    Supports OpenAI Codex (device-code flow) and Anthropic/Claude Code
+    (credential-linking flow). Other providers are rejected.
+    """
+    _cleanup_oauth_flows()
+    provider = str((body or {}).get("provider") or "").strip().lower()
+    if provider not in _ALLOWED_ONBOARDING_OAUTH_PROVIDERS:
+        if provider in _REJECTED_ONBOARDING_OAUTH_PROVIDERS or provider:
+            raise ValueError(
+                "Only OpenAI Codex and Anthropic/Claude OAuth are supported "
+                "in WebUI onboarding right now"
+            )
+        raise ValueError("provider is required")
+
+    # Normalize Claude aliases to canonical "anthropic"
+    if provider in _ANTHROPIC_PROVIDER_ALIASES:
+        return _start_anthropic_flow(_get_active_hermes_home())
+
+    # Codex flow
+    hermes_home = _get_active_hermes_home()
+    try:
+        device = _request_codex_user_code()
+    except Exception as exc:
+        raise RuntimeError(f"Failed to start Codex OAuth: {exc}") from exc
+
+    user_code = str(device.get("user_code") or "").strip()
+    device_auth_id = str(device.get("device_auth_id") or "").strip()
+    if not user_code or not device_auth_id:
+        raise RuntimeError("Device code response missing required fields")
+
+    interval = max(3, int(device.get("interval") or 5))
+    expires_in = int(device.get("expires_in") or CODEX_FLOW_MAX_WAIT_SECONDS)
+    expires_at = time.time() + min(max(expires_in, 60), CODEX_FLOW_MAX_WAIT_SECONDS)
+    flow_id = uuid.uuid4().hex
+    flow = {
+        "provider": "openai-codex",
+        "status": "pending",
+        "device_auth_id": device_auth_id,
+        "user_code": user_code,
+        "expires_at": expires_at,
+        "poll_interval_seconds": interval,
+        "hermes_home": str(hermes_home),
+        "created_at": time.time(),
+        "updated_at": time.time(),
+    }
+    with _OAUTH_FLOWS_LOCK:
+        _OAUTH_FLOWS[flow_id] = flow
+    _spawn_codex_oauth_worker(flow_id)
+    return _public_start_payload(flow_id, flow)
+
+
+def poll_onboarding_oauth_flow(flow_id: str) -> dict[str, Any]:
+    _cleanup_oauth_flows()
+    fid = str(flow_id or "").strip()
+    if not fid:
+        raise ValueError("flow_id is required")
+    with _OAUTH_FLOWS_LOCK:
+        flow = _OAUTH_FLOWS.get(fid)
+        if not flow:
+            raise KeyError("OAuth flow not found")
+        if flow.get("status") == "pending" and float(flow.get("expires_at") or 0) <= time.time():
+            flow["status"] = "expired"
+            flow["updated_at"] = time.time()
+            _drop_sensitive_flow_fields(flow)
+        return _public_status_payload(fid, dict(flow))
+
+
+def cancel_onboarding_oauth_flow(body: dict[str, Any] | None) -> dict[str, Any]:
+    fid = str((body or {}).get("flow_id") or "").strip()
+    if not fid:
+        raise ValueError("flow_id is required")
+    requested_provider = _normalize_onboarding_oauth_provider(str((body or {}).get("provider") or ""))
+    if requested_provider not in {"openai-codex", "anthropic"}:
+        requested_provider = "openai-codex"
+    with _OAUTH_FLOWS_LOCK:
+        flow = _OAUTH_FLOWS.get(fid)
+        if not flow:
+            return {"ok": True, "provider": requested_provider, "flow_id": fid, "status": "cancelled"}
+        if flow.get("status") == "pending":
+            flow["status"] = "cancelled"
+            flow["updated_at"] = time.time()
+            _drop_sensitive_flow_fields(flow)
+        result = _public_status_payload(fid, dict(flow))
+    return result
+
+
+# Backward-compatible names from the abandoned spike. They intentionally do not
+# expose provider device secrets to callers anymore.
+def start_codex_device_code():
+    return start_onboarding_oauth_flow({"provider": "openai-codex"})
+
+
+def poll_codex_token(device_code, interval=5):
+    yield {"status": "error", "error": "Use /api/onboarding/oauth/poll with flow_id"}

api/onboarding.py

@@ -0,0 +1,993 @@
+"""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",
+        "oauth_provider": "anthropic",
+        "oauth_label": "Claude Code OAuth",
+    },
+    "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 = (
+    "Advanced provider flows such as Nous Portal and GitHub Copilot are still "
+    "terminal-first. OpenAI Codex and Anthropic Claude Code can be authenticated in this onboarding flow "
+    "when your Hermes config selects the corresponding provider."
+)
+
+
+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", "anthropic"}
+    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()
+    provider = {"claude": "anthropic", "claude-code": "anthropic"}.get(provider, provider)
+    if not provider:
+        return False
+
+    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous", "anthropic"}
+    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):
+                for entry in entries:
+                    if _oauth_payload_has_token(entry):
+                        return True
+                    if (
+                        provider == "anthropic"
+                        and isinstance(entry, dict)
+                        and entry.get("auth_type") == "oauth"
+                        and entry.get("source") == "claude_code_linked"
+                    ):
+                        return True
+
+        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)
+                if not provider_ready and meta.get("oauth_provider"):
+                    provider_ready = _provider_oauth_authenticated(
+                        str(meta.get("oauth_provider")), _get_active_hermes_home()
+                    )
+        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),
+                "oauth_provider": meta.get("oauth_provider") or "",
+                "oauth_label": meta.get("oauth_label") or "",
+            }
+        )
+
+    # 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)
+    ) or _provider_oauth_authenticated(current_provider, _get_active_hermes_home())
+
+    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. OAuth-capable wizard providers (currently Anthropic
+        # via Claude Code) are also allowed once their server-side OAuth/link
+        # marker is present.
+        oauth_ready = bool(provider_meta.get("oauth_provider")) and _provider_oauth_authenticated(
+            str(provider_meta.get("oauth_provider")), _get_active_hermes_home()
+        )
+        if not provider_meta.get("key_optional") and not oauth_ready:
+            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/request_diagnostics.py

@@ -0,0 +1,160 @@
+"""Slow request diagnostics for latency-sensitive browser API paths."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import threading
+import time
+import traceback
+import uuid
+from typing import Any
+
+
+DEFAULT_SLOW_REQUEST_SECONDS = 5.0
+MAX_STACK_FRAMES_PER_THREAD = 40
+
+
+def _slow_request_seconds() -> float:
+    raw = os.getenv("HERMES_WEBUI_SLOW_REQUEST_SECONDS", "").strip()
+    if not raw:
+        return DEFAULT_SLOW_REQUEST_SECONDS
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_SLOW_REQUEST_SECONDS
+    return max(0.0, value)
+
+
+class RequestDiagnostics:
+    """Track request stages and emit a watchdog record if a request wedges."""
+
+    def __init__(
+        self,
+        method: str,
+        path: str,
+        *,
+        logger: logging.Logger | None = None,
+        timeout_seconds: float | None = None,
+        auto_start: bool = True,
+    ) -> None:
+        self.request_id = uuid.uuid4().hex[:10]
+        self.method = str(method or "-")
+        self.path = str(path or "-").split("?", 1)[0]
+        self.logger = logger or logging.getLogger(__name__)
+        self.timeout_seconds = _slow_request_seconds() if timeout_seconds is None else max(0.0, float(timeout_seconds))
+        self.started_monotonic = time.monotonic()
+        self.started_wall = time.time()
+        self._lock = threading.Lock()
+        self._stages: list[dict[str, Any]] = []
+        self._current_stage = "start"
+        self._current_stage_started = self.started_monotonic
+        self._finished = False
+        self._watchdog_logged = False
+        self._timer: threading.Timer | None = None
+        if auto_start and self.timeout_seconds > 0:
+            self._timer = threading.Timer(self.timeout_seconds, self._on_timeout)
+            self._timer.daemon = True
+            self._timer.start()
+
+    @classmethod
+    def maybe_start(
+        cls,
+        method: str,
+        path: str,
+        *,
+        logger: logging.Logger | None = None,
+    ) -> "RequestDiagnostics | None":
+        clean_path = str(path or "").split("?", 1)[0]
+        if (method.upper(), clean_path) not in {
+            ("GET", "/api/sessions"),
+            ("POST", "/api/chat/start"),
+        }:
+            return None
+        return cls(method, clean_path, logger=logger)
+
+    def stage(self, name: str) -> None:
+        now = time.monotonic()
+        clean = str(name or "unknown").strip() or "unknown"
+        with self._lock:
+            if self._finished:
+                return
+            self._stages.append(
+                {
+                    "name": self._current_stage,
+                    "ms": round((now - self._current_stage_started) * 1000, 1),
+                }
+            )
+            self._current_stage = clean
+            self._current_stage_started = now
+
+    def finish(self) -> None:
+        timer = None
+        record = None
+        with self._lock:
+            if self._finished:
+                return
+            self._finished = True
+            timer = self._timer
+            record = self._build_record_locked(include_stacks=False)
+        if timer is not None:
+            timer.cancel()
+        if record and self.timeout_seconds > 0 and record["elapsed_ms"] >= self.timeout_seconds * 1000:
+            self.logger.warning(
+                "Slow WebUI request completed: %s",
+                json.dumps(record, sort_keys=True),
+            )
+
+    def _on_timeout(self) -> None:
+        with self._lock:
+            if self._finished or self._watchdog_logged:
+                return
+            self._watchdog_logged = True
+            record = self._build_record_locked(include_stacks=True)
+        self.logger.warning(
+            "Slow WebUI request still running: %s",
+            json.dumps(record, sort_keys=True),
+        )
+
+    def _build_record_locked(self, *, include_stacks: bool) -> dict[str, Any]:
+        now = time.monotonic()
+        stages = list(self._stages)
+        stages.append(
+            {
+                "name": self._current_stage,
+                "ms": round((now - self._current_stage_started) * 1000, 1),
+            }
+        )
+        record: dict[str, Any] = {
+            "request_id": self.request_id,
+            "method": self.method,
+            "path": self.path,
+            "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(self.started_wall)),
+            "elapsed_ms": round((now - self.started_monotonic) * 1000, 1),
+            "current_stage": self._current_stage,
+            "stages": stages,
+        }
+        if include_stacks:
+            record["thread_stacks"] = _thread_stack_snapshot()
+        return record
+
+
+def _thread_stack_snapshot() -> list[dict[str, Any]]:
+    frames = sys._current_frames()
+    threads = {thread.ident: thread for thread in threading.enumerate()}
+    snapshot: list[dict[str, Any]] = []
+    for ident, frame in frames.items():
+        thread = threads.get(ident)
+        stack = traceback.format_stack(frame, limit=MAX_STACK_FRAMES_PER_THREAD)
+        snapshot.append(
+            {
+                "thread_id": ident,
+                "thread_name": thread.name if thread else "",
+                "daemon": bool(thread.daemon) if thread else None,
+                "stack": [line.rstrip() for line in stack],
+            }
+        )
+    snapshot.sort(key=lambda item: str(item.get("thread_name") or ""))
+    return snapshot

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/session_recovery.py

@@ -0,0 +1,158 @@
+"""
+Session recovery from .bak snapshots — last line of defense against
+data-loss bugs like #1558.
+
+``Session.save()`` writes a ``<sid>.json.bak`` snapshot of the previous
+state whenever an incoming save would shrink the messages array. This
+module reads those snapshots back and restores any session whose live
+file has fewer messages than its backup.
+
+Three integration points:
+
+1. ``recover_all_sessions_on_startup()`` — called from server.py at boot,
+   scans the session dir, restores any session whose JSON has fewer
+   messages than its .bak. Idempotent: a clean run is a no-op.
+
+2. ``recover_session(sid)`` — single-session helper backing the
+   ``POST /api/session/recover`` endpoint, so users can re-run recovery
+   manually if their session was open through a server restart.
+
+3. ``inspect_session_recovery_status(sid)`` — read-only audit returning
+   message counts for the live JSON, the .bak, and a recommendation.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _msg_count(p: Path) -> int:
+    """Return the number of messages in a session JSON file, or -1 on read/parse error.
+
+    Returns -1 for any non-session-shape file:
+    - File can't be read (OSError)
+    - Top-level isn't valid JSON or is invalid (JSONDecodeError, ValueError)
+    - Top-level isn't a dict (AttributeError on .get) — e.g. ``_index.json``
+      which is a top-level list of session metadata, not a session itself.
+      The startup recovery scanner globs ``*.json`` and would otherwise
+      crash on the first non-dict file it encounters.
+    """
+    try:
+        data = json.loads(p.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return -1
+    if not isinstance(data, dict):
+        return -1
+    msgs = data.get('messages')
+    return len(msgs) if isinstance(msgs, list) else -1
+
+
+def inspect_session_recovery_status(session_path: Path) -> dict:
+    """Return a status dict describing whether recovery is recommended.
+
+    {
+      "session_id": "...",
+      "live_messages": int,    # -1 if live file unreadable
+      "bak_messages": int,     # -1 if no .bak or unreadable
+      "recommend": "restore" | "no_action" | "no_backup",
+    }
+    """
+    bak_path = session_path.with_suffix('.json.bak')
+    live_count = _msg_count(session_path)
+    if not bak_path.exists():
+        return {
+            "session_id": session_path.stem,
+            "live_messages": live_count,
+            "bak_messages": -1,
+            "recommend": "no_backup",
+        }
+    bak_count = _msg_count(bak_path)
+    if bak_count > live_count:
+        return {
+            "session_id": session_path.stem,
+            "live_messages": live_count,
+            "bak_messages": bak_count,
+            "recommend": "restore",
+        }
+    return {
+        "session_id": session_path.stem,
+        "live_messages": live_count,
+        "bak_messages": bak_count,
+        "recommend": "no_action",
+    }
+
+
+def recover_session(session_path: Path) -> dict:
+    """Restore session_path from its .bak when the bak has more messages.
+
+    Returns a status dict identical to ``inspect_session_recovery_status``
+    plus a "restored" boolean.
+    """
+    status = inspect_session_recovery_status(session_path)
+    if status["recommend"] != "restore":
+        return {**status, "restored": False}
+    bak_path = session_path.with_suffix('.json.bak')
+    # Stage the recovery via a tmp copy + atomic replace so a crash mid-restore
+    # cannot leave a half-written session.json.
+    tmp_path = session_path.with_suffix('.json.recover.tmp')
+    try:
+        shutil.copyfile(bak_path, tmp_path)
+        tmp_path.replace(session_path)
+    except OSError as exc:
+        logger.warning("recover_session: copy failed for %s: %s", session_path, exc)
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return {**status, "restored": False, "error": str(exc)}
+    logger.warning(
+        "recover_session: restored %s from .bak (live=%d → bak=%d messages). "
+        "See #1558 for the data-loss class this guards against.",
+        session_path.name, status["live_messages"], status["bak_messages"],
+    )
+    return {**status, "restored": True}
+
+
+def recover_all_sessions_on_startup(session_dir: Path) -> dict:
+    """Scan session_dir for shrunken sessions, restore each from its .bak.
+
+    Returns {"scanned": N, "restored": M, "details": [...]}.
+    """
+    if not session_dir.exists():
+        return {"scanned": 0, "restored": 0, "details": []}
+    scanned = 0
+    restored = 0
+    details: list[dict] = []
+    for path in session_dir.glob('*.json'):
+        # Skip non-session JSON files in the same dir:
+        # - ``_index.json`` is a top-level list of session metadata
+        # - any future non-session JSON marked with the ``_`` convention is
+        #   skipped automatically (project convention for system files in
+        #   directories that otherwise hold user data)
+        if path.name.startswith('_'):
+            continue
+        scanned += 1
+        try:
+            result = recover_session(path)
+        except Exception as exc:
+            # Defensive: a malformed session file shouldn't break recovery
+            # for the rest. Log and continue.
+            logger.warning(
+                "recover_all_sessions_on_startup: skipped %s due to %s: %s",
+                path.name, type(exc).__name__, exc,
+            )
+            continue
+        if result.get("restored"):
+            restored += 1
+            details.append(result)
+    if restored:
+        logger.warning(
+            "recover_all_sessions_on_startup: restored %d/%d sessions from .bak. "
+            "If you weren't expecting this, check the session list for missing "
+            "messages — see #1558.", restored, scanned,
+        )
+    return {"scanned": scanned, "restored": restored, "details": details}

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

@@ -0,0 +1,118 @@
+"""
+Hermes Web UI -- Optional state.db sync bridge.
+
+Mirrors WebUI session metadata (token usage, title, model) into the
+hermes-agent state.db so that /insights, session lists, and cost
+tracking include WebUI activity.
+
+This is opt-in via the 'sync_to_insights' setting (default: off).
+All operations are wrapped in try/except -- if state.db is unavailable,
+locked, or the schema doesn't match, the WebUI continues normally.
+
+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.
+    Returns None if hermes_state is not importable or DB is unavailable.
+    Each caller is responsible for calling db.close() when done.
+    """
+    try:
+        from hermes_state import SessionDB
+    except ImportError:
+        return None
+
+    try:
+        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'
+    if not db_path.exists():
+        return None
+
+    try:
+        return SessionDB(db_path)
+    except Exception:
+        logger.debug("Failed to open state.db")
+        return 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.
+    """
+    db = _get_state_db()
+    if not db:
+        return
+    try:
+        db.ensure_session(
+            session_id=session_id,
+            source='webui',
+            model=model,
+        )
+    except Exception:
+        logger.debug("Failed to sync session start to state.db")
+    finally:
+        try:
+            db.close()
+        except Exception:
+            logger.debug("Failed to close state.db")
+
+
+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).
+    """
+    db = _get_state_db()
+    if not db:
+        return
+    try:
+        # Ensure session exists first (idempotent)
+        db.ensure_session(session_id=session_id, source='webui', model=model)
+        # Set absolute token counts
+        db.update_token_counts(
+            session_id=session_id,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            estimated_cost_usd=estimated_cost,
+            model=model,
+            absolute=True,
+        )
+        # Update title if we have one, using the public API
+        if title:
+            try:
+                db.set_session_title(session_id, title)
+            except Exception:
+                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:
+        logger.debug("Failed to sync session usage to state.db")
+    finally:
+        try:
+            db.close()
+        except Exception:
+            logger.debug("Failed to close state.db")

api/system_health.py

@@ -0,0 +1,167 @@
+"""Safe aggregate host resource metrics for the WebUI VPS panel (#693).
+
+The browser only needs coarse CPU/RAM/disk usage. Keep this module intentionally
+small and dependency-free: no process lists, command strings, user identities,
+environment variables, or filesystem topology leave the server.
+"""
+
+from __future__ import annotations
+
+import shutil
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+_PROC_STAT = Path("/proc/stat")
+_PROC_MEMINFO = Path("/proc/meminfo")
+_CPU_SAMPLE_SECONDS = 0.05
+
+
+def _checked_at() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _clamp_percent(value: Any) -> float:
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    if numeric < 0:
+        numeric = 0.0
+    if numeric > 100:
+        numeric = 100.0
+    return round(numeric, 1)
+
+
+def _read_proc_stat_cpu() -> tuple[int, int]:
+    """Return (idle_ticks, total_ticks) from Linux /proc/stat."""
+    with _PROC_STAT.open("r", encoding="utf-8") as handle:
+        first = handle.readline().strip().split()
+    if not first or first[0] != "cpu":
+        raise RuntimeError("proc_stat_unavailable")
+    values = [int(part) for part in first[1:]]
+    if len(values) < 4:
+        raise RuntimeError("proc_stat_unavailable")
+    idle = values[3] + (values[4] if len(values) > 4 else 0)
+    total = sum(values)
+    if total <= 0:
+        raise RuntimeError("proc_stat_unavailable")
+    return idle, total
+
+
+def _cpu_delta_percent(start: tuple[int, int], end: tuple[int, int]) -> float:
+    idle_delta = end[0] - start[0]
+    total_delta = end[1] - start[1]
+    if total_delta <= 0:
+        return 0.0
+    busy_delta = max(0, total_delta - max(0, idle_delta))
+    return _clamp_percent((busy_delta / total_delta) * 100.0)
+
+
+def _cpu_percent() -> float:
+    """Sample aggregate CPU usage without psutil.
+
+    A short local sample avoids storing cross-request state and returns a stable
+    percentage on the first poll. Unsupported platforms raise a safe error code.
+    """
+    start = _read_proc_stat_cpu()
+    time.sleep(_CPU_SAMPLE_SECONDS)
+    end = _read_proc_stat_cpu()
+    return _cpu_delta_percent(start, end)
+
+
+def _read_meminfo_kib() -> dict[str, int]:
+    data: dict[str, int] = {}
+    with _PROC_MEMINFO.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            key, _, rest = line.partition(":")
+            if not key or not rest:
+                continue
+            parts = rest.strip().split()
+            if not parts:
+                continue
+            try:
+                data[key] = int(parts[0])
+            except ValueError:
+                continue
+    return data
+
+
+def _memory_usage() -> dict[str, int | float]:
+    meminfo = _read_meminfo_kib()
+    total = int(meminfo.get("MemTotal") or 0) * 1024
+    if total <= 0:
+        raise RuntimeError("meminfo_unavailable")
+    available_kib = meminfo.get("MemAvailable")
+    if available_kib is None:
+        available_kib = (
+            meminfo.get("MemFree", 0)
+            + meminfo.get("Buffers", 0)
+            + meminfo.get("Cached", 0)
+            + meminfo.get("SReclaimable", 0)
+            - meminfo.get("Shmem", 0)
+        )
+    available = max(0, int(available_kib) * 1024)
+    used = max(0, min(total, total - available))
+    return {
+        "used_bytes": used,
+        "total_bytes": total,
+        "percent": _clamp_percent((used / total) * 100.0),
+    }
+
+
+def _disk_usage() -> dict[str, int | float]:
+    usage = shutil.disk_usage("/")
+    total = int(usage.total)
+    if total <= 0:
+        raise RuntimeError("disk_unavailable")
+    used = int(usage.used)
+    return {
+        "used_bytes": used,
+        "total_bytes": total,
+        "percent": _clamp_percent((used / total) * 100.0),
+    }
+
+
+def _safe_error(metric: str, exc: Exception) -> dict[str, str]:
+    # Keep this intentionally coarse. Exception messages can contain local paths
+    # on unusual platforms; the browser only needs a safe unavailable reason.
+    return {"metric": metric, "code": type(exc).__name__}
+
+
+def build_system_health_payload() -> dict[str, Any]:
+    metrics: dict[str, Any] = {"cpu": None, "memory": None, "disk": None}
+    errors: list[dict[str, str]] = []
+
+    collectors = {
+        "cpu": _cpu_percent,
+        "memory": _memory_usage,
+        "disk": _disk_usage,
+    }
+    for name, collect in collectors.items():
+        try:
+            value = collect()
+            if name == "cpu":
+                metrics[name] = {"percent": _clamp_percent(value)}
+            else:
+                metrics[name] = {
+                    "used_bytes": max(0, int(value["used_bytes"])),
+                    "total_bytes": max(0, int(value["total_bytes"])),
+                    "percent": _clamp_percent(value["percent"]),
+                }
+        except Exception as exc:
+            errors.append(_safe_error(name, exc))
+
+    available = any(metrics[name] is not None for name in metrics)
+    status = "ok" if available and not errors else "partial" if available else "unavailable"
+    return {
+        "status": status,
+        "available": available,
+        "checked_at": _checked_at(),
+        "cpu": metrics["cpu"],
+        "memory": metrics["memory"],
+        "disk": metrics["disk"],
+        "errors": errors,
+    }

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,545 @@
+"""
+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, STREAMS, STREAMS_LOCK
+
+# 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 _active_stream_count() -> int:
+    """Return the current in-memory chat stream count.
+
+    Self-update schedules an in-process re-exec after git pull/reset.  That is
+    restart-equivalent for live streams, even when systemd does not see a unit
+    restart.  Refuse update/force-update while a stream exists so a browser
+    update click cannot recreate the pending-message loss class fixed in #1543.
+    """
+    with STREAMS_LOCK:
+        return len(STREAMS)
+
+
+def _restart_blocked_response(target: str, active_streams: int) -> dict:
+    plural = "s" if active_streams != 1 else ""
+    return {
+        'ok': False,
+        'message': (
+            f'Cannot update {target} while {active_streams} active chat stream{plural} '
+            'is running. Wait for the response to finish, then retry the update.'
+        ),
+        'target': target,
+        'restart_blocked': True,
+        'active_streams': active_streams,
+    }
+
+
+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'
+
+
+def _detect_agent_version() -> str:
+    """Detect the running Hermes Agent version for UI display."""
+    if _AGENT_DIR is None:
+        return 'not detected'
+
+    version_file = Path(_AGENT_DIR) / "VERSION"
+    try:
+        if version_file.exists():
+            text = version_file.read_text(encoding='utf-8').strip()
+            if text:
+                return text
+    except Exception:
+        pass
+
+    # Fallback: infer from git describe when the checkout exists but no VERSION
+    # file is available (common in source checkouts and developer environments).
+    if not Path(_AGENT_DIR).exists():
+        return 'not detected'
+    # Symmetric with _detect_webui_version() above — `--dirty` flags a
+    # locally-modified checkout so operators can see when their agent has
+    # uncommitted changes vs a clean tag. Per Opus advisor on stage-293.
+    out, ok = _run_git(['describe', '--tags', '--always', '--dirty'], _AGENT_DIR, timeout=3)
+    if ok and out:
+        return out
+
+    return 'not detected'
+
+
+# Resolved once at import time — tags cannot change without a process restart.
+WEBUI_VERSION: str = _detect_webui_version()
+AGENT_VERSION: str = _detect_agent_version()
+
+
+def _normalize_remote_url(remote_url):
+    """Return the browser-facing repository URL for update compare links.
+
+    Git remotes may be HTTPS or SSH and may include a literal ``.git`` suffix.
+    Strip only that literal suffix — never use ``str.rstrip('.git')`` because it
+    treats the argument as a character set and can truncate ``hermes-webui`` to
+    ``hermes-webu``.
+    """
+    if not remote_url:
+        return remote_url
+    remote_url = remote_url.strip()
+    if remote_url.startswith('git@'):
+        remote_url = remote_url.replace(':', '/', 1).replace('git@', 'https://', 1)
+    remote_url = remote_url.rstrip('/')
+    if remote_url.endswith('.git'):
+        remote_url = remote_url[:-4]
+    return remote_url.rstrip('/')
+
+
+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.
+    #
+    # latest_sha = upstream tip (compare_ref). Always exists on github.com
+    # because it is literally the commit `git fetch` just pulled.
+    #
+    # current_sha is trickier. The intuitive choice — local HEAD — breaks
+    # the "What's new?" compare URL whenever HEAD is not a public commit:
+    # unpushed work, dirty stage branches, forks, in-flight rebases, or
+    # release-time merge commits whose SHA only lives in the maintainer's
+    # checkout. We saw exactly this in #1579: a banner reporting "17 updates"
+    # linked to /compare/<localHEAD>...<upstream> and 404'd because <localHEAD>
+    # was never pushed to the canonical repo.
+    #
+    # The right base is the merge-base between HEAD and the upstream ref —
+    # that's the most recent commit both sides agree on, and (because
+    # `git fetch` succeeded above) it is guaranteed to be present upstream.
+    # If a user is 17 commits behind with no local-only commits, merge-base
+    # equals local HEAD and the URL is identical to what we shipped before;
+    # if they ARE ahead with local-only commits, the URL still resolves to
+    # the public history they share with upstream. If merge-base fails for
+    # any reason (e.g. shallow clone where the bases diverge before the
+    # cutoff), fall back to None so the JS link guard suppresses the link
+    # rather than emitting a known-broken URL.
+    mb_full, mb_ok = _run_git(['merge-base', 'HEAD', compare_ref], path)
+    if mb_ok and mb_full:
+        short, ok = _run_git(['rev-parse', '--short', mb_full], path)
+        current = short if (ok and short) else None
+    else:
+        current = None
+    latest, _ = _run_git(['rev-parse', '--short', compare_ref], path)
+
+    # Get repo URL for "What's new?" link
+    remote_url, _ = _run_git(['remote', 'get-url', 'origin'], path)
+    remote_url = _normalize_remote_url(remote_url)
+
+    return {
+        'name': name,
+        'behind': behind,
+        'current_sha': current,
+        'latest_sha': latest,
+        'branch': compare_ref,
+        'repo_url': remote_url,
+    }
+
+
+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.
+    """
+    active_streams = _active_stream_count()
+    if active_streams:
+        return _restart_blocked_response(target, active_streams)
+
+    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."""
+    active_streams = _active_stream_count()
+    if active_streams:
+        return _restart_blocked_response(target, active_streams)
+
+    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,9 +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]
-        dest = workspace / safe_name
+        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:
-        return j(handler, {'error': str(e), 'trace': _tb.format_exc()}, status=500)
+        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

@@ -1,72 +1,745 @@
 """
 Hermes Web UI -- Workspace and file system helpers.
+
+Workspace lists and last-used workspace are stored per-profile so each
+profile has its own workspace configuration.  State files live at
+``{profile_home}/webui_state/workspaces.json`` and
+``{profile_home}/webui_state/last_workspace.txt``.  The global STATE_DIR
+paths are used as fallback when no profile module is available.
 """
 import json
+import logging
 import os
+import stat
+import subprocess
+import concurrent.futures
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 from api.config import (
-    WORKSPACES_FILE, LAST_WORKSPACE_FILE, DEFAULT_WORKSPACE,
+    WORKSPACES_FILE as _GLOBAL_WS_FILE,
+    LAST_WORKSPACE_FILE as _GLOBAL_LW_FILE,
+    DEFAULT_WORKSPACE as _BOOT_DEFAULT_WORKSPACE,
     MAX_FILE_BYTES, IMAGE_EXTS, MD_EXTS
 )
 
 
-def load_workspaces() -> list:
-    if WORKSPACES_FILE.exists():
+# ── Profile-aware path resolution ───────────────────────────────────────────
+
+def _profile_state_dir() -> Path:
+    """Return the webui_state directory for the active profile.
+
+    For the default profile, returns the global STATE_DIR (respects
+    HERMES_WEBUI_STATE_DIR env var for test isolation).
+    For named profiles, returns {profile_home}/webui_state/.
+    """
+    try:
+        from api.profiles import get_active_profile_name, get_active_hermes_home
+        name = get_active_profile_name()
+        if name and name != 'default':
+            d = get_active_hermes_home() / 'webui_state'
+            d.mkdir(parents=True, exist_ok=True)
+            return d
+    except ImportError:
+        logger.debug("Failed to import profiles module, using global state dir")
+    return _GLOBAL_WS_FILE.parent
+
+
+def _workspaces_file() -> Path:
+    """Return the workspaces.json path for the active profile."""
+    return _profile_state_dir() / 'workspaces.json'
+
+
+def _last_workspace_file() -> Path:
+    """Return the last_workspace.txt path for the active profile."""
+    return _profile_state_dir() / 'last_workspace.txt'
+
+
+def _profile_default_workspace() -> str:
+    """Read the profile's default workspace from its config.yaml.
+
+    Checks keys in priority order:
+      1. 'workspace'         — explicit webui workspace key
+      2. 'default_workspace' — alternate explicit key
+      3. 'terminal.cwd'      — hermes-agent terminal working dir (most common)
+
+    Falls back to the boot-time DEFAULT_WORKSPACE constant.
+    """
+    try:
+        from api.config import get_config
+        cfg = get_config()
+        # Explicit webui workspace keys first
+        for key in ('workspace', 'default_workspace'):
+            ws = cfg.get(key)
+            if ws:
+                p = Path(str(ws)).expanduser().resolve()
+                if p.is_dir():
+                    return str(p)
+        # Fall through to terminal.cwd — the agent's configured working directory
+        terminal_cfg = cfg.get('terminal', {})
+        if isinstance(terminal_cfg, dict):
+            cwd = terminal_cfg.get('cwd', '')
+            if cwd and str(cwd) not in ('.', ''):
+                p = Path(str(cwd)).expanduser().resolve()
+                if p.is_dir():
+                    return str(p)
+    except (ImportError, Exception):
+        logger.debug("Failed to load profile default workspace config")
+    return str(_BOOT_DEFAULT_WORKSPACE)
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
+
+def _clean_workspace_list(workspaces: list) -> list:
+    """Sanitize a workspace list:
+    - Preserve saved paths even when they are currently missing or inaccessible;
+      picker state must not be destroyed by a transient stat/permission failure.
+    - 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
+      confusion with the 'default' profile name).
+    Returns the cleaned list (may be empty).
+    """
+    hermes_profiles = (Path.home() / '.hermes' / 'profiles').resolve()
+    result = []
+    for w in workspaces:
+        path = w.get('path', '')
+        name = w.get('name', '')
+        if not path:
+            continue
+        p = _safe_resolve(Path(path).expanduser())
+        # 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:
-            return json.loads(WORKSPACES_FILE.read_text(encoding='utf-8'))
+            p.relative_to(hermes_profiles)
+            # 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  # not under profiles/ at all — keep it
+        # Rename confusing 'default' label to 'Home'
+        if name.lower() == 'default':
+            name = 'Home'
+        result.append({'path': str(p), 'name': name})
+    return result
+
+
+def _workspace_access_error(candidate: Path, *, missing_label: str = "Path does not exist") -> str | None:
+    """Return a user-facing validation error for an unusable workspace path.
+
+    ``Path.exists()`` can collapse permission/stat failures into a generic falsey
+    result on some Python/OS combinations, which produced misleading "does not
+    exist" messages for macOS/TCC-denied directories.  Probe with ``stat()`` so
+    missing paths, non-directories, and permission-denied paths can be reported
+    separately.
+    """
+    try:
+        st = candidate.stat()
+    except FileNotFoundError:
+        return f"{missing_label}: {candidate}"
+    except PermissionError as exc:
+        return (
+            f"Cannot access path: {candidate}. The server process could not inspect "
+            f"this directory ({exc}). On macOS, grant Full Disk Access or Files and "
+            f"Folders permission to the Hermes/WebUI app or server process, then try again."
+        )
+    except OSError as exc:
+        return f"Cannot access path: {candidate}. The server process could not inspect this path ({exc})."
+    if not stat.S_ISDIR(st.st_mode):
+        return f"Path is not a directory: {candidate}"
+    return None
+
+
+def _migrate_global_workspaces() -> list:
+    """Read the legacy global workspaces.json, clean it, and return the result.
+
+    This is the migration path for users upgrading from a pre-profile version:
+    their global file may contain cross-profile entries, test artifacts, and
+    stale paths accumulated over time.  We clean it in-place and rewrite it.
+    """
+    if not _GLOBAL_WS_FILE.exists():
+        return []
+    try:
+        raw = json.loads(_GLOBAL_WS_FILE.read_text(encoding='utf-8'))
+        cleaned = _clean_workspace_list(raw)
+        if len(cleaned) != len(raw):
+            # Rewrite the cleaned version so future reads are already clean
+            _GLOBAL_WS_FILE.write_text(
+                json.dumps(cleaned, ensure_ascii=False, indent=2), encoding='utf-8'
+            )
+        return cleaned
+    except Exception:
+        return []
+
+
+def load_workspaces() -> list:
+    ws_file = _workspaces_file()
+    if ws_file.exists():
+        try:
+            raw = json.loads(ws_file.read_text(encoding='utf-8'))
+            cleaned = _clean_workspace_list(raw)
+            if len(cleaned) != len(raw):
+                # Persist the cleaned version so stale entries don't keep reappearing
+                try:
+                    ws_file.write_text(
+                        json.dumps(cleaned, ensure_ascii=False, indent=2), encoding='utf-8'
+                    )
+                except Exception:
+                    logger.debug("Failed to persist cleaned workspace list")
+            return cleaned or [{'path': _profile_default_workspace(), 'name': 'Home'}]
         except Exception:
-            pass
-    return [{'path': str(DEFAULT_WORKSPACE), 'name': 'default'}]
+            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.
+    try:
+        from api.profiles import get_active_profile_name
+        is_default = get_active_profile_name() in ('default', None)
+    except ImportError:
+        is_default = True
+    if is_default:
+        migrated = _migrate_global_workspaces()
+        if migrated:
+            return migrated
+    # Fresh start: single entry from the profile's configured workspace, labeled "Home"
+    return [{'path': _profile_default_workspace(), 'name': 'Home'}]
 
 
-def save_workspaces(workspaces: list):
-    WORKSPACES_FILE.write_text(json.dumps(workspaces, ensure_ascii=False, indent=2), encoding='utf-8')
+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')
 
 
 def get_last_workspace() -> str:
-    if LAST_WORKSPACE_FILE.exists():
+    lw_file = _last_workspace_file()
+    if lw_file.exists():
         try:
-            p = LAST_WORKSPACE_FILE.read_text(encoding='utf-8').strip()
+            p = lw_file.read_text(encoding='utf-8').strip()
             if p and Path(p).is_dir():
                 return p
         except Exception:
-            pass
-    return str(DEFAULT_WORKSPACE)
+            logger.debug("Failed to read last workspace from %s", lw_file)
+    # Fallback: try global file
+    if _GLOBAL_LW_FILE.exists():
+        try:
+            p = _GLOBAL_LW_FILE.read_text(encoding='utf-8').strip()
+            if p and Path(p).is_dir():
+                return p
+        except Exception:
+            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:
-        LAST_WORKSPACE_FILE.write_text(str(path), encoding='utf-8')
+        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()
+
+    access_error = _workspace_access_error(candidate)
+    if access_error:
+        raise ValueError(access_error)
+
+    # (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 _strip_surrounding_quotes(path: str) -> str:
+    """Strip a single pair of surrounding single or double quotes from a path string.
+
+    macOS Finder's "Copy as Pathname" (Cmd+Option+C) returns paths wrapped in
+    single quotes, e.g. ``'/Users/x/Documents/foo'``. Other shells and OS file
+    managers do similar things with double quotes. Users routinely paste these
+    quoted strings into the Add Space input expecting them to "just work" —
+    the only reason they didn't was a missing strip.
+
+    Only paired quotes are stripped (matching opener and closer). One-sided quotes
+    are preserved on the slim chance a path legitimately contains a literal quote
+    character.
+    """
+    s = path.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ("'", '"'):
+        return s[1:-1]
+    return s
+
+
+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.
+
+    Surrounding quotes (single or double) are stripped before validation —
+    macOS Finder's "Copy as Pathname" wraps paths in single quotes by default,
+    and users routinely paste those into the Add Space input.
+    """
+    path = _strip_surrounding_quotes(path)
+    candidate = Path(path).expanduser().resolve()
+
+    access_error = _workspace_access_error(candidate)
+    if access_error:
+        raise ValueError(access_error)
+
+    # 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}")
@@ -75,3 +748,58 @@ def read_file_content(workspace: Path, rel: str):
         raise ValueError(f"File too large ({size} bytes, max {MAX_FILE_BYTES})")
     content = target.read_text(encoding='utf-8', errors='replace')
     return {'path': rel, 'content': content, 'size': size, 'lines': content.count('\n') + 1}
+
+
+# ── Git detection ──────────────────────────────────────────────────────────
+
+def _run_git(args, cwd, timeout=3):
+    """Run a git command and return stdout, or None on failure."""
+    try:
+        r = subprocess.run(
+            ['git'] + args, cwd=str(cwd), capture_output=True,
+            text=True, timeout=timeout,
+        )
+        return r.stdout.strip() if r.returncode == 0 else None
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+
+
+def git_info_for_workspace(workspace: Path) -> dict:
+    """Return git info for a workspace directory, or None if not a git repo."""
+    if not (workspace / '.git').exists():
+        return None
+    branch = _run_git(['rev-parse', '--abbrev-ref', 'HEAD'], workspace)
+    if branch is None:
+        return None
+    # 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': ahead,
+        'behind': behind,
+        'is_git': True,
+    }

bootstrap.py

@@ -0,0 +1,484 @@
+#!/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 _agent_dir_from_hermes_cli() -> Path | None:
+    """Resolve the agent install root by inspecting the `hermes` CLI shebang.
+
+    The Hermes Agent installer drops a `hermes` console-script in the user's
+    PATH whose shebang points at the agent's bundled venv:
+
+        #!/path/to/hermes-agent/venv/bin/python3
+
+    Walking up the parents until we find a directory that contains
+    `run_agent.py` recovers the install root regardless of where the user
+    chose to clone the agent (e.g. ~/Projects/GitHub/hermes-agent), which
+    the hard-coded candidate list in :func:`discover_agent_dir` cannot.
+
+    Last-resort only: this is invoked after every explicit candidate
+    (`HERMES_WEBUI_AGENT_DIR`, `$HERMES_HOME/hermes-agent`, etc.) has missed.
+    A stale clone in a known location still wins over the live `hermes` CLI
+    — that's intentional, since the candidate list is treated as
+    authoritative when present, and matches existing behavior.
+    """
+    hermes_path = shutil.which("hermes")
+    if not hermes_path:
+        return None
+    try:
+        with open(hermes_path, "r", encoding="utf-8", errors="replace") as f:
+            first_line = f.readline().strip()
+    except OSError:
+        return None
+    if not first_line.startswith("#!"):
+        return None
+    interp_field = first_line[2:].strip().split(None, 1)
+    if not interp_field:
+        return None
+    interp = Path(interp_field[0])
+    if not interp.is_absolute():
+        return None
+    for parent in interp.parents:
+        if (parent / "run_agent.py").exists():
+            return parent.resolve()
+    return None
+
+
+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 _agent_dir_from_hermes_cli()
+
+
+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}")
+        # symlinks=True: some Python builds (notably mise/asdf shared-library
+        # installs on macOS) default venv to copy mode. The copied binary still
+        # uses @executable_path/../lib/libpython3.X.dylib for its load command,
+        # so the venv binary aborts with SIGABRT on first import because the
+        # dylib never gets copied into .venv/lib. Symlinking the interpreter
+        # keeps @executable_path resolving back to the original install.
+        # CPython's venv falls back to copy mode automatically when symlink
+        # creation fails (e.g. older Windows without SeCreateSymbolicLinkPrivilege),
+        # so this is safe to set unconditionally.
+        venv.EnvBuilder(with_pip=True, symlinks=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)

ctl.sh

@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HERMES_HOME="${HERMES_HOME:-${HOME}/.hermes}"
+PID_FILE="${HERMES_WEBUI_PID_FILE:-${HERMES_HOME}/webui.pid}"
+LOG_FILE="${HERMES_WEBUI_LOG_FILE:-${HERMES_HOME}/webui.log}"
+STATE_FILE="${HERMES_WEBUI_CTL_STATE_FILE:-${HERMES_HOME}/webui.ctl.env}"
+DEFAULT_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${HERMES_HOME}/webui}"
+
+usage() {
+  cat <<'EOF'
+Usage: ./ctl.sh <command> [args]
+
+Commands:
+  start [bootstrap args...]   Start Hermes WebUI as a background daemon
+  stop                        Stop the daemon started by ctl.sh
+  restart [bootstrap args...] Stop, then start again
+  status                      Show daemon, host/port, log, and health status
+  logs [--lines N] [--follow|--no-follow]
+                              Show the daemon log (defaults to tail -n 100 -f)
+EOF
+}
+
+ensure_home() {
+  mkdir -p "${HERMES_HOME}" "${DEFAULT_STATE_DIR}"
+}
+
+_load_repo_dotenv_preserving_env() {
+  local env_file="${REPO_ROOT}/.env"
+  [[ -f "${env_file}" ]] || return 0
+
+  local -a preserved=()
+  local line key value
+  while IFS= read -r line || [[ -n "${line}" ]]; do
+    line="${line#${line%%[![:space:]]*}}"
+    [[ -z "${line}" || "${line}" == \#* || "${line}" != *=* ]] && continue
+    key="${line%%=*}"
+    key="${key#export }"
+    key="${key//[[:space:]]/}"
+    [[ "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    if [[ -n "${!key+x}" ]]; then
+      value="${!key}"
+      preserved+=("${key}=${value}")
+    fi
+  done < "${env_file}"
+
+  set -a
+  # shellcheck source=/dev/null
+  source "${env_file}"
+  set +a
+
+  local assignment
+  for assignment in "${preserved[@]}"; do
+    export "${assignment}"
+  done
+}
+
+_find_python() {
+  if [[ -n "${HERMES_WEBUI_PYTHON:-}" ]]; then
+    printf '%s\n' "${HERMES_WEBUI_PYTHON}"
+  elif command -v python3 >/dev/null 2>&1; then
+    command -v python3
+  elif command -v python >/dev/null 2>&1; then
+    command -v python
+  else
+    echo "[ctl] Python 3 is required to run bootstrap.py" >&2
+    return 1
+  fi
+}
+
+_parse_launch_binding() {
+  CTL_HOST="${HERMES_WEBUI_HOST:-127.0.0.1}"
+  CTL_PORT="${HERMES_WEBUI_PORT:-8787}"
+  local arg next_is_host=0 saw_port=0
+  for arg in "$@"; do
+    if (( next_is_host )); then
+      CTL_HOST="${arg}"
+      next_is_host=0
+      continue
+    fi
+    case "${arg}" in
+      --host)
+        next_is_host=1
+        ;;
+      --host=*)
+        CTL_HOST="${arg#--host=}"
+        ;;
+      --*)
+        ;;
+      *)
+        if (( ! saw_port )) && [[ "${arg}" =~ ^[0-9]+$ ]]; then
+          CTL_PORT="${arg}"
+          saw_port=1
+        fi
+        ;;
+    esac
+  done
+}
+
+_build_bootstrap_args() {
+  CTL_BOOTSTRAP_ARGS=()
+  local arg next_is_host=0 saw_port=0
+  for arg in "$@"; do
+    if (( next_is_host )); then
+      next_is_host=0
+      continue
+    fi
+    case "${arg}" in
+      --host)
+        next_is_host=1
+        ;;
+      --host=*)
+        ;;
+      --*)
+        CTL_BOOTSTRAP_ARGS+=("${arg}")
+        ;;
+      *)
+        if (( ! saw_port )) && [[ "${arg}" =~ ^[0-9]+$ ]]; then
+          saw_port=1
+        else
+          CTL_BOOTSTRAP_ARGS+=("${arg}")
+        fi
+        ;;
+    esac
+  done
+}
+
+_write_state() {
+  local pid="$1" host="$2" port="$3"
+  local state_dir="${HERMES_WEBUI_STATE_DIR:-${DEFAULT_STATE_DIR}}"
+  {
+    printf 'PID=%q\n' "${pid}"
+    printf 'REPO_ROOT=%q\n' "${REPO_ROOT}"
+    printf 'HOST=%q\n' "${host}"
+    printf 'PORT=%q\n' "${port}"
+    printf 'LOG_FILE=%q\n' "${LOG_FILE}"
+    printf 'STATE_DIR=%q\n' "${state_dir}"
+    printf 'STARTED_AT=%q\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  } > "${STATE_FILE}"
+}
+
+_load_state_if_present() {
+  if [[ -f "${STATE_FILE}" ]]; then
+    # shellcheck source=/dev/null
+    source "${STATE_FILE}"
+  fi
+}
+
+_pid_from_file() {
+  [[ -f "${PID_FILE}" ]] || return 1
+  local pid
+  pid="$(tr -d '[:space:]' < "${PID_FILE}")"
+  [[ "${pid}" =~ ^[0-9]+$ ]] || return 1
+  printf '%s\n' "${pid}"
+}
+
+_is_alive() {
+  local pid="$1"
+  kill -0 "${pid}" >/dev/null 2>&1
+}
+
+_proc_args() {
+  local pid="$1"
+  ps -p "${pid}" -o args= 2>/dev/null || true
+}
+
+_is_owned_webui_pid() {
+  local pid="$1" args state_repo=""
+  [[ -f "${STATE_FILE}" ]] || return 1
+  _load_state_if_present
+  state_repo="${REPO_ROOT:-}"
+  [[ "${state_repo}" == "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ]] || return 1
+  args="$(_proc_args "${pid}")"
+  [[ -n "${args}" ]] || return 1
+  [[ "${args}" == *"${state_repo}/bootstrap.py"* || "${args}" == *"${state_repo}/server.py"* || "${args}" == *"${state_repo}/start.sh"* ]]
+}
+
+_current_pid() {
+  local pid
+  pid="$(_pid_from_file)" || return 1
+  if _is_alive "${pid}" && _is_owned_webui_pid "${pid}"; then
+    printf '%s\n' "${pid}"
+    return 0
+  fi
+  return 1
+}
+
+_clear_stale_pid() {
+  if [[ -f "${PID_FILE}" ]]; then
+    rm -f "${PID_FILE}" "${STATE_FILE}"
+    echo "[ctl] Removed stale PID file: ${PID_FILE}"
+  fi
+}
+
+start_cmd() {
+  ensure_home
+  _load_repo_dotenv_preserving_env
+  export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${DEFAULT_STATE_DIR}}"
+  mkdir -p "${HERMES_WEBUI_STATE_DIR}"
+  _parse_launch_binding "$@"
+  _build_bootstrap_args "$@"
+  export HERMES_WEBUI_HOST="${CTL_HOST}"
+  export HERMES_WEBUI_PORT="${CTL_PORT}"
+
+  local existing_pid
+  if existing_pid="$(_current_pid 2>/dev/null)"; then
+    echo "[ctl] Hermes WebUI is already running (PID ${existing_pid})"
+    return 0
+  fi
+  _clear_stale_pid >/dev/null 2>&1 || true
+
+  local python_exe pid
+  python_exe="$(_find_python)"
+  : >> "${LOG_FILE}"
+  (
+    cd "${REPO_ROOT}"
+    exec "${python_exe}" "${REPO_ROOT}/bootstrap.py" --no-browser --foreground --host "${CTL_HOST}" "${CTL_PORT}" ${CTL_BOOTSTRAP_ARGS[@]+"${CTL_BOOTSTRAP_ARGS[@]}"}
+  ) >> "${LOG_FILE}" 2>&1 &
+  pid=$!
+
+  printf '%s\n' "${pid}" > "${PID_FILE}"
+  _write_state "${pid}" "${CTL_HOST}" "${CTL_PORT}"
+  sleep 0.15
+  if ! _is_alive "${pid}"; then
+    echo "[ctl] Hermes WebUI failed to stay running. Log: ${LOG_FILE}" >&2
+    rm -f "${PID_FILE}" "${STATE_FILE}"
+    return 1
+  fi
+  echo "[ctl] Started Hermes WebUI (PID ${pid})"
+  echo "[ctl] Bound: ${CTL_HOST}:${CTL_PORT}"
+  echo "[ctl] Log: ${LOG_FILE}"
+}
+
+stop_cmd() {
+  ensure_home
+  local pid
+  if ! pid="$(_pid_from_file 2>/dev/null)"; then
+    echo "[ctl] Hermes WebUI is stopped"
+    rm -f "${PID_FILE}" "${STATE_FILE}"
+    return 0
+  fi
+
+  if ! _is_alive "${pid}" || ! _is_owned_webui_pid "${pid}"; then
+    _clear_stale_pid
+    return 0
+  fi
+
+  echo "[ctl] Stopping Hermes WebUI (PID ${pid})"
+  kill "${pid}" >/dev/null 2>&1 || true
+  local i
+  for i in {1..50}; do
+    if ! _is_alive "${pid}"; then
+      rm -f "${PID_FILE}" "${STATE_FILE}"
+      echo "[ctl] Stopped"
+      return 0
+    fi
+    sleep 0.1
+  done
+
+  echo "[ctl] Process did not exit after SIGTERM; sending SIGKILL" >&2
+  kill -KILL "${pid}" >/dev/null 2>&1 || true
+  rm -f "${PID_FILE}" "${STATE_FILE}"
+}
+
+_health_line() {
+  local host="$1" port="$2" url result
+  url="http://${host}:${port}/health"
+  if command -v curl >/dev/null 2>&1; then
+    if result="$(curl -fsS --max-time 2 "${url}" 2>/dev/null)"; then
+      if command -v python3 >/dev/null 2>&1; then
+        printf '%s' "${result}" | python3 -c 'import json,sys
+try:
+    data=json.load(sys.stdin)
+    sessions=data.get("sessions", data.get("session_count", "?"))
+    active=data.get("active_streams", "?")
+    status=data.get("status", "ok")
+    print(f"ok ({sessions} sessions, {active} active streams)" if status == "ok" else status)
+except Exception:
+    print("ok")'
+      else
+        echo "ok"
+      fi
+    else
+      echo "unreachable (${url})"
+    fi
+  else
+    echo "unknown (curl not found; ${url})"
+  fi
+}
+
+status_cmd() {
+  ensure_home
+  _load_state_if_present
+  local host="${HOST:-${HERMES_WEBUI_HOST:-127.0.0.1}}"
+  local port="${PORT:-${HERMES_WEBUI_PORT:-8787}}"
+  local log_path="${LOG_FILE}"
+  local pid uptime health
+
+  if pid="$(_current_pid 2>/dev/null)"; then
+    uptime="$(ps -p "${pid}" -o etime= 2>/dev/null | sed 's/^ *//' || true)"
+    health="$(_health_line "${host}" "${port}")"
+    echo "● hermes-webui — running"
+    echo "  PID:     ${pid}"
+    echo "  Uptime:  ${uptime:-unknown}"
+    echo "  Bound:   ${host}:${port}"
+    echo "  Log:     ${log_path}"
+    echo "  Health:  ${health}"
+  else
+    [[ -f "${PID_FILE}" ]] && _clear_stale_pid >/dev/null 2>&1 || true
+    echo "● hermes-webui — stopped"
+    echo "  PID:     -"
+    echo "  Bound:   ${host}:${port}"
+    echo "  Log:     ${log_path}"
+    echo "  Health:  not checked"
+  fi
+}
+
+logs_cmd() {
+  ensure_home
+  local lines=100 follow=1
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --lines)
+        shift
+        lines="${1:-}"
+        [[ "${lines}" =~ ^[0-9]+$ ]] || { echo "[ctl] --lines requires a number" >&2; return 2; }
+        ;;
+      --lines=*)
+        lines="${1#--lines=}"
+        [[ "${lines}" =~ ^[0-9]+$ ]] || { echo "[ctl] --lines requires a number" >&2; return 2; }
+        ;;
+      --follow|-f)
+        follow=1
+        ;;
+      --no-follow)
+        follow=0
+        ;;
+      *)
+        echo "[ctl] Unknown logs option: $1" >&2
+        return 2
+        ;;
+    esac
+    shift
+  done
+  touch "${LOG_FILE}"
+  if (( follow )); then
+    tail -n "${lines}" -f "${LOG_FILE}"
+  else
+    tail -n "${lines}" "${LOG_FILE}"
+  fi
+}
+
+cmd="${1:-}"
+if [[ $# -gt 0 ]]; then
+  shift
+fi
+
+case "${cmd}" in
+  start) start_cmd "$@" ;;
+  stop) stop_cmd ;;
+  restart) stop_cmd; start_cmd "$@" ;;
+  status) status_cmd ;;
+  logs) logs_cmd "$@" ;;
+  -h|--help|help|"") usage ;;
+  *) echo "[ctl] Unknown command: ${cmd}" >&2; usage >&2; exit 2 ;;
+esac

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

@@ -0,0 +1,57 @@
+# 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:
+      # 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
+      # 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

docker_init.bash

@@ -0,0 +1,380 @@
+#!/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"
+
+# Keep init scratch files private to the container user that owns them.
+umask 0077
+
+write_privtmpfile() {
+  tmpfile=$1
+  if [ -z "${tmpfile}" ]; then error_exit "write_privtmpfile: missing argument"; fi
+  if [ -f "$tmpfile" ]; then rm -f "$tmpfile"; fi
+  printf '%s' "$2" > "$tmpfile"
+  chmod 600 "$tmpfile"
+}
+
+itdir=/tmp/hermeswebui_init
+if [ ! -d "$itdir" ]; then mkdir -p "$itdir"; fi
+chmod 700 "$itdir" || error_exit "Failed to secure $itdir"
+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 the root init phase to the hermeswebui runtime phase
+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_privtmpfile $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_privtmpfile $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
+}
+
+# The production image does not ship sudo. The entrypoint starts as root only
+# long enough to align the hermeswebui UID/GID with mounted volumes, prepare
+# root-owned paths, and then drop privileges for the server process.
+if [ "A${whoami}" == "Aroot" ]; then
+  echo "-- Running as root for one-time container init; will switch to hermeswebui"
+
+  # We are altering the UID/GID of the hermeswebui user to the desired ones and restarting as that user
+  # using usermod for the already created 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"
+  # Guard for read-only root filesystem (podman with read_only=true, issue #1470).
+  _readonly_root=false
+  if ! sh -c 'test -w /etc/group && test -w /etc/passwd' 2>/dev/null; then
+    _readonly_root=true
+    echo "  !! Detected read-only root filesystem — /etc/group or /etc/passwd is not writable"
+  fi
+  if [ "A${_readonly_root}" == "Atrue" ]; then
+    _current_hermeswebui_gid=$(id -g hermeswebui 2>/dev/null || echo "")
+    _current_hermeswebui_uid=$(id -u hermeswebui 2>/dev/null || echo "")
+    if [ "A${_current_hermeswebui_gid}" == "A${WANTED_GID}" ] && [ "A${_current_hermeswebui_uid}" == "A${WANTED_UID}" ]; then
+      echo "  -- Skipping groupmod/usermod — hermeswebui already has UID ${WANTED_UID} GID ${WANTED_GID} and root fs is read-only"
+    else
+      error_exit "Cannot modify /etc/group or /etc/passwd (read-only root fs). Set UID=${_current_hermeswebui_uid} and GID=${_current_hermeswebui_gid} to match, or run without read_only=true. See issue #1470."
+    fi
+  else
+    groupmod -o -g "${WANTED_GID}" hermeswebui || error_exit "Failed to set GID of hermeswebui user"
+    usermod -o -u "${WANTED_UID}" hermeswebui || error_exit "Failed to set UID of hermeswebui user"
+  fi
+
+  chown -R "${WANTED_UID}:${WANTED_GID}" /home/hermeswebui || error_exit "Failed to set owner of /home/hermeswebui"
+
+  echo ""; echo "-- Preparing /app for the hermeswebui runtime user"
+  mkdir -p /app || error_exit "Failed to create /app directory"
+  chown hermeswebui:hermeswebui /app || error_exit "Failed to set owner of /app to hermeswebui user"
+  rsync -av --chown=hermeswebui:hermeswebui /apptoo/ /app/ || error_exit "Failed to sync /apptoo to /app with correct ownership"
+
+  if [ -z "${HERMES_WEBUI_DEFAULT_WORKSPACE+x}" ]; then export HERMES_WEBUI_DEFAULT_WORKSPACE="/workspace"; fi
+  if [ ! -d "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then
+    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
+  chown hermeswebui:hermeswebui "$HERMES_WEBUI_DEFAULT_WORKSPACE" 2>/dev/null || echo "!! WARNING: Could not chown $HERMES_WEBUI_DEFAULT_WORKSPACE (continuing)"
+
+  export UV_CACHE_DIR=${UV_CACHE_DIR:-/uv_cache}
+  mkdir -p "${UV_CACHE_DIR}" || error_exit "Failed to create ${UV_CACHE_DIR} directory"
+  chown hermeswebui:hermeswebui "${UV_CACHE_DIR}" || error_exit "Failed to set owner of ${UV_CACHE_DIR} to hermeswebui user"
+
+  chown -R "${WANTED_UID}:${WANTED_GID}" "$itdir" || error_exit "Failed to set owner of $itdir"
+  save_env /tmp/hermeswebui_root_env.txt
+  chown "${WANTED_UID}:${WANTED_GID}" /tmp/hermeswebui_root_env.txt || error_exit "Failed to set owner of /tmp/hermeswebui_root_env.txt"
+  chmod 600 /tmp/hermeswebui_root_env.txt || error_exit "Failed to secure /tmp/hermeswebui_root_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}"
+  exec su -s /bin/bash -c "exec \"${script_fullname}\"" hermeswebui || error_exit "subscript failed"
+fi
+
+# If we are here, the script is started as an unprivileged runtime user.
+# Because the whoami value for the hermeswebui user can be any existing user, we cannot 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 the root init phase
+tmp_root_env=/tmp/hermeswebui_root_env.txt
+if [ -f $tmp_root_env ]; then
+  echo "-- Loading not already set environment variables from $tmp_root_env"
+  load_env $tmp_root_env true
+fi
+
+##
+echo ""; echo "-- Verifying /app is writable by the hermeswebui runtime user"
+if [ ! -d /app ]; then error_exit "/app directory does not exist"; fi
+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"
+# The root init phase creates/chowns missing bind-mount directories before
+# dropping privileges. After that, the runtime user only verifies access.
+if [ ! -d "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then
+  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 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
+  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 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_DIR:-/uv_cache}
+mkdir -p "${UV_CACHE_DIR}" || error_exit "Failed to create ${UV_CACHE_DIR} directory"
+test -w "${UV_CACHE_DIR}" || error_exit "${UV_CACHE_DIR} is not writable by hermeswebui"
+
+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,220 @@
+# 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.
+
+## Production image security model
+
+The production Docker image is hardened for the normal single-tenant container threat model:
+Hermes WebUI assumes one operator controls the container, mounted Hermes home, and workspace.
+The image does **not** install `sudo`, does not add runtime users to a sudo group, and does not
+grant `NOPASSWD` escalation. If an agent/tool process gains a shell as `hermeswebui`, it should
+not be able to become root with a passwordless sudo command.
+
+The entrypoint still starts as `root` for a narrow init phase because Docker bind mounts often need
+UID/GID alignment and ownership preparation before the app can read `~/.hermes`, `/workspace`,
+`/app`, and `/uv_cache`. After that setup, `docker_init.bash` re-execs itself as the unprivileged
+`hermeswebui` user and starts the server there. Init scratch files under `/tmp/hermeswebui_init`
+are owner-only (`0700` directory, `0600` files), not world-writable.
+
+For multi-tenant or hostile-container environments, rebuild with your own runtime user, mount policy,
+and supervisor assumptions. Development images that need package-manager convenience should add
+those tools in a dev-only Dockerfile instead of reintroducing passwordless sudo to production.
+
+## 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/pr-media/1772/cli-tool-metadata-api-evidence.json

@@ -0,0 +1,25 @@
+{
+  "issue": 1772,
+  "check": "api.models.get_cli_session_messages preserves CLI tool metadata for WebUI rendering",
+  "session_id": "cli_issue_1772_demo",
+  "message_count": 2,
+  "assistant_tool_calls": [
+    {
+      "id": "call_1772_demo",
+      "type": "function",
+      "function": {
+        "name": "terminal",
+        "arguments": "{\"command\": \"printf ok\"}"
+      }
+    }
+  ],
+  "tool_result": {
+    "role": "tool",
+    "tool_call_id": "call_1772_demo",
+    "tool_name": "terminal",
+    "name": "terminal",
+    "content": {
+      "output": "ok"
+    }
+  }
+}

docs/pr-media/1784/sidebar-scroll-qa.json

@@ -0,0 +1,25 @@
+{
+  "issue": 1784,
+  "commit_under_test": "9875967",
+  "fixture": "Synthetic 180-row session sidebar with active sid_0 streaming and long chat pane content.",
+  "pre_fix_observation": {
+    "steps": [
+      "Set _scrollPinned=true with #messages at scrollTop 0 in a long chat fixture.",
+      "Dispatch a wheel gesture on the active sidebar session row.",
+      "Call scrollIfPinned() to mimic the next streaming token render."
+    ],
+    "result": "#messages jumped from scrollTop 0 to 3073 immediately after the sidebar wheel gesture, showing the chat auto-scroll path fought non-chat scroll intent."
+  },
+  "post_fix_observation": {
+    "steps": [
+      "Repeat the same fixture and sidebar wheel gesture after the fix.",
+      "Call scrollIfPinned() immediately, then again after the 350ms non-chat intent guard expires."
+    ],
+    "result": {
+      "afterSidebarWheel": 0,
+      "afterIntentExpires": 2992,
+      "sessionListCss": "overscroll-behavior-y: contain; touch-action: pan-y"
+    },
+    "meaning": "A sidebar wheel/touch scroll intent now suppresses only the immediate chat-pane auto-scroll write, leaving the sidebar gesture free while streaming continues."
+  }
+}