Release v0.51.29 — Release F (Docker hardening + login persistence + scroll/lineage fixes + i18n cleanup)

Merge stage-324 to master.

.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

.github/workflows/release.yml

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

.github/workflows/tests.yml

@@ -24,7 +24,14 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pyyaml>=6.0 pytest pytest-timeout
+          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,10 +12,11 @@ __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
+!.env.docker.example
 .claude/
 CLAUDE.md
 AGENTS.md
@@ -28,6 +29,9 @@ copilot-instructions.md
 screenshot-*.png
 full-UI.png
 
+# Version file written by Docker/CI build — generated, never committed
+api/_version.py
+
 # OS files
 .DS_Store
 Thumbs.db
@@ -36,3 +40,13 @@ Thumbs.db
 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

ARCHITECTURE.md

@@ -7,10 +7,10 @@
 >
 > Keep this document updated as architecture changes are made.
 
-> Current shipped build: `v0.50.36-local.1` (April 16, 2026).
-> Baseline: upstream `nesquena/hermes-webui` `v0.50.36`.
-> Intentional local delta: first-time password enablement from Settings immediately issues a `hermes_session` cookie so the current browser remains signed in. The previous `Assistant Reply Language` customization has been removed, legacy `assistant_language` settings are filtered out on load/save, the workspace panel closed/open state is preloaded via a `documentElement` dataset marker before `style.css` paints to avoid a first-load desktop flash, transcript disclosure cards now animate caret rotation and body expansion with transitionable `max-height`/`opacity` states instead of `display:none/block`, and thinking cards now share the same rounded bordered card chrome as tool cards while keeping their gold palette.
-> Automated coverage: 1353 tests collected (`pytest tests/ --collect-only -q`).
+> 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.
 
 ---
 
@@ -33,11 +33,6 @@ frontend framework. The Python server is split into a routing shell (server.py)
 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.
 
-For the current local build, the codebase is intentionally as close to upstream as possible:
-the app now tracks upstream `v0.50.36`, keeps the password-session continuity patch in the
-settings/onboarding flow, and does not carry forward the prior reply-language preference
-feature.
-
 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
@@ -1629,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)

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

@@ -21,9 +21,9 @@ RUN apt-get update -y --fix-missing --no-install-recommends \
     apt-utils \
     locales \
     ca-certificates \
-    sudo \
     curl \
     rsync \
+    openssh-client \
     && apt-get upgrade -y \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
@@ -40,24 +40,12 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 
 WORKDIR /apptoo
 
-# Every sudo group user does not need a password
-RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
-
-# Create a new group for the hermeswebui and hermeswebuitoo users
-RUN groupadd -g 1024 hermeswebui \ 
-    && groupadd -g 1025 hermeswebuitoo
-
-# The hermeswebui (resp. hermeswebuitoo) user will have UID 1024 (resp. 1025), 
-# be part of the hermeswebui (resp. hermeswebuitoo) and users groups and be sudo capable (passwordless) 
-RUN useradd -u 1024 -d /home/hermeswebui -g hermeswebui -s /bin/bash -m hermeswebui \
-    && usermod -G users hermeswebui \
-    && adduser hermeswebui sudo
-RUN useradd -u 1025 -d /home/hermeswebuitoo -g hermeswebuitoo -s /bin/bash -m hermeswebuitoo \
-    && usermod -G users hermeswebuitoo \
-    && adduser hermeswebuitoo sudo
-RUN chown -R hermeswebuitoo:hermeswebuitoo /apptoo
-
-USER root
+# 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
 
@@ -74,9 +62,14 @@ USER root
 # The init script will skip the download when uv is already on PATH.
 RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
 
-USER hermeswebuitoo
+COPY --chown=root:root . /apptoo
 
-COPY . /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
@@ -84,5 +77,11 @@ 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"]
 

README.md

@@ -109,6 +109,18 @@ Or keep using the shell launcher:
 ./start.sh
 ```
 
+For self-hosted VM or homelab installs, `ctl.sh` wraps the common daemon lifecycle commands without requiring `fuser` or `pkill`:
+
+```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`).
@@ -118,6 +130,7 @@ The bootstrap will:
 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.
 
@@ -125,150 +138,91 @@ If provider setup is still incomplete after install, the onboarding wizard will
 
 ## Docker
 
-**Pre-built images** (amd64 + arm64) are published to GHCR on every release:
+**Pre-built images** (amd64 + arm64) are published to GHCR on every release.
 
-Make sure the `HERMES_WEBUI_STATE_DIR` (by default `~/.hermes/webui-mvp`, as detailed in the `.env.example` file) folder exist with the UID/GID of the owner of the `.hermes` folder. 
-The container will also mount your configured "workspace" (also from the example .env.example) as `/workspace`. adapt the location as needed.
+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-mvp \
--v ~/workspace:/workspace \
--p 8787:8787 ghcr.io/nesquena/hermes-webui:latest
+  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
+  -v ~/.hermes:/home/hermeswebui/.hermes \
+  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
+  -v ~/workspace:/workspace \
+  -p 127.0.0.1:8787:8787 \
+  ghcr.io/nesquena/hermes-webui:latest
 ```
 
-Or run with Docker Compose (recommended):
-
-```bash
-# Check the docker-compose.yml and make sure to adapt as needed, at minimum WANTED_UID/WANTED_GID
-docker compose up -d
-```
-
-Or build locally:
+### 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-mvp \
--v ~/workspace:/workspace \
--p 8787:8787 hermes-webui
+  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
+  -v ~/.hermes:/home/hermeswebui/.hermes \
+  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
+  -v ~/workspace:/workspace \
+  -p 127.0.0.1:8787:8787 \
+  hermes-webui
 ```
 
-Open http://localhost:8787 in your browser.
+### Multi-container setups
 
-To enable password protection:
+If you want the agent and WebUI in separate containers (for isolation, or because you're already running an agent gateway elsewhere):
 
 ```bash
-docker run -d \
--e WANTED_UID=`id -u` -e WANTED_GID=`id -g` \
--v ~/.hermes:/home/hermeswebui/.hermes -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp \
--v ~/workspace:/workspace \
--p 8787:8787 -e HERMES_WEBUI_PASSWORD=your-secret ghcr.io/nesquena/hermes-webui:latest
+# Agent + WebUI
+docker compose -f docker-compose.two-container.yml up -d
+
+# Agent + Dashboard + WebUI
+docker compose -f docker-compose.three-container.yml up -d
 ```
 
+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.
 
-### Two-container setup (Agent + WebUI)
-
-If you run the Hermes Agent in its own Docker container and want the WebUI
-in a separate container:
-
-```bash
-docker compose -f docker-compose.two-container.yml up -d
-```
-
-This starts both containers with shared volumes:
-
-- **`hermes-home`** — shared `~/.hermes` for config, sessions, skills, memory
-- **`hermes-agent-src`** — the agent's source code, mounted into the WebUI
-  container so it can install the agent's Python dependencies at startup
-
-The WebUI's init script automatically installs hermes-agent and all its
-dependencies (openai, anthropic, etc.) into its own Python environment on
-first boot. Subsequent restarts reuse the installed packages.
-
-> **How it works:** The WebUI imports hermes-agent's Python modules directly
-> (not via HTTP). The shared volume makes the agent source available, and
-> the init script runs `uv pip install` to set up the dependencies. Both
-> containers share the same `~/.hermes` directory for config and state.
-
-See `docker-compose.two-container.yml` for the full configuration.
-
-### Running alongside hermes-dashboard (three-container setup)
-
-To run the Hermes Agent, Hermes Dashboard, and the WebUI together on a
-shared volume, use the three-container Compose file:
-
-```bash
-docker compose -f docker-compose.three-container.yml up -d
-```
-
-This brings up:
-- **`hermes-agent`** — gateway API on port 8642
-- **`hermes-dashboard`** — monitoring UI on port 9119
-- **`hermes-webui`** — browser chat interface on port 8787
-
-All three services share the same `hermes-home` named volume so config,
-sessions, skills, and memory are consistent across all surfaces.
-
-#### Why UIDs must match
-
-The `hermes-home` volume is a bind-mount in practice — all three containers
-write to the same filesystem tree under `~/.hermes`. If the containers run
-as different UIDs, whichever container creates a file first becomes its
-owner, and the others hit `PermissionError` on subsequent writes.
-
-The fix is to make all containers run as **your host user's UID and GID**.
-
-#### Variable name asymmetry
-
-> ⚠️ **The two image families use different environment variable names** for
-> the UID/GID setting:
->
-> | Image | Variable |
-> |---|---|
-> | `nousresearch/hermes-agent` (agent + dashboard) | `HERMES_UID` / `HERMES_GID` |
-> | `ghcr.io/nesquena/hermes-webui` | `WANTED_UID` / `WANTED_GID` |
->
-> You must set **both pairs** when using a `.env` file.
-
-#### Recommended setup
-
-For a standard Linux user (UID ≥ 1000):
-
-```bash
-# Create a .env file with your host UID/GID
-echo "UID=$(id -u)" >> .env
-echo "GID=$(id -g)" >> .env
-# hermes-agent / hermes-dashboard
-echo "HERMES_UID=$(id -u)" >> .env
-echo "HERMES_GID=$(id -g)" >> .env
-```
-
-For NAS/Unraid deployments where a fixed service account is preferred, use
-`10000:10000` (or your NAS service UID) instead of `$(id -u)`.
-
-If you get `PermissionError` on an **existing** `~/.hermes` directory, run
-the one-time ownership fix:
-
-```bash
-chown -R $(id -u):$(id -g) ~/.hermes
-```
-
-#### Volume mount mode
-
-The dashboard container needs **read-write** access to the shared volume
-(it writes session logs and dashboard state). Do **not** add `:ro` to the
-`hermes-home` volume in `hermes-dashboard`'s `volumes:` entry.
-
-See `docker-compose.three-container.yml` for the full reference configuration.
-
 ---
 
 ## What start.sh discovers automatically
@@ -291,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
 ```
 
@@ -306,12 +261,15 @@ 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_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 |
 
@@ -408,8 +366,8 @@ Or using the agent venv explicitly:
 ```
 
 Tests run against an isolated server on port 8788 with a separate state directory.
-Production data and real cron jobs are never touched. Current count: **961 tests**
-across 53 test files.
+Production data and real cron jobs are never touched. Current count: **3309 tests**
+across 100+ test files.
 
 ---
 
@@ -577,12 +535,32 @@ State lives outside the repo at `~/.hermes/webui-mvp/` by default
 - `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 rebase — shapes the project, and we're grateful to everyone who has taken the time to contribute.
+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.
 
-### Major contributions
+**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.
@@ -601,8 +579,8 @@ Three interlocking improvements: workspace fallback resolution so the server rec
 **[@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)** — Real-time gateway session sync (PR #274)
-Bridged the gateway session database (Telegram, Discord, Slack, etc.) into the WebUI sidebar with live SSE polling. Gateway sessions now appear alongside WebUI sessions in real time, without any changes to hermes-agent.
+**[@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.
@@ -613,8 +591,8 @@ Added the 7th built-in theme: pure black backgrounds with warm accents tuned to
 **[@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)** — Session title guard + breadcrumb nav (PRs #301, #302)
-Two clean bug fixes / features: the session title guard that stops `title_from()` from overwriting user-renamed sessions after every turn, and clickable breadcrumb navigation in the workspace file preview panel.
+**[@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.

ROADMAP.md

@@ -1,354 +1,349 @@
-# Hermes Web UI: Full Parity Roadmap
+# Hermes Web UI — Roadmap
 
-> Goal: Full 1:1 parity with the Hermes CLI experience via a clean dark web UI.
-> Everything you can do from the CLI terminal, you can do from this UI.
+> Web companion to the Hermes Agent CLI. Same workflows, browser-native.
 >
-> Last updated: v0.50.44 (April 16, 2026) — 1353 tests collected
-> Local delta: enabling password from Settings keeps the current browser signed in; the former Assistant Reply Language enhancement has been removed; workspace panel closed-state now preloads in `<head>` so desktop first paint no longer flashes open before boot sync; thinking cards and tool call cards now animate both their carets and disclosure bodies smoothly on expand/collapse, and thinking cards now use the same bordered rounded panel chrome as tool cards with a gold palette.
-> Tests: 1353 collected (`pytest tests/ --collect-only -q`)
-> Source: <repo>/
+> Last updated: v0.51.29 (May 8, 2026) — 4960 tests collected — 6-PR Release F batch (Docker hardening + login persistence + scroll/lineage fixes + i18n cleanup)
+> 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, session action dropdown, pin indicator, project border, safe HTML rendering | 289 |
-| Sprint 17 | Workspace polish + slash commands + settings | Breadcrumb navigation, slash command autocomplete, send key setting (#26) | 318 |
-| Sprint 18 | Thinking display + workspace tree | File preview auto-close, thinking/reasoning cards, expandable directory tree (#22) | 318 |
-| Sprint 19 | Auth + security hardening | Password auth (off by default), login page, security headers, 20MB body limit (#23) | 328 |
-| Sprint 20 | Voice input + send button | Voice input (Web Speech API), send button icon-circle with pop-in animation | 415 |
-| Sprint 21 | Mobile responsive + Docker | Hamburger sidebar, mobile nav, files slide-over, Docker support (#21, #7) | 415 |
-| Sprint 22 | Multi-profile support | Profile picker, management panel, seamless switching, per-session tracking (#28) | 415 |
-| Sprint 23 | Agentic transparency | Token/cost display, subagent cards, skill picker in cron, skill linked files, workspace tree persistence, timestamp fixes | 424 |
-| v0.44.0 patch | Fix batch: approval card, login CSP, update diagnostics, Lucide icons | PRs #221 #225 #226 #227 #228 | 579 |
-| v0.45.0 | Custom endpoint in new profile form | Base URL + API key fields; server-side URL validation; config.yaml merge; 9 new tests (PR #233, fixes #170) | 604 |
-| v0.46.0 | Security, Docker UID/GID, model discovery, i18n, cancel fix | Credential redaction in API responses (PR #243); Docker UID/GID matching (PR #237); custom model API key discovery (PR #238); HTML entity decode + zh/zh-Hant i18n (PR #239); cancel interrupts agent (PR #244); +20 tests | 624 |
-| v0.47.0 | Dialogs, session menu, skills command, mobile fixes, mobile QA | Shared app dialogs (#251); session ⋯ menu (#252); mobile QA suite (#254); custom provider slash routing fix (#255); Android Chrome mobile fixes (#256); /skills command (#257); +21 tests | 645 |
-| v0.47.1 | Spanish locale | Full Spanish (es) locale, 175 keys, key-parity tests (#275 @gabogabucho); +3 tests | 648 |
-| v0.48.0 | Gateway session sync | Real-time Telegram/Discord/Slack sessions in sidebar via SSE + DB polling (#274 @bergeouss); +10 tests | 658 |
-| v0.48.1 | Table inline formatting | `inlineMd()` in table cells — **bold**, *italic*, `code`, links render correctly (PR #278); 0 new tests | 658 |
-| v0.48.2 | Provider mismatch warning | Toast warning + auth_mismatch error type for provider/model mismatches (#283, fixes #266); +21 tests | 679 |
-| v0.49.1 | Docker docs + mobile Profiles button | Two-container Docker compose (#291/#288); Profiles added to the mobile navigation flow with correct panel wiring and SVG sizing (#297/#265 @gabogabucho); +3 tests | 700 |
-| v0.49.0 | First-run onboarding wizard + self-update hardening | One-shot bootstrap + guided setup wizard; provider config persisted to config.yaml + .env; OpenRouter/Anthropic/OpenAI/Custom; wizard hidden after completion (#285); self-update stderr/split-ref/conflict fixes (#287); skip flaky redaction test (#289); +18 tests | 697 |
-| v0.32 | Auto-compaction handling | Compression detection, /compact command, real context window indicator | 424 |
-| v0.33 | /insights sync | Opt-in state.db sync so `hermes /insights` includes WebUI sessions | 424 |
-| v0.34 | Sprint 26 — Pluggable themes | Dark, Light, Slate, Solarized, Monokai, Nord; settings unsaved-changes guard; /theme command | 433 |
-| v0.34.1 | Theme variable polish | 30+ hardcoded dark-navy colors replaced with theme-aware CSS variables | 433 |
-| v0.34.2 | Theme text colors | 5 new per-theme typography variables (--strong, --em, --code-text, --code-inline-bg, --pre-text) | 433 |
-| v0.34.3 | Light theme final polish | 46 light-scoped selector overrides for sidebar, roles, chips, interactive elements | 433 |
-| v0.35 | Security hardening | Env race fix, random signing key, upload path traversal, PBKDF2 password hash | 433 |
-| v0.36–v0.37 | Model routing, personality config, tool card reload, duplicate model fixes | Model routing by provider prefix, personality via config.yaml, tool cards reload on page refresh | 466 |
-| v0.38.0–v0.38.6 | Model selector, custom endpoints, OLED theme, reasoning display, insights sync | Custom endpoint URL fix, OLED theme, top-level reasoning field fix, message_count sync to state.db | 466 |
-| v0.39.0 | Security hardening (Sprint 29) | CSRF, PBKDF2, rate limiting, session ID validation, SSRF, ENV_LOCK, XSS, HMAC, skills traversal, secure cookie, error sanitization, startup warning | 499 |
-| v0.40–v0.44.2 | Approval card + Lucide icons + sprint auth | Approval prompt surfaced in UI, emoji icons → Lucide SVG, login CSP inline fix, update diagnostics | 579 |
-| v0.45–v0.46 | Custom endpoints + security + i18n + cancel | Custom endpoint Base URL + API key on profile create, credential redaction (PR #243), Docker UID/GID (PR #237), HTML entity decode + zh/zh-Hant i18n, cancel interrupts agent | 624 |
-| v0.47–v0.47.1 | Dialogs + session menu + skills + mobile QA + Spanish | Shared app dialogs, session ⋯ menu, /skills command, mobile QA suite, Android Chrome fixes, Spanish locale (@gabogabucho) | 648 |
-| v0.48–v0.48.2 | Gateway session sync + table formatting + provider warnings | Real-time Telegram/Discord/Slack sessions in sidebar (@bergeouss), inlineMd() in table cells, provider/model mismatch toast | 679 |
-| v0.49–v0.49.1 | Onboarding wizard + Docker two-container | One-shot bootstrap + guided setup wizard, OpenRouter/Anthropic/OpenAI/Custom provider config, two-container Docker compose, mobile Profiles button | 700 |
-| v0.50.0 | v0.50.0 UI overhaul (Sprint 34) | Composer-centric controls, Hermes Control Center modal, workspace panel state machine, collapsible date groups, rAF streaming throttle, context ring indicator (@aronprins) | 742 |
-| v0.50.5–v0.50.10 | Think-tag edge cases + onboarding hardening + mobile fixes | MiniMax M2.5 leading-whitespace think-tag fix, skip-onboarding env var, OAuth provider path, Docker bridge networks fix, model dropdown dedup, title auto-generation fix, mobile close button | 802 |
-| v0.50.11–v0.50.12 | Chat table styles + URL autolink + profile env isolation | .msg-body table borders, plain URL auto-linking, profile .env secret isolation on switch (prevents API key leakage across profiles, @Hinotoi-agent) | 815 |
-| v0.50.13–v0.50.15 | session_search + security sweep + KaTeX math | SessionDB injection for session_search in WebUI (@DelightRun), bandit B310/B324/B110 + QuietHTTPServer (@lawrencel1ng), KaTeX math rendering with fence-before-math fix | 871 |
-| v0.50.16–v0.50.17 | CSRF reverse proxy + Docker uv pre-install | Scheme-aware CSRF port normalization for non-standard ports (@lx3133584), Docker uv pre-installed at build time as root (fixes air-gapped startup, @mmartial-pattern) | 900 |
-| v0.50.18–v0.50.19 | Workspace fallback + Unicode filenames | Cascading workspace path recovery (@Jordan-SkyLF), Unicode Content-Disposition headers with RFC 5987 filename* (@shaoxianbilly), silent auth error surfacing, stale model cleanup | 924 |
-| v0.50.20–v0.50.21 | Silent errors + live model fetching + durable streaming recovery | apperror on empty agent response, /api/models/live endpoint with SSRF guard, live reasoning cards, tool_complete SSE events, SESSION_QUEUES, localStorage reload recovery (@Jordan-SkyLF) | 961 |
-| v0.50.22–v0.50.36-local.1 | Upstream sync + minimal local patch retention | Synced to upstream `v0.50.36`; retained first-password session continuity in Settings/onboarding; removed local Assistant Reply Language enhancement; added legacy settings cleanup regression coverage | 1059 |
-| v0.50.37–v0.50.40 | Sprint 40 — rendering fixes + KaTeX CSP + MEDIA images | Think-tag edge cases, renderMd link double-linking fix, MEDIA: inline image rendering, KaTeX CSP font-src fix | 1117 |
-| v0.50.41–v0.50.43 | Sprint 41/42 — context ring, session polish, renderMd hardening | Context indicator live usage, session display fixes, renderMd bold+code stash, outer link pass ordering, _ob_stash, autolink double-link fixes (@multiple contributors) | 1150 |
-| v0.50.44 | Renderer formatting bug fixes (#486, #487) | CSS: inline code sizing in table cells; JS: markdown image syntax ![alt](url) → <img> in renderMd + inlineMd; _img_stash for autolink protection | 1195 |
+| 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 (~165 lines) + api/ modules (~5000 lines) | Thin shell + QuietHTTPServer + auth middleware + business logic in api/ |
-| HTML template | <repo>/static/index.html (~600 lines) | Served from disk |
-| CSS | <repo>/static/style.css (~1050 lines) | Served from disk, incl. mobile responsive, KaTeX, table styles |
-| JavaScript | <repo>/static/{ui,workspace,sessions,messages,panels,boot,commands,icons,i18n,login}.js | 10 modules, ~7100 lines total |
-| Docker | Dockerfile, docker-compose.yml, .dockerignore | python:3.12-slim, multi-arch (amd64+arm64) |
-| CI/CD | .github/workflows/release.yml | Auto-release + GHCR publish on tag push |
-| Runtime state | ~/.hermes/webui-mvp/sessions/ | Session JSON files |
-| Test server | Port 8788 (conftest.py), port 8789 (browser sanity) | 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] Composer-scoped model picker in footer (moved from sidebar to align with per-conversation model selection)
-- [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 inline in the conversation via live tool cards
-- [x] Approval card for dangerous commands (Allow once/session/always, Deny)
+- [x] Composer-scoped model picker (per-conversation model selection)
+- [x] Multi-provider API support — OpenAI, Anthropic, Google, OpenRouter, xAI, GLM, DeepSeek, Mistral, MiniMax, Kimi, OpenCode, Nous Portal, custom OpenAI-compatible endpoints
+- [x] Live custom-endpoint model discovery (Ollama, LM Studio, vLLM via `/v1/models`)
+- [x] Free-form OpenRouter model name (autocomplete + custom input)
+- [x] Tool progress shown inline via live tool cards
+- [x] Approval card for dangerous commands (Allow once / session / always, Deny)
 - [x] Approval polling + SSE-pushed approval events
+- [x] Clarify dialog — agent can ask blocking clarifying questions
+- [x] Subagent delegation cards in tool view
 - [x] INFLIGHT guard: switch sessions mid-request without losing response
 - [x] Session restores from localStorage on page load
 - [x] Reconnect banner if page reloaded mid-stream
+- [x] SSE auto-reconnect with stream replay
+- [x] Token / cost estimate per message and per session
+- [x] Context usage indicator (compact ring badge in composer footer)
+- [x] Auto-compaction handling + `/compact` command
+- [x] rAF-throttled token rendering (smooth, no DOM thrash)
+- [x] Cancel / stop button in composer footer
+- [x] Reasoning effort selector (low / medium / high / xhigh) + `/reasoning`
+- [x] Pure-text streaming with crash-recovery — partial messages restored from localStorage on reload
+
+### Conversation controls
 - [x] Copy message to clipboard (hover icon on each bubble)
 - [x] Edit last user message and regenerate
-- [ ] Branch/fork conversation (Wave 3)
-- [x] Token/cost estimate per message (Sprint 23)
-
-### Tool Visibility
-- [x] Tool progress in live tool cards (kept out of the composer/footer chrome)
-- [x] Approval card with all 4 choices
-- [x] Tool call cards inline (collapsed, show name/args/result)
-
-### Workspace / Files
-- [x] Workspace panel defaults closed and opens only for active browsing or preview
-- [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, confirmation modal)
-- [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] Shared app modal for confirm/input flows (Sprint 33)
+- [x] Regenerate last response
+- [x] Clear conversation (wipe messages, keep session)
+- [x] Branch / fork conversation from any message point (#465)
+- [x] Pure-text + tool-call streams both recover
 
 ### Sessions
 - [x] Create session (+ button or Cmd/Ctrl+K)
 - [x] Load session (click in sidebar)
-- [x] Delete session (hover trash, toast, correct fallback)
-- [x] Auto-title from first user message
-- [x] Rename session title (double-click in sidebar, Enter saves, Escape cancels)
-- [x] Filter/search sessions by title (live filter box)
-- [x] Date group headers (Today / Yesterday / Earlier)
-- [x] Download session as Markdown transcript
-- [x] Export session as JSON (full messages + metadata)
-- [x] Session inherits last-used workspace on creation
-- [x] Session content search (search message text across sessions)
-- [x] Session tags / labels (Sprint 14)
-- [x] Archive sessions (Sprint 14)
-- [x] Clear conversation (wipe messages, keep session) (Wave 3)
-- [x] Import session from JSON (Sprint 12)
-- [x] Pin/star sessions to top of list (Sprint 12)
-- [x] Duplicate session (Sprint 13)
-- [x] Session projects / folders (Sprint 15)
+- [x] Delete session (hover trash, toast undo, fallback)
+- [x] Auto-title from first user message + adaptive title refresh (configurable cadence)
+- [x] LLM-generated titles via auxiliary route (configurable model)
+- [x] Rename session inline (double-click, Enter saves, Escape cancels)
+- [x] Title search (live filter)
+- [x] Content search (full-text across all sessions)
+- [x] Date group headers (Today / Yesterday / Earlier) with collapsible groups
+- [x] Pin / star sessions to top
+- [x] Duplicate session
+- [x] Import / Export session as JSON (full messages + metadata)
+- [x] Download as Markdown transcript
+- [x] Tags (`#tag` extraction + filter chips)
+- [x] Archive sessions (hidden by default, "Show N archived" toggle)
+- [x] Projects / folders (chip filter bar, "Unassigned" filter)
+- [x] Per-session profile tracking
+- [x] Per-session toolset override (`/toolsets`)
+- [x] Batch select mode (multi-select, bulk delete / move / archive)
+- [x] CLI session bridge — read CLI sessions from state.db, import as WebUI sessions
 
-### Workspace Management
-- [x] Add workspace with path validation (must be existing directory)
-- [x] Remove workspace
-- [x] Rename workspace display name
-- [x] Quick-switch workspace from topbar dropdown
-- [x] Sidebar live workspace display (name + path, updates in real time)
-- [x] New sessions inherit last used workspace
-- [x] Workspace list persists to workspaces.json
-- [ ] Workspace reorder (drag) (Wave 2)
+### Workspace and files
+- [x] Add workspace with path validation (existing directory, follows symlinks)
+- [x] Remove / rename workspace
+- [x] Quick-switch from topbar dropdown
+- [x] Sidebar live workspace display (name + path)
+- [x] New sessions inherit last-used workspace
+- [x] Browse workspace directory tree with type icons
+- [x] Tree view with expand / collapse + lazy load (#22)
+- [x] Breadcrumb navigation in subdirectories
+- [x] Preview text / code (read-only)
+- [x] Preview markdown (rendered + tables + Mermaid + KaTeX)
+- [x] Preview images (PNG, JPG, GIF, SVG, WEBP, AVIF inline)
+- [x] Preview PDF / SVG / audio / video / Excalidraw / CSV / JSON / YAML
+- [x] Edit files inline (Edit button, Enter saves, Escape cancels)
+- [x] Create / rename / delete files and folders (in current directory)
+- [x] Drag-drop / click / clipboard paste upload
+- [x] Archive upload (zip / tar) with extraction
+- [x] Syntax highlighted code preview (Prism.js, language-aware)
+- [x] File preview auto-close on directory navigation
+- [x] Right panel resizable (drag inner edge)
+- [x] Embedded workspace terminal (`/api/terminal/{start,input,output}`)
+- [x] Git branch + dirty status badge in workspace header
 
-### Scheduled Tasks (Cron)
-- [x] View all cron jobs (Tasks sidebar tab)
-- [x] View last run output per job (auto-loaded on expand)
-- [x] Expand job to see prompt, schedule, last output
-- [x] Run job manually (Run now button)
-- [x] Pause / Resume job
-- [x] Create cron job from UI (+ New job form with name, schedule, prompt, delivery)
-- [x] Edit existing cron job
-- [x] Delete cron job
-- [x] View full cron run history (expandable per job)
-- [x] Skill picker in cron create form (Sprint 23)
+### Cron jobs
+- [x] List all cron jobs (Tasks sidebar tab)
+- [x] View job details (prompt, schedule, last run, output)
+- [x] Run / pause / resume / delete
+- [x] Create job from UI (name, schedule, prompt, delivery target)
+- [x] Edit job inline (full create-form parity, including skills)
+- [x] Skill picker in create + edit forms
+- [x] Cron run history viewer (expandable per job)
+- [x] Cron completion alerts (toast + badge)
+- [x] Run-status tracking with live watch mode
 
 ### Skills
-- [x] List all skills grouped by category (Skills sidebar tab)
-- [x] Search/filter skills by name, description, category
-- [x] View full SKILL.md content in right preview panel
-- [x] Create skill
-- [x] Edit skill
-- [x] Delete skill
-- [x] View skill linked files (Sprint 23)
+- [x] List all skills grouped by category
+- [x] Search / filter by name, description, category
+- [x] View full SKILL.md content
+- [x] View skill linked files
+- [x] Create / edit / delete skill
+- [x] `/skills` slash command
 
 ### Memory
-- [x] View personal notes (MEMORY.md) rendered as markdown (Memory tab)
-- [x] View user profile (USER.md) rendered as markdown (Memory tab)
-- [x] Last-modified timestamp on each section
-- [x] Add/edit memory entry inline
-
-### Configuration
-- [x] Settings panel (default model, default workspace) (Sprint 12)
-- [x] Send key preference (Enter or Ctrl+Enter) (Sprint 17)
-- [x] Password authentication (Sprint 19)
-- [ ] Enable/disable toolsets per session (deferred)
-
-### Notifications
-- [x] Cron job completion alerts (Sprint 13)
-- [x] Background agent error alerts (Sprint 13)
-
-### Workspace
-- [x] Breadcrumb navigation in subdirectories (Sprint 17)
-- [x] Workspace tree view with expand/collapse (Sprint 18, Issue #22)
-- [x] File preview auto-close on directory navigation (Sprint 18)
-
-### Slash Commands
-- [x] Command registry + autocomplete dropdown (Sprint 17)
-- [x] Built-in: /help, /clear, /model, /workspace, /new (Sprint 17)
-
-### Security
-- [x] Password auth with signed cookies (Sprint 19, Issue #23)
-- [x] Security headers (X-Content-Type-Options, X-Frame-Options) (Sprint 19)
-- [x] POST body size limit (20MB) (Sprint 19)
-
-### Thinking / Reasoning
-- [x] Collapsible thinking cards for extended-thinking models (Sprint 18)
-
-### Voice
-- [x] Voice input via Web Speech API (Sprint 20)
-
-### Mobile
-- [x] Mobile responsive layout — hamburger sidebar, sidebar tabs on phones, files slide-over (Sprint 21 + later mobile nav simplification)
+- [x] View personal notes (MEMORY.md) rendered as markdown
+- [x] View user profile (USER.md) rendered as markdown
+- [x] Last-modified timestamp per section
+- [x] Add / edit memory entries inline
 
 ### Profiles
-- [x] Multi-profile support — create, switch, delete profiles (Sprint 22, Issue #28)
+- [x] Multi-profile support — create, switch, delete (#28)
+- [x] Topbar profile picker with gateway-status dots
+- [x] Profile management panel (full CRUD)
+- [x] Seamless switching (no server restart, refreshes models / skills / memory / cron / workspace)
+- [x] Profile-local workspace storage
+- [x] First-run onboarding wizard with provider config (OpenRouter / Anthropic / OpenAI / Custom)
+- [x] In-app OAuth for Codex and Claude
 
-### Advanced / Future
-- [ ] Subagent session tree -- show subagent hierarchy in sidebar with expand/collapse (PR #75)
-- [ ] Specialized tool card renderers -- diff viewer, terminal output, todo checklist views (PR #75)
-- [x] Streaming performance -- rAF-throttled token rendering (Sprint 24, PR #81)
-- [x] Workspace git detection -- branch name and dirty status badge (Sprint 24, PR #82)
-- [x] Collapsible date groups -- click group headers to collapse (Sprint 24, PR #80)
-- [x] Context usage indicator -- compact circular badge in composer footer (Sprint 24, PR #83; refreshed April 10, 2026)
-- [ ] LLM-generated session titles -- auto-title via small model instead of first-message substring (PR #75)
-- [ ] Workspace git detection -- show branch name, dirty status in workspace header (PR #75)
-- [ ] Clarify dialog -- agent can ask clarifying questions that block until user responds (PR #75)
-- [ ] Gateway approval polling -- support blocking approvals from messaging gateway (PR #75)
-- [ ] Unified session storage -- SessionDB shared between webui and CLI (PR #75)
-- [ ] TTS playback of responses (deferred)
-- [x] Background task cancel (composer footer stop button)
-- [ ] Code execution cell (deferred)
-- [ ] Desktop application (Sprint 25, PLANNED)
-- [x] Pluggable UI themes -- Dark, Light, Slate, Solarized, Monokai, Nord (Sprint 26, v0.34)
-- [ ] Extended slash command / skill integration (deferred)
-- [ ] Virtual scroll for large lists (deferred)
+### Configuration
+- [x] Settings panel (default model, default workspace, send key, theme, voice, font size)
+- [x] Send key preference (Enter or Ctrl+Enter)
+- [x] Password authentication (off by default)
+- [x] Per-session toolset override
+- [x] Personality config via `config.yaml`
+- [x] Reasoning effort persistence
+
+### Notifications
+- [x] Cron job completion alerts
+- [x] Background agent error banner
+- [x] Approval pending badge
+- [x] Provider / model mismatch toast warning
+
+### Slash commands
+- [x] Command registry + autocomplete dropdown
+- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/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 |
 
 ---
 
-## Completed Waves (Summary)
+## Versioning conventions
 
-| Wave | Theme | Key Deliverables |
-|------|-------|-----------------|
-| Wave 2 | Full CRUD + Interaction | Cron/skill/memory CRUD, session search, workspace management, session rename |
-| Wave 3 | Power Features | Tool call cards, multi-model dropdown, resizable panels, file actions, conversation controls |
-| Wave 4 | Settings + Notifications | Settings panel, cron alerts, background error banner |
-| Wave 5 | Session Continuity | Session tags, archive, projects/folders |
-| Wave 6 | Agentic Features | Background task cancel, voice input (Web Speech API) |
-| Wave 7 | Production Hardening | Password auth, security headers, mobile responsive, Docker + GHCR CI |
+- **Patch** (`v0.50.X`) — small batches, contributor PR releases, hotfixes
+- **Minor** (`v0.X.0`) — sprint completion, new feature surface, architecture milestone
+- **Major** (`v1.0.0`) — declared when CLI parity + Claude parity reach steady state and the feature surface stabilizes
 
----
-
-## User Requested Features
-
-Community-requested enhancements tracked from GitHub issues. All shipped.
-
-| Feature | Issue | Shipped | Sprint |
-|---------|-------|---------|--------|
-| Workspace tree view | #22 | Done | Sprint 18 |
-| Docker container + GHCR images | #7 | Done | Sprint 21 + v0.28.1 CI |
-| Authentication | #23 | Done | Sprint 19 |
-| Send key / personalization | #26 | Done | Sprint 17 |
-| Multi-profile support | #28 | Done | Sprint 22 |
-| Mobile responsive UI | #21 | Done | Sprint 21 |
-| Profile creation in Docker | #44 | Done | v0.27 |
+Per-version detail and contributor attribution live in [CHANGELOG.md](./CHANGELOG.md).

TESTING.md

@@ -8,7 +8,7 @@
 > 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: 1353 tests collected via `pytest tests/ --collect-only -q`. Includes onboarding coverage for bootstrap/static wizard presence, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, and CSS regression coverage for smooth thinking/tool card disclosure animation.
+> 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.
@@ -240,6 +240,32 @@ 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
@@ -306,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:
@@ -1782,8 +1835,8 @@ Bridged CLI sessions:
 
 ---
 
-*Last updated: v0.50.91, April 19, 2026*
-*Total automated tests collected: 1688*
+*Last updated: v0.51.29, May 8, 2026*
+*Total automated tests collected: 4960*
 *Regression gate: tests/test_regressions.py*
 *Run: pytest tests/ -v --timeout=60*
 *Source: <repo>/*

api/agent_health.py

@@ -0,0 +1,284 @@
+"""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 _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 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

@@ -6,9 +6,11 @@ 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
@@ -19,33 +21,135 @@ logger = logging.getLogger(__name__)
 PUBLIC_PATHS = frozenset({
     '/login', '/health', '/favicon.ico',
     '/api/auth/login', '/api/auth/status',
+    '/manifest.json', '/manifest.webmanifest',
 })
 
 COOKIE_NAME = 'hermes_session'
-SESSION_TTL = 86400  # 24 hours
+SESSION_TTL = 86400 * 30  # 30 days
 
-# Active sessions: token -> expiry timestamp
-_sessions = {}
+_SESSIONS_FILE = STATE_DIR / '.sessions.json'
+
+
+def _load_sessions() -> dict[str, float]:
+    """Load persisted sessions from STATE_DIR, pruning expired entries.
+
+    Returns an empty dict on any read or parse error so startup is never
+    blocked by a corrupt or missing sessions file.
+    """
+    try:
+        if _SESSIONS_FILE.exists():
+            data = json.loads(_SESSIONS_FILE.read_text(encoding='utf-8'))
+            if not isinstance(data, dict):
+                raise ValueError('malformed sessions file — expected dict')
+            now = time.time()
+            return {t: exp for t, exp in data.items()
+                    if isinstance(t, str) and isinstance(exp, (int, float)) and exp > now}
+    except Exception as e:
+        logger.debug("Failed to load sessions file, starting fresh: %s", e)
+    return {}
+
+
+def _save_sessions(sessions: dict[str, float]) -> None:
+    """Atomically persist sessions to STATE_DIR/.sessions.json (0600).
+
+    Uses a temp file + os.replace() so a crash mid-write never leaves a
+    truncated file.  Mirrors the same pattern as .signing_key persistence.
+    """
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=STATE_DIR, suffix='.sessions.tmp')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(sessions, f)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, _SESSIONS_FILE)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception as e:
+        logger.debug("Failed to persist sessions: %s", e)
+
+
+# Active sessions: token -> expiry timestamp (persisted across restarts via STATE_DIR)
+_sessions = _load_sessions()
 
 # ── Login rate limiter ──────────────────────────────────────────────────────
-_login_attempts = {}  # ip -> [timestamp, ...]
+_LOGIN_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]
-    _login_attempts[ip] = attempts
+    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():
@@ -107,6 +211,7 @@ def create_session() -> str:
     """Create a new auth session. Returns signed cookie value."""
     token = secrets.token_hex(32)
     _sessions[token] = time.time() + SESSION_TTL
+    _save_sessions(_sessions)
     sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
     return f"{token}.{sig}"
 
@@ -114,8 +219,11 @@ def create_session() -> str:
 def _prune_expired_sessions():
     """Remove all expired session entries to prevent unbounded memory growth."""
     now = time.time()
-    for token in [t for t, exp in _sessions.items() if now > exp]:
-        _sessions.pop(token, None)
+    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:
@@ -138,7 +246,9 @@ def invalidate_session(cookie_value) -> None:
     """Remove a session token."""
     if cookie_value and '.' in cookie_value:
         token = cookie_value.rsplit('.', 1)[0]
-        _sessions.pop(token, None)
+        if token in _sessions:
+            _sessions.pop(token, None)
+            _save_sessions(_sessions)
 
 
 def parse_cookie(handler) -> str | None:
@@ -161,7 +271,7 @@ def check_auth(handler, parsed) -> bool:
     if not is_auth_enabled():
         return True
     # Public paths don't require auth
-    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/'):
+    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/') or parsed.path.startswith('/session/static/'):
         return True
     # Check session cookie
     cookie_val = parse_cookie(handler)
@@ -175,7 +285,33 @@ def check_auth(handler, parsed) -> bool:
         handler.wfile.write(b'{"error":"Authentication required"}')
     else:
         handler.send_response(302)
-        handler.send_header('Location', '/login')
+        # Pass the original path as ?next= so login.js redirects back after auth.
+        # SECURITY/CORRECTNESS: the inner `?` and `&` MUST be percent-encoded
+        # when stuffed into the outer `?next=` parameter, otherwise:
+        #   (a) multi-param query strings get truncated at the first inner `&`
+        #       (e.g. `/api/sessions?limit=50&offset=0` would round-trip as
+        #       just `/api/sessions?limit=50` after the browser parses the
+        #       outer URL — `offset=0` becomes a separate top-level query
+        #       parameter that the login page ignores).
+        #   (b) attacker-controlled paths could inject a second `next=`
+        #       parameter; per RFC 3986 the duplicate behaviour is undefined
+        #       and parsers diverge (Python's parse_qs returns last-match,
+        #       URLSearchParams returns first-match), opening a query-pollution
+        #       footgun even though _safeNextPath() rejects most malicious
+        #       shapes downstream.
+        # Encoding the entire `path?query` blob with quote(safe='/') turns
+        # `?` → `%3F` and `&` → `%26`, so the outer parameter holds exactly
+        # one path-with-query string and `searchParams.get('next')` returns
+        # the full original URL (the browser auto-decodes once).
+        # (Opus pre-release advisor finding for v0.50.258.)
+        import urllib.parse as _urlparse
+        _path_with_query = parsed.path or '/'
+        if parsed.query:
+            _path_with_query += '?' + parsed.query
+        # safe='/' keeps path separators readable; everything else (including
+        # `?`, `&`, `=`) gets percent-encoded.
+        _next = _urlparse.quote(_path_with_query, safe='/')
+        handler.send_header('Location', 'login?next=' + _next)
         handler.end_headers()
     return False
 

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

@@ -6,15 +6,21 @@ 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."""
@@ -57,14 +63,57 @@ def clear_pending(session_key: str) -> int:
     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:
-        queue = _gateway_queues.setdefault(session_key, [])
+        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 queue:
-            last = queue[-1]
+        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 [])
@@ -73,7 +122,7 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                 entry = last
                 cb = _gateway_notify_cbs.get(session_key)
                 # Keep _pending aligned to the oldest unresolved entry.
-                _pending[session_key] = queue[0].data
+                _pending[session_key] = gw_queue[0].data
                 if cb:
                     try:
                         cb(dict(entry.data))
@@ -82,9 +131,11 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                 return entry
 
         entry = _ClarifyEntry(data)
-        queue.append(entry)
-        _pending[session_key] = queue[0].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)
@@ -111,15 +162,17 @@ def has_pending(session_key: str) -> bool:
 def resolve_clarify(session_key: str, response: str, resolve_all: bool = False) -> int:
     """Resolve the oldest pending clarify request for a session."""
     with _lock:
-        queue = _gateway_queues.get(session_key)
-        if not queue:
+        q = _gateway_queues.get(session_key)
+        if not q:
             _pending.pop(session_key, None)
             return 0
-        entries = list(queue) if resolve_all else [queue.pop(0)]
-        if queue:
-            _pending[session_key] = queue[0].data
+        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

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

@@ -13,12 +13,12 @@ import json
 import logging
 import os
 import queue
-import sqlite3
 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__)
 
@@ -55,33 +55,21 @@ def _get_agent_sessions_from_db() -> list:
         return []
 
     try:
-        with sqlite3.connect(str(db_path)) as conn:
-            conn.row_factory = sqlite3.Row
-            cur = conn.cursor()
-            cur.execute("""
-                SELECT s.id, s.title, s.model, s.message_count,
-                       s.started_at, s.source,
-                       MAX(m.timestamp) AS last_activity
-                FROM sessions s
-                LEFT JOIN messages m ON m.session_id = s.id
-                WHERE s.source IS NOT NULL AND s.source != 'webui'
-                GROUP BY s.id
-                HAVING COUNT(m.id) > 0
-                ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC
-                LIMIT 200
-            """)
-            sessions = []
-            for row in cur.fetchall():
-                sessions.append({
-                    'session_id': row['id'],
-                    'title': row['title'] or 'Agent Session',
-                    'model': row['model'] or None,
-                    'message_count': row['message_count'] or 0,
-                    'created_at': row['started_at'],
-                    'updated_at': row['last_activity'] or row['started_at'],
-                    'source': row['source'] or 'cli',
-                })
-            return sessions
+        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 []
 
@@ -119,6 +107,19 @@ class GatewayWatcher:
         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()

api/goals.py

@@ -0,0 +1,489 @@
+"""WebUI bridge for Hermes persistent session goals."""
+
+from __future__ import annotations
+
+import copy
+import logging
+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,
+) -> 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
+    return body
+
+
+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":
+        return _payload(action="status", message=mgr.status_line(), state=getattr(mgr, "state", None))
+
+    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.")
+        return _payload(action="pause", message=f"⏸ Goal paused: {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.")
+        return _payload(
+            action="resume",
+            message=(
+                f"▶ Goal resumed: {state.goal}\n"
+                "Send a new message, or type continue, to kick it off."
+            ),
+            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.",
+            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"
+        ),
+        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", "")
+    return decision

api/helpers.py

@@ -2,6 +2,7 @@
 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
@@ -42,26 +43,52 @@ def _security_headers(handler):
     handler.send_header('Referrer-Policy', 'same-origin')
     handler.send_header(
         'Content-Security-Policy',
-        "default-src 'self'; "
-        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
-        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
-        "img-src 'self' data: https: blob:; font-src 'self' data: https://cdn.jsdelivr.net; connect-src 'self'; "
+        "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=()'
+        'camera=(), microphone=(self), geolocation=(), clipboard-write=(self)'
     )
 
 
-def j(handler, payload, status: int=200) -> None:
-    """Send a JSON response."""
+def _accepts_gzip(handler) -> bool:
+    """Check if the client accepts gzip encoding."""
+    headers = getattr(handler, 'headers', None)
+    if not headers:
+        return False
+    ae = headers.get('Accept-Encoding', '')
+    return 'gzip' in ae
+
+
+def j(handler, payload, status: int=200, extra_headers: dict=None) -> None:
+    """Send a JSON response.
+
+    *extra_headers*: optional dict of additional headers to include
+    (e.g., {'Set-Cookie': '...'}).  Headers are sent before end_headers().
+    """
     body = _json.dumps(payload, ensure_ascii=False, indent=2).encode('utf-8')
     handler.send_response(status)
     handler.send_header('Content-Type', 'application/json; charset=utf-8')
+
+    # Gzip-compress responses over 1KB when the client accepts it.
+    # Typical JSON API responses compress 70-80%, giving a big speedup
+    # for large payloads (session history, message lists).
+    if _accepts_gzip(handler) and len(body) > 1024:
+        import gzip
+        body = gzip.compress(body, compresslevel=4)
+        handler.send_header('Content-Encoding', 'gzip')
+
     handler.send_header('Content-Length', str(len(body)))
     handler.send_header('Cache-Control', 'no-store')
     _security_headers(handler)
+    if extra_headers:
+        for k, v in extra_headers.items():
+            handler.send_header(k, v)
     handler.end_headers()
     handler.wfile.write(body)
 
@@ -84,14 +111,10 @@ MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
 # ── Credential redaction ──────────────────────────────────────────────────────
 
 def _build_redact_fn():
-    """Return redact_sensitive_text from hermes-agent if available, else a fallback."""
-    try:
-        from agent.redact import redact_sensitive_text
-        return redact_sensitive_text
-    except ImportError:
-        pass
-
-    # Minimal fallback covering the most common credential prefixes
+    """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
@@ -130,20 +153,62 @@ def _build_redact_fn():
         text = _PRIVKEY_RE.sub("[REDACTED PRIVATE KEY]", text)
         return text
 
-    return _fallback_redact
+    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_text = _build_redact_fn()
+_redact_fn_cached = _build_redact_fn()
 
 
-def _redact_value(v):
-    """Recursively redact credentials from strings, dicts, and lists."""
+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)
+        return _redact_text(v, _enabled=_enabled)
     if isinstance(v, dict):
-        return {k: _redact_value(val) for k, val in v.items()}
+        return {k: _redact_value(val, _enabled=_enabled) for k, val in v.items()}
     if isinstance(v, list):
-        return [_redact_value(item) for item in v]
+        return [_redact_value(item, _enabled=_enabled) for item in v]
     return v
 
 
@@ -152,14 +217,22 @@ def redact_session_data(session_dict: dict) -> dict:
 
     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'])
+        result['title'] = _redact_text(result['title'], _enabled=_enabled)
     if 'messages' in result:
-        result['messages'] = _redact_value(result['messages'])
+        result['messages'] = _redact_value(result['messages'], _enabled=_enabled)
     if 'tool_calls' in result:
-        result['tool_calls'] = _redact_value(result['tool_calls'])
+        result['tool_calls'] = _redact_value(result['tool_calls'], _enabled=_enabled)
     return result
 
 
@@ -173,3 +246,57 @@ def read_body(handler) -> dict:
         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

@@ -2,8 +2,12 @@
 
 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
 
@@ -23,12 +27,14 @@ from api.config import (
     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",
@@ -37,6 +43,8 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "models": [
             {"id": model["id"], "label": model["label"]} for model in _FALLBACK_MODELS
         ],
+        "category": "easy_start",
+        "quick": True,
     },
     "anthropic": {
         "label": "Anthropic",
@@ -44,6 +52,9 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "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",
@@ -52,19 +63,133 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "default_base_url": "https://api.openai.com/v1",
         "requires_base_url": False,
         "models": list(_PROVIDER_MODELS.get("openai", [])),
+        "category": "easy_start",
+    },
+    # ── Open / self-hosted ─────────────────────────────────────────────
+    "ollama": {
+        "label": "Ollama",
+        "env_var": "OLLAMA_API_KEY",
+        "default_model": "qwen3:32b",
+        "default_base_url": "http://localhost:11434/v1",
+        "requires_base_url": True,
+        # Local Ollama runs keyless by default — only Ollama Cloud requires
+        # OLLAMA_API_KEY.  The wizard accepts an empty api_key for this
+        # provider; users with auth enabled can still type one.  See #1499.
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
+    },
+    "lmstudio": {
+        "label": "LM Studio",
+        # Canonical env var matches the agent CLI runtime (hermes_cli/auth.py:182,
+        # api_key_env_vars=("LM_API_KEY",)).  Onboarding writes this name so the
+        # agent runtime actually picks up the key on the next chat — pre-#1499/#1500
+        # the WebUI wrote LMSTUDIO_API_KEY which the agent runtime ignored, masked
+        # in practice by the LMSTUDIO_NOAUTH_PLACEHOLDER fallback for keyless installs.
+        "env_var": "LM_API_KEY",
+        # Legacy env var written by older WebUI builds (≤ v0.50.272).  Detection
+        # paths (_provider_api_key_present here, _provider_has_key in providers.py)
+        # also read this name so existing users with the old key in their .env
+        # don't flip to "no key" in Settings → Providers after upgrading.
+        # Onboarding only writes the canonical name going forward.
+        "env_var_aliases": ["LMSTUDIO_API_KEY"],
+        "default_model": "gpt-4o-mini",
+        "default_base_url": "http://localhost:1234/v1",
+        "requires_base_url": True,
+        # Most LM Studio installs run keyless (LMSTUDIO_NOAUTH_PLACEHOLDER on the
+        # agent side handles this).  The wizard accepts an empty api_key; auth-
+        # enabled servers still need one but the user types it in the same field.
+        # See #1499 (third sub-bug from #1420).
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
     },
     "custom": {
         "label": "Custom OpenAI-compatible",
         "env_var": "OPENAI_API_KEY",
         "default_model": "gpt-4o-mini",
         "requires_base_url": True,
+        # Many self-hosted OpenAI-compatible servers (vLLM, llama-server,
+        # TabbyAPI, etc.) run keyless behind a private network.  The wizard
+        # accepts an empty api_key — auth-protected endpoints can still
+        # supply one.  See #1499.
+        "key_optional": True,
         "models": [],
+        "category": "self_hosted",
+    },
+    # ── Specialized / extended ──────────────────────────────────────────
+    "gemini": {
+        "label": "Google Gemini",
+        "env_var": "GOOGLE_API_KEY",
+        "default_model": "gemini-3.1-pro-preview",
+        "default_base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "requires_base_url": False,
+        # _PROVIDER_MODELS in api/config.py is keyed under "google" even though
+        # the agent's alias map normalizes "google" → "gemini".  Use the catalog
+        # key here so the wizard surfaces the actual model list.
+        "models": list(_PROVIDER_MODELS.get("google", [])),
+        "category": "specialized",
+    },
+    "deepseek": {
+        "label": "DeepSeek",
+        "env_var": "DEEPSEEK_API_KEY",
+        "default_model": "deepseek-v4-flash",
+        "default_base_url": "https://api.deepseek.com",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("deepseek", [])),
+        "category": "specialized",
+    },
+    "zai": {
+        "label": "Z.AI / GLM (智谱)",
+        "env_var": "GLM_API_KEY",
+        "default_model": "glm-5.1",
+        "default_base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("zai", [])),
+        "category": "specialized",
+    },
+    "nvidia": {
+        "label": "NVIDIA NIM",
+        "env_var": "NVIDIA_API_KEY",
+        "default_model": "nvidia/llama-3.3-nemotron-super-49b-v1.5",
+        "default_base_url": "https://integrate.api.nvidia.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("nvidia", [])),
+        "category": "specialized",
+    },
+    "mistralai": {
+        "label": "Mistral",
+        "env_var": "MISTRAL_API_KEY",
+        "default_model": "mistral-large-latest",
+        "default_base_url": "https://api.mistral.ai/v1",
+        "requires_base_url": False,
+        # No catalog entry for mistralai today — wizard shows a free-text input.
+        "models": list(_PROVIDER_MODELS.get("mistralai", [])),
+        "category": "specialized",
+    },
+    "x-ai": {
+        "label": "xAI (Grok)",
+        "env_var": "XAI_API_KEY",
+        "default_model": "grok-4.20",
+        "default_base_url": "https://api.x.ai/v1",
+        "requires_base_url": False,
+        # Agent normalizes "x-ai" → "xai"; _PROVIDER_MODELS is also keyed "xai"
+        # when populated, so check both keys for forward-compatibility.
+        "models": list(_PROVIDER_MODELS.get("xai", []) or _PROVIDER_MODELS.get("x-ai", [])),
+        "category": "specialized",
     },
 }
 
+_PROVIDER_CATEGORIES = [
+    {"id": "easy_start", "label": "Easy start", "order": 0},
+    {"id": "self_hosted", "label": "Open / self-hosted", "order": 1},
+    {"id": "specialized", "label": "Specialized", "order": 2},
+]
+
 _UNSUPPORTED_PROVIDER_NOTE = (
-    "OAuth and advanced provider flows such as Nous Portal, OpenAI Codex, and GitHub "
-    "Copilot are still terminal-first. Use `hermes model` for those flows."
+    "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."
 )
 
 
@@ -93,26 +218,6 @@ def _load_env_file(env_path: Path) -> dict[str, str]:
     return values
 
 
-def _write_env_file(env_path: Path, updates: dict[str, str]) -> None:
-    current = _load_env_file(env_path)
-    for key, value in updates.items():
-        if value is None:
-            current.pop(key, None)
-            os.environ.pop(key, None)
-            continue
-        clean = str(value).strip()
-        if not clean:
-            continue
-        # Reject embedded newlines/carriage returns to prevent .env injection
-        if "\n" in clean or "\r" in clean:
-            raise ValueError("API key must not contain newline characters.")
-        current[key] = clean
-        os.environ[key] = clean
-
-    env_path.parent.mkdir(parents=True, exist_ok=True)
-    lines = [f"{key}={current[key]}" for key in sorted(current)]
-    env_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
-
 
 def _load_yaml_config(config_path: Path) -> dict:
     try:
@@ -155,6 +260,216 @@ 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):
@@ -191,6 +506,15 @@ def _provider_api_key_present(
     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
@@ -216,7 +540,7 @@ def _provider_api_key_present(
     # 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"}
+    _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
@@ -230,27 +554,41 @@ def _provider_api_key_present(
 
 
 
+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.
 
-    Checks via hermes_cli.auth.get_auth_status() when available, then falls
-    back to reading auth.json directly for the known OAuth provider IDs
-    (openai-codex, copilot, copilot-acp, qwen-oauth, nous).
-
-    This covers users who authenticated via 'hermes auth' or 'hermes model'
-    but whose provider is not in _SUPPORTED_PROVIDER_SETUPS because it does
-    not use a plain API key.
+    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
 
-    # Check auth.json for known OAuth provider IDs.
-    # hermes_home scopes the check — callers must pass the correct home directory.
-    # (A prior CLI fast path via hermes_cli.auth.get_auth_status() was removed
-    # because it ignored hermes_home and read from the real system home, breaking
-    # both test isolation and deployments with multiple profiles.)
-    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous"}
+    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous", "anthropic"}
     if provider not in _known_oauth_providers:
         return False
 
@@ -261,20 +599,29 @@ def _provider_oauth_authenticated(provider: str, hermes_home: "Path") -> bool:
         if not auth_path.exists():
             return False
         store = _j.loads(auth_path.read_text(encoding="utf-8"))
+
         providers_store = store.get("providers")
-        if not isinstance(providers_store, dict):
-            return False
-        state = providers_store.get(provider)
-        if not isinstance(state, dict):
-            return False
-        # Any non-empty token is enough to confirm the user has credentials.
-        # Token refresh happens at runtime inside the agent.
-        has_token = bool(
-            str(state.get("access_token") or "").strip()
-            or str(state.get("api_key") or "").strip()
-            or str(state.get("refresh_token") or "").strip()
-        )
-        return has_token
+        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
 
@@ -289,12 +636,34 @@ def _status_from_runtime(cfg: dict, imports_ok: bool) -> dict:
     provider_ready = False
 
     if provider_configured:
-        if provider == "custom":
-            provider_ready = bool(
-                base_url and _provider_api_key_present(provider, cfg, env_values)
-            )
-        elif provider in _SUPPORTED_PROVIDER_SETUPS:
-            provider_ready = _provider_api_key_present(provider, cfg, env_values)
+        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,
@@ -370,20 +739,41 @@ def _build_setup_catalog(cfg: dict) -> dict:
                 "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", [])),
-                "quick": provider_id == "openrouter",
+                "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
-    )
+    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": {
@@ -416,11 +806,52 @@ def get_onboarding_status() -> dict:
     auto_completed = skip_requested  # unconditional: operator says skip, we skip
 
     # Auto-complete for existing Hermes users: if config.yaml already exists
-    # AND 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.
+    # 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()
-    config_auto_completed = config_exists and bool(runtime.get("chat_ready"))
+
+    # 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,
@@ -501,7 +932,16 @@ def apply_onboarding_setup(body: dict) -> dict:
     env_values = _load_env_file(env_path)
 
     if not api_key and not _provider_api_key_present(provider, cfg, env_values):
-        raise ValueError(f"{provider_meta['env_var']} is required")
+        # 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):
@@ -510,12 +950,10 @@ def apply_onboarding_setup(body: dict) -> dict:
     model_cfg["provider"] = provider
     model_cfg["default"] = _normalize_model_for_provider(provider, model)
 
-    if provider == "custom":
+    if provider_meta.get("requires_base_url"):
         model_cfg["base_url"] = base_url
-    elif provider == "openai":
-        model_cfg["base_url"] = (
-            provider_meta.get("default_base_url") or "https://api.openai.com/v1"
-        )
+    elif provider_meta.get("default_base_url"):
+        model_cfg["base_url"] = provider_meta["default_base_url"]
     else:
         model_cfg.pop("base_url", None)
 

api/profiles.py

@@ -31,6 +31,19 @@ _active_profile = 'default'
 _profile_lock = threading.Lock()
 _loaded_profile_env_keys: set[str] = set()
 
+# Thread-local profile context: set per-request by server.py, cleared after.
+# Enables per-client profile isolation (issue #798) — each HTTP request thread
+# reads its own profile from the hermes_profile cookie instead of the
+# process-global _active_profile.
+_tls = threading.local()
+
+def _unwrap_profile_home_to_base(home: Path) -> Path:
+    """Return the base Hermes home when *home* is already a named profile dir."""
+    if home.parent.name == 'profiles':
+        return home.parent.parent
+    return home
+
+
 def _resolve_base_hermes_home() -> Path:
     """Return the BASE ~/.hermes directory — the root that contains profiles/.
 
@@ -50,20 +63,22 @@ def _resolve_base_hermes_home() -> Path:
     reading it here would make _DEFAULT_HERMES_HOME point to that subdir,
     causing switch_profile('webui') to look for
     /home/user/.hermes/profiles/webui/profiles/webui — which doesn't exist.
+
+    HERMES_BASE_HOME normally points at the base home already, but isolated
+    single-profile WebUI deployments can provide /base/profiles/<name> there as
+    well.  Normalize both env vars through the same helper so active-profile
+    and per-request resolution share one base-root contract (#749).
     """
     # Explicit override for tests or unusual setups
     base_override = os.getenv('HERMES_BASE_HOME', '').strip()
     if base_override:
-        return Path(base_override).expanduser()
+        return _unwrap_profile_home_to_base(Path(base_override).expanduser())
 
     hermes_home = os.getenv('HERMES_HOME', '').strip()
     if hermes_home:
         p = Path(hermes_home).expanduser()
         # If HERMES_HOME points to a profiles/ subdir, walk up two levels to the base
-        if p.parent.name == 'profiles':
-            return p.parent.parent
-        # Otherwise trust it (e.g. test isolation sets HERMES_HOME to TEST_STATE_DIR)
-        return p
+        return _unwrap_profile_home_to_base(p)
 
     return Path.home() / '.hermes'
 
@@ -85,19 +100,511 @@ def _read_active_profile_file() -> str:
 
 # ── Public API ──────────────────────────────────────────────────────────────
 
+# ── Root-profile resolution (#1612) ────────────────────────────────────────
+#
+# Hermes Agent allows the root/default profile (~/.hermes itself) to have a
+# display name other than the legacy literal 'default'.  When that happens,
+# WebUI must NOT resolve the display name as ~/.hermes/profiles/<name> — that
+# directory doesn't exist, and every site that does `if name == 'default':`
+# will fall through to the wrong filesystem path.
+#
+# `_is_root_profile(name)` answers "does this name resolve to ~/.hermes?" and
+# is the canonical replacement for scattered `if name == 'default':` checks
+# in switch_profile, get_active_hermes_home, _validate_profile_name, etc.
+#
+# Cost note: list_profiles_api() shells out via hermes_cli (non-trivial), so
+# we memoize the lookup. The cache is invalidated whenever profiles are
+# created, deleted, renamed, or cloned — i.e. on every mutation site we
+# control.
+_root_profile_name_cache: set[str] = {'default'}
+_root_profile_name_cache_lock = threading.Lock()
+_root_profile_name_cache_loaded = False
+
+
+def _invalidate_root_profile_cache() -> None:
+    """Drop the memoized root-profile-name set.
+
+    Called whenever profile metadata might have changed: create, clone,
+    delete, rename. The next _is_root_profile() call repopulates from
+    list_profiles_api().
+    """
+    global _root_profile_name_cache_loaded
+    with _root_profile_name_cache_lock:
+        _root_profile_name_cache.clear()
+        _root_profile_name_cache.add('default')
+        _root_profile_name_cache_loaded = False
+
+
+def _is_root_profile(name: str) -> bool:
+    """True if *name* resolves to the Hermes Agent root profile (~/.hermes).
+
+    Matches the legacy 'default' alias plus any name where list_profiles_api()
+    reports is_default=True. Memoized; call _invalidate_root_profile_cache()
+    after mutating profile metadata.
+    """
+    global _root_profile_name_cache_loaded
+    if not name:
+        return False
+    if name == 'default':
+        return True
+    with _root_profile_name_cache_lock:
+        if _root_profile_name_cache_loaded:
+            return name in _root_profile_name_cache
+    # Cache miss — populate from list_profiles_api(). Done outside the lock to
+    # avoid holding it across a hermes_cli subprocess call.
+    try:
+        infos = list_profiles_api()
+    except Exception:
+        logger.debug("Failed to list profiles for root-profile lookup", exc_info=True)
+        return False
+    with _root_profile_name_cache_lock:
+        _root_profile_name_cache.clear()
+        _root_profile_name_cache.add('default')
+        for p in infos:
+            try:
+                if p.get('is_default') and p.get('name'):
+                    _root_profile_name_cache.add(p['name'])
+            except (AttributeError, TypeError):
+                continue
+        _root_profile_name_cache_loaded = True
+        return name in _root_profile_name_cache
+
+
+def _profiles_match(row_profile, active_profile) -> bool:
+    """Return True if a session/project row's profile matches the active profile.
+
+    Treats both the literal alias 'default' and any renamed-root display name
+    (per _is_root_profile) as equivalent, so legacy rows tagged 'default'
+    still surface when the user has renamed the root profile to e.g. 'kinni',
+    and vice versa.
+
+    A row with no profile (`None` or empty string) is treated as belonging to
+    the root profile — that's the convention used by the legacy backfill at
+    api/models.py::all_sessions, and matches the default seen in
+    `static/sessions.js` (`S.activeProfile||'default'`).
+
+    Originally lived in api/routes.py; relocated here so both routes.py and
+    out-of-process consumers (mcp_server.py) can import the canonical helper
+    instead of duplicating the body. See #1614 for the visibility model.
+    """
+    row = row_profile or 'default'
+    active = active_profile or 'default'
+    if row == active:
+        return True
+    # Cross-alias the renamed root.
+    if _is_root_profile(row) and _is_root_profile(active):
+        return True
+    return False
+
+
 def get_active_profile_name() -> str:
-    """Return the currently active profile name."""
+    """Return the currently active profile name.
+
+    Priority:
+      1. Thread-local (set per-request from hermes_profile cookie) — issue #798
+      2. Process-level default (_active_profile)
+    """
+    tls_name = getattr(_tls, 'profile', None)
+    if tls_name is not None:
+        return tls_name
     return _active_profile
 
 
-def get_active_hermes_home() -> Path:
-    """Return the HERMES_HOME path for the currently active profile."""
-    if _active_profile == 'default':
+def set_request_profile(name: str) -> None:
+    """Set the per-request profile context for this thread.
+
+    Called by server.py at the start of each request when a hermes_profile
+    cookie is present.  Always paired with clear_request_profile() in a
+    finally block so the thread-local is released after the request.
+    """
+    _tls.profile = name
+
+
+def clear_request_profile() -> None:
+    """Clear the per-request profile context for this thread.
+
+    Called by server.py in the finally block of do_GET / do_POST.
+    Safe to call even if set_request_profile() was never called.
+    """
+    _tls.profile = None
+
+
+def _resolve_profile_home_for_name(name: str) -> Path:
+    """Resolve a logical profile name to its Hermes home path.
+
+    Root/default aliases resolve to _DEFAULT_HERMES_HOME.  Valid named profiles
+    resolve to _DEFAULT_HERMES_HOME/profiles/<name> even when the directory has
+    not been created yet; the agent layer may create it on first use.  Invalid
+    names fall back to the base home so traversal-shaped cookie values cannot
+    influence filesystem paths.
+    """
+    if not name or _is_root_profile(name):
         return _DEFAULT_HERMES_HOME
-    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / _active_profile
-    if profile_dir.is_dir():
-        return profile_dir
-    return _DEFAULT_HERMES_HOME
+    if not _PROFILE_ID_RE.fullmatch(name):
+        return _DEFAULT_HERMES_HOME
+    return _resolve_named_profile_home(name)
+
+
+def get_active_hermes_home() -> Path:
+    """Return the HERMES_HOME path for the currently active profile.
+
+    Uses get_active_profile_name() so per-request TLS context (issue #798)
+    is respected, not just the process-level global.
+    """
+    return _resolve_profile_home_for_name(get_active_profile_name())
+
+
+
+# ── Cron-call profile isolation (issue: Scheduled jobs ignored active profile) ─
+# `cron.jobs` reads HERMES_HOME from os.environ (process-global) at function-
+# call time. That bypasses our per-request thread-local profile, so the
+# `/api/crons*` endpoints always returned the process-default profile's jobs.
+# This context manager swaps HERMES_HOME (and the cached module-level constants
+# in cron.jobs) for the duration of a cron call, serialized by a lock so
+# concurrent requests from different profiles don't race on the global env var.
+#
+# Thread-safety note on os.environ mutation:
+# CPython's os.environ assignment is GIL-protected at the bytecode level, but
+# multi-step read-modify-write sequences (snapshot prev → assign new → restore
+# on exit) are NOT atomic without explicit serialization. The _cron_env_lock
+# below makes the entire context-manager body run-to-completion serially, so
+# all webui access to HERMES_HOME goes through one thread at a time. Any
+# subprocess.Popen() call inside `run_job` inherits the env at fork time,
+# which is also under the lock — so child processes always see a consistent
+# (own-profile) HERMES_HOME, never a half-swapped state.
+_cron_env_lock = threading.Lock()
+
+
+def _cron_profile_context_depth() -> int:
+    return int(getattr(_tls, 'cron_profile_depth', 0) or 0)
+
+
+def _push_cron_profile_context_depth() -> None:
+    _tls.cron_profile_depth = _cron_profile_context_depth() + 1
+
+
+def _pop_cron_profile_context_depth() -> None:
+    depth = _cron_profile_context_depth()
+    _tls.cron_profile_depth = max(0, depth - 1)
+
+
+def _home_for_scheduled_cron_job(job: dict) -> Path:
+    """Resolve the profile home an auto-fired scheduler job should execute in.
+
+    Legacy jobs with no profile keep the scheduler's server-default profile.
+    Jobs pinned to a named profile execute under that profile's HERMES_HOME, so
+    an in-process WebUI scheduler thread does not leak process-global config or
+    .env into the agent run. If a profile was deleted after the job was saved,
+    fall back to the server default rather than crashing every scheduler tick.
+    """
+    raw = str((job or {}).get('profile') or '').strip()
+    if not raw:
+        return get_active_hermes_home()
+    if _is_root_profile(raw):
+        return _DEFAULT_HERMES_HOME
+    if not _PROFILE_ID_RE.fullmatch(raw):
+        logger.warning(
+            "Cron job %s has invalid profile %r; falling back to server default",
+            (job or {}).get('id', '?'), raw,
+        )
+        return get_active_hermes_home()
+    home = _resolve_named_profile_home(raw)
+    if not home.is_dir():
+        logger.warning(
+            "Cron job %s references missing profile %r; falling back to server default",
+            (job or {}).get('id', '?'), raw,
+        )
+        return get_active_hermes_home()
+    return home
+
+
+def install_cron_scheduler_profile_isolation() -> None:
+    """Patch cron.scheduler.run_job for WebUI in-process scheduler safety.
+
+    Standard WebUI deployments do not start the scheduler thread in-process, but
+    if a future/single-process deployment calls cron.scheduler.tick() from the
+    WebUI worker, tick's background job path has no request TLS context. Wrap
+    run_job so each auto-fired job's persisted ``profile`` field gets the same
+    HERMES_HOME isolation as the manual /api/crons/run path.
+    """
+    try:
+        import cron.scheduler as _cs
+    except ImportError:
+        logger.debug("install_cron_scheduler_profile_isolation: cron.scheduler unavailable")
+        return
+
+    original = getattr(_cs, 'run_job', None)
+    if original is None or getattr(original, '_webui_profile_isolated', False):
+        return
+
+    def _webui_profile_isolated_run_job(job, *args, **kwargs):
+        # Manual WebUI runs already enter cron_profile_context_for_home before
+        # calling run_job. Avoid nesting the non-reentrant env lock or changing
+        # the explicitly selected manual execution profile.
+        if _cron_profile_context_depth() > 0:
+            return original(job, *args, **kwargs)
+        with cron_profile_context_for_home(_home_for_scheduled_cron_job(job)):
+            return original(job, *args, **kwargs)
+
+    _webui_profile_isolated_run_job._webui_profile_isolated = True
+    _webui_profile_isolated_run_job._webui_original_run_job = original
+    _cs.run_job = _webui_profile_isolated_run_job
+
+
+class cron_profile_context_for_home:
+    """Context manager that pins HERMES_HOME to an explicit profile home path.
+
+    Use this variant from worker threads that don't have TLS context (e.g. the
+    background thread started by /api/crons/run). The HTTP-side variant below
+    resolves the home via TLS.
+    """
+
+    def __init__(self, home: Path):
+        self._home = Path(home)
+
+    def __enter__(self):
+        _cron_env_lock.acquire()
+        _push_cron_profile_context_depth()
+        try:
+            self._prev_env = os.environ.get('HERMES_HOME')
+            os.environ['HERMES_HOME'] = str(self._home)
+
+            # Re-patch cron.jobs module-level constants (see main context manager
+            # below for the rationale).
+            self._prev_cj = None
+            try:
+                import cron.jobs as _cj
+                self._prev_cj = (_cj.HERMES_DIR, _cj.CRON_DIR, _cj.JOBS_FILE, _cj.OUTPUT_DIR)
+                _cj.HERMES_DIR = self._home
+                _cj.CRON_DIR = self._home / 'cron'
+                _cj.JOBS_FILE = _cj.CRON_DIR / 'jobs.json'
+                _cj.OUTPUT_DIR = _cj.CRON_DIR / 'output'
+            except (ImportError, AttributeError):
+                logger.debug("cron_profile_context_for_home: cron.jobs unavailable")
+
+            # cron.scheduler snapshots _hermes_home at import time and run_job()
+            # reads config/.env from that module global. Patch it alongside
+            # cron.jobs so manual WebUI runs actually execute under the selected
+            # profile, not merely write output metadata there (#617).
+            self._prev_cs = None
+            try:
+                import cron.scheduler as _cs
+                self._prev_cs = (
+                    getattr(_cs, '_hermes_home', None),
+                    getattr(_cs, '_LOCK_DIR', None),
+                    getattr(_cs, '_LOCK_FILE', None),
+                )
+                _cs._hermes_home = self._home
+                _cs._LOCK_DIR = self._home / 'cron'
+                _cs._LOCK_FILE = _cs._LOCK_DIR / '.tick.lock'
+            except (ImportError, AttributeError):
+                logger.debug("cron_profile_context_for_home: cron.scheduler unavailable")
+        except Exception:
+            _pop_cron_profile_context_depth()
+            _cron_env_lock.release()
+            raise
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            if self._prev_env is None:
+                os.environ.pop('HERMES_HOME', None)
+            else:
+                os.environ['HERMES_HOME'] = self._prev_env
+            if self._prev_cj is not None:
+                try:
+                    import cron.jobs as _cj
+                    _cj.HERMES_DIR, _cj.CRON_DIR, _cj.JOBS_FILE, _cj.OUTPUT_DIR = self._prev_cj
+                except (ImportError, AttributeError):
+                    pass
+            if getattr(self, '_prev_cs', None) is not None:
+                try:
+                    import cron.scheduler as _cs
+                    _cs._hermes_home, _cs._LOCK_DIR, _cs._LOCK_FILE = self._prev_cs
+                except (ImportError, AttributeError):
+                    pass
+        finally:
+            _pop_cron_profile_context_depth()
+            _cron_env_lock.release()
+        return False
+
+
+class cron_profile_context:
+    """Context manager that pins HERMES_HOME to the TLS-active profile.
+
+    Usage:
+        with cron_profile_context():
+            from cron.jobs import list_jobs
+            jobs = list_jobs(include_disabled=True)
+
+    Serializes cron API calls across profiles (cron API is low-frequency;
+    serialization cost is negligible compared to correctness).
+    """
+
+    def __enter__(self):
+        _cron_env_lock.acquire()
+        _push_cron_profile_context_depth()
+        try:
+            self._prev_env = os.environ.get('HERMES_HOME')
+            home = get_active_hermes_home()
+            os.environ['HERMES_HOME'] = str(home)
+
+            # Re-patch cron.jobs module-level constants. They are snapshot at
+            # import time (line 68-71 of cron/jobs.py) and don't participate in
+            # the module's __getattr__ lazy path, so env-var alone is not enough
+            # for callers that reference the module constants directly.
+            self._prev_cj = None
+            try:
+                import cron.jobs as _cj
+                self._prev_cj = (_cj.HERMES_DIR, _cj.CRON_DIR, _cj.JOBS_FILE, _cj.OUTPUT_DIR)
+                _cj.HERMES_DIR = home
+                _cj.CRON_DIR = home / 'cron'
+                _cj.JOBS_FILE = _cj.CRON_DIR / 'jobs.json'
+                _cj.OUTPUT_DIR = _cj.CRON_DIR / 'output'
+            except (ImportError, AttributeError):
+                logger.debug("cron_profile_context: cron.jobs unavailable; env-var only")
+
+            self._prev_cs = None
+            try:
+                import cron.scheduler as _cs
+                self._prev_cs = (
+                    getattr(_cs, '_hermes_home', None),
+                    getattr(_cs, '_LOCK_DIR', None),
+                    getattr(_cs, '_LOCK_FILE', None),
+                )
+                _cs._hermes_home = home
+                _cs._LOCK_DIR = home / 'cron'
+                _cs._LOCK_FILE = _cs._LOCK_DIR / '.tick.lock'
+            except (ImportError, AttributeError):
+                logger.debug("cron_profile_context: cron.scheduler unavailable; env-var only")
+        except Exception:
+            _pop_cron_profile_context_depth()
+            _cron_env_lock.release()
+            raise
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            # Restore env var
+            if self._prev_env is None:
+                os.environ.pop('HERMES_HOME', None)
+            else:
+                os.environ['HERMES_HOME'] = self._prev_env
+
+            # Restore cron.jobs module constants
+            if self._prev_cj is not None:
+                try:
+                    import cron.jobs as _cj
+                    _cj.HERMES_DIR, _cj.CRON_DIR, _cj.JOBS_FILE, _cj.OUTPUT_DIR = self._prev_cj
+                except (ImportError, AttributeError):
+                    pass
+            if getattr(self, '_prev_cs', None) is not None:
+                try:
+                    import cron.scheduler as _cs
+                    _cs._hermes_home, _cs._LOCK_DIR, _cs._LOCK_FILE = self._prev_cs
+                except (ImportError, AttributeError):
+                    pass
+        finally:
+            _pop_cron_profile_context_depth()
+            _cron_env_lock.release()
+        return False
+
+
+def get_hermes_home_for_profile(name: str) -> Path:
+    """Return the HERMES_HOME Path for *name* without mutating any process state.
+
+    Safe to call from per-request context (streaming, session creation) because
+    it reads only the filesystem — it never touches os.environ, module-level
+    cached paths, or the process-level _active_profile global.
+
+    Falls back to _DEFAULT_HERMES_HOME (same as 'default') when *name* is None,
+    empty, 'default', or does not match the profile-name format (rejects path
+    traversal such as '../../etc').
+    """
+    return _resolve_profile_home_for_name(name)
+
+
+_TERMINAL_ENV_MAPPINGS = {
+    'backend': 'TERMINAL_ENV',
+    'env_type': 'TERMINAL_ENV',
+    'cwd': 'TERMINAL_CWD',
+    'timeout': 'TERMINAL_TIMEOUT',
+    'lifetime_seconds': 'TERMINAL_LIFETIME_SECONDS',
+    'modal_mode': 'TERMINAL_MODAL_MODE',
+    'docker_image': 'TERMINAL_DOCKER_IMAGE',
+    'docker_forward_env': 'TERMINAL_DOCKER_FORWARD_ENV',
+    'docker_env': 'TERMINAL_DOCKER_ENV',
+    'docker_mount_cwd_to_workspace': 'TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE',
+    'singularity_image': 'TERMINAL_SINGULARITY_IMAGE',
+    'modal_image': 'TERMINAL_MODAL_IMAGE',
+    'daytona_image': 'TERMINAL_DAYTONA_IMAGE',
+    'container_cpu': 'TERMINAL_CONTAINER_CPU',
+    'container_memory': 'TERMINAL_CONTAINER_MEMORY',
+    'container_disk': 'TERMINAL_CONTAINER_DISK',
+    'container_persistent': 'TERMINAL_CONTAINER_PERSISTENT',
+    'docker_volumes': 'TERMINAL_DOCKER_VOLUMES',
+    'persistent_shell': 'TERMINAL_PERSISTENT_SHELL',
+    'ssh_host': 'TERMINAL_SSH_HOST',
+    'ssh_user': 'TERMINAL_SSH_USER',
+    'ssh_port': 'TERMINAL_SSH_PORT',
+    'ssh_key': 'TERMINAL_SSH_KEY',
+    'ssh_persistent': 'TERMINAL_SSH_PERSISTENT',
+    'local_persistent': 'TERMINAL_LOCAL_PERSISTENT',
+}
+
+
+def _stringify_env_value(value) -> str:
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    if isinstance(value, (list, dict)):
+        return json.dumps(value)
+    return str(value)
+
+
+def get_profile_runtime_env(home: Path) -> dict[str, str]:
+    """Return env vars needed to run an agent turn for a profile home.
+
+    WebUI profile switching is per-client/cookie scoped, so it intentionally
+    does not call ``switch_profile(..., process_wide=True)`` for every browser.
+    Agent/tool code still consumes terminal backend settings through
+    environment variables (matching ``hermes -p <profile>``), so streaming must
+    apply the selected profile's terminal config and ``.env`` for the duration
+    of that run.
+    """
+    home = Path(home).expanduser()
+    env: dict[str, str] = {}
+
+    try:
+        import yaml as _yaml
+
+        cfg_path = home / 'config.yaml'
+        cfg = _yaml.safe_load(cfg_path.read_text(encoding='utf-8')) if cfg_path.exists() else {}
+        if not isinstance(cfg, dict):
+            cfg = {}
+    except Exception:
+        cfg = {}
+
+    terminal_cfg = cfg.get('terminal', {}) if isinstance(cfg, dict) else {}
+    if isinstance(terminal_cfg, dict):
+        for key, env_key in _TERMINAL_ENV_MAPPINGS.items():
+            if key in terminal_cfg and terminal_cfg[key] is not None:
+                env[env_key] = _stringify_env_value(terminal_cfg[key])
+
+    env_path = home / '.env'
+    if env_path.exists():
+        try:
+            for line in env_path.read_text(encoding='utf-8').splitlines():
+                line = line.strip()
+                if line and not line.startswith('#') and '=' in line:
+                    k, v = line.split('=', 1)
+                    k = k.strip()
+                    v = v.strip().strip('"').strip("'")
+                    if k and v:
+                        env[k] = v
+        except Exception:
+            logger.debug("Failed to read runtime env from %s", env_path)
+
+    return env
 
 
 def _set_hermes_home(home: Path):
@@ -122,6 +629,14 @@ def _set_hermes_home(home: Path):
     except (ImportError, AttributeError):
         logger.debug("Failed to patch cron.jobs module")
 
+    try:
+        import cron.scheduler as _cs
+        _cs._hermes_home = home
+        _cs._LOCK_DIR = home / 'cron'
+        _cs._LOCK_FILE = _cs._LOCK_DIR / '.tick.lock'
+    except (ImportError, AttributeError):
+        logger.debug("Failed to patch cron.scheduler module")
+
 
 def _reload_dotenv(home: Path):
     """Load .env from the profile dir into os.environ with profile isolation.
@@ -167,15 +682,22 @@ def init_profile_state() -> None:
     _active_profile = _read_active_profile_file()
     home = get_active_hermes_home()
     _set_hermes_home(home)
+    install_cron_scheduler_profile_isolation()
     _reload_dotenv(home)
 
 
-def switch_profile(name: str) -> dict:
+def switch_profile(name: str, *, process_wide: bool = True) -> dict:
     """Switch the active profile.
 
     Validates the profile exists, updates process state, patches module caches,
     reloads .env, and reloads config.yaml.
 
+    Args:
+        name: Profile name to switch to.
+        process_wide: If True (default), updates the process-global
+            _active_profile.  Set to False for per-client switches from the
+            WebUI where the profile is managed via cookie + thread-local (#798).
+
     Returns: {'profiles': [...], 'active': name}
     Raises ValueError if profile doesn't exist or agent is busy.
     """
@@ -184,16 +706,21 @@ def switch_profile(name: str) -> dict:
     # Import here to avoid circular import at module load
     from api.config import STREAMS, STREAMS_LOCK, reload_config
 
-    # Block if agent is running
-    with STREAMS_LOCK:
-        if len(STREAMS) > 0:
-            raise RuntimeError(
-                'Cannot switch profiles while an agent is running. '
-                'Cancel or wait for it to finish.'
-            )
+    # Process-wide profile switches mutate HERMES_HOME, module-level path caches,
+    # os.environ-backed .env keys, and the global config cache. Keep those blocked
+    # while any agent stream is active. Per-client WebUI switches are cookie/TLS
+    # scoped (process_wide=False) and do not mutate those globals, so users can
+    # leave a running session in one profile and start work in another (#1700).
+    if process_wide:
+        with STREAMS_LOCK:
+            if len(STREAMS) > 0:
+                raise RuntimeError(
+                    'Cannot switch profiles while an agent is running. '
+                    'Cancel or wait for it to finish.'
+                )
 
     # Resolve profile directory
-    if name == 'default':
+    if _is_root_profile(name):
         home = _DEFAULT_HERMES_HOME
     else:
         home = _resolve_named_profile_home(name)
@@ -201,24 +728,40 @@ def switch_profile(name: str) -> dict:
             raise ValueError(f"Profile '{name}' does not exist.")
 
     with _profile_lock:
-        _active_profile = name
-        _set_hermes_home(home)
-        _reload_dotenv(home)
+        if process_wide:
+            global _active_profile
+            _active_profile = name
+            _set_hermes_home(home)
+            _reload_dotenv(home)
 
-    # Write sticky default for CLI consistency
-    try:
-        ap_file = _DEFAULT_HERMES_HOME / 'active_profile'
-        ap_file.write_text(name if name != 'default' else '', encoding='utf-8')
-    except Exception:
-        logger.debug("Failed to write active profile file")
+    if process_wide:
+        # Write sticky default for CLI consistency
+        try:
+            ap_file = _DEFAULT_HERMES_HOME / 'active_profile'
+            ap_file.write_text('' if _is_root_profile(name) else name, encoding='utf-8')
+        except Exception:
+            logger.debug("Failed to write active profile file")
 
-    # Reload config.yaml from the new profile
-    reload_config()
+        # Reload config.yaml from the new profile
+        reload_config()
 
-    # Return profile-specific defaults so frontend can apply them
-    from api.workspace import get_last_workspace
-    from api.config import get_config
-    cfg = get_config()
+    # Return profile-specific defaults so frontend can apply them.
+    # For process_wide=False (per-client switch), read the target profile's
+    # config.yaml directly from disk rather than from _cfg_cache (process-global),
+    # since reload_config() was intentionally skipped.
+    if process_wide:
+        from api.config import get_config
+        cfg = get_config()
+    else:
+        # Direct disk read — does not touch _cfg_cache
+        try:
+            import yaml as _yaml
+            cfg_path = home / 'config.yaml'
+            cfg = _yaml.safe_load(cfg_path.read_text(encoding='utf-8')) if cfg_path.exists() else {}
+            if not isinstance(cfg, dict):
+                cfg = {}
+        except Exception:
+            cfg = {}
     model_cfg = cfg.get('model', {})
     default_model = None
     if isinstance(model_cfg, str):
@@ -226,11 +769,57 @@ def switch_profile(name: str) -> dict:
     elif isinstance(model_cfg, dict):
         default_model = model_cfg.get('default')
 
+    # Read the target profile's workspace directly from *home* rather than via
+    # get_last_workspace() which routes through the thread-local/process-global active
+    # profile — both of which still point to the OLD profile during process_wide=False
+    # switches (the Set-Cookie has been sent but hasn't been processed by a new request
+    # yet).  We derive workspace in priority order:
+    #   1. {home}/webui_state/last_workspace.txt  (previously chosen workspace for this profile)
+    #   2. cfg terminal.cwd / workspace / default_workspace keys
+    #   3. Boot-time DEFAULT_WORKSPACE constant
+    # Use the module-level ``Path`` (imported at line 17) rather than re-importing
+    # it locally — keeps the exception fallback simple and avoids a latent NameError
+    # if a future refactor moves the inner imports.
+    default_workspace = None
+    try:
+        from api.config import DEFAULT_WORKSPACE as _DW
+        lw_file = home / 'webui_state' / 'last_workspace.txt'
+        if lw_file.exists():
+            _p = lw_file.read_text(encoding='utf-8').strip()
+            if _p:
+                _pp = Path(_p).expanduser()
+                if _pp.is_dir():
+                    default_workspace = str(_pp.resolve())
+        if default_workspace is None:
+            for _key in ('workspace', 'default_workspace'):
+                _v = cfg.get(_key)
+                if _v:
+                    _pp = Path(str(_v)).expanduser().resolve()
+                    if _pp.is_dir():
+                        default_workspace = str(_pp)
+                        break
+        if default_workspace is None:
+            _tc = cfg.get('terminal', {})
+            if isinstance(_tc, dict):
+                _cwd = _tc.get('cwd', '')
+                if _cwd and str(_cwd) not in ('.', ''):
+                    _pp = Path(str(_cwd)).expanduser().resolve()
+                    if _pp.is_dir():
+                        default_workspace = str(_pp)
+        if default_workspace is None:
+            default_workspace = str(_DW)
+    except Exception:
+        try:
+            from api.config import DEFAULT_WORKSPACE as _DW2
+            default_workspace = str(_DW2)
+        except Exception:
+            default_workspace = str(Path.home())
+
     return {
         'profiles': list_profiles_api(),
         'active': name,
         'default_model': default_model,
-        'default_workspace': get_last_workspace(),
+        'default_workspace': default_workspace,
     }
 
 
@@ -243,7 +832,7 @@ def list_profiles_api() -> list:
         # hermes_cli not available -- return just the default
         return [_default_profile_dict()]
 
-    active = _active_profile
+    active = get_active_profile_name()
     result = []
     for p in infos:
         result.append({
@@ -319,7 +908,7 @@ def _create_profile_fallback(name: str, clone_from: str = None,
 
     # Clone config files from source profile if requested
     if clone_config and clone_from:
-        if clone_from == 'default':
+        if _is_root_profile(clone_from):
             source_dir = _DEFAULT_HERMES_HOME
         else:
             source_dir = _DEFAULT_HERMES_HOME / 'profiles' / clone_from
@@ -368,7 +957,7 @@ def create_profile_api(name: str, clone_from: str = None,
     _validate_profile_name(name)
     # Defense-in-depth: validate clone_from here too, even though routes.py
     # also validates it. Any caller that bypasses the HTTP layer gets protection.
-    if clone_from is not None and clone_from != 'default':
+    if clone_from is not None and not _is_root_profile(clone_from):
         _validate_profile_name(clone_from)
 
     try:
@@ -399,6 +988,10 @@ def create_profile_api(name: str, clone_from: str = None,
     profile_path.mkdir(parents=True, exist_ok=True)
     _write_endpoint_to_config(profile_path, base_url=base_url, api_key=api_key)
 
+    # Invalidate cached root-profile-name lookup; create_profile may have added
+    # a new profile that flips is_default semantics on the agent side (#1612).
+    _invalidate_root_profile_cache()
+
     # Find and return the newly created profile info.
     # When hermes_cli is not importable, list_profiles_api() also falls back
     # to the stub default-only list and won't find the new profile by name.
@@ -421,7 +1014,7 @@ def create_profile_api(name: str, clone_from: str = None,
 
 def delete_profile_api(name: str) -> dict:
     """Delete a profile. Switches to default first if it's the active one."""
-    if name == 'default':
+    if _is_root_profile(name):
         raise ValueError("Cannot delete the default profile.")
     _validate_profile_name(name)
 
@@ -447,4 +1040,6 @@ def delete_profile_api(name: str) -> dict:
         else:
             raise ValueError(f"Profile '{name}' does not exist.")
 
+    # Drop cached root-profile-name lookup — list_profiles_api() shape changed.
+    _invalidate_root_profile_cache()
     return {'ok': True, 'name': name}

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

@@ -9,12 +9,24 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-from api.config import LOCK
+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.
 
@@ -27,38 +39,47 @@ def retry_last(session_id: str) -> dict[str, Any]:
         KeyError: session not found
         ValueError: no user message in transcript
     """
-    # 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 outside
-    # the lock and is naturally last-write-wins on a consistent state.
-    #
-    # 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.')
+    # 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]
-    s.save()
+            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}
 
 
@@ -72,23 +93,32 @@ def undo_last(session_id: str) -> dict[str, Any]:
         KeyError: session not found
         ValueError: no user message in transcript
     """
-    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.')
+    # 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]
-    s.save()  # outside LOCK -- save() re-acquires LOCK via _write_session_index()
+            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,
@@ -105,16 +135,30 @@ def session_status(session_id: str) -> dict[str, Any]:
     (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,
     }
 
 

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

@@ -14,7 +14,25 @@ _SENSITIVE_FILES = (
 
 
 def fix_credential_permissions() -> None:
-    """Ensure sensitive files in HERMES_HOME are chmod 600 (owner-only)."""
+    """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
@@ -24,9 +42,15 @@ def fix_credential_permissions() -> None:
             continue
         try:
             current = stat.S_IMODE(fpath.stat().st_mode)
-            if current & 0o077:  # group or other bits set
-                fpath.chmod(0o600)
-                print(f'  [security] fixed permissions on {fpath.name} ({oct(current)} -> 0600)', flush=True)
+            # 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
 
@@ -41,11 +65,41 @@ def _agent_dir() -> Path | None:
             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():

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

@@ -13,7 +13,7 @@ import threading
 import time
 from pathlib import Path
 
-from api.config import REPO_ROOT
+from api.config import REPO_ROOT, STREAMS, STREAMS_LOCK
 
 # Lazy -- may be None if agent not found
 try:
@@ -28,6 +28,32 @@ _apply_lock = threading.Lock()   # prevents concurrent stash/pull/pop on same re
 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).
 
@@ -53,6 +79,96 @@ def _run_git(args, cwd, timeout=10):
         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').
 
@@ -104,16 +220,48 @@ def _check_repo(path, name):
     out, ok = _run_git(['rev-list', '--count', f'HEAD..{compare_ref}'], path)
     behind = int(out) if ok and out.isdigit() else 0
 
-    # Get short SHAs for display
-    current, _ = _run_git(['rev-parse', '--short', 'HEAD'], path)
+    # 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,
     }
 
 
@@ -141,8 +289,121 @@ def check_for_updates(force=False):
         _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:
@@ -193,7 +454,16 @@ def _apply_update_inner(target):
     # 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': 'Repository has unresolved merge conflicts'}
+        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)
@@ -254,4 +524,22 @@ def _apply_update_inner(target):
     with _cache_lock:
         _update_cache['checked_at'] = 0
 
-    return {'ok': True, 'message': f'{target} updated successfully', 'target': target}
+    # 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,6 +1,7 @@
 """
 Hermes Web UI -- File upload: multipart parser and upload handler.
 """
+import mimetypes
 import re as _re
 import email.parser
 import tempfile
@@ -80,7 +81,14 @@ def handle_upload(handler):
         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})
+        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:
@@ -88,6 +96,151 @@ def handle_upload(handler):
         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

api/workspace.py

@@ -10,7 +10,9 @@ 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__)
@@ -91,7 +93,8 @@ def _profile_default_workspace() -> str:
 
 def _clean_workspace_list(workspaces: list) -> list:
     """Sanitize a workspace list:
-    - Remove entries whose paths no longer exist on disk.
+    - 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
@@ -103,10 +106,9 @@ def _clean_workspace_list(workspaces: list) -> list:
     for w in workspaces:
         path = w.get('path', '')
         name = w.get('name', '')
-        p = Path(path).resolve() if path else Path('/')
-        # Skip paths that no longer exist
-        if not p.is_dir():
+        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/).
@@ -129,6 +131,32 @@ def _clean_workspace_list(workspaces: list) -> list:
     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.
 
@@ -219,6 +247,277 @@ def set_last_workspace(path: str) -> None:
         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.
 
@@ -240,39 +539,28 @@ def resolve_trusted_workspace(path: str | Path | None = None) -> Path:
     None/empty path falls back to the boot-time DEFAULT_WORKSPACE, which is always
     trusted (it was validated at server startup).
     """
-    _BLOCKED_SYSTEM_ROOTS = {
-        # Linux / macOS
-        Path('/etc'), Path('/usr'), Path('/var'), Path('/bin'), Path('/sbin'),
-        Path('/boot'), Path('/proc'), Path('/sys'), Path('/dev'),
-        Path('/lib'), Path('/lib64'), Path('/opt/homebrew'),
-    }
-
     if path in (None, ""):
         return Path(_BOOT_DEFAULT_WORKSPACE).expanduser().resolve()
 
     candidate = Path(path).expanduser().resolve()
 
-    if not candidate.exists():
-        raise ValueError(f"Path does not exist: {candidate}")
-    if not candidate.is_dir():
-        raise ValueError(f"Path is not a directory: {candidate}")
-
-    # Block known system roots and their children
-    for blocked in _BLOCKED_SYSTEM_ROOTS:
-        try:
-            candidate.relative_to(blocked)
-            raise ValueError(f"Path points to a system directory: {candidate}")
-        except ValueError as e:
-            if "system directory" in str(e):
-                raise
-            # relative_to raised ValueError = candidate is NOT under blocked = safe
+    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()
-    try:
-        candidate.relative_to(Path.home().resolve())
-        return candidate
-    except ValueError:
-        pass
+    # 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:
@@ -302,10 +590,89 @@ def resolve_trusted_workspace(path: str | Path | None = None) -> Path:
     )
 
 
+
+
+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
 
 
@@ -313,14 +680,60 @@ 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
@@ -358,22 +771,35 @@ def git_info_for_workspace(workspace: Path) -> dict:
     branch = _run_git(['rev-parse', '--abbrev-ref', 'HEAD'], workspace)
     if branch is None:
         return None
-    # Status counts
-    status_out = _run_git(['status', '--porcelain'], workspace) or ''
-    lines = [l for l in status_out.splitlines() if l]
-    # git status --porcelain: XY format where X=index, Y=worktree
-    modified = sum(1 for l in lines if len(l) >= 2 and (l[0] in 'MAR' or l[1] in 'MAR'))
-    untracked = sum(1 for l in lines if l.startswith('??'))
-    dirty = len(lines)
-    # Ahead/behind
-    ahead = _run_git(['rev-list', '--count', '@{u}..HEAD'], workspace)
-    behind = _run_git(['rev-list', '--count', 'HEAD..@{u}'], workspace)
+    # Run the remaining git commands in parallel via threads — they are
+    # independent subprocess calls and together can take 50-200ms when run
+    # serially.  Threading is safe here because each call blocks only on the
+    # subprocess pipe, not on the GIL.
+    def _ahead():
+        r = _run_git(['rev-list', '--count', '@{u}..HEAD'], workspace)
+        return int(r) if r and r.isdigit() else 0
+    def _behind():
+        r = _run_git(['rev-list', '--count', 'HEAD..@{u}'], workspace)
+        return int(r) if r and r.isdigit() else 0
+    def _status():
+        out = _run_git(['status', '--porcelain'], workspace) or ''
+        lines = [l for l in out.splitlines() if l]
+        modified = sum(1 for l in lines if len(l) >= 2 and (l[0] in 'MAR' or l[1] in 'MAR'))
+        untracked = sum(1 for l in lines if l.startswith('??'))
+        return len(lines), modified, untracked
+    with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
+        f_status = pool.submit(_status)
+        f_ahead  = pool.submit(_ahead)
+        f_behind = pool.submit(_behind)
+        dirty, modified, untracked = f_status.result()
+        ahead  = f_ahead.result()
+        behind = f_behind.result()
     return {
         'branch': branch,
         'dirty': dirty,
         'modified': modified,
         'untracked': untracked,
-        'ahead': int(ahead) if ahead and ahead.isdigit() else 0,
-        'behind': int(behind) if behind and behind.isdigit() else 0,
+        'ahead': ahead,
+        'behind': behind,
         'is_git': True,
     }

bootstrap.py

@@ -19,6 +19,50 @@ 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
@@ -46,6 +90,47 @@ def ensure_supported_platform() -> None:
         )
 
 
+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 = [
@@ -61,7 +146,7 @@ def discover_agent_dir() -> Path | None:
         candidate = Path(raw).expanduser().resolve()
         if candidate.exists() and (candidate / "run_agent.py").exists():
             return candidate
-    return None
+    return _agent_dir_from_hermes_cli()
 
 
 def discover_launcher_python(agent_dir: Path | None) -> str:
@@ -69,7 +154,7 @@ def discover_launcher_python(agent_dir: Path | None) -> str:
     if env_python:
         return env_python
     if agent_dir:
-        for rel in ("venv/bin/python", "venv/Scripts/python.exe"):
+        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)
@@ -80,22 +165,71 @@ def discover_launcher_python(agent_dir: Path | None) -> str:
     return shutil.which("python3") or shutil.which("python") or sys.executable
 
 
-def ensure_python_has_webui_deps(python_exe: str) -> str:
+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", "import yaml"],
+        [python_exe, "-c", script],
         capture_output=True,
         text=True,
+        env=env,
     )
-    if check.returncode == 0:
+    return check.returncode == 0
+
+
+def ensure_python_has_webui_deps(python_exe: str, agent_dir: Path | None = None) -> str:
+    """Return a Python executable that can run both WebUI and Hermes Agent.
+
+    The WebUI can be launched directly with its local .venv. That venv has the
+    WebUI dependencies (for example PyYAML), but may not have Hermes Agent on its
+    import path. In that case the server starts healthy, then chat fails later
+    with "AIAgent not available". Prefer the agent venv when it is usable, and
+    validate the final interpreter before starting the server.
+    """
+    if _python_can_run_webui_and_agent(python_exe, agent_dir):
         return python_exe
 
+    agent_candidates: list[Path] = []
+    if agent_dir:
+        for rel in (
+            "venv/bin/python",
+            "venv/Scripts/python.exe",
+            ".venv/bin/python",
+            ".venv/Scripts/python.exe",
+        ):
+            agent_candidates.append(agent_dir / rel)
+        for candidate in agent_candidates:
+            if str(candidate) != python_exe and candidate.exists():
+                if _python_can_run_webui_and_agent(str(candidate), agent_dir):
+                    return str(candidate)
+
     venv_dir = REPO_ROOT / ".venv"
     venv_python = venv_dir / (
         "Scripts/python.exe" if platform.system() == "Windows" else "bin/python"
     )
     if not venv_python.exists():
         info(f"Creating local virtualenv at {venv_dir}")
-        venv.EnvBuilder(with_pip=True).create(venv_dir)
+        # 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(
@@ -114,7 +248,13 @@ def ensure_python_has_webui_deps(python_exe: str) -> str:
         ],
         check=True,
     )
-    return str(venv_python)
+    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:
@@ -164,9 +304,83 @@ def parse_args() -> argparse.Namespace:
         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()
@@ -180,26 +394,64 @@ def main() -> int:
         install_hermes_agent()
         agent_dir = discover_agent_dir()
 
-    python_exe = ensure_python_has_webui_deps(discover_launcher_python(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)
-    log_path = state_dir / f"bootstrap-{args.port}.log"
 
-    env = os.environ.copy()
-    env["HERMES_WEBUI_HOST"] = args.host
-    env["HERMES_WEBUI_PORT"] = str(args.port)
-    env.setdefault("HERMES_WEBUI_STATE_DIR", str(state_dir))
+    # 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:
-        env["HERMES_WEBUI_AGENT_DIR"] = str(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, str(REPO_ROOT / "server.py")],
-            cwd=str(agent_dir or REPO_ROOT),
-            env=env,
+            [python_exe, server_path],
+            cwd=server_cwd,
+            env=os.environ.copy(),
             stdout=log_file,
             stderr=subprocess.STDOUT,
             start_new_session=True,

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 [[ -v ${key} ]]; 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[@]}"
+  ) >> "${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

@@ -1,18 +1,37 @@
 # 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.
 #
-# Usage:
-#   docker compose -f docker-compose.three-container.yml up -d
-#
 # Services:
-#   hermes-agent   — gateway API on port 8642 (CLI, Telegram, cron, tools)
+#   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
+#   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:
@@ -23,13 +42,24 @@ services:
       - "127.0.0.1:8642:8642"
     volumes:
       # Persist config, state, sessions, skills, memory across restarts
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
       # Expose agent source so the WebUI can install dependencies from it
       - hermes-agent-src:/opt/hermes
     environment:
-      - HERMES_HOME=/root/.hermes
-      - HERMES_UID=${HERMES_UID:-10000}
-      - HERMES_GID=${HERMES_GID:-10000}
+      - 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:
@@ -46,11 +76,13 @@ services:
     ports:
       - "127.0.0.1:9119:9119"
     volumes:
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
     environment:
-      - HERMES_HOME=/root/.hermes
-      - HERMES_UID=${HERMES_UID:-10000}
-      - HERMES_GID=${HERMES_GID:-10000}
+      - 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:
@@ -102,6 +134,13 @@ services:
       # 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

docker-compose.two-container.yml

@@ -1,15 +1,49 @@
 # Two-container Docker Compose: Hermes Agent + Hermes WebUI
 #
-# This runs the agent and web UI in separate containers connected via
-# shared volumes. The WebUI installs the agent's Python dependencies
-# at startup from the shared agent source volume.
-#
-# Usage:
+# QUICK START:
 #   docker compose -f docker-compose.two-container.yml up -d
+#   Open http://localhost:8787
 #
-# The agent container runs the gateway (CLI, Telegram, cron, etc.).
-# The WebUI container serves the browser interface on port 8787.
-# Both share ~/.hermes for config, sessions, and state.
+# 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:
@@ -23,11 +57,25 @@ services:
       - "127.0.0.1:8642:8642"
     volumes:
       # Persist config, state, sessions, skills, memory across restarts
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
       # Expose agent source so the WebUI can install dependencies from it
       - hermes-agent-src:/opt/hermes
     environment:
-      - HERMES_HOME=/root/.hermes
+      - 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
@@ -64,7 +112,14 @@ services:
       - WANTED_UID=${UID:-1000}
       - WANTED_GID=${GID:-1000}
       # Optional: set a password for remote access
-      # - HERMES_WEBUI_PASSWORD=***
+      # - 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

docker-compose.yml

@@ -1,4 +1,15 @@
-version: "3.8"
+# Hermes WebUI — single-container Docker Compose
+#
+# QUICK START (most users):
+#   1. (Optional) Copy .env.docker.example to .env and edit values
+#   2. docker compose up -d
+#   3. Open http://localhost:8787
+#
+# This is the simplest setup: one WebUI container that runs the agent in-process.
+# The WebUI auto-detects host UID/GID from the mounted .hermes volume.
+#
+# For multi-container setups (separate agent + webui or agent+webui+dashboard),
+# see docker-compose.two-container.yml or docker-compose.three-container.yml.
 
 services:
   hermes-webui:
@@ -33,5 +44,14 @@ services:
 #      - 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

@@ -36,25 +36,25 @@ script_fullname=$0
 echo "  - script_fullname: ${script_fullname}"
 ignore_value="VALUE_TO_IGNORE"
 
-# everyone can read our files by default
-umask 0022
+# Keep init scratch files private to the container user that owns them.
+umask 0077
 
-# Write a world-writeable file (preferably inside /tmp -- ie within the container)
-write_worldtmpfile() {
+write_privtmpfile() {
   tmpfile=$1
-  if [ -z "${tmpfile}" ]; then error_exit "write_worldfile: missing argument"; fi
-  if [ -f $tmpfile ]; then rm -f $tmpfile; fi
-  echo -n $2 > ${tmpfile}
-  chmod 777 ${tmpfile}
+  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 $itdir; chmod 777 $itdir; fi
-if [ ! -d $itdir ]; then error_exit "Failed to create $itdir"; fi
+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 hermeswebuitoo to hermeswebuitoo transition (those values are the only ones loaded before the environment variables dump file are loaded)
+# 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
@@ -88,7 +88,7 @@ if [ -z "${WANTED_UID+x}" ] || [ "${WANTED_UID}" = "1024" ]; then
   fi
 fi
 WANTED_UID=${WANTED_UID:-1024}
-write_worldtmpfile $it "$WANTED_UID"
+write_privtmpfile $it "$WANTED_UID"
 echo "-- WANTED_UID: \"${WANTED_UID}\""
 
 it=$itdir/hermeswebui_user_gid
@@ -120,7 +120,7 @@ if [ -z "${WANTED_GID+x}" ] || [ "${WANTED_GID}" = "1024" ]; then
   fi
 fi
 WANTED_GID=${WANTED_GID:-1024}
-write_worldtmpfile $it "$WANTED_GID"
+write_privtmpfile $it "$WANTED_GID"
 echo "-- WANTED_GID: \"${WANTED_GID}\""
 
 echo "== Most Environment variables set"
@@ -180,27 +180,65 @@ load_env() {
   fi
 }
 
-# hermeswebuitoo is a specfiic user not existing by default on ubuntu, we can check its whomai
-if [ "A${whoami}" == "Ahermeswebuitoo" ]; then 
-  echo "-- Running as hermeswebuitoo, will switch hermeswebui to the desired UID/GID"
-  # The script is started as hermeswebuitoo -- UID/GID 1025/1025
+# 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 create hermeswebui user, knowing it is not already in use
+  # 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"
-  sudo groupmod -o -g ${WANTED_GID} hermeswebui || error_exit "Failed to set GID of hermeswebui user"
-  sudo usermod -o -u ${WANTED_UID} hermeswebui || error_exit "Failed to set UID of hermeswebui user"
-  sudo chown -R ${WANTED_UID}:${WANTED_GID} /home/hermeswebui || error_exit "Failed to set owner of /home/hermeswebui"
-  save_env /tmp/hermeswebuitoo_env.txt  
+  # 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}"
-  sudo su hermeswebui $script_fullname || error_exit "subscript failed"
-  ok_exit "Clean exit"
+  exec su -s /bin/bash -c "exec \"${script_fullname}\"" hermeswebui || error_exit "subscript failed"
 fi
 
-# If we are here, the script is started as another user than hermeswebuitoo
-# because the whoami value for the hermeswebui user can be any existing user, we can not check against it
-# instead we check if the UID/GID are the expected ones
+# If 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
 
@@ -209,18 +247,16 @@ if [ "$WANTED_UID" != "$new_uid" ]; then error_exit "hermeswebui MUST be running
 # We are therefore running as hermeswebui
 echo ""; echo "== Running as hermeswebui"
 
-# Load environment variables one by one if they do not exist from /tmp/hermeswebuitoo_env.txt
-it=/tmp/hermeswebuitoo_env.txt
-if [ -f $it ]; then
-  echo "-- Loading not already set environment variables from $it"
-  load_env $it true
+# 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 "-- Making sure /app is owned by the hermeswebui user to avoid permission issues when running the server "
-sudo mkdir -p /app || error_exit "Failed to create /app directory"
-sudo chown hermeswebui:hermeswebui /app || error_exit "Failed to set owner of /app to hermeswebui user"
-sudo rsync -av --chown=hermeswebui:hermeswebui /apptoo/ /app/ || error_exit "Failed to sync /apptoo to /app with correct ownership"
+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"
 
@@ -239,19 +275,18 @@ rm -f $it || error_exit "Failed to delete test file in $HERMES_WEBUI_STATE_DIR"
 echo ""; echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE: Default workspace directory shown on first launch"
 if [ -z "${HERMES_WEBUI_DEFAULT_WORKSPACE+x}" ]; then echo "HERMES_WEBUI_DEFAULT_WORKSPACE not set, setting to /workspace"; export HERMES_WEBUI_DEFAULT_WORKSPACE="/workspace"; fi;
 echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE: $HERMES_WEBUI_DEFAULT_WORKSPACE"
-# Use sudo for mkdir — Docker may auto-create bind-mount directories as root (#357).
-# Skip mkdir if the directory already exists (e.g. a read-only mount — #670).
+# 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
-  sudo mkdir -p "$HERMES_WEBUI_DEFAULT_WORKSPACE" || error_exit "Failed to create default workspace at $HERMES_WEBUI_DEFAULT_WORKSPACE"
+  mkdir -p "$HERMES_WEBUI_DEFAULT_WORKSPACE" || error_exit "Failed to create default workspace at $HERMES_WEBUI_DEFAULT_WORKSPACE"
 fi
 if [ ! -d "$HERMES_WEBUI_DEFAULT_WORKSPACE" ]; then error_exit "HERMES_WEBUI_DEFAULT_WORKSPACE directory does not exist at $HERMES_WEBUI_DEFAULT_WORKSPACE"; fi
-# Only chown and write-test if the workspace is writable. Read-only bind-mounts
-# (:ro) are valid — the workspace is used for browsing, not writing by the server.
+# 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
-  sudo chown hermeswebui:hermeswebui "$HERMES_WEBUI_DEFAULT_WORKSPACE" || echo "!! WARNING: Could not chown $HERMES_WEBUI_DEFAULT_WORKSPACE (continuing)"
   it="$HERMES_WEBUI_DEFAULT_WORKSPACE/.testfile"; touch $it && rm -f $it || echo "!! WARNING: Could not write to $HERMES_WEBUI_DEFAULT_WORKSPACE (continuing)"
 else
-  echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE is read-only — skipping chown/write check (read-only workspace is supported)"
+  echo "-- HERMES_WEBUI_DEFAULT_WORKSPACE is read-only — skipping write check (read-only workspace is supported)"
 fi
 
 echo ""; echo "==================="
@@ -266,9 +301,9 @@ else
 fi
 export UV_PROJECT_ENVIRONMENT=venv
 
-export UV_CACHE_DIR=/uv_cache
-sudo mkdir -p ${UV_CACHE_DIR} || error_exit "Failed to create /uv_cache directory"
-sudo chown hermeswebui:hermeswebui ${UV_CACHE_DIR} || error_exit "Failed to set owner of ${UV_CACHE_DIR} to hermeswebui user"
+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
@@ -285,6 +320,19 @@ 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
@@ -294,20 +342,37 @@ else
   test -x /app/venv/bin/pip
 
   echo ""; echo "== Adding hermes-agent's pyproject.toml base dependencies to the virtual environment"
-  if [ -d "/home/hermeswebui/.hermes/hermes-agent" ] && [ -f "/home/hermeswebui/.hermes/hermes-agent/pyproject.toml" ]; then
-    uv pip install "/home/hermeswebui/.hermes/hermes-agent[honcho]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
+  _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 at /home/hermeswebui/.hermes/hermes-agent"
+    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. See:"
+    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"
 

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."
+  }
+}

docs/pr-media/1807/providers-api-openai-codex.json

@@ -0,0 +1,35 @@
+{
+  "id": "openai-codex",
+  "display_name": "OpenAI Codex",
+  "has_key": true,
+  "configurable": false,
+  "is_oauth": true,
+  "key_source": "oauth",
+  "models": [
+    {
+      "id": "gpt-5.5",
+      "label": "GPT 5.5"
+    },
+    {
+      "id": "gpt-5.4",
+      "label": "GPT 5.4"
+    },
+    {
+      "id": "gpt-5.4-mini",
+      "label": "GPT 5.4 Mini"
+    },
+    {
+      "id": "gpt-5.3-codex",
+      "label": "GPT 5.3 Codex"
+    },
+    {
+      "id": "gpt-5.2",
+      "label": "GPT 5.2"
+    },
+    {
+      "id": "gpt-5.3-codex-spark",
+      "label": "GPT 5.3 Codex Spark"
+    }
+  ],
+  "models_total": 6
+}