Merge pull request #2866 from nesquena/release/stage-batch11

Release DA — v0.51.129 (stage-batch11, 4-PR feature + perf: HTTP/1.1 keep-alive + Aux Models card + PWA startup polish + runtime adapter harness)

.env.example

@@ -15,12 +15,15 @@
 # Port to listen on (default: 8787)
 # HERMES_WEBUI_PORT=8787
 
-# Where to store sessions, workspaces, and other state (default: ~/.hermes/webui-mvp)
+# Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)
 # HERMES_WEBUI_STATE_DIR=~/.hermes/webui
 
 # Default workspace directory shown on first launch
 # HERMES_WEBUI_DEFAULT_WORKSPACE=~/workspace
 
+# Optional model override. Leave unset to use the active Hermes provider default.
+# HERMES_WEBUI_DEFAULT_MODEL=
+
 # Base directory for all Hermes state (affects all paths above if set)
 # HERMES_HOME=~/.hermes
 

.github/workflows/docker-smoke.yml

@@ -0,0 +1,208 @@
+name: Docker smoke
+
+# Runtime smoke gate for Docker init logic.
+#
+# Background: v0.51.84 (PR #2470) shipped a startup-killing :ro mount + chown
+# interaction (EROFS under `set -e`) that 9 source-level pytest invariants +
+# 5800+ existing tests all passed. The independent reviewer caught it by eye.
+# This workflow closes that class of gap by actually `docker compose up`-ing
+# each variant against a real Docker daemon on the GHA runner.
+#
+# Scope (intentionally small for v1):
+#   - 3 compose variants (single, two-container, three-container)
+#   - For multi-container variants, rebuild the local Dockerfile and re-tag
+#     it as ghcr.io/nesquena/hermes-webui:latest BEFORE `up` so the PR's
+#     changes to docker_init.bash / Dockerfile actually execute. Without this
+#     the multi-container variants would pull the previous release from GHCR
+#     and silently miss every PR-level regression.
+#   - Pre-flight `docker compose config` job to catch schema/interpolation drift.
+#   - Reaper before each smoke run + trap on EXIT for orphan defence.
+#
+# Out of scope for v1 (per design review):
+#   - HERMES_WEBUI_SMOKE_TEST env flag in docker_init.bash (production-code footgun)
+#   - --user 60000:60000 (skips the chown branch we're protecting against)
+#   - Hadolint / yamllint (separate lint workflow, follow-up PR)
+#   - Local-runnable scripts/docker-smoke-test.sh (ship CI first, then iterate)
+#   - Podman runtime smoke (defer until a podman-specific bug ships)
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - 'Dockerfile'
+      - 'docker_init.bash'
+      - 'docker-compose*.yml'
+      - '.dockerignore'
+      - '.env.docker.example'
+      - '.github/workflows/docker-smoke.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'Dockerfile'
+      - 'docker_init.bash'
+      - 'docker-compose*.yml'
+      - '.dockerignore'
+      - '.env.docker.example'
+      - '.github/workflows/docker-smoke.yml'
+  workflow_dispatch:
+
+# Fork PRs run with no secrets — that's the right model. Pin to least privilege.
+permissions:
+  contents: read
+
+jobs:
+  compose-config:
+    name: Compose config validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate every compose file parses
+        run: |
+          set -euo pipefail
+          for f in docker-compose.yml docker-compose.two-container.yml docker-compose.three-container.yml; do
+            echo "::group::compose config: $f"
+            docker compose -f "$f" config > /dev/null
+            echo "::endgroup::"
+          done
+
+  smoke:
+    name: Smoke ${{ matrix.variant }}
+    runs-on: ubuntu-latest
+    needs: compose-config
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        variant:
+          - single
+          - two-container
+          - three-container
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve compose file + project name
+        id: vars
+        run: |
+          set -euo pipefail
+          case "${{ matrix.variant }}" in
+            single)
+              echo "compose_file=docker-compose.yml" >> "$GITHUB_OUTPUT"
+              ;;
+            two-container)
+              echo "compose_file=docker-compose.two-container.yml" >> "$GITHUB_OUTPUT"
+              ;;
+            three-container)
+              echo "compose_file=docker-compose.three-container.yml" >> "$GITHUB_OUTPUT"
+              ;;
+          esac
+          # Per-run project name so concurrent jobs / reruns can't clobber each other.
+          echo "project=hermes-smoke-${{ matrix.variant }}-${{ github.run_id }}-${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"
+
+      - name: Reap any prior hermes-smoke resources on this runner
+        run: |
+          set -euo pipefail
+          # Hosted GHA runners are fresh, so this is mostly defence-in-depth for
+          # self-hosted runner re-use. We rely primarily on the unique per-run
+          # project name + `compose down -v --remove-orphans` in the EXIT trap
+          # to clean up the resources THIS run creates; this step only sweeps
+          # leftovers from prior runs that crashed before their trap fired.
+          # Match by project-name prefix instead of labels (the compose files
+          # don't carry hermes-smoke labels on their resources).
+          for c in $(docker ps -aq --filter "name=hermes-smoke-"); do
+            docker rm -f "$c" || true
+          done
+          for v in $(docker volume ls -q | grep "^hermes-smoke-" || true); do
+            docker volume rm -f "$v" || true
+          done
+          for n in $(docker network ls --format '{{.Name}}' | grep "^hermes-smoke-" || true); do
+            docker network rm "$n" || true
+          done
+
+      - name: Build local Dockerfile
+        # We always build the local Dockerfile so the PR's changes are tested,
+        # even on the multi-container variants whose compose files reference
+        # ghcr.io/nesquena/hermes-webui:latest. Without this retag, multi-container
+        # smoke runs would test the previous release, not the PR.
+        run: |
+          set -euo pipefail
+          docker build -t ghcr.io/nesquena/hermes-webui:latest .
+
+      - name: Prepare ephemeral host paths
+        id: paths
+        run: |
+          set -euo pipefail
+          STATE_DIR="$(mktemp -d -t hermes-smoke-state-XXXXXX)"
+          WORK_DIR="$(mktemp -d -t hermes-smoke-work-XXXXXX)"
+          echo "state_dir=$STATE_DIR" >> "$GITHUB_OUTPUT"
+          echo "work_dir=$WORK_DIR" >> "$GITHUB_OUTPUT"
+          echo "Allocated:"
+          echo "  HERMES_HOME      = $STATE_DIR"
+          echo "  HERMES_WORKSPACE = $WORK_DIR"
+
+      - name: Smoke (up + health + log scan + down)
+        env:
+          COMPOSE_FILE: ${{ steps.vars.outputs.compose_file }}
+          PROJECT: ${{ steps.vars.outputs.project }}
+          HERMES_HOME: ${{ steps.paths.outputs.state_dir }}
+          HERMES_WORKSPACE: ${{ steps.paths.outputs.work_dir }}
+        run: |
+          set -euo pipefail
+
+          # ----- Trap-guaranteed cleanup, regardless of exit reason -----
+          cleanup() {
+            local rc=$?
+            echo "::group::Cleanup (rc=$rc)"
+            docker compose -p "$PROJECT" -f "$COMPOSE_FILE" logs --no-color --tail=200 || true
+            docker compose -p "$PROJECT" -f "$COMPOSE_FILE" down -v --remove-orphans || true
+            rm -rf "$HERMES_HOME" "$HERMES_WORKSPACE" || true
+            echo "::endgroup::"
+            return $rc
+          }
+          trap cleanup EXIT
+
+          echo "::group::docker compose up"
+          # --wait blocks until all services report healthy OR --wait-timeout fires.
+          # Compose v2 returns nonzero on either failure mode.
+          docker compose -p "$PROJECT" -f "$COMPOSE_FILE" up -d --wait --wait-timeout 120
+          echo "::endgroup::"
+
+          echo "::group::container roster"
+          docker compose -p "$PROJECT" -f "$COMPOSE_FILE" ps
+          echo "::endgroup::"
+
+          # ----- WebUI /health probe -----
+          # Single-container: WebUI is on the host on 127.0.0.1:8787.
+          # Two/three-container: same — both compose files publish 127.0.0.1:8787.
+          echo "::group::Probe /health"
+          attempts=0
+          max_attempts=30
+          until curl --fail --silent --max-time 5 http://127.0.0.1:8787/health > /dev/null; do
+            attempts=$((attempts + 1))
+            if [ "$attempts" -ge "$max_attempts" ]; then
+              echo "❌ WebUI /health never returned 200 after $max_attempts attempts (~60s)"
+              exit 1
+            fi
+            sleep 2
+          done
+          echo "✅ /health = 200 after $attempts attempts"
+          echo "::endgroup::"
+
+          # ----- Startup log scan: must not contain any known-bad signatures -----
+          # These are the exact patterns that would have flagged #2470 in real time.
+          # The grep -i is anchored to actual error tokens; benign log lines that
+          # contain the substring 'error' in a stack-friendly context (e.g.
+          # "errorless", URL paths) are improbable for these specific tokens.
+          echo "::group::Startup log scan"
+          LOGS="$(docker compose -p "$PROJECT" -f "$COMPOSE_FILE" logs --no-color)"
+          # `!! ERROR` + `!! Exiting script` are the actual strings emitted by
+          # docker_init.bash's error_exit() helper — the function name itself
+          # never appears in output. The literal token `error_exit` is kept as
+          # a belt-and-suspenders catch for any stray debug/echo of the name.
+          BAD_PATTERNS='EROFS|Read-only file system|Traceback|PermissionError|!! ERROR|!! Exiting script|error_exit|groupmod: cannot|usermod: cannot|Failed to set (UID|GID|owner|permissions|ownership)'
+          if echo "$LOGS" | grep -E -i "$BAD_PATTERNS"; then
+            echo "❌ Startup logs contain known-bad pattern (see above)"
+            exit 1
+          fi
+          echo "✅ No known-bad patterns in startup logs"
+          echo "::endgroup::"

.github/workflows/native-windows-startup.yml

@@ -0,0 +1,132 @@
+name: Native Windows startup
+
+# Runs on PRs that touch start.ps1 (or this workflow). Validates the
+# native-Windows launch script catches the bug classes the recent
+# Windows-only batch caught manually (#2805 WOW64 ProgramFiles redirect,
+# #2806 venv-portability claim, #2807 port-parse + finally-cleanup).
+#
+# Scope (per nesquena-hermes comment on #2811 — option 1, mock-only):
+# hermes-agent is not published to PyPI, so we cannot pip-install it on
+# the runner. Instead we stub a hermes_cli/ directory next to a sibling
+# hermes-agent/ folder — just enough for start.ps1's existence guard to
+# pass. The workflow then runs start.ps1 for a few seconds and asserts
+# that none of start.ps1's own Write-Error guards fired. Server-boot
+# regressions remain covered by the Linux jobs and docker-smoke.yml.
+
+on:
+  pull_request:
+    paths:
+      - 'start.ps1'
+      - '.github/workflows/native-windows-startup.yml'
+  workflow_dispatch:
+
+jobs:
+  native-windows-startup:
+    name: start.ps1 path discovery (mock hermes-agent)
+    runs-on: windows-latest
+    timeout-minutes: 8
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Create the WebUI venv. start.ps1 prefers $AgentDir\venv if it
+      # exists, then falls back to the python on PATH. We create a
+      # WebUI-local venv to mirror the README's documented native path
+      # and to give start.ps1 a real python.exe to invoke.
+      - name: Create venv (README path)
+        shell: pwsh
+        run: |
+          python -m venv venv
+          if (-not (Test-Path venv\Scripts\python.exe)) {
+            throw "venv\Scripts\python.exe missing after venv create"
+          }
+
+      # Mock-only hermes-agent provisioning. We can't pip-install
+      # hermes-agent (not on PyPI), so we stub the minimum that
+      # start.ps1's `Test-Path hermes_cli -PathType Container` guard
+      # needs to pass. server.py would crash on this stub at import
+      # time — we deliberately do NOT probe /health below.
+      - name: Stub hermes-agent (mock hermes_cli only)
+        shell: pwsh
+        run: |
+          $agentDir = Join-Path (Split-Path -Parent $PWD) 'hermes-agent'
+          $cliDir = Join-Path $agentDir 'hermes_cli'
+          New-Item -ItemType Directory -Force -Path $cliDir | Out-Null
+          Set-Content -Path (Join-Path $cliDir '__init__.py') -Value '# stub for CI path-discovery test only'
+          "HERMES_WEBUI_AGENT_DIR=$agentDir" >> $env:GITHUB_ENV
+          Write-Host "Stub hermes-agent provisioned at $agentDir"
+
+      # Run start.ps1 and verify it passes its own discovery guards
+      # without erroring out. server.py will exit non-zero on the stub
+      # (no real CLI code) — that's expected and not asserted against.
+      # We only fail if start.ps1's own Write-Error guards fire.
+      - name: Run start.ps1 + verify path discovery
+        shell: pwsh
+        run: |
+          $stdout = Join-Path $env:RUNNER_TEMP 'start-ps1.out'
+          $stderr = Join-Path $env:RUNNER_TEMP 'start-ps1.err'
+          $proc = Start-Process -FilePath 'pwsh' `
+            -ArgumentList '-NoLogo','-File','.\start.ps1' `
+            -WorkingDirectory $PWD `
+            -PassThru `
+            -RedirectStandardOutput $stdout `
+            -RedirectStandardError  $stderr
+          "SERVER_PID=$($proc.Id)" >> $env:GITHUB_ENV
+          Write-Host "Spawned start.ps1 wrapper PID $($proc.Id)"
+
+          # Path discovery is sub-second; the 8s buffer lets the python
+          # launch land in the logs (and immediately exit on the stub).
+          Start-Sleep -Seconds 8
+
+          Write-Host "===== start.ps1 stdout ====="
+          $stdoutContent = if (Test-Path $stdout) { Get-Content $stdout -Raw } else { '<empty>' }
+          Write-Host $stdoutContent
+          Write-Host "===== start.ps1 stderr ====="
+          $stderrContent = if (Test-Path $stderr) { Get-Content $stderr -Raw } else { '<empty>' }
+          Write-Host $stderrContent
+
+          # Pattern set: every Write-Error message start.ps1 can emit on
+          # its own discovery path. If any of these appear in stderr,
+          # path discovery regressed and the job must fail.
+          $guardErrors = @(
+            'Python 3 is required',
+            'hermes-agent not found',
+            'HERMES_WEBUI_AGENT_DIR is set to',
+            'is not a valid integer port',
+            'is out of TCP-port range',
+            'server.py not found'
+          )
+          foreach ($msg in $guardErrors) {
+            if ($stderrContent -and $stderrContent -match [regex]::Escape($msg)) {
+              throw "REGRESSION: start.ps1 errored on guard '$msg' - path discovery failed."
+            }
+          }
+          Write-Host "OK: start.ps1 path discovery - all guards passed."
+
+      # taskkill /T walks the process tree, /F forces. taskkill returns
+      # 128 ("process not found") if the PID is already gone — that's
+      # the expected steady state for this mock-only workflow because
+      # server.py exits immediately on the stub hermes_cli. Reset
+      # $LASTEXITCODE so the step never fails on the cleanup itself.
+      - name: Stop background server (tree-kill)
+        if: always()
+        shell: pwsh
+        run: |
+          if ($env:SERVER_PID) {
+            & taskkill /PID $env:SERVER_PID /T /F 2>&1 | Out-Host
+            $global:LASTEXITCODE = 0
+          }
+          # Belt-and-suspenders: kill anything still bound to 8787.
+          $hanging = Get-NetTCPConnection -LocalPort 8787 -State Listen -ErrorAction SilentlyContinue
+          if ($hanging) {
+            foreach ($c in $hanging) {
+              try { Stop-Process -Id $c.OwningProcess -Force -ErrorAction Stop } catch {}
+            }
+          }
+          exit 0

.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

@@ -19,7 +19,7 @@ archive/
 !.env.docker.example
 .claude/
 CLAUDE.md
-AGENTS.md
+AGENTS.local.md
 .cursorrules
 .windsurfrules
 .aider*
@@ -36,12 +36,20 @@ api/_version.py
 .DS_Store
 Thumbs.db
 
-# Local reference clones — never committed (except tracked design/UI-UX reference pages)
+# Local reference clones/artifacts — never committed by default.
+# Markdown docs at docs/*.md are intentionally trackable for contributor docs.
 docs/*
+!docs/*.md
 !docs/ui-ux/
 !docs/ui-ux/**
-!docs/docker.md
-!docs/supervisor.md
+!docs/rfcs/
+!docs/rfcs/**
+
+# Local-only AI assistant context — never committed even under docs/.
+docs/AGENTS.md
+docs/CLAUDE.md
+docs/.cursorrules
+docs/.windsurfrules
 
 # Local-only PR review harness: rendering drivers, sample bank, fixtures.
 # Used by Claude during deep reviews; never shared in the repo.
@@ -49,3 +57,5 @@ docs/*
 graphify-out/
 .graphify_cached.json
 .graphify_uncached.txt
+
+.venv/

AGENTS.md

@@ -0,0 +1,80 @@
+# Agent instructions for Hermes WebUI
+
+This file is the shared entry point for AI assistants working in this
+repository. Keep it project-specific and safe to publish. Do not put personal
+machine setup, private network details, credentials, tokens, or local-only
+workflow notes here.
+
+## Read first
+
+Before making changes, read:
+
+1. `README.md`
+2. `CONTRIBUTING.md`
+3. `docs/CONTRACTS.md`
+4. `CHANGELOG.md`
+
+For architecture, testing, or setup work, also read the matching reference:
+
+- `ARCHITECTURE.md` for design constraints and current module layout
+- `TESTING.md` for local verification commands and manual test guidance
+- `docs/onboarding.md` for first-run onboarding behavior
+- `docs/troubleshooting.md` for diagnostic flows
+- `docs/rfcs/README.md` for larger RFCs and state/durability contracts
+
+For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before
+changing layout, interaction flow, themes, chat rendering, or composer chrome.
+
+## Onboarding and reinstall support
+
+If the task involves install, reinstall, bootstrap, first-run onboarding,
+provider setup, local model server setup, Docker onboarding, WSL onboarding, or
+support for a failed first run, read `docs/onboarding-agent-checklist.md`
+before running commands or inspecting logs.
+
+Follow that checklist's safety rules:
+
+- use isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` for trials unless the
+  human explicitly asks to use real state
+- do not delete or overwrite a real `~/.hermes` directory without explicit
+  approval
+- do not print API keys, OAuth tokens, cookies, full `.env` files, full
+  `auth.json` files, or password hashes
+- collect non-secret status and log evidence before recommending a fix
+
+## Contribution style
+
+- Keep one logical change per PR; split unrelated refactors or cleanup.
+- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched
+  subsystem before editing.
+- Prefer the existing Python + vanilla JavaScript structure. Do not add
+  dependencies, build tools, frameworks, or long-lived processes without clear
+  justification and a rollback story.
+- Update docs when changing setup, onboarding, runtime behavior, architecture,
+  testing guidance, or user-facing workflows.
+- Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or
+  documentation changes that should be release-note ready.
+- For UI or UX changes, include before/after evidence and test relevant
+  desktop, narrow, and mobile states.
+- For behavior changes, add or update automated tests where practical and list
+  the manual verification performed.
+- For runtime, streaming, recovery, replay, compression, or sidebar metadata
+  changes, name the state layer being mutated and prove the relevant invariant.
+
+## Local state and secrets
+
+Hermes WebUI can read and write real agent state, sessions, workspaces,
+credentials, and cron data. Treat local validation as potentially destructive
+unless you have confirmed the active state directories.
+
+Prefer isolated trial state for experiments:
+
+```bash
+HERMES_HOME=/tmp/hermes-webui-agent-home \
+HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
+HERMES_WEBUI_PORT=8789 \
+python3 bootstrap.py
+```
+
+Do not include private machine instructions in this tracked file. Use a
+git-ignored local note for personal workflow details.

ARCHITECTURE.md

@@ -7,10 +7,10 @@
 >
 > Keep this document updated as architecture changes are made.
 
-> Current shipped build: `v0.50.245` (April 30, 2026).
-> Automated coverage: 3309 tests via `pytest tests/ --collect-only -q`. CI runs on Python 3.11, 3.12, and 3.13 against every PR.
+> Current shipped build: `v0.51.54` (May 13, 2026).
+> Automated coverage: 5303 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.
+> Notable architecture state as of v0.51.54: the bootstrap and first-run onboarding flow own setup discovery; the default WebUI state directory is `~/.hermes/webui`; `ctl.sh` provides a daemon wrapper for homelab installs; chat streaming is still WebUI-owned SSE with stream-ownership guards, cancellation, async manual compression, and turn-journal audit plumbing; provider/model discovery is profile-aware with live-model cache invalidation and custom-provider scoping.
 
 ---
 
@@ -43,42 +43,42 @@ actions. The topbar remains focused on conversation context and the workspace/fi
 ## 2. File Inventory
 
     <repo>/
-    server.py              Thin routing shell + HTTP Handler + auth middleware. ~81 lines.
+    server.py              Thin routing shell + HTTP Handler + auth middleware. ~446 lines.
                            Delegates all route handling to api/routes.py.
     bootstrap.py           One-shot launcher: optional agent install, deps, health wait, browser open.
     start.sh               Thin wrapper around bootstrap.py for shell-based startup.
-    Dockerfile             python:3.12-slim container image (~23 lines)
-    docker-compose.yml     Compose config with named volume and optional auth (~22 lines)
+    Dockerfile             python:3.12-slim container image (~89 lines)
+    docker-compose.yml     Compose config with named volume and optional auth (~57 lines)
     .dockerignore          Excludes .git, tests/, .env* from Docker builds
     api/
       __init__.py          Package marker
-      auth.py              Optional password authentication, signed cookies (~149 lines)
-      config.py            Discovery, globals, model detection, reloadable config (~701 lines)
-      helpers.py           HTTP helpers: j(), bad(), require(), safe_resolve(), security headers (~71 lines)
-      models.py            Session model + CRUD, per-session profile tracking (~137 lines)
-      profiles.py          Profile state management, hermes_cli wrapper (~246 lines)
-      onboarding.py        First-run onboarding status, real provider config writes, and readiness detection.
-      routes.py            All GET + POST route handlers (~1180 lines)
-      startup.py           Startup helpers: auto_install_agent_deps() (~50 lines)
-      streaming.py         SSE engine, run_agent, cancel, HERMES_HOME save/restore (~236 lines)
-      upload.py            Multipart parser, file upload handler (~78 lines)
-      workspace.py         File ops: list_dir, read_file_content, workspace helpers (~77 lines)
+      auth.py              Optional password authentication, signed cookies (~366 lines)
+      config.py            Discovery, globals, model detection, reloadable config (~4139 lines)
+      helpers.py           HTTP helpers: j(), bad(), require(), safe_resolve(), security headers (~302 lines)
+      models.py            Session model + CRUD, per-session profile tracking (~1927 lines)
+      profiles.py          Profile state management, hermes_cli wrapper (~1056 lines)
+      onboarding.py        First-run onboarding status, real provider config writes, OAuth linking, and readiness detection (~1002 lines)
+      routes.py            All GET + POST route handlers (~9772 lines)
+      startup.py           Startup helpers: auto_install_agent_deps() (~128 lines)
+      streaming.py         SSE engine, run_agent, cancel, HERMES_HOME save/restore (~4420 lines)
+      upload.py            Multipart parser, file upload handler (~284 lines)
+      workspace.py         File ops: list_dir, read_file_content, workspace helpers (~810 lines)
     static/
-      index.html           HTML template (~364 lines)
-      style.css            All CSS incl. mobile responsive (~670 lines)
-      ui.js                DOM helpers, renderMd, tool cards, model dropdown, file tree (~977 lines)
-      workspace.js         File preview, file ops, loadDir, clearPreview (~185 lines)
-      sessions.js          Session CRUD, list rendering, search, SVG icons, dropdown actions (~533 lines)
-      messages.js          send(), SSE event handlers, approval, transcript (~297 lines)
-      panels.js            Cron, skills, memory, workspace, profiles, todo, settings (~974 lines)
-      commands.js          Slash command registry, parser, autocomplete dropdown (~156 lines)
+      index.html           HTML template (~1323 lines)
+      style.css            All CSS incl. mobile responsive (~3767 lines)
+      ui.js                DOM helpers, renderMd, tool cards, model dropdown, file tree (~7216 lines)
+      workspace.js         File preview, file ops, loadDir, clearPreview (~369 lines)
+      sessions.js          Session CRUD, list rendering, search, SVG icons, dropdown actions (~3517 lines)
+      messages.js          send(), SSE event handlers, approval, transcript (~2301 lines)
+      panels.js            Cron, skills, memory, workspace, profiles, todo, settings (~6480 lines)
+      commands.js          Slash command registry, parser, autocomplete dropdown (~1302 lines)
       onboarding.js        First-run wizard overlay, provider setup flow, and settings/workspace orchestration.
-      boot.js              Event wiring, mobile sidebar/workspace nav, voice input, boot IIFE (~338 lines)
+      boot.js              Event wiring, mobile sidebar/workspace nav, voice input, boot IIFE (~1607 lines)
     tests/
-      conftest.py          Isolated test server (port 8788, separate HERMES_HOME) (~240 lines)
-      test_sprint{1-20b}.py Feature tests per sprint (21 files, 415 test functions)
-      test_regressions.py  Permanent regression gate (23 tests)
-    AGENTS.md              Instruction file for agents working in this directory.
+      conftest.py          Isolated test server/state fixtures (~644 lines)
+      488 test files       5303 tests collected via pytest
+      test_regressions.py  Permanent regression gate (~976 lines)
+    CONTRIBUTING.md        Contributor workflow and PR expectations.
     ROADMAP.md             Feature and product roadmap document.
     SPRINTS.md             Forward sprint plan with CLI + Claude parity targets.
     ARCHITECTURE.md        THIS FILE.
@@ -90,7 +90,7 @@ actions. The topbar remains focused on conversation context and the workspace/fi
 
 State directory (runtime data, separate from source):
 
-    ~/.hermes/webui-mvp/
+    ~/.hermes/webui/
     sessions/          One JSON file per session: {session_id}.json
     workspaces.json    Registered workspaces list
     last_workspace.txt Last-used workspace path
@@ -99,7 +99,8 @@ State directory (runtime data, separate from source):
 
 Log file:
 
-    /tmp/webui-mvp.log   stdout/stderr from the background server process
+    ~/.hermes/webui/bootstrap-8787.log   start.sh/bootstrap background server log
+    ~/.hermes/webui.log                  ctl.sh daemon log
 
 ---
 
@@ -118,15 +119,16 @@ Environment variables controlling behavior:
     HERMES_WEBUI_DEFAULT_WORKSPACE Default workspace path for new sessions
     HERMES_WEBUI_STATE_DIR         Where sessions/ folder lives
     HERMES_CONFIG_PATH             Path to ~/.hermes/config.yaml
-    HERMES_WEBUI_DEFAULT_MODEL     Default LLM model string
+    HERMES_WEBUI_DEFAULT_MODEL     Optional model override; unset means provider default
     HERMES_WEBUI_PASSWORD          Optional: enable password auth (off by default)
+    HERMES_WEBUI_SKIP_ONBOARDING   Optional: bypass the first-run onboarding wizard
     HERMES_HOME                    Base directory for Hermes state (~/.hermes by default)
 
 Test isolation environment variables (set by conftest.py):
 
-    HERMES_WEBUI_PORT=8788                           Isolated test port
-    HERMES_WEBUI_STATE_DIR=~/.hermes/webui-mvp-test  Isolated test state
-    HERMES_WEBUI_DEFAULT_WORKSPACE=.../test-workspace Isolated test workspace
+    HERMES_WEBUI_TEST_PORT=...                         Optional pinned test port
+    HERMES_WEBUI_TEST_STATE_DIR=~/.hermes/webui-test-* Optional pinned test state
+    HERMES_WEBUI_DEFAULT_WORKSPACE=.../test-workspace  Isolated test workspace
 
 Tests NEVER talk to the production server (port 8787).
 The test state dir is wiped before each test session and deleted after.
@@ -156,10 +158,11 @@ Python stdlib ThreadingHTTPServer (from http.server). Each HTTP request runs in
 thread. The Handler class subclasses BaseHTTPRequestHandler with two methods:
 
     do_GET    Routes: /, /health, /api/session, /api/sessions, /api/list,
-                      /api/chat/stream, /api/file, /api/approval/pending
+                      /api/chat/stream, /api/file, /api/approval/pending,
+                      /api/session/worktree/status
     do_POST   Routes: /api/upload, /api/session/new, /api/session/update,
                       /api/session/delete, /api/chat/start, /api/chat,
-                      /api/approval/respond
+                      /api/approval/respond, /api/session/worktree/remove
 
 Routing is a flat if/elif chain inside each method. No routing framework.
 
@@ -319,7 +322,7 @@ POST /api/approval/respond:
 ### 4.6 File Upload Parser
 
 parse_multipart(rfile, content_type, content_length):
-    - Reads all content_length bytes from rfile into memory (up to MAX_UPLOAD_BYTES = 20MB)
+    - Reads all content_length bytes from rfile into memory (up to MAX_UPLOAD_BYTES, default 20MB, env-overridable via HERMES_WEBUI_MAX_UPLOAD_MB)
     - Extracts boundary from Content-Type header
     - Splits raw bytes on b'--' + boundary
     - For each part: parses MIME headers via email.parser.HeaderParser
@@ -362,16 +365,18 @@ read_file_content(workspace, rel):
 ### 5.1 Structure
 
 The frontend is served from static/ as separate files: one HTML template, one CSS file,
-and six JavaScript modules (~2,786 lines total). External dependencies: Prism.js (syntax
-highlighting) and Mermaid.js (diagrams) from CDN, both loaded async/deferred with SRI hashes.
+and multiple JavaScript modules. External dependencies include Prism.js (syntax
+highlighting), Mermaid.js (diagrams), xterm.js, and KaTeX assets loaded with the
+current static template's integrity/CSP assumptions.
 
-Six JS modules loaded in order at end of <body>:
-  1. ui.js       (~846 lines) DOM helpers, renderMd, tool card rendering, global state
-  2. workspace.js (~169 lines) File tree, preview, file operations
-  3. sessions.js  (~532 lines) Session CRUD, list rendering, search, SVG icons, dropdown actions, project picker
-  4. messages.js  (~293 lines) send(), SSE event handlers, approval, transcript
-  5. panels.js    (~771 lines) Cron, skills, memory, workspace, todo, switchPanel
-  6. boot.js      (~175 lines) Event wiring + boot IIFE
+Core JS modules loaded by the app include:
+  1. ui.js         (~7216 lines) DOM helpers, renderMd, tool card rendering, global state
+  2. workspace.js  (~369 lines) File tree, preview, file operations
+  3. sessions.js  (~3517 lines) Session CRUD, list rendering, search, SVG icons, dropdown actions, project picker
+  4. messages.js  (~2301 lines) send(), SSE event handlers, approval, transcript
+  5. panels.js    (~6480 lines) Cron, skills, memory, workspace, profiles, todo, settings
+  6. commands.js  (~1302 lines) Slash command registry, parser, autocomplete dropdown
+  7. boot.js      (~1607 lines) Event wiring + boot IIFE
 
 sessions.js defines an `ICONS` constant at module level with hardcoded SVG strings for all
 session action buttons (pin, unpin, folder, archive, unarchive, duplicate, trash). All icons
@@ -679,27 +684,28 @@ Split server.py into a proper package. Completed across Sprints 4-10.
 Current structure:
 
     <repo>/
-      server.py               Entry point + HTTP Handler dispatch (~76 lines)
+      server.py               Entry point + HTTP Handler dispatch (~446 lines)
       api/
         __init__.py
-        routes.py             All GET + POST route handlers (~1016 lines)
-        config.py             Configuration, constants, global state, model discovery (~640 lines)
-        helpers.py            HTTP helpers: j(), bad(), require(), safe_resolve() (~57 lines)
-        models.py             Session model + CRUD (~132 lines)
-        workspace.py          File ops, workspace management (~77 lines)
-        upload.py             Multipart parser, file upload handler (~77 lines)
-        streaming.py          SSE engine, run_agent, cancel support (~222 lines)
+        routes.py             All GET + POST route handlers (~9772 lines)
+        config.py             Configuration, constants, global state, model discovery (~4139 lines)
+        helpers.py            HTTP helpers: j(), bad(), require(), safe_resolve() (~302 lines)
+        models.py             Session model + CRUD (~1927 lines)
+        workspace.py          File ops, workspace management (~810 lines)
+        upload.py             Multipart parser, file upload handler (~284 lines)
+        streaming.py          SSE engine, run_agent, cancel support (~4420 lines)
       static/
         index.html            HTML document (served from disk)
-        style.css             All CSS (~560 lines)
-        ui.js, workspace.js, sessions.js, messages.js, panels.js, boot.js
+        style.css             All CSS (~3767 lines)
+        ui.js, workspace.js, sessions.js, messages.js, panels.js, commands.js, boot.js
       tests/
-        conftest.py           Isolated test server on port 8788
-        test_sprint1-16.py    Feature tests per sprint (14 files)
+        conftest.py           Isolated test server/state fixtures
+        488 test files        5303 tests collected
         test_regressions.py   Permanent regression gate
 
-Route extraction to api/routes.py completed in Sprint 11. server.py is now a ~76-line
-thin shell: Handler class with structured logging, dispatch to routes, and main().
+Route extraction to api/routes.py completed in Sprint 11. server.py remains a
+thin shell relative to the rest of the app: Handler class with headers,
+structured logging, dispatch to routes, TLS wrapping, and main().
 
 ### Phase B: Thread-Safe Request Context (Priority: Critical, Effort: Medium)
 
@@ -778,7 +784,7 @@ Replacing with marked.js + DOMPurify is a future improvement (not blocking).
 
 ### Phase G: Observability -- MOSTLY COMPLETE
 
-1. Structured JSON logging: COMPLETE (Sprint 1). Per-request JSON to /tmp/webui-mvp.log.
+1. Structured JSON logging: COMPLETE (Sprint 1). Per-request JSON is printed to the active launcher log (`~/.hermes/webui/bootstrap-8787.log` for `start.sh`, `~/.hermes/webui.log` for `ctl.sh`).
 2. Enhanced /health: COMPLETE (Sprint 7). Returns `active_streams`, `uptime_seconds`.
 3. GET /api/debug/stats: NOT YET IMPLEMENTED. Low priority.
 
@@ -794,13 +800,13 @@ Optional password gate for non-SSH-tunnel deployments.
 
 ### Phase I: Test Infrastructure -- COMPLETE
 
-289 tests across 14 test files + regression gate. Isolated test server on port 8788
-with separate HERMES_HOME, wiped per run. Production data never touched.
+5303 tests across 488 test files + regression gates. The pytest fixture derives
+an isolated port and state directory from the repo path unless
+`HERMES_WEBUI_TEST_PORT` / `HERMES_WEBUI_TEST_STATE_DIR` pin them explicitly.
+Production data never touched.
 
-Test files: `test_sprint1.py` through `test_sprint11.py`, `test_sprint16.py`, `test_regressions.py`.
-Fixtures in `conftest.py`: auto-cleanup, cron isolation, workspace reset.
-
-Remaining: no CI (GitHub Actions), no frontend tests (browser-based).
+Fixtures in `conftest.py`: auto-cleanup, profile/config isolation, cron
+isolation, workspace reset, and test-server lifecycle.
 
 ### Phase J: Performance (Priority: Low, Effort: High)
 
@@ -888,7 +894,8 @@ The api() helper:
     curl -s http://127.0.0.1:8787/health | python3 -m json.tool
 
     # Tail the server log live
-    tail -f /tmp/webui-mvp.log
+    tail -f ~/.hermes/webui/bootstrap-8787.log
+    tail -f ~/.hermes/webui.log  # when launched through ctl.sh
 
     # List all sessions (metadata only)
     curl -s http://127.0.0.1:8787/api/sessions | python3 -m json.tool
@@ -898,15 +905,15 @@ The api() helper:
     curl -s "http://127.0.0.1:8787/api/session?session_id=$SID" | python3 -m json.tool
 
     # Kill and restart server cleanly
-    pkill -f "python.*webui-mvp/server.py"
-    <agent-dir>/webui-mvp/start.sh
+    pkill -f "python.*server.py"
+    <repo>/start.sh
 
     # Check if server process is running
-    ps aux | grep "webui-mvp/server.py"
+    ps aux | grep "server.py"
 
     # Inspect session files on disk
-    ls -lt ~/.hermes/webui-mvp/sessions/
-    cat ~/.hermes/webui-mvp/sessions/SESSION_ID.json | python3 -m json.tool
+    ls -lt ~/.hermes/webui/sessions/
+    cat ~/.hermes/webui/sessions/SESSION_ID.json | python3 -m json.tool
 
     # Count messages in a session
     python3 -c "import json; d=json.load(open('sessions/SID.json')); print(len(d['messages']))"
@@ -919,9 +926,9 @@ The api() helper:
     curl -s http://127.0.0.1:8787/health  # streams not exposed yet, add in Phase G
 
     # Find all sessions with messages (not Untitled empty)
-    ls ~/.hermes/webui-mvp/sessions/ | xargs -I{} python3 -c "
+    ls ~/.hermes/webui/sessions/ | xargs -I{} python3 -c "
     import json, sys
-    d = json.load(open('~/.hermes/webui-mvp/sessions/{}'))
+    d = json.load(open('~/.hermes/webui/sessions/{}'))
     if d['messages']: print('{}', d['title'][:50])
     " 2>/dev/null
 
@@ -1194,31 +1201,22 @@ will be working on this codebase. Read this before touching any file.
 ### Before Making Any Change
 
 1. Read this document (ARCHITECTURE.md) fully. Especially sections 4, 5, and the ADRs.
-2. Read the relevant section of server.py by searching for the SECTION header.
+2. Inspect the relevant module under `api/` or `static/`; `server.py` is only the routing shell.
 3. Check the Sprint Log (Section 15) to understand what was recently changed.
-4. Run the test suite first to confirm baseline: cd <agent-dir> &&
-   venv/bin/python -m pytest webui-mvp/tests/test_sprint1.py -v
+4. Run the relevant test slice first to confirm baseline, for example:
+   venv/bin/python -m pytest tests/test_regressions.py -q
 5. Check server health: curl -s http://127.0.0.1:8787/health
 
 ### Making Changes
 
-Always back up server.py before a non-trivial change:
-    cp server.py server.py.$(date +%Y%m%d_%H%M).bak
-
-Use exact string matching when patching. The pitfalls are documented in the
-hermes-webui-mvp skill. Key ones:
-- Never use sed on this file from the shell. Use execute_code with Python string replace.
-- Always assert the old string is found before replacing (prevents silent no-op patches).
-- Unicode escape sequences in JS (\u2026) exist as literal backslash-u in the file.
-  Match the file's raw content, not interpreted Python strings.
-- The HTML block is a Python raw string (r"""..."""). Standard triple-quote escaping
-  rules do not apply inside it, but Python escape sequences \n etc. work in JS strings
-  inside it as literal two-character sequences.
+Keep edits scoped to the module that owns the behavior. Use exact string
+matching when making mechanical patches and verify that the intended old string
+was found before replacing it.
 
 After any change:
-    venv/bin/python -m py_compile webui-mvp/server.py   # syntax check
+    venv/bin/python -m py_compile server.py             # syntax check
     curl -s http://127.0.0.1:8787/health                # server still alive
-    venv/bin/python -m pytest webui-mvp/tests/ -v       # tests still pass
+    venv/bin/python -m pytest tests/ -v                 # tests still pass
 
 ### Critical Rules (do NOT regress these)
 
@@ -1320,7 +1318,7 @@ Complete list of all HTTP endpoints as of Sprint 1 (v0.3).
     /api/crons/output          ?job_id=X&limit=N -> {outputs: [{filename, content}]}
     /api/skills                All skills. Returns {skills: [{name, description, category}]}
     /api/skills/content        ?name=X -> full skill data including SKILL.md content
-    /api/memory                MEMORY.md + USER.md. Returns {memory, user, *_path, *_mtime}
+    /api/memory                MEMORY.md + USER.md + SOUL.md. Returns {memory, user, soul, *_path, *_mtime}
 
 ### POST Endpoints Added in Sprint 3
 
@@ -1455,7 +1453,7 @@ fetches GET /api/skills/content and renders in the right panel using `showPrevie
 #### Memory Panel
 
 `loadMemory()` fetches GET /api/memory (reads MEMORY.md + USER.md from
-~/.hermes/memories/), renders both as markdown via renderMd() with timestamps.
+~/.hermes/memories/, and SOUL.md from ~/.hermes/), renders both as markdown via renderMd() with timestamps.
 
 #### New API Endpoints (Section 18 update)
 
@@ -1466,7 +1464,7 @@ fetches GET /api/skills/content and renders in the right panel using `showPrevie
     POST /api/crons/resume       {job_id} -> resume_job(job_id)
     GET  /api/skills             All skills via tools.skills_tool.skills_list()
     GET  /api/skills/content     ?name=X -> full skill data via skill_view(name)
-    GET  /api/memory             MEMORY.md + USER.md content and mtimes
+    GET  /api/memory             MEMORY.md + USER.md + SOUL.md content and mtimes
 
 #### Phase D Input Validation Applied
 

CONTRIBUTING.md

@@ -4,6 +4,22 @@ Thanks for contributing.
 
 Hermes WebUI is intentionally simple to work on: Python on the server, vanilla JS in the browser, no build step, no bundler, no frontend framework. The best pull requests preserve that simplicity while solving a real problem cleanly.
 
+## Before You Start
+
+- Read [`AGENTS.md`](AGENTS.md) if an AI assistant is doing or helping with the
+  change.
+- Read [`docs/CONTRACTS.md`](docs/CONTRACTS.md) and any linked contract/RFC for
+  the subsystem you will touch.
+- For UI or UX work, read [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md)
+  and [`DESIGN.md`](DESIGN.md).
+- For runtime, streaming, recovery, replay, compression, context reconstruction,
+  or session metadata work, start with [`docs/rfcs/README.md`](docs/rfcs/README.md)
+  and the relevant RFC listed there.
+
+Use those documents as review guardrails: keep the change scoped, preserve the
+no-build-step architecture, update docs/changelog when behavior changes, include
+UI evidence for UI changes, and add tests for behavior changes where practical.
+
 ## Two Paths to a Strong Pull Request
 
 ### Path 1: Small, Focused Changes
@@ -60,7 +76,7 @@ There is currently no PR template in this repo, so include the important section
 
 If the change is user-visible, include screenshots or a short video.
 
-For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images will likely be ignored, or closed in a regular maintainer sweep without review.
+For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images may not receive meaningful review until that evidence is added.
 
 ### 4. AI Usage Disclosure
 

CONTRIBUTORS.md

@@ -1,61 +1,100 @@
 # 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).
+Hermes WebUI is a community project. **137 people** have shipped code that landed in a release tag — including the long tail of folks whose work was salvaged into batch releases or absorbed via Co-authored-by trailers. This file is the canonical credit roll.
 
-**Total contributors tracked:** 66  
-**Total PRs landed:** 142  
-**Last refreshed:** v0.50.245, 2026-04-30
+A contributor's PR count is the number of distinct PRs they get credit for: PRs they authored that merged directly, PRs they authored that were closed-but-absorbed into a release commit (batch merges, salvage rewrites), and PRs where they were explicitly attributed in `CHANGELOG.md`. All three count the same.
 
-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.
+**Total contributors tracked:** 137
+**Total PR credits:** 646
+**Last refreshed:** v0.51.58, 2026-05-13
+
+Generated from `git log` + the GitHub PR list (merged and closed) + the `CHANGELOG.md` attribution lines (`PR #N by @user`, `(credit: @user)`, `@user — PR #N`). 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)
+## Top contributors (5+ PRs landed)
 
 | # | 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 |
+| 1 | [@franksong2702](https://github.com/franksong2702) | 117 | `v0.49.3` | `v0.51.58` |
+| 2 | [@Michaelyklam](https://github.com/Michaelyklam) | 92 | `v0.50.240` | `v0.51.57` |
+| 3 | [@bergeouss](https://github.com/bergeouss) | 62 | `v0.48.0` | `v0.51.46` |
+| 4 | [@ai-ag2026](https://github.com/ai-ag2026) | 55 | `v0.50.279` | `v0.51.47` |
+| 5 | [@dso2ng](https://github.com/dso2ng) | 23 | `v0.50.227` | `v0.51.51` |
+| 6 | [@jasonjcwu](https://github.com/jasonjcwu) | 16 | `v0.50.227` | `v0.51.55` |
+| 7 | [@Jordan-SkyLF](https://github.com/Jordan-SkyLF) | 12 | `v0.50.18` | `v0.51.58` |
+| 8 | [@aronprins](https://github.com/aronprins) | 10 | `v0.44.0` | `v0.50.233` |
+| 9 | [@JKJameson](https://github.com/JKJameson) | 10 | `v0.50.233` | `v0.51.31` |
+| 10 | [@starship-s](https://github.com/starship-s) | 10 | `v0.50.128` | `v0.51.58` |
+| 11 | [@ccqqlo](https://github.com/ccqqlo) | 9 | `v0.44.0` | `v0.50.270` |
+| 12 | [@24601](https://github.com/24601) | 8 | `v0.50.233` | `v0.51.5` |
+| 13 | [@armorbreak001](https://github.com/armorbreak001) | 7 | `v0.50.47` | `v0.50.50` |
+| 14 | [@NocGeek](https://github.com/NocGeek) | 7 | `v0.50.251` | `v0.50.252` |
+| 15 | [@dobby-d-elf](https://github.com/dobby-d-elf) | 6 | `v0.51.38` | `v0.51.58` |
+| 16 | [@Hinotoi-agent](https://github.com/Hinotoi-agent) | 6 | `v0.50.12` | `v0.51.44` |
+| 17 | [@iRonin](https://github.com/iRonin) | 6 | `v0.41.0` | `v0.41.0` |
+| 18 | [@Sanjays2402](https://github.com/Sanjays2402) | 6 | `v0.50.292` | `v0.51.31` |
+| 19 | [@cloudyun888](https://github.com/cloudyun888) | 5 | `v0.50.47` | `v0.50.140` |
+| 20 | [@fxd-jason](https://github.com/fxd-jason) | 5 | `v0.50.245` | `v0.50.249` |
+| 21 | [@happy5318](https://github.com/happy5318) | 5 | `v0.50.238` | `v0.51.31` |
 
-## Sustained contributors (3–4 merged PRs)
+## Sustained contributors (3–4 PRs landed)
 
-| 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 |
+| Contributor | PRs | First release | Latest release |
+|---|---:|---|---|
+| [@bsgdigital](https://github.com/bsgdigital) | 4 | `v0.50.228` | `v0.50.258` |
+| [@fecolinhares](https://github.com/fecolinhares) | 4 | `v0.50.238` | `v0.50.250` |
+| [@frap129](https://github.com/frap129) | 4 | `v0.50.140` | `v0.50.233` |
+| [@KingBoyAndGirl](https://github.com/KingBoyAndGirl) | 4 | `v0.50.238` | `v0.50.240` |
+| [@LumenYoung](https://github.com/LumenYoung) | 4 | `v0.51.47` | `v0.51.55` |
+| [@qxxaa](https://github.com/qxxaa) | 4 | `v0.50.233` | `v0.51.37` |
+| [@renheqiang](https://github.com/renheqiang) | 4 | `v0.50.61` | `v0.50.95` |
+| [@Thanatos-Z](https://github.com/Thanatos-Z) | 4 | `v0.50.257` | `v0.50.278` |
+| [@AlexeyDsov](https://github.com/AlexeyDsov) | 3 | `v0.50.267` | `v0.50.278` |
+| [@deboste](https://github.com/deboste) | 3 | `v0.50.269` | `v0.50.297` |
+| [@dutchaiagency](https://github.com/dutchaiagency) | 3 | `v0.50.281` | `v0.50.286` |
+| [@lucasrc](https://github.com/lucasrc) | 3 | `v0.51.57` | `v0.51.57` |
+| [@pavolbiely](https://github.com/pavolbiely) | 3 | `v0.50.159` | `v0.50.233` |
 
-## Two-PR contributors
+## Two-PR contributors (19)
 
-[@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).
+[@ChaseFlorell](https://github.com/ChaseFlorell), [@gabogabucho](https://github.com/gabogabucho), [@hacker1e7](https://github.com/hacker1e7), [@hualong1009](https://github.com/hualong1009), [@lost9999](https://github.com/lost9999), [@michael-dg](https://github.com/michael-dg), [@mmartial](https://github.com/mmartial), [@MrFant](https://github.com/MrFant), [@nickgiulioni1](https://github.com/nickgiulioni1), [@renatomott](https://github.com/renatomott), [@ruxme](https://github.com/ruxme), [@Saik0s](https://github.com/Saik0s), [@samuelgudi](https://github.com/samuelgudi), [@shruggr](https://github.com/shruggr), [@TaraTheStar](https://github.com/TaraTheStar), [@vansour](https://github.com/vansour), [@vcavichini](https://github.com/vcavichini), [@xz-dev](https://github.com/xz-dev), [@zichen0116](https://github.com/zichen0116).
 
-## Single-PR contributors
+## Single-PR contributors (84)
 
-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.
+Each of these folks landed exactly one PR that shipped — a bug fix, a locale, a security hardening, a doc improvement, an infrastructure tweak. Every one 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).
+[@29n](https://github.com/29n), [@amlyczz](https://github.com/amlyczz), [@andrewy-wizard](https://github.com/andrewy-wizard), [@Argonaut790](https://github.com/Argonaut790), [@Asunfly](https://github.com/Asunfly), [@ayushere](https://github.com/ayushere), [@betamod](https://github.com/betamod), [@Bobby9228](https://github.com/Bobby9228), [@bschmidy10](https://github.com/bschmidy10), [@carlytwozero](https://github.com/carlytwozero), [@davidsben](https://github.com/davidsben), [@DavidSchuchert](https://github.com/DavidSchuchert), [@DelightRun](https://github.com/DelightRun), [@DrMaks22](https://github.com/DrMaks22), [@eba8](https://github.com/eba8), [@eov128](https://github.com/eov128), [@galvani](https://github.com/galvani), [@GeoffBao](https://github.com/GeoffBao), [@georgebdavis](https://github.com/georgebdavis), [@GiggleSamurai](https://github.com/GiggleSamurai), [@hacker2005](https://github.com/hacker2005), [@halmisen](https://github.com/halmisen), [@hermes-gimmethebeans](https://github.com/hermes-gimmethebeans), [@hi-friday](https://github.com/hi-friday), [@huangzt](https://github.com/huangzt), [@indigokarasu](https://github.com/indigokarasu), [@insecurejezza](https://github.com/insecurejezza), [@jeffscottward](https://github.com/jeffscottward), [@Jellypowered](https://github.com/Jellypowered), [@jimdawdy-hub](https://github.com/jimdawdy-hub), [@JinYue-GitHub](https://github.com/JinYue-GitHub), [@joaompfp](https://github.com/joaompfp), [@jundev0001](https://github.com/jundev0001), [@KayZz69](https://github.com/KayZz69), [@kcclaw001](https://github.com/kcclaw001), [@kevin-ho](https://github.com/kevin-ho), [@koshikai](https://github.com/koshikai), [@kowenhaoai](https://github.com/kowenhaoai), [@lawrencel1ng](https://github.com/lawrencel1ng), [@legeantbleu](https://github.com/legeantbleu), [@likawa3b](https://github.com/likawa3b), [@lucky-yonug](https://github.com/lucky-yonug), [@lx3133584](https://github.com/lx3133584), [@MacLeodMike](https://github.com/MacLeodMike), [@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), [@mittyok](https://github.com/mittyok), [@ng-technology-llc](https://github.com/ng-technology-llc), [@octo-patch](https://github.com/octo-patch), [@plerohellec](https://github.com/plerohellec), [@rhelmer](https://github.com/rhelmer), [@rickchew](https://github.com/rickchew), [@ryan-remeo](https://github.com/ryan-remeo), [@ryansombraio](https://github.com/ryansombraio), [@s905060](https://github.com/s905060), [@SaulgoodMan-C](https://github.com/SaulgoodMan-C), [@sbe27](https://github.com/sbe27), [@shaoxianbilly](https://github.com/shaoxianbilly), [@sheng-di](https://github.com/sheng-di), [@sixianli](https://github.com/sixianli), [@skspade](https://github.com/skspade), [@smurmann](https://github.com/smurmann), [@snuffxxx](https://github.com/snuffxxx), [@spektro33](https://github.com/spektro33), [@Stampede](https://github.com/Stampede), [@suinia](https://github.com/suinia), [@sunnysktsang](https://github.com/sunnysktsang), [@tgaalman](https://github.com/tgaalman), [@thadreber-web](https://github.com/thadreber-web), [@the-own-lab](https://github.com/the-own-lab), [@tomaioo](https://github.com/tomaioo), [@trucuit](https://github.com/trucuit), [@vCillusion](https://github.com/vCillusion), [@vikarag](https://github.com/vikarag), [@wali-reheman](https://github.com/wali-reheman), [@watzon](https://github.com/watzon), [@woaijiadanoo](https://github.com/woaijiadanoo), [@xingyue52077](https://github.com/xingyue52077), [@yunyunyunyun-yun](https://github.com/yunyunyunyun-yun), [@yzp12138](https://github.com/yzp12138), [@zenc-cp](https://github.com/zenc-cp).
 
 ---
 
 ## How credit is tracked
 
-Most PRs in this repo land via one of three paths:
+Most PRs in this repo land via one of four 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.
+1. **Direct merge** — your PR is reviewed and merged on its own. Author shows up directly in `git log` and on the PR's `merged_at` timestamp.
+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.51.55 — 9-PR contributor batch`). The original PR closes (not merges) on GitHub but the squashed release 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 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.
+4. **Auto-rebase + auto-fix** — for merge-ready contributor PRs with mechanical blockers (CHANGELOG conflicts, lint, drifted tests), a maintainer rebases the contributor's branch, fixes the blockers, and force-pushes back. The `Co-authored-by` trailer preserves your authorship.
 
-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).
+All four paths count as a contribution. GitHub's `merged_at` field only catches path 1; paths 2-4 show as "closed" on the contributor's PR even though the work is live in master. That's why this file consults the CHANGELOG attribution lines, not just GitHub's merged-PR list.
 
 ## 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.
+- **[@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. PR #242 didn't merge as-is, but it is the design language of the app.
+- **[@franksong2702](https://github.com/franksong2702)** — most prolific external contributor across the project's history. 117 PRs spanning the session sidebar, mobile/responsive layout, workspace state machine, profile context, slash autocomplete, breadcrumb navigation, streaming-session exemption, cron output preservation, embedded terminal, the manual-compress async start/status endpoint pair, the worktree status surface (PR #2109) + guarded remove (PR #2156) for the lifecycle umbrella #2057, session post-render dedup (PR #2166), the `/api/session` native-WebUI fast path (PR #2170), tail-window response trim (PR #2171), the second-wave stale-stream guard extension (PR #2158), CSP report collector (PR #2160), and the long tail of polish.
+- **[@Michaelyklam](https://github.com/Michaelyklam)** — most prolific contributor of late-2025/early-2026. 92 PRs covering Docker hardening, profile-scoped skills, KaTeX delimiter parsing, Codex quota surfacing, Goal command, Kanban polish, auto-compression toast lifetime, the localization parity backfills, the v0.51.51 mobile Insights bucketing/layout pair (PRs #2120/#2121), the Hermes run adapter RFC (PR #2105 for #1925), the fork-from-here absolute-index fix (PR #2198 for #2184), and the opencode-go custom-provider overlap routing fix (PR #2204 for #1894).
+- **[@bergeouss](https://github.com/bergeouss)** — provider-management UI, OAuth status, two-container Docker docs, profile isolation hardening, Reveal-in-Finder, the OpenRouter free-tier live fetch, and most of Settings → Providers. 62 PRs.
+- **[@ai-ag2026](https://github.com/ai-ag2026)** — autonomous-AI contributor (Hermes Agent-driven). 55 PRs focused on session recovery (state.db sidecar reconciliation, orphan `.bak` recovery, audit + safe-repair endpoints), workspace/run lifecycle health, the crash-safe turn-journal RFC, the append-only turn-journal helper (PR #2059), the matching lifecycle-events layer (PR #2062), the `Content-Security-Policy-Report-Only` header (PR #2084), and the per-cron toast notification toggle (PR #2100).
+- **[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming, session recovery, workspace fallback, and a recent burst of presentation polish: the manual "Refresh usage" button on the Provider quota card (PR #2150), cancelled-turn status classification (PR #2151), Firefox sidebar scroll stabilization (PR #2200), early provisional session titles (PR #2202), target-aware "What's new?" links (PR #2207), and MCP tools overflow fix in Settings (PR #2210). 12 PRs total.
+- **[@LumenYoung](https://github.com/LumenYoung)** — newer contributor focused on the streaming hot path's correctness. 4 PRs including the original stale-stream writeback guard (PR #2136 — the bug class the next two releases extended), gateway-state alive-null classification (PR #2075), compression-banner anchor alignment (PR #2182), and context-progress ring auto-refresh on compression complete (PR #2188).
+- **[@iRonin](https://github.com/iRonin)** — security hardening sprint (PRs #196–#204): session memory leak fix, CSP + Permissions-Policy headers, slow-client connection timeout, optional HTTPS/TLS, upstream branch tracking, CLI session file-browser support. Six consecutive, focused, high-quality security PRs.
+- **[@indigokarasu](https://github.com/indigokarasu)** — visual redesign proposal (PR #213). Icon rail sidebar, design token system, 7 themes. Didn't merge as-is but shaped the design language that landed in v0.50.0.
+- **[@zenc-cp](https://github.com/zenc-cp)** — anti-hallucination guard for the ReAct loop (PR #133). Three-layer approach (ephemeral prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.
+- **[@deboste](https://github.com/deboste)** — reverse-proxy auth, mobile responsive layout, model routing (PRs #3, #4, #5). Three of the very first community PRs. Early foundation work.
+- **[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — security fixes spanning profile `.env` isolation (PR #351), session-import workspace validation (PR #2048), and bandit B105 hardening. Subtle, high-leverage credential and path-traversal fixes.
+- **[@lucasrc](https://github.com/lucasrc)** — auth-hardening trilogy in v0.51.57 (PRs #2191/#2192/#2193): thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on settings change, and the full 64-char HMAC-SHA256 session signature with backwards-compatible migration bridge. Three coordinated security PRs that landed together.
+- **[@jasonjcwu](https://github.com/jasonjcwu)** — composer and transcript polish, 16 PRs. Recent: silent compress-status during session switch (PR #2185), concurrent-send loss fix (PR #2186), in-transcript steer message badge (PR #2187), plus sidebar collapse via active-rail click (PR #2054).
+- **[@dobby-d-elf](https://github.com/dobby-d-elf)** — frontend reliability and motion polish: workspace fallback on deleted directories (PR #2138), iPhone PWA bottom-scroll fix (PR #2143), the new "Activity: X tools" composer footer animation (PR #2203) and its follow-up tuning (PR #2212).
 
-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.
+If you've contributed and aren't here, **open a PR**. We cross-check the CHANGELOG on every release, but if a credit fell through (a Co-authored-by trailer that didn't make it into the changelog entry, an attribution in a PR comment that should be in the release notes), this list is the right place to fix it.

DESIGN.md

@@ -140,7 +140,7 @@ Use almost no shadows in the transcript. Shadows are reserved for popovers, drop
 
 ### Tool/thinking activity group
 
-Collapsed by default in settled history and during live runs. Summary line uses one disclosure for internals, e.g. `Activity: thinking + 4 tools · read_file, patch, terminal`. Expanding reveals thinking and individual tool cards together. Thinking and tools should not create separate transcript rows unless there is an error or approval state that needs attention.
+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
 

Dockerfile

@@ -21,10 +21,11 @@ RUN apt-get update -y --fix-missing --no-install-recommends \
     apt-utils \
     locales \
     ca-certificates \
-    sudo \
     curl \
     rsync \
     openssh-client \
+    git \
+    xz-utils \
     && apt-get upgrade -y \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
@@ -41,24 +42,14 @@ 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 /workspace \
+    && chown -R hermeswebui:hermeswebui /home/hermeswebui /app /uv_cache /workspace \
+    && chmod 0755 /home/hermeswebui \
+    && chmod 1777 /app /uv_cache /workspace
 
 COPY --chmod=555 docker_init.bash /hermeswebui_init.bash
 
@@ -75,9 +66,7 @@ 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=hermeswebuitoo:hermeswebuitoo . /apptoo
+COPY --chown=root:root . /apptoo
 
 # Bake the git version tag into the image so the settings badge works even
 # when .git is not present (it is excluded by .dockerignore).
@@ -95,5 +84,8 @@ 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

@@ -68,7 +68,7 @@ What makes it different from other agentic tools:
   the results back into its own memory
 - **Self-hosted** — your conversations, your memory, your hardware
 
-**vs. the field** *(landscape is actively shifting — see [HERMES.md](HERMES.md) for the full breakdown)*:
+**vs. the field** *(landscape is actively shifting — see [docs/why-hermes.md](docs/why-hermes.md) for the full breakdown)*:
 
 | | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
 |---|---|---|---|---|---|
@@ -89,7 +89,7 @@ with memory, cron, and messaging. The key differences: Hermes writes and saves i
 automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
 Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
 has had security incidents involving malicious skills); and Hermes runs natively in the Python
-ecosystem. See [HERMES.md](HERMES.md) for the full side-by-side.
+ecosystem. See [docs/why-hermes.md](docs/why-hermes.md) for the full side-by-side.
 
 ---
 
@@ -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,8 +130,19 @@ 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).
+
+A community-maintained native Windows setup is documented at [@markwang2658/hermes-windows-native-guide](https://github.com/markwang2658/hermes-windows-native-guide) (companion setup repo: [@markwang2658/hermes-windows-native](https://github.com/markwang2658/hermes-windows-native)). Notes from the community report in [#1952](https://github.com/nesquena/hermes-webui/issues/1952):
+
+- **Memory:** community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
+- **What works:** chat, workspace browser, session management, all themes.
+- **Known limitations:** some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.
+- **Native Windows setup:** install Python 3.11+, then from the hermes-agent root in PowerShell: `python -m venv venv` → `pip install -r requirements.txt` → `pwsh .\start.ps1` (it auto-discovers `venv\Scripts\python.exe`).
+- **WSL2 relationship:** not a prerequisite — a WSL2-built venv (`venv/bin/python`, ELF) isn't invokable by native Windows Python, so use the native setup above. WSL2 stays useful as a parallel install if you want the full `bootstrap.py` + Linux runtime.
 
 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.
+For a step-by-step walkthrough of the wizard, provider choices, local model server Base URLs, and safe re-runs, see [`docs/onboarding.md`](docs/onboarding.md).
+If an AI assistant is helping with install, reinstall, bootstrap, provider setup, or first-run support, have it read [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) before running commands or inspecting logs.
 
 ---
 
@@ -192,6 +215,8 @@ 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).
+>
+> **Source boundary note (#2453)**: the multi-container setup mounts `hermes-agent-src` read-only into the WebUI by default. This prevents WebUI-side source rewrites but is still an implementation-coupling bridge, not a stable Agent API boundary. See [`docs/rfcs/agent-source-boundary.md`](docs/rfcs/agent-source-boundary.md) for the current source/API decoupling inventory.
 
 ### Common failure modes
 
@@ -218,7 +243,7 @@ For the deep dive on each of these, see [`docs/docker.md`](docs/docker.md).
 |---|---|
 | Hermes agent dir | `HERMES_WEBUI_AGENT_DIR` env, then `~/.hermes/hermes-agent`, then sibling `../hermes-agent` |
 | Python executable | Agent venv first, then `.venv` in this repo, then system `python3` |
-| State directory | `HERMES_WEBUI_STATE_DIR` env, then `~/.hermes/webui-mvp` |
+| State directory | `HERMES_WEBUI_STATE_DIR` env, then `~/.hermes/webui` |
 | Default workspace | `HERMES_WEBUI_DEFAULT_WORKSPACE` env, then `~/workspace`, then state dir |
 | Port | `HERMES_WEBUI_PORT` env or first argument, default `8787` |
 
@@ -248,11 +273,11 @@ 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_STATE_DIR` | `~/.hermes/webui` | 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_DEFAULT_MODEL` | *(provider default)* | Optional model override; leave unset to use the active Hermes provider default |
 | `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) |
@@ -312,6 +337,22 @@ That's it. Traffic is encrypted end-to-end by WireGuard, and password auth
 protects the UI at the application level. You can add it to your home screen
 for an app-like experience.
 
+### Community field report: ARM64 Android via AVF
+
+A community report in [#2364](https://github.com/nesquena/hermes-webui/issues/2364)
+documents Hermes Agent + WebUI running on a mid-range ARM64 Android phone inside
+a Debian 12 VM via Android Virtualization Framework (AVF). The reported setup
+used a Xiaomi Redmi Note 13 Pro 4G, 3.8 GiB RAM allocated to the VM, 8 visible
+CPU cores, Chrome on Android at `localhost:8787`, and cloud-hosted inference.
+
+This is not an official support baseline or provider/model benchmark, but it is
+a useful compatibility signal for mobile ARM64 experiments: the WebUI rendered
+smoothly in Chrome, ARM64 Debian worked for the agent stack, and the total local
+footprint was about 1.7 GB. Practical caveats from the report: first install can
+take longer when dependencies compile from source, Android browser tabs may
+reload when switching apps, and disabling battery optimization for the terminal
+or VM host may be needed for longer-running sessions.
+
 > **Tip:** If using Docker, set `HERMES_WEBUI_HOST=0.0.0.0` in your
 > `docker-compose.yml` environment (already the default) and set
 > `HERMES_WEBUI_PASSWORD`.
@@ -352,9 +393,9 @@ Or using the agent venv explicitly:
 /path/to/hermes-agent/venv/bin/python -m pytest tests/ -v
 ```
 
-Tests run against an isolated server on port 8788 with a separate state directory.
-Production data and real cron jobs are never touched. Current count: **3309 tests**
-across 100+ test files.
+Tests run against an isolated server with a separate state directory.
+Production data and real cron jobs are never touched. Current snapshot:
+**5303 tests collected** across **488 test files**.
 
 ---
 
@@ -362,7 +403,7 @@ across 100+ test files.
 
 ### Chat and agent
 - Streaming responses via SSE (tokens appear as they are generated)
-- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Z.AI); dynamic model dropdown populated from configured keys
+- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI); dynamic model dropdown populated from configured keys
 - Send a message while one is processing -- it queues automatically
 - Edit any past user message inline and regenerate from that point
 - Retry the last assistant response with one click
@@ -373,7 +414,7 @@ across 100+ test files.
 - Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
 - Approval card for dangerous shell commands (allow once / session / always / deny)
 - SSE auto-reconnect on network blips (SSH tunnel resilience)
-- File attachments persist across page reloads
+- File attachments persist across page reloads and are stored outside the active workspace by default (`~/.hermes/webui/attachments/<session_id>/`, or `HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/` when configured)
 - Message timestamps (HH:MM next to each message, full date on hover)
 - Code block copy button with "Copied!" feedback
 - Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
@@ -433,10 +474,13 @@ across 100+ test files.
 - CDN resources pinned with SRI integrity hashes
 
 ### Themes
-- 7 built-in themes: Dark (default), Light, Slate, Solarized Dark, Monokai, Nord, OLED
-- Switch via Settings panel dropdown (instant live preview) or `/theme` command
+- Appearance is split into two axes: Theme (`system`, `dark`, `light`) and Skin
+  (`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, `charizard`,
+  `sienna`, `catppuccin`, `nous`, `geist-contrast` / Geist Contrast)
+- Switch via Settings -> Appearance (instant live preview) or `/theme <theme-or-skin>`
 - Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
-- Custom themes: define a `:root[data-theme="name"]` CSS block and it works — see [THEMES.md](THEMES.md)
+- Skins use `data-skin` plus CSS variables; dark mode resolves through the
+  `.dark` class, not a `data-theme` custom-theme axis — see [THEMES.md](THEMES.md)
 
 ### Settings and configuration
 - **Hermes Control Center** (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
@@ -476,184 +520,183 @@ across 100+ test files.
 ## Architecture
 
 ```
-server.py               HTTP routing shell + auth middleware (~154 lines)
+server.py               HTTP routing shell + auth middleware (~446 lines)
 api/
-  auth.py               Optional password authentication, signed cookies (~201 lines)
-  config.py             Discovery, globals, model detection, reloadable config (~1110 lines)
-  helpers.py            HTTP helpers, security headers (~175 lines)
-  models.py             Session model + CRUD + CLI bridge (~377 lines)
-  onboarding.py         First-run onboarding wizard, OAuth provider support (~507 lines)
-  profiles.py           Profile state management, hermes_cli wrapper (~411 lines)
-  routes.py             All GET + POST route handlers (~2250 lines)
-  state_sync.py         /insights sync — message_count to state.db (~113 lines)
-  streaming.py          SSE engine, run_agent, cancel support (~660 lines)
-  updates.py            Self-update check and release notes (~257 lines)
-  upload.py             Multipart parser, file upload handler (~82 lines)
-  workspace.py          File ops, workspace helpers, git detection (~288 lines)
+  auth.py               Optional password authentication, signed cookies (~366 lines)
+  config.py             Discovery, globals, model detection, reloadable config (~4139 lines)
+  helpers.py            HTTP helpers, security headers (~302 lines)
+  models.py             Session model + CRUD + CLI bridge (~1927 lines)
+  onboarding.py         First-run onboarding wizard, OAuth provider support (~1002 lines)
+  profiles.py           Profile state management, hermes_cli wrapper (~1056 lines)
+  routes.py             All GET + POST route handlers (~9772 lines)
+  state_sync.py         /insights sync — message_count to state.db (~118 lines)
+  streaming.py          SSE engine, run_agent, cancel support (~4420 lines)
+  updates.py            Self-update check and release notes (~545 lines)
+  upload.py             Multipart parser, file upload handler (~284 lines)
+  workspace.py          File ops, workspace helpers, git detection (~810 lines)
 static/
-  index.html            HTML template (~600 lines)
-  style.css             All CSS incl. mobile responsive, themes (~1050 lines)
-  ui.js                 DOM helpers, renderMd, tool cards, context indicator (~1740 lines)
-  workspace.js          File preview, file ops, git badge (~286 lines)
-  sessions.js           Session CRUD, collapsible groups, search, reload recovery (~800 lines)
-  messages.js           send(), SSE handlers, live streaming, session recovery (~655 lines)
-  panels.js             Cron, skills, memory, profiles, settings (~1438 lines)
-  commands.js           Slash command autocomplete (~267 lines)
-  boot.js               Mobile nav, voice input, boot IIFE (~524 lines)
+  index.html            HTML template (~1323 lines)
+  style.css             All CSS incl. mobile responsive, themes (~3767 lines)
+  ui.js                 DOM helpers, renderMd, tool cards, context indicator (~7216 lines)
+  workspace.js          File preview, file ops, git badge (~369 lines)
+  sessions.js           Session CRUD, collapsible groups, search, reload recovery (~3517 lines)
+  messages.js           send(), SSE handlers, live streaming, session recovery (~2301 lines)
+  panels.js             Cron, skills, memory, profiles, settings (~6480 lines)
+  commands.js           Slash command autocomplete (~1302 lines)
+  boot.js               Mobile nav, voice input, boot IIFE (~1607 lines)
 tests/
-  conftest.py           Isolated test server (port 8788)
-  61 test files          961 test functions
+  conftest.py           Isolated test server/state fixtures
+  488 test files         5303 tests collected
 Dockerfile              python:3.12-slim container image
 docker-compose.yml      Compose with named volume and optional auth
 .github/workflows/      CI: multi-arch Docker build + GitHub Release on tag
 ```
 
-State lives outside the repo at `~/.hermes/webui-mvp/` by default
+State lives outside the repo at `~/.hermes/webui/` by default
 (sessions, workspaces, settings, projects, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`.
 
 ---
 
 ## Docs
 
-- `HERMES.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
+- `docs/why-hermes.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
 - `ROADMAP.md` -- feature roadmap and sprint history
 - `ARCHITECTURE.md` -- system design, all API endpoints, implementation notes
 - `TESTING.md` -- manual browser test plan and automated coverage reference
 - `CHANGELOG.md` -- release notes per sprint
 - `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets
 - `THEMES.md` -- theme system documentation, custom theme guide
+- `docs/CONTRACTS.md` -- project contract/RFC/design index for contributors and agents
+- `docs/UIUX-GUIDE.md` -- UI/UX principles sourced from existing design docs and visual inventories
+- `docs/docker.md` -- Docker compose setup, common failures, and bind-mount migration
+- `docs/supervisor.md` -- launchd, systemd, supervisord, runit, and s6 process-supervisor setup
+- `docs/onboarding.md` -- first-run wizard, provider setup, local model server Base URLs, and safe re-runs
+- `docs/onboarding-agent-checklist.md` -- safety rules, evidence commands, and pass/fail checks for assistant-led install or reinstall support
+- `docs/troubleshooting.md` -- diagnostic flows for common failures (e.g. "AIAgent not available")
+- `docs/wsl-autostart.md` -- WSL2 auto-start at Windows login
+- `docs/EXTENSIONS.md` -- administrator-controlled WebUI extension injection
+- `docs/rfcs/README.md` -- RFC index for larger architecture and durability proposals
 
 ## Contributors
 
-Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly or incorporated via batch release — shapes the project, and we're grateful to everyone who has taken the time to contribute.
+Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute.
 
-**66 contributors have shipped code that landed in a release tag** as of v0.50.245. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights:
+**137 contributors have shipped code that landed in a release tag** as of v0.51.58. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights:
 
-### Top contributors (by merged-PR count)
+### Top contributors (by PR count, including absorbed/batch-released work)
 
 | # | 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` |
+| 1 | [@franksong2702](https://github.com/franksong2702) | 117 | `v0.49.3` → `v0.51.58` |
+| 2 | [@Michaelyklam](https://github.com/Michaelyklam) | 92 | `v0.50.240` → `v0.51.57` |
+| 3 | [@bergeouss](https://github.com/bergeouss) | 62 | `v0.48.0` → `v0.51.46` |
+| 4 | [@ai-ag2026](https://github.com/ai-ag2026) | 55 | `v0.50.279` → `v0.51.47` |
+| 5 | [@dso2ng](https://github.com/dso2ng) | 23 | `v0.50.227` → `v0.51.51` |
+| 6 | [@jasonjcwu](https://github.com/jasonjcwu) | 16 | `v0.50.227` → `v0.51.55` |
+| 7 | [@Jordan-SkyLF](https://github.com/Jordan-SkyLF) | 12 | `v0.50.18` → `v0.51.58` |
+| 8 | [@aronprins](https://github.com/aronprins) | 10 | `v0.44.0` → `v0.50.233` |
+| 9 | [@JKJameson](https://github.com/JKJameson) | 10 | `v0.50.233` → `v0.51.31` |
+| 10 | [@starship-s](https://github.com/starship-s) | 10 | `v0.50.128` → `v0.51.58` |
 
-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.
+See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full ranked list of all 137 contributors, including everyone with one or two 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.
+**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (117 PRs, `v0.49.3` → `v0.51.58`)
+Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual `/compress` async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine.
+
+**[@Michaelyklam](https://github.com/Michaelyklam)** — Most prolific contributor of recent releases (92 PRs, `v0.50.240` → `v0.51.57`)
+Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), `/goal` command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894).
+
+**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + Docker hardening (62 PRs, `v0.48.0` → `v0.51.46`)
+Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile `.env` secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644).
+
+**[@ai-ag2026](https://github.com/ai-ag2026)** — Session recovery + audit infrastructure (55 PRs, `v0.50.279` → `v0.51.47`)
+Autonomous-AI contributor (Hermes Agent-driven) focused on durability: `state.db`-backed sidecar reconciliation (#2041), orphan `.json.bak` recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in `/health` (#2039), crash-safe turn-journal RFC at `docs/rfcs/turn-journal.md` (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), `Content-Security-Policy-Report-Only` header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014).
+
+**[@dso2ng](https://github.com/dso2ng)** — Session lineage + diagnostics (23 PRs, `v0.50.227` → `v0.51.51`)
+`/api/session/lineage-report/<sid>` endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), `session_source="fork"` continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading.
+
+**[@jasonjcwu](https://github.com/jasonjcwu)** — Composer + transcript polish (16 PRs, `v0.50.227` → `v0.51.55`)
+Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes.
+
+**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming + UX polish (12 PRs, `v0.50.18` → `v0.51.58`)
+Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210).
+
+**[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242, plus 9 follow-ups)
+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. Plus chat transcript redesign (#587), sidebar declutter (#584), three-column layout refactor (#899), light/dark theme + accent skins (#627), and shared `confirm()`/`prompt()` dialog replacement (PR #251 extracted from #242).
 
 **[@iRonin](https://github.com/iRonin)** — Security hardening sprint (PRs #196–#204)
-Six consecutive security and reliability PRs: session memory leak fix (expired token pruning), Content-Security-Policy + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file browser API. This is the kind of focused, high-quality security work that makes a self-hosted tool trustworthy.
+Six consecutive, focused security PRs: session memory leak fix (expired token pruning), CSP + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file-browser API. The kind of focused, high-quality security work that makes a self-hosted tool trustworthy.
+
+**[@lucasrc](https://github.com/lucasrc)** — Auth-hardening trilogy (PRs #2191, #2192, #2193)
+Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces.
+
+**[@LumenYoung](https://github.com/LumenYoung)** — Streaming hot-path correctness (4 PRs, `v0.51.47` → `v0.51.55`)
+The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase.
+
+**[@dobby-d-elf](https://github.com/dobby-d-elf)** — Frontend reliability + motion polish (6 PRs, `v0.51.38` → `v0.51.58`)
+Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212).
+
+**[@JKJameson](https://github.com/JKJameson)** — Composer + session polish (10 PRs)
+Persistent composer draft per session (#1956), and a long tail of polish across the composer and session sidebar.
+
+**[@gabogabucho](https://github.com/gabogabucho)** — Spanish locale + onboarding wizard
+Full Spanish (`es`) locale covering all UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch.
+
+**[@deboste](https://github.com/deboste)** — Reverse-proxy auth + mobile responsive layout (PRs #3, #4, #5)
+Three of the very first community PRs: fixed EventSource/fetch to use URL origin for reverse-proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.
+
+**[@indigokarasu](https://github.com/indigokarasu)** — Visual redesign proposal (PR #213)
+A CSS-only redesign of the full UI — proper design tokens, an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but shaped the design language and theme architecture that shipped in v0.50.0.
+
+**[@zenc-cp](https://github.com/zenc-cp)** — Anti-hallucination guard for the ReAct loop (PR #133)
+A three-layer approach (ephemeral anti-hallucination prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.
+
+**[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — Profile + session security (PRs #351, #2048)
+Profile `.env` secret isolation fix (PR #351) preventing API key leakage between profiles, and session-import workspace validation (PR #2048) blocking a crafted-JSON file-read against `/`.
+
+**[@Sanjays2402](https://github.com/Sanjays2402)** — Endless-scroll + Start-jump race fix (PR #1949)
+A generation-token + mutex pair fixing the v0.51.30 race between endless-scroll prefetch and Start-jump's `_ensureAllMessagesLoaded`. The naive same-flag-check approach (proposed in #1942 and #1962) was a no-op for the post-await race — Sanjays2402's fix was the correct shape.
+
+**[@fxd-jason](https://github.com/fxd-jason)** — Real-time approval + clarify via SSE (PRs #1350, #1355)
+Replaced 1.5s HTTP polling with SSE long-connections for both approval and clarify, cutting latency from up to 1.5s to near-instant. Got all the correctness details right (atomic subscribe + snapshot, notify-inside-lock, head-of-queue payload, trailing event re-emission).
+
+**[@happy5318](https://github.com/happy5318)** — Custom provider model dedup (PR #1947)
+Fixed the same model from different named custom providers being silently deduplicated in the picker, with Opus catching a race in the original tests that needed augmentation.
+
+**[@NocGeek](https://github.com/NocGeek)** — Streaming scroll + manual cron output persistence (7 PRs)
+Streaming scroll viewport stability when tool/queue cards insert (#1360), manual cron-run output and metadata persistence (#1372, split from held #1352).
 
 **[@DavidSchuchert](https://github.com/DavidSchuchert)** — German translation (PR #190)
-Complete German locale (`de`) covering all UI strings, settings labels, commands, and system messages — and in doing so, stress-tested the i18n system and exposed several elements that weren't yet translatable, which got fixed as part of the same PR.
+Complete German locale (`de`) covering all UI strings, settings labels, commands, and system messages — and stress-tested the i18n system, exposing several elements that weren't yet translatable and getting them fixed as part of the same PR.
 
-**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming, session recovery, workspace fallback (PRs #366, #367)
-Three interlocking improvements: workspace fallback resolution so the server recovers gracefully when the configured workspace is deleted or unavailable; live reasoning cards that upgrade the generic thinking spinner to a real-time reasoning display as the model thinks; and durable session state recovery via `localStorage` so in-flight tool cards, partial assistant output, and the live SSE stream all survive a full page reload or session switch.
-
-### Feature contributions
-
-**[@gabogabucho](https://github.com/gabogabucho)** — Spanish locale + onboarding wizard (PRs #275, #285)
-Full Spanish (`es`) locale covering all 175 UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch — the feature most responsible for new users actually getting started.
-
-**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + gateway sync + Docker hardening (18 PRs, `v0.50.49` → `v0.50.240`)
-Real-time gateway session sync (Telegram/Discord/Slack into the WebUI sidebar via SSE), the provider management UI for adding/editing custom providers from Settings, the two-container Docker setup docs, OAuth provider status detection, profile isolation hardening (per-profile `.env` secrets), and the bulk of what users see when they touch Settings → Providers.
-
-**[@ccqqlo](https://github.com/ccqqlo)** — Terminal approval UX + custom model discovery + mobile close button (PRs #224, #225, #238, #333)
-A run of focused quality-of-life improvements: terminal tool approval prompts that stay visible long enough to actually be read, restored custom model API key discovery, and the redundant mobile close button fix that had been confusing users on narrow screens.
+**[@Bobby9228](https://github.com/Bobby9228)** — Mobile Profiles button (PR #265)
+Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones.
 
 **[@kevin-ho](https://github.com/kevin-ho)** — OLED theme (PR #168)
-Added the 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk. Small diff, big impact for anyone on an OLED display.
-
-**[@Bobby9228](https://github.com/Bobby9228)** — Mobile Profiles button + Android Chrome fixes (PRs #253, #263, #265)
-Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones, plus a set of Android Chrome-specific fixes for the profile dropdown.
-
-**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (22 PRs, `v0.50.49` → `v0.50.245`)
-The session title guard, breadcrumb workspace navigation, mobile workspace panel sliver fix (#1300), composer footer container queries, streaming session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, and a long tail of polish across the session sidebar, mobile responsive layout, and workspace state machine.
-
-**[@betamod](https://github.com/betamod)** — Security hardening (PR #171)
-A comprehensive security audit PR covering CSRF protection, SSRF guards, XSS escaping improvements, and the env race condition between concurrent agent sessions — foundational security work that shipped in v0.39.0.
-
-**[@TaraTheStar](https://github.com/TaraTheStar)** — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
-Made the assistant display name configurable throughout the UI, added thinking/reasoning block display in chat, and refactored the login page to use template variables instead of inline string replacement.
-
-**[@thadreber-web](https://github.com/thadreber-web)** — CLI session bridge (PR #56)
-The original CLI session bridge: reads CLI sessions from the agent's SQLite state store and surfaces them in the WebUI sidebar. This was the first bridge between the CLI and WebUI session worlds.
-
-**[@deboste](https://github.com/deboste)** — Reverse proxy auth + mobile responsive layout + model routing (PRs #3, #4, #5)
-Three of the very first community PRs: fixed EventSource/fetch to use the URL origin for reverse proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.
-
-### Bug fix and security contributions
-
-**[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — Profile .env secret isolation (PR #351)
-Fixed API key leakage between profiles on switch — switching from a profile with `OPENAI_API_KEY` to one without it left the key in the process environment for the duration of the session, effectively leaking credentials. A subtle and important security fix.
-
-**[@lawrencel1ng](https://github.com/lawrencel1ng)** — Bandit security fixes B310/B324/B110 + QuietHTTPServer (PR #354)
-Systematic bandit security scan fixes: URL scheme validation before `urlopen`, MD5 `usedforsecurity=False`, and 40+ bare `except: pass` blocks replaced with proper logging — plus `QuietHTTPServer` to stop client-disconnect log spam from SSE streams.
-
-**[@lx3133584](https://github.com/lx3133584)** — CSRF fix for reverse proxy on non-standard ports (PR #360)
-Fixed CSRF rejection for deployments behind Nginx Proxy Manager or similar on non-standard ports — a real-world blocker for anyone hosting on a port other than 80/443.
-
-**[@DelightRun](https://github.com/DelightRun)** — session_search fix for WebUI sessions (PR #356)
-The `session_search` tool silently returned "Session database not available" in every WebUI session. Tracked down the missing `SessionDB` injection in the streaming path and fixed it.
-
-**[@shaoxianbilly](https://github.com/shaoxianbilly)** — Unicode filename downloads (PR #378)
-Fixed `UnicodeEncodeError` crashes when downloading workspace files with Chinese, Japanese, or other non-ASCII names. Implemented proper `Content-Disposition` header with RFC 5987 `filename*=UTF-8''...` encoding.
-
-**[@huangzt](https://github.com/huangzt)** — Cancel interrupts agent (PR #244)
-Made the Cancel button actually interrupt the running agent and clean up UI state, rather than just hiding the button while the agent kept running.
-
-**[@tgaalman](https://github.com/tgaalman)** — Thinking card fix (PR #169)
-Fixed top-level reasoning fields being missed in the thinking card display — an edge case in how Claude's extended thinking blocks surface in the API response.
-
-**[@smurmann](https://github.com/smurmann)** — Custom provider routing fix (PR #189)
-Fixed model routing for slash-prefixed custom provider models, which were being misrouted in the model selector. A precise fix for a real edge case in multi-provider setups.
-
-**[@jeffscottward](https://github.com/jeffscottward)** — Claude Haiku model ID fix (PR #145)
-Caught and corrected the Claude Haiku model ID (`3-5` → `4-5`) immediately after the Anthropic release — the kind of quick community catch that keeps the model dropdown accurate.
-
-**[@kcclaw001](https://github.com/kcclaw001)** — Credential redaction in API responses (PR #243)
-Added credential redaction to all API response paths so API keys, tokens, and other secrets in session data or error messages are masked before reaching the browser.
-
-**[@mbac](https://github.com/mbac)** — Phantom "Custom" provider group fix (PR #191)
-Removed the phantom "Custom" optgroup that appeared in the model dropdown even when no custom provider was configured — a small but consistently confusing UI noise issue.
+The 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk.
 
 **[@andrewy-wizard](https://github.com/andrewy-wizard)** — Chinese localization (PR #177)
-Added Simplified Chinese (`zh`) locale to the WebUI. One of the first non-English locales and the most-used non-English locale in the codebase.
+Initial Simplified Chinese (`zh`) locale. One of the first non-English locales.
 
-**[@mmartial](https://github.com/mmartial)** — Docker UID/GID matching (PR #237)
-Added Docker support for running as an arbitrary UID/GID matching the host user, eliminating permission issues with bind-mounted volumes — essential for Docker deployments where the host user isn't UID 1000.
+**[@DelightRun](https://github.com/DelightRun)** — `session_search` fix for WebUI sessions (PR #356)
+Tracked down the missing `SessionDB` injection in the streaming path that was silently breaking the tool for every WebUI session.
 
-**[@vCillusion](https://github.com/vCillusion)** — pip package resolution fix (PR #76)
-Fixed agent dependency resolution to prefer packages from the venv's site-packages over the agent directory itself, preventing shadowing bugs when developing locally.
+**[@lawrencel1ng](https://github.com/lawrencel1ng)** — Bandit security fixes (PR #354)
+Systematic bandit-scan fixes: URL scheme validation before `urlopen`, MD5 `usedforsecurity=False`, and 40+ bare `except: pass` blocks replaced with proper logging.
 
-**[@carlytwozero](https://github.com/carlytwozero)** — API key pass-through for non-Anthropic providers (PR #78)
-Fixed `api_key` not being passed to `AIAgent` for non-Anthropic `/anthropic` providers — a quiet regression that silently broke any non-default provider.
+**[@shaoxianbilly](https://github.com/shaoxianbilly)** — Unicode filename downloads (PR #378)
+Proper `Content-Disposition` with RFC 5987 `filename*=UTF-8''...` encoding so non-ASCII filenames download without crashing.
 
-**[@mangodxd](https://github.com/mangodxd)** — Type hints cleanup (PR #115)
-Added missing type hints across 10 files and corrected 9 inaccurate existing ones — the kind of maintenance work that makes the codebase easier to reason about.
+**[@lx3133584](https://github.com/lx3133584)** — CSRF fix for reverse proxy (PR #360)
+A real-world blocker for anyone hosting behind Nginx Proxy Manager or similar on a port other than 80/443.
 
-**[@Argonaut790](https://github.com/Argonaut790)** — HTML entity decode + Traditional Chinese locale (PR #239)
-Fixed double-escaping of HTML entities in `renderMd()` — LLM output containing `&lt;code&gt;` was being escaped a second time, rendering as literal text instead of the intended markdown. The same PR also completed the Simplified Chinese translation (40+ missing keys) and added a full Traditional Chinese (`zh-Hant`) locale.
+**[@betamod](https://github.com/betamod)** — Security audit (PR #171)
+A comprehensive CSRF / SSRF / XSS / env-race-condition audit that shipped in v0.39.0.
 
-**[@indigokarasu](https://github.com/indigokarasu)** — Visual redesign proposal: icon rail + design token system + 7 themes (PR #213)
-A CSS-only redesign of the full UI — proper design tokens (`--bg-primary`, `--text-info`, spacing scale), an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but directly shaped the design language and theme architecture that shipped in v0.50.0.
-
-**[@zenc-cp](https://github.com/zenc-cp)** — Anti-hallucination guard for ReAct loop (PR #133)
-Added a streaming token buffer and post-run message scrub to `streaming.py` to detect and strip fake tool execution JSON that weaker models write inline instead of calling tools properly. A three-layer approach: ephemeral anti-hallucination prompt, live token filtering, and session history cleanup. The pattern influenced later streaming.py improvements.
-
----
-
-Want to contribute? See [ARCHITECTURE.md](ARCHITECTURE.md) for the codebase layout and [TESTING.md](TESTING.md) for how to run the test suite. The best contributions are focused, well-tested, and solve a real problem — exactly what every person on this list did.
+**[@TaraTheStar](https://github.com/TaraTheStar)** — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
+Configurable assistant display name, thinking/reasoning block display, and a login page refactor.
 
 ## Repo
 

ROADMAP.md

@@ -2,7 +2,7 @@
 
 > Web companion to the Hermes Agent CLI. Same workflows, browser-native.
 >
-> Last updated: v0.50.287 (May 03, 2026) — 4053 tests collected
+> Last updated: v0.51.31 (May 9, 2026) — 5028 tests collected — Release H 12-PR contributor batch (image-mode fix + race fixes + composer drafts + locale parity + custom-provider dedup + TTL config + heartbeat polish)
 > Test source: `pytest tests/ --collect-only -q`
 > Per-version detail: see [CHANGELOG.md](./CHANGELOG.md)
 
@@ -168,7 +168,7 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 
 ### Slash commands
 - [x] Command registry + autocomplete dropdown
-- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/btw`, `/reasoning`, `/skills`, `/toolsets`
+- [x] 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
@@ -238,6 +238,7 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 - [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)
@@ -284,7 +285,6 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 
 - **Insights / monitoring suite** — agent heartbeat + alerts (#716), quota / rate-limit display (#706), data tabs (#722), monitor dashboard concepts (#766, #721)
 - **Native MCP server expose** — Hermes WebUI as an MCP server for direct agent integration (#733)
-- **Provider failover status** — show active provider per model + LLM Gateway failover state (#732)
 - **Teams / agents management panel** — editable names, roles, assignments (#719)
 - **Web UI profile model alignment with Hermes runtime** — design parity (#749)
 - **DOM windowing / message virtualization** — for sessions with hundreds of messages (#734)

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: 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.
+> Automated coverage: 5303 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 11 languages, and hundreds of 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.
@@ -533,7 +533,8 @@ FAIL: Sidebar causes layout overflow or blocks chat.
 ### T11.3: Structured Log Output
 SETUP: SSH access to the server.
 STEPS:
-  1. In a terminal: tail -f /tmp/webui-mvp.log
+  1. In a terminal: tail -f ~/.hermes/webui/bootstrap-8787.log
+     (or tail -f ~/.hermes/webui.log when launched through `ctl.sh`)
   2. In browser: perform any action (load page, send message, click file)
 EXPECT:
   - Log entries appear in terminal as JSON: {"ts":"...","method":"GET","path":"/health","status":200,"ms":0.1}
@@ -557,7 +558,7 @@ FAIL: Multiple messages sent while one is in flight.
 ### T12.2: Upload Failure Shows Status
 SETUP: Active session.
 STEPS:
-  1. Try to attach a file larger than 20MB (if available)
+  1. Try to attach a file larger than the configured upload limit (20MB by default; overridden by `HERMES_WEBUI_MAX_UPLOAD_MB` if set)
 EXPECT:
   - Status bar shows an error message about file size or the upload is rejected
   - The chat is not broken (can still send messages)
@@ -577,7 +578,7 @@ FAIL: Browser freezes, crash, or security issue.
 
 ## Automated Test Coverage Reference
 
-These behaviors are verified by pytest (run: venv/bin/python -m pytest webui-mvp/tests/ -v):
+These behaviors are verified by pytest (run: venv/bin/python -m pytest tests/ -v):
 
 Sprint 1 tests (test_sprint1.py):
   - Server health, session CRUD (create/load/update/delete/sort)
@@ -1835,8 +1836,8 @@ Bridged CLI sessions:
 
 ---
 
-*Last updated: v0.50.287, May 03, 2026*
-*Total automated tests collected: 4053*
+*Last updated: v0.51.54, May 13, 2026*
+*Total automated tests collected: 5303*
 *Regression gate: tests/test_regressions.py*
 *Run: pytest tests/ -v --timeout=60*
 *Source: <repo>/*

THEMES.md

@@ -1,19 +1,32 @@
 # Hermes Web UI — Themes
 
-Hermes Web UI supports pluggable color themes. Seven themes ship built-in, and
-you can create your own with pure CSS — no Python changes needed.
+Hermes Web UI splits **appearance** into two independent pickers:
+
+- **Theme** — the mode: `System`, `Dark`, or `Light`. Drives the background,
+  text, surface, and chrome colors.
+- **Skin** — the accent palette: built-in skins ship as named keys. Drives only
+  the `--accent` family (active states, links, focus rings, primary actions).
+
+You pick one of each and they combine, so the look adapts to your environment
+without losing your favorite accent — pure CSS, no Python changes needed.
 
 ---
 
-## Switching Themes
+## Switching Appearance
 
-**Settings panel:** Click the gear icon, select a theme from the dropdown. The
-preview is instant — the UI updates as you click through options.
+**Settings panel:** Click the gear icon → **Appearance**. The **Theme** card
+toggles Light/Dark/System; the **Skin** grid offers the built-in accent palettes.
+Preview is instant — the UI updates as you click.
 
-**Slash command:** Type `/theme dark` or `/theme light` in the composer.
+**Slash command:** Type `/theme <name>` in the composer. The command accepts
+both theme names (`system`, `dark`, `light`) and skin names (`default`, `ares`,
+`mono`, `slate`, `poseidon`, `sisyphus`, `charizard`, `sienna`,
+`catppuccin`, `nous`, `geist-contrast`). It updates the matching axis and leaves the other one
+alone.
 
-**Themes persist** across page reloads and server restarts (stored in
-`settings.json` server-side, with `localStorage` for flicker-free loading).
+**Persistence:** Both choices are stored in `localStorage` for flicker-free
+loading, and saved server-side via `POST /api/settings` (under `theme` and
+`skin` keys in `settings.json`).
 
 ---
 
@@ -21,125 +34,137 @@ preview is instant — the UI updates as you click through options.
 
 | Theme | Description |
 |-------|-------------|
-| **Dark** (default) | Deep navy/indigo with muted blue accents. Easy on the eyes for long sessions. |
-| **Light** | Warm off-white with dark text. High contrast for bright environments. |
-| **Slate** | Warm charcoal, lighter than Dark. Easier on the eyes for extended use. |
-| **Solarized Dark** | Ethan Schoonover's classic dark palette. Teal background, warm accents. |
-| **Monokai** | Warm dark theme inspired by the Monokai editor scheme. Green/pink accents. |
-| **Nord** | Arctic blue-gray palette from the Nord color system. Calm and minimal. |
-| **OLED** | True black (#000) backgrounds for OLED displays. Minimizes glow and burn-in risk. |
-| **Custom themes** | Any string accepted by `settings.json`, `POST /api/settings`, and `/theme` if added to the picker/command list. Pure CSS variables only. |
+| **System** (default) | Follows the OS `prefers-color-scheme` preference and updates live. |
+| **Dark** | Deep dark surfaces, low-glare for long sessions. |
+| **Light** | Bright surfaces with dark text, high contrast for daylight environments. |
+
+The theme is applied as a class on `<html>`: `.dark` is present for dark mode,
+absent for light. System mode tracks the OS preference at runtime.
+
+---
+
+## Built-in Skins
+
+| Skin | Description |
+|------|-------------|
+| **Default** | The original Hermes gold accent. Warm and understated. |
+| **Ares** | Fiery red. High-energy and assertive. |
+| **Mono** | Neutral gray. Distraction-free, for deep focus. |
+| **Slate** | Slate blue-gray. Subtle and grown-up. |
+| **Poseidon** | Ocean blue. Calm and focused for long sessions. |
+| **Sisyphus** | Vivid purple. Distinctive without being loud. |
+| **Charizard** | Warm orange. Energetic and easy on the eyes. |
+| **Sienna** | Warm clay and sand earth palette. Soft and natural. |
+| **Catppuccin** | Catppuccin Latte/Mocha palette with Mauve accent. |
+| **Nous** | Steel-blue accent with dashed technical surfaces. |
+| **Geist Contrast** (`geist-contrast`) | Geist-inspired monochrome surfaces with a restrained dark-mode `#FFF175` accent. |
+
+Each skin defines paired light + dark variants so it reads cleanly on either
+theme. The skin is applied as `data-skin="<name>"` on `<html>` (the default
+skin clears the attribute).
+
+---
+
+## Creating a Custom Skin
+
+A skin is a small CSS block that overrides the accent variables for both the
+light and dark variants:
+
+```css
+/* Light variant */
+:root[data-skin="my-skin"] {
+  --accent:           #2E7D32;                   /* Active states, links, primary buttons */
+  --accent-hover:     #1B5E20;                   /* Hover */
+  --accent-bg:        rgba(46,125,50,0.08);      /* Soft tinted backgrounds */
+  --accent-bg-strong: rgba(46,125,50,0.15);      /* Highlighted backgrounds */
+  --accent-text:      #1B5E20;                   /* Text on accent bg */
+}
+
+/* Dark variant — usually lighter or more saturated for contrast */
+:root.dark[data-skin="my-skin"] {
+  --accent:           #66BB6A;
+  --accent-hover:     #43A047;
+  --accent-bg:        rgba(102,187,106,0.08);
+  --accent-bg-strong: rgba(102,187,106,0.15);
+  --accent-text:      #66BB6A;
+}
+```
+
+Two ways to ship it:
+
+1. **In the repo (built-in):** add the block to `static/style.css`, register it
+   in the Settings skin picker (`static/index.html`) and in the `/theme` command
+   list (`static/commands.js`), then open a PR.
+
+2. **Self-hosted (no fork):** use the WebUI extensions surface — see
+   `docs/EXTENSIONS.md`. Drop your CSS in `HERMES_WEBUI_EXTENSION_DIR` and
+   declare it in `HERMES_WEBUI_EXTENSION_STYLESHEET_URLS`. No code changes
+   needed; the skin attribute can be set from your own JS.
+
+### Tips
+
+- **Test both themes.** A skin that pops on Dark can be illegible on Light.
+  Always check `:root[data-skin]` (light) *and* `:root.dark[data-skin]` (dark).
+- **Pick contrasting `--accent-text` on `--accent-bg`.** The strong variant
+  appears behind small labels and chips; weak contrast there reads as blur.
+- **The logo gradient uses `--accent` automatically**, so it adapts to your
+  skin without any extra work.
+- **No server changes needed.** The `skin` setting in `settings.json` accepts
+  any string, so your custom skin name persists without code changes once you
+  load the CSS.
 
 ---
 
 ## Creating a Custom Theme
 
-A theme is a CSS block that overrides the color variables. Add it to
-`static/style.css` (or a separate file that you link after the main stylesheet).
+A full custom *theme* (a different overall mood, not just an accent change) is
+a larger task than a skin: it has to redefine the core palette variables
+(`--bg`, `--surface`, `--text`, `--border`, `--code-bg`, and friends) for one
+or both modes. The contract is defined in the top `:root` and `:root.dark`
+blocks of `static/style.css` — start there.
 
-### Step 1: Define your theme block
-
-Every color in the UI comes from these CSS variables:
-
-```css
-:root[data-theme="your-theme-name"] {
-  /* Core palette */
-  --bg: #1a1a2e;          /* Main background */
-  --sidebar: #16213e;      /* Sidebar background */
-  --border: rgba(255,255,255,0.08);   /* Subtle borders */
-  --border2: rgba(255,255,255,0.14);  /* Stronger borders */
-  --text: #e8e8f0;         /* Primary text color */
-  --muted: #8888aa;        /* Secondary/muted text */
-  --accent: #e94560;       /* Accent color (errors, warnings, delete) */
-  --blue: #7cb9ff;         /* Primary action color (links, active states) */
-  --gold: #c9a84c;         /* Secondary accent (pinned items, gold highlights) */
-  --code-bg: #0d1117;      /* Code block background */
-
-  /* Surface and chrome (required for full theme polish) */
-  --surface: #1a2535;      /* Dropdowns, popups, toast, approval card */
-  --topbar-bg: rgba(22,33,62,.98);   /* Topbar background */
-  --main-bg: rgba(26,26,46,0.5);    /* Main chat area background */
-  --input-bg: rgba(255,255,255,.04); /* Input/button subtle backgrounds */
-  --hover-bg: rgba(255,255,255,.06); /* Hover state backgrounds */
-  --focus-ring: rgba(124,185,255,.35); /* Focus border color */
-  --focus-glow: rgba(124,185,255,.08); /* Focus box-shadow glow */
-
-  /* Typography (required for readable text across themes) */
-  --strong: #fff;          /* Bold text in messages */
-  --em: #c9c9e8;           /* Italic text in messages */
-  --code-text: #f0c27f;    /* Inline code text color */
-  --code-inline-bg: rgba(0,0,0,.35); /* Inline code background */
-  --pre-text: #e2e8f0;     /* Code block text color */
-}
-```
-
-The **core palette** controls the overall mood. The **surface/chrome** and
-**typography** variables are part of the standard theme contract — define all
-of them for a complete theme.
-
-For **light themes**, you also need `:root[data-theme="name"]` overrides
-for elements that use `rgba(255,255,255,.XX)` hover/border effects (these
-are invisible on light backgrounds). See the built-in light theme for the
-full pattern — it overrides ~45 selectors for proper dark-on-light contrast
-on hover states, borders, chips, role labels, session items, and
-interactive elements.
-
-### Step 2: Add it to the theme picker (optional)
-
-To make your theme appear in the Settings dropdown, add an `<option>` to the
-theme `<select>` in `static/index.html`:
-
-```html
-<option value="your-theme-name">Your Theme Name</option>
-```
-
-And update the `/theme` command's valid theme list in `static/commands.js`.
-
-### Step 3: Test it
-
-Switch to your theme via `/theme your-theme-name` or the Settings panel.
-Check these areas:
-- Sidebar session list (hover states, active state, project borders)
-- Message bubbles (user vs assistant styling)
-- Code blocks (background contrast, copy button visibility)
-- Tool cards (running indicator, expand/collapse)
-- Settings panel and login page
-- Mobile layout (hamburger sidebar, bottom nav)
-
-### Tips
-
-- **Light themes** need scrollbar and selection overrides, plus the full
-  text/code set (`--strong`, `--em`, `--code-text`, `--code-inline-bg`,
-  `--pre-text`) or they will look broken.
-- The **logo gradient** uses `--accent` automatically, so it adapts to your
-  theme without extra work.
-- **Prism.js syntax highlighting** uses its own CDN stylesheet (Tomorrow theme).
-  It works well on dark themes; on light themes the contrast is acceptable but
-  not perfect. Custom Prism theme support is planned for a future update.
-- **No server changes needed.** The `theme` setting in `settings.json` accepts
-  any string — your custom theme name will persist without code changes.
+Most of the time, a custom **skin** is what you actually want. Reach for a
+custom theme only when the existing Light/Dark modes don't fit (for example,
+a high-contrast accessibility theme or an OLED black variant).
 
 ---
 
-## How Themes Work Internally
+## Font Size
 
-1. Each theme is a `:root[data-theme="name"]` CSS block that overrides variables.
-2. Switching themes sets `document.documentElement.dataset.theme = name` in JS.
-3. A tiny inline `<script>` in `<head>` reads `localStorage` before the
-   stylesheet loads — this prevents a flash of the wrong theme on page load.
-4. The theme preference is saved server-side via `POST /api/settings` and
-   loaded on boot via `GET /api/settings`.
-5. The `/theme` command and Settings dropdown both update the DOM, localStorage,
-   and server settings simultaneously.
+Right under Theme/Skin in **Settings → Appearance**: `Small`, `Default`,
+`Large`. Applied as `data-font-size` on `<html>` and scales the WebUI's root
+font size. Persists alongside theme and skin.
 
 ---
 
-## Contributing a Theme
+## How It Works Internally
 
-To contribute a new built-in theme:
+1. **Theme:** `document.documentElement.classList.toggle('dark', isDark)` —
+   light mode removes the class. System mode tracks
+   `matchMedia('(prefers-color-scheme: dark)')`.
+2. **Skin:** `document.documentElement.dataset.skin = name` (or remove the
+   attribute for `default`).
+3. **Font size:** `document.documentElement.dataset.fontSize = size` (or
+   remove for `default`).
+4. **No flash on load:** a tiny inline `<script>` in `<head>` reads
+   `localStorage` before the stylesheet does, so the right look is applied
+   before paint.
+5. **Server sync:** preferences are saved via `POST /api/settings` and
+   rehydrated on boot via `GET /api/settings`.
 
-1. Add your `:root[data-theme="name"]` block to `static/style.css`
-2. Add the `<option>` to the Settings panel in `static/index.html`
-3. Add the theme name to the valid list in `cmdTheme()` in `static/commands.js`
-4. Test on desktop and mobile
-5. Open a PR — themes are pure CSS additions with no backend changes needed
+---
+
+## Contributing a Skin
+
+Skins are the easiest extension point — pure CSS, no Python, no JS logic. To
+contribute one upstream:
+
+1. Add your `:root[data-skin="name"]` and `:root.dark[data-skin="name"]`
+   blocks to `static/style.css`.
+2. Register it in the Settings skin picker in `static/index.html` and in the
+   skin list used by `cmdTheme()` in `static/commands.js`.
+3. Test on desktop and mobile across both Light and Dark themes.
+4. Open a PR — skins are pure CSS additions with no backend changes needed.
+
+For a custom *theme* (overriding the base palette), prefer opening an issue
+first to discuss scope, since it touches many selectors.

api/agent_health.py

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

api/agent_sessions.py

@@ -9,16 +9,21 @@ logger = logging.getLogger(__name__)
 
 MESSAGING_SOURCES = {
     'discord',
+    'email',
     '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',
+    'email': 'Email',
     'slack': 'Slack',
     'telegram': 'Telegram',
     'tool': 'Tool',
@@ -71,6 +76,115 @@ 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.
 
@@ -79,9 +193,20 @@ def _is_continuation_session(parent: dict | None, child: dict | None) -> bool:
     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
+    if str(child.get('session_source') or '').strip().lower() == 'fork':
+        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')
@@ -133,10 +258,13 @@ def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
         if not parent_id:
             continue
         children_by_parent.setdefault(parent_id, []).append(row)
-        if _is_continuation_session(rows_by_id.get(parent_id), 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
@@ -189,7 +317,7 @@ def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
         # 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',
+            'id', 'model', 'message_count', 'actual_message_count', 'actual_user_message_count',
             'ended_at', 'end_reason', 'last_activity',
         ):
             if key in tip:
@@ -243,6 +371,8 @@ def read_importable_agent_session_rows(
         # 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 "
@@ -253,6 +383,7 @@ def read_importable_agent_session_rows(
             return []
 
         parent_expr = _optional_col('parent_session_id', session_cols)
+        session_source_expr = _optional_col('session_source', 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)
@@ -263,9 +394,14 @@ def read_importable_agent_session_rows(
         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] = []
+        params: list[object] = []
         if exclude_sources:
             excluded = tuple(str(source) for source in exclude_sources if source)
             if excluded:
@@ -273,10 +409,10 @@ def read_importable_agent_session_rows(
                 where_clauses.append(f"s.source NOT IN ({placeholders})")
                 params.extend(excluded)
 
-        cur.execute(
-            f"""
+        select_sql = f"""
             SELECT s.id, s.title, s.model, s.message_count,
                    s.started_at, s.source,
+                   {session_source_expr},
                    {user_id_expr},
                    {chat_id_expr},
                    {chat_type_expr},
@@ -289,23 +425,225 @@ def read_importable_agent_session_rows(
                    {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,
-        )
+        """
+        if limit is not None:
+            result_limit = max(0, int(limit))
+            if result_limit == 0:
+                return []
+            # The sidebar only needs a small visible window. Bound the expensive
+            # messages join to a recent-activity candidate set instead of
+            # aggregating every historical Hermes state.db session before
+            # slicing in Python. The candidate ordering must include the latest
+            # message timestamp, not only ``started_at``: long-lived CLI sessions
+            # can be resumed days later and should still surface at the top.
+            # Oversampling preserves room for hidden compression segments or
+            # other rows filtered after projection.
+            candidate_limit = max(result_limit * 8, result_limit)
+            cur.execute(
+                f"""
+                WITH candidates AS (
+                    SELECT s.id
+                    FROM sessions s
+                    WHERE {' AND '.join(where_clauses)}
+                    ORDER BY COALESCE(
+                        (SELECT MAX(mx.timestamp) FROM messages mx WHERE mx.session_id = s.id),
+                        s.started_at
+                    ) DESC,
+                    s.started_at DESC
+                    LIMIT ?
+                )
+                {select_sql}
+                FROM sessions s
+                JOIN candidates c ON c.id = s.id
+                LEFT JOIN messages m ON m.session_id = s.id
+                GROUP BY s.id
+                ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC
+                """,
+                [*params, candidate_limit],
+            )
+        else:
+            cur.execute(
+                f"""
+                {select_sql}
+                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 _lineage_report_row(row: dict, role: str) -> dict:
+    updated_at = row.get('ended_at') if row.get('ended_at') is not None else row.get('started_at')
+    return {
+        'session_id': row.get('id'),
+        'role': role,
+        'title': row.get('title'),
+        'source': row.get('source'),
+        'started_at': row.get('started_at'),
+        'updated_at': updated_at,
+        'end_reason': row.get('end_reason'),
+        'active': row.get('ended_at') is None,
+        'archived': False,
+    }
+
+
+def _empty_lineage_report(session_id: str, *, found: bool = False) -> dict:
+    return {
+        'mutation': False,
+        'found': found,
+        'session_id': session_id,
+        'lineage_key': session_id,
+        'tip_session_id': session_id,
+        'total_segments': 0,
+        'materialized_segments': 0,
+        'segments': [],
+        'children': [],
+        'manual_review': False,
+    }
+
+
+def read_session_lineage_report(db_path: Path, session_id: str | None, max_hops: int = 20) -> dict:
+    """Return a bounded, read-only lifecycle report for a session lineage.
+
+    This helper intentionally reports only facts that can be derived from
+    ``state.db.sessions`` without mutating WebUI JSON, archiving rows, or
+    deleting historical segments. It mirrors the sidebar continuation rules so
+    a future UI/PR can explain which rows are hidden compression/cli-close
+    segments and which child-session branches remain distinct.
+    """
+    sid = str(session_id or '').strip()
+    if not sid:
+        return _empty_lineage_report('')
+    db_path = Path(db_path)
+    if not db_path.exists():
+        return _empty_lineage_report(sid)
+
+    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()}
+            required = {'id', 'parent_session_id', 'end_reason'}
+            if not required.issubset(session_cols):
+                return _empty_lineage_report(sid)
+
+            source_expr = _optional_col('source', session_cols)
+            session_source_expr = _optional_col('session_source', session_cols)
+            title_expr = _optional_col('title', session_cols)
+            started_expr = _optional_col('started_at', session_cols, '0')
+            ended_expr = _optional_col('ended_at', session_cols)
+            end_reason_expr = _optional_col('end_reason', session_cols)
+            parent_expr = _optional_col('parent_session_id', session_cols)
+
+            def fetch_one(row_id: str | None) -> dict | None:
+                if not row_id:
+                    return None
+                cur.execute(
+                    f"""
+                    SELECT s.id,
+                           {source_expr},
+                           {session_source_expr},
+                           {title_expr},
+                           {started_expr},
+                           {parent_expr},
+                           {ended_expr},
+                           {end_reason_expr}
+                    FROM sessions s
+                    WHERE s.id = ?
+                    """,
+                    (row_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+            target = fetch_one(sid)
+            if not target:
+                return _empty_lineage_report(sid)
+
+            segments = [target]
+            current = target
+            seen = {sid}
+            manual_review = False
+            for _hop in range(max(0, int(max_hops))):
+                parent_id = current.get('parent_session_id')
+                parent = fetch_one(parent_id)
+                if not parent or parent_id in seen:
+                    manual_review = bool(parent_id and parent_id in seen)
+                    break
+                if not _is_continuation_session(parent, current):
+                    break
+                segments.append(parent)
+                seen.add(parent_id)
+                current = parent
+            else:
+                manual_review = True
+
+            segment_ids = {row['id'] for row in segments}
+            child_rows: list[dict] = []
+            for parent in segments:
+                cur.execute(
+                    f"""
+                    SELECT s.id,
+                           {source_expr},
+                           {session_source_expr},
+                           {title_expr},
+                           {started_expr},
+                           {parent_expr},
+                           {ended_expr},
+                           {end_reason_expr}
+                    FROM sessions s
+                    WHERE s.parent_session_id = ?
+                    ORDER BY s.started_at DESC
+                    """,
+                    (parent['id'],),
+                )
+                for child_row in cur.fetchall():
+                    child = dict(child_row)
+                    if child['id'] in segment_ids:
+                        continue
+                    if _is_continuation_session(parent, child):
+                        # A continuation outside the selected path means the
+                        # lineage is branched or the caller selected an older
+                        # segment. Report manual review rather than proposing
+                        # destructive cleanup candidates.
+                        manual_review = True
+                        continue
+                    child_rows.append(child)
+    except Exception:
+        return _empty_lineage_report(sid)
+
+    root_id = segments[-1]['id'] if segments else sid
+    tip_id = segments[0]['id'] if segments else sid
+    return {
+        'mutation': False,
+        'found': True,
+        'session_id': sid,
+        'lineage_key': root_id,
+        'tip_session_id': tip_id,
+        'total_segments': len(segments),
+        'materialized_segments': len(segments),
+        'segments': [
+            _lineage_report_row(row, 'tip' if idx == 0 else 'hidden_segment')
+            for idx, row in enumerate(segments)
+        ],
+        'children': [_lineage_report_row(row, 'child_session') for row in child_rows],
+        'manual_review': manual_review,
+    }
+
+
 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.
 
@@ -330,6 +668,7 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
             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 {}
+            session_source_expr = _optional_col('session_source', session_cols)
             # 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
@@ -363,9 +702,9 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
                     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})
+                        SELECT s.id, s.source, {session_source_expr}, s.title, s.started_at, s.parent_session_id, s.ended_at, s.end_reason
+                        FROM sessions s
+                        WHERE s.id IN ({placeholders})
                         """,
                         chunk,
                     )
@@ -385,6 +724,10 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
         if not row:
             continue
 
+        state_title = str(row.get('title') or '').strip()
+        if state_title:
+            metadata.setdefault(sid, {})['_state_db_title'] = state_title
+
         parent_id = row.get('parent_session_id')
         parent_row = rows.get(parent_id) if parent_id else None
         if parent_id and parent_row:
@@ -394,6 +737,10 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
                 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

api/auth.py

@@ -11,21 +11,50 @@ import logging
 import os
 import secrets
 import tempfile
+import threading
 import time
 
 from api.config import STATE_DIR, load_settings
 
 logger = logging.getLogger(__name__)
 
+
+# Default session TTL — 30 days. Kept as a module-level constant for backwards
+# compatibility with downstream code and regression tests that import it.
+# At runtime, prefer ``_resolve_session_ttl()`` which honours the env var and
+# settings.json overrides; this constant is the floor / fallback.
+SESSION_TTL = 86400 * 30  # 30 days
+
+
+def _resolve_session_ttl() -> int:
+    """Resolve session TTL from env > settings > default.
+
+    Priority mirrors get_password_hash(): HERMES_WEBUI_SESSION_TTL env var
+    first, then settings.json, falling back to ``SESSION_TTL`` (30 days).
+    Clamped to [60s, 1 year] to prevent runaway cookies or self-lockout.
+    """
+    env_v = os.getenv('HERMES_WEBUI_SESSION_TTL', '').strip()
+    if env_v.isdigit():
+        val = int(env_v)
+        if 60 <= val <= 86400 * 365:
+            return val
+    s = load_settings()
+    v = s.get('session_ttl_seconds')
+    if isinstance(v, int) and 60 <= v <= 86400 * 365:
+        return v
+    return SESSION_TTL
+
+
 # ── Public paths (no auth required) ─────────────────────────────────────────
 PUBLIC_PATHS = frozenset({
-    '/login', '/health', '/favicon.ico',
+    '/login', '/health', '/favicon.ico', '/sw.js',
     '/api/auth/login', '/api/auth/status',
     '/manifest.json', '/manifest.webmanifest',
+    '/session/manifest.json', '/session/manifest.webmanifest',
 })
 
 COOKIE_NAME = 'hermes_session'
-SESSION_TTL = 86400 * 30  # 30 days
+CSRF_HEADER_NAME = 'X-Hermes-CSRF-Token'
 
 _SESSIONS_FILE = STATE_DIR / '.sessions.json'
 
@@ -77,66 +106,188 @@ def _save_sessions(sessions: dict[str, float]) -> None:
 _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, ...]
+_LOGIN_ATTEMPTS_LOCK = threading.Lock()
+
+
 def _check_login_rate(ip: str) -> bool:
-    """Return True if the IP is allowed to attempt login."""
-    now = time.time()
-    attempts = _login_attempts.get(ip, [])
-    # Prune old attempts
-    attempts = [t for t in attempts if now - t < _LOGIN_WINDOW]
-    _login_attempts[ip] = attempts
-    return len(attempts) < _LOGIN_MAX_ATTEMPTS
+    """Return True if the IP is allowed to attempt login (thread-safe)."""
+    with _LOGIN_ATTEMPTS_LOCK:
+        now = time.time()
+        attempts = _login_attempts.get(ip, [])
+        # Prune old attempts
+        attempts = [t for t in attempts if now - t < _LOGIN_WINDOW]
+        if attempts:
+            _login_attempts[ip] = attempts
+        else:
+            _login_attempts.pop(ip, None)
+        _save_login_attempts(_login_attempts)
+        return len(attempts) < _LOGIN_MAX_ATTEMPTS
+
 
 def _record_login_attempt(ip: str) -> None:
-    now = time.time()
-    attempts = _login_attempts.get(ip, [])
-    attempts.append(now)
-    _login_attempts[ip] = attempts
+    """Record a login attempt for rate limiting (thread-safe)."""
+    with _LOGIN_ATTEMPTS_LOCK:
+        now = time.time()
+        attempts = _login_attempts.get(ip, [])
+        attempts.append(now)
+        _login_attempts[ip] = attempts
+        _save_login_attempts(_login_attempts)
 
 
-def _signing_key():
-    """Return a random signing key, generating and persisting one on first call."""
-    key_file = STATE_DIR / '.signing_key'
+def _load_key(filename: str) -> bytes:
+    """Load a 32-byte key from STATE_DIR, generating and persisting one if missing."""
+    key_file = STATE_DIR / filename
     try:
         if key_file.exists():
             raw = key_file.read_bytes()
             if len(raw) >= 32:
                 return raw[:32]
-    except Exception:
-        logger.debug("Failed to read or access signing key file, using in-memory key")
-    # Generate a new random key
+    except OSError:
+        logger.debug("Failed to read key %s", filename)
     key = secrets.token_bytes(32)
     try:
         STATE_DIR.mkdir(parents=True, exist_ok=True)
         key_file.write_bytes(key)
         key_file.chmod(0o600)
-    except Exception:
-        logger.debug("Failed to persist signing key, using in-memory key only")
+    except OSError:
+        logger.debug("Failed to persist key %s", filename)
     return key
 
 
-def _hash_password(password):
+_PBKDF2_KEY_CACHE: bytes | None = None
+_SIGNING_KEY_CACHE: bytes | None = None
+
+
+def _pbkdf2_key() -> bytes:
+    global _PBKDF2_KEY_CACHE
+    if _PBKDF2_KEY_CACHE is None:
+        _PBKDF2_KEY_CACHE = _load_key('.pbkdf2_key')
+    return _PBKDF2_KEY_CACHE
+
+
+def _signing_key() -> bytes:
+    global _SIGNING_KEY_CACHE
+    if _SIGNING_KEY_CACHE is None:
+        _SIGNING_KEY_CACHE = _load_key('.signing_key')
+    return _SIGNING_KEY_CACHE
+
+
+def _hash_password(password, *, salt: bytes | None = None) -> str:
     """PBKDF2-SHA256 with 600k iterations (OWASP recommendation).
-    Salt is the persisted random signing key, which is secret and unique per
+    Salt is the persisted PBKDF2 key, which is secret and unique per
     installation. This keeps the stored hash format a plain hex string
     (no format change to settings.json) while replacing the predictable
-    STATE_DIR-derived salt from the original implementation."""
-    salt = _signing_key()
+    STATE_DIR-derived salt from the original implementation.
+
+    The *salt* parameter exists solely to support transparent migration
+    of password hashes that were computed with a different key (e.g. the
+    old `.signing_key`). Normal callers should never pass it.
+    """
+    if salt is None:
+        salt = _pbkdf2_key()
     dk = hashlib.pbkdf2_hmac('sha256', password.encode(), salt, 600_000)
     return dk.hex()
 
 
+_AUTH_HASH_LOCK = threading.Lock()
+_AUTH_HASH_COMPUTED: bool = False
+_AUTH_HASH_CACHE: str | None = None
+
+
+def _invalidate_password_hash_cache() -> None:
+    """Invalidate the in-process password hash cache so the next call to
+    get_password_hash() re-reads from settings.json or the env var."""
+    global _AUTH_HASH_COMPUTED, _AUTH_HASH_CACHE
+    with _AUTH_HASH_LOCK:
+        _AUTH_HASH_COMPUTED = False
+        _AUTH_HASH_CACHE = None
+
+
 def get_password_hash() -> str | None:
     """Return the active password hash, or None if auth is disabled.
-    Priority: env var > settings.json."""
-    env_pw = os.getenv('HERMES_WEBUI_PASSWORD', '').strip()
-    if env_pw:
-        return _hash_password(env_pw)
-    settings = load_settings()
-    return settings.get('password_hash') or None
+    Priority: env var > settings.json.
+
+    The hash is computed once and cached for the lifetime of the process.
+    PBKDF2-600k takes ~1 s and is called on nearly every HTTP request via
+    check_auth → is_auth_enabled, so caching avoids wasting a full second
+    of CPU per request after the first one.
+
+    Thread-safe: double-checked locking ensures that under a burst of
+    concurrent requests only one thread computes PBKDF2, while the fast
+    path (after initialisation) requires zero locks.
+    """
+    global _AUTH_HASH_COMPUTED, _AUTH_HASH_CACHE
+
+    # Fast path — no lock needed once cache is populated.
+    if _AUTH_HASH_COMPUTED:
+        return _AUTH_HASH_CACHE
+
+    with _AUTH_HASH_LOCK:
+        # Re-check inside lock — another thread may have populated while
+        # we were waiting to acquire.
+        if _AUTH_HASH_COMPUTED:
+            return _AUTH_HASH_CACHE
+
+        env_pw = os.getenv('HERMES_WEBUI_PASSWORD', '').strip()
+        if env_pw:
+            result = _hash_password(env_pw)
+        else:
+            result = load_settings().get('password_hash') or None
+
+        _AUTH_HASH_CACHE = result
+        _AUTH_HASH_COMPUTED = True
+        return result
 
 
 def is_auth_enabled() -> bool:
@@ -144,20 +295,43 @@ def is_auth_enabled() -> bool:
     return get_password_hash() is not None
 
 
-def verify_password(plain) -> bool:
-    """Verify a plaintext password against the stored hash."""
+def verify_password(plain: str) -> bool:
+    """Verify a plaintext password against the stored hash.
+
+    Supports transparent migration of password hashes that were computed
+    with the old `.signing_key` salt.  When the two keys differ and the
+    legacy-salted hash matches, the password is transparently re-hashed
+    with the current `.pbkdf2_key` and persisted to settings.json.
+    """
     expected = get_password_hash()
     if not expected:
         return False
-    return hmac.compare_digest(_hash_password(plain), expected)
+    # Fast path: current PBKDF2 key
+    if hmac.compare_digest(_hash_password(plain), expected):
+        return True
+    # Migration: some hashes were computed with `.signing_key` before the
+    # PBKDF2 key was separated.  Try the legacy salt; if it matches,
+    # transparently upgrade so the next login uses the fast path.
+    legacy_salt = _signing_key()
+    current_salt = _pbkdf2_key()
+    if legacy_salt != current_salt:
+        if hmac.compare_digest(_hash_password(plain, salt=legacy_salt), expected):
+            from api.config import save_settings
+
+            save_settings({'_set_password': plain})
+            # Password re-hashed and persisted to disk using the current salt.
+            # Cache invalidation is handled by fix 2/3 (#2192) which adds the
+            # _invalidate_password_hash_cache() call inside save_settings().
+            return True
+    return False
 
 
 def create_session() -> str:
     """Create a new auth session. Returns signed cookie value."""
     token = secrets.token_hex(32)
-    _sessions[token] = time.time() + SESSION_TTL
+    _sessions[token] = time.time() + _resolve_session_ttl()
     _save_sessions(_sessions)
-    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
+    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()
     return f"{token}.{sig}"
 
 
@@ -171,14 +345,20 @@ def _prune_expired_sessions():
         _save_sessions(_sessions)
 
 
-def verify_session(cookie_value) -> bool:
+def verify_session(cookie_value: str) -> bool:
     """Verify a signed session cookie. Returns True if valid and not expired."""
     if not cookie_value or '.' not in cookie_value:
         return False
     _prune_expired_sessions()  # lazy cleanup on every verification attempt
     token, sig = cookie_value.rsplit('.', 1)
-    expected_sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
-    if not hmac.compare_digest(sig, expected_sig):
+    full_sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()
+    # Accept both new (64-char) and legacy (32-char truncated) signatures so
+    # existing sessions survive the upgrade without a forced global logout.
+    # The legacy branch can be removed once session TTLs have expired (~30 days).
+    valid = hmac.compare_digest(sig, full_sig) or (
+        len(sig) == 32 and hmac.compare_digest(sig, full_sig[:32])
+    )
+    if not valid:
         return False
     expiry = _sessions.get(token)
     if not expiry or time.time() > expiry:
@@ -187,6 +367,37 @@ def verify_session(cookie_value) -> bool:
     return True
 
 
+def _session_token_from_cookie_value(cookie_value: str) -> str | None:
+    """Return the raw server-side session token from a signed cookie value."""
+    if not cookie_value or '.' not in cookie_value:
+        return None
+    token, _sig = cookie_value.rsplit('.', 1)
+    return token or None
+
+
+def csrf_token_for_session(cookie_value: str) -> str | None:
+    """Return the CSRF token bound to an authenticated WebUI session.
+
+    The browser can read this token from the authenticated shell and echoes it
+    in ``X-Hermes-CSRF-Token`` on unsafe API requests. The token is derived
+    from the HttpOnly session cookie's server-side token, so it automatically
+    rotates on login and is invalidated when the auth session expires or logs
+    out. Callers must still verify the auth session before trusting it.
+    """
+    token = _session_token_from_cookie_value(cookie_value)
+    if not token:
+        return None
+    return hmac.new(_signing_key(), f"csrf:{token}".encode(), hashlib.sha256).hexdigest()
+
+
+def verify_csrf_token(cookie_value: str, csrf_token: str) -> bool:
+    """Verify a submitted CSRF token against the authenticated session."""
+    if not cookie_value or not csrf_token or not verify_session(cookie_value):
+        return False
+    expected = csrf_token_for_session(cookie_value)
+    return bool(expected and hmac.compare_digest(str(csrf_token), expected))
+
+
 def invalidate_session(cookie_value) -> None:
     """Remove a session token."""
     if cookie_value and '.' in cookie_value:
@@ -224,10 +435,12 @@ def check_auth(handler, parsed) -> bool:
         return True
     # Not authorized
     if parsed.path.startswith('/api/'):
+        body = b'{"error":"Authentication required"}'
         handler.send_response(401)
         handler.send_header('Content-Type', 'application/json')
+        handler.send_header('Content-Length', str(len(body)))
         handler.end_headers()
-        handler.wfile.write(b'{"error":"Authentication required"}')
+        handler.wfile.write(body)
     else:
         handler.send_response(302)
         # Pass the original path as ?next= so login.js redirects back after auth.
@@ -256,11 +469,41 @@ def check_auth(handler, parsed) -> bool:
         # 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.send_header('Location', 'login?next=' + _next)
+        handler.send_header('Content-Length', '0')
         handler.end_headers()
     return False
 
 
+def _is_secure_context(handler=None) -> bool:
+    """Return True if cookies should carry the Secure flag.
+
+    Behaviour is overridable via HERMES_WEBUI_SECURE env var for
+    reverse-proxy setups where TLS terminates at a frontend proxy
+    (nginx, Cloudflare, etc.) and Python only sees plain HTTP.
+    1/true/yes → force Secure on; 0/false/no → force Secure off.
+    When unset, fall back to heuristics: direct TLS socket (getpeercert)
+    or X-Forwarded-Proto header from the request.
+
+    .. warning::
+       The ``X-Forwarded-Proto`` header is only trustworthy when a
+       reverse proxy (nginx, Cloudflare, etc.) is deployed in front
+       of the application.  Without a proxy, any client can forge the
+       header and cause the Secure flag to be set on plain HTTP.
+    """
+    env = os.getenv('HERMES_WEBUI_SECURE', '').strip().lower()
+    if env in ('1', 'true', 'yes'):
+        return True
+    if env in ('0', 'false', 'no'):
+        return False
+    if handler is not None:
+        if getattr(handler.request, 'getpeercert', None) is not None:
+            return True
+        if handler.headers.get('X-Forwarded-Proto', '') == 'https':
+            return True
+    return False
+
+
 def set_auth_cookie(handler, cookie_value) -> None:
     """Set the auth cookie on the response."""
     cookie = http.cookies.SimpleCookie()
@@ -268,9 +511,8 @@ def set_auth_cookie(handler, cookie_value) -> None:
     cookie[COOKIE_NAME]['httponly'] = True
     cookie[COOKIE_NAME]['samesite'] = 'Lax'
     cookie[COOKIE_NAME]['path'] = '/'
-    cookie[COOKIE_NAME]['max-age'] = str(SESSION_TTL)
-    # Set Secure flag when connection is HTTPS
-    if getattr(handler.request, 'getpeercert', None) is not None or handler.headers.get('X-Forwarded-Proto', '') == 'https':
+    cookie[COOKIE_NAME]['max-age'] = str(_resolve_session_ttl())
+    if _is_secure_context(handler):
         cookie[COOKIE_NAME]['secure'] = True
     handler.send_header('Set-Cookie', cookie[COOKIE_NAME].OutputString())
 

api/clarify.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import queue
 import threading
 import time
+import uuid
 from typing import Optional
 
 
@@ -25,12 +26,13 @@ _clarify_sse_subscribers: dict[str, list[queue.Queue]] = {}
 class _ClarifyEntry:
     """One pending clarify request inside a session."""
 
-    __slots__ = ("event", "data", "result")
+    __slots__ = ("event", "data", "result", "clarify_id")
 
     def __init__(self, data: dict):
         self.event = threading.Event()
         self.data = data
         self.result: Optional[str] = None
+        self.clarify_id: str = data.get("clarify_id", "") or uuid.uuid4().hex[:12]
 
 
 def register_gateway_notify(session_key: str, cb) -> None:
@@ -120,6 +122,11 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                 == list(data.get("choices_offered") or [])
             ):
                 entry = last
+                # Dedup re-uses the existing entry with its original clarify_id.
+                # If a future caller pre-populates clarify_id in data, it is
+                # silently discarded here — the original entry's id wins.
+                # Today no caller sets clarify_id (it's generated by __init__),
+                # so this is a non-issue.
                 cb = _gateway_notify_cbs.get(session_key)
                 # Keep _pending aligned to the oldest unresolved entry.
                 _pending[session_key] = gw_queue[0].data
@@ -131,6 +138,8 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                 return entry
 
         entry = _ClarifyEntry(data)
+        # Ensure clarify_id is present in the serialised data the frontend receives.
+        entry.data["clarify_id"] = entry.clarify_id
         gw_queue.append(entry)
         _pending[session_key] = gw_queue[0].data
         cb = _gateway_notify_cbs.get(session_key)
@@ -179,3 +188,28 @@ def resolve_clarify(session_key: str, response: str, resolve_all: bool = False)
         entry.event.set()
         count += 1
     return count
+
+
+def resolve_clarify_by_id(session_key: str, clarify_id: str, response: str) -> bool:
+    """Resolve a specific pending clarify request by its stable id.
+
+    Returns True if the id was found and resolved, False otherwise.
+    """
+    with _lock:
+        q = _gateway_queues.get(session_key)
+        if not q:
+            _pending.pop(session_key, None)
+            return False
+        for i, entry in enumerate(q):
+            if entry.clarify_id == clarify_id:
+                q.pop(i)
+                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)
+                entry.result = response
+                entry.event.set()
+                return True
+        return False

api/commands.py

@@ -53,4 +53,72 @@ def list_commands(_registry=None) -> list[dict[str, Any]]:
             'cli_only': bool(cmd.cli_only),
             'gateway_only': bool(cmd.gateway_only),
         })
+
+    # Include plugin-registered slash commands
+    try:
+        from hermes_cli.plugins import get_plugin_commands
+        plugin_cmds = get_plugin_commands() or {}
+        existing_names = {c['name'] for c in out}
+        for cmd_name, cmd_info in plugin_cmds.items():
+            if cmd_name in existing_names or cmd_name in _NEVER_EXPOSE:
+                continue
+            out.append({
+                'name': cmd_name,
+                'description': str(cmd_info.get('description', 'Plugin command')),
+                'category': 'Plugin',
+                'aliases': [],
+                'args_hint': str(cmd_info.get('args_hint', '')),
+                'subcommands': [],
+                'cli_only': False,
+                'gateway_only': False,
+            })
+    except Exception:
+        pass
+
     return out
+
+
+def execute_plugin_command(command: str) -> str:
+    """Execute a plugin-registered slash command and return printable output.
+
+    Unknown commands raise ``KeyError`` so the HTTP layer can return 404.
+    Plugin handler failures are returned as output text instead of surfacing as
+    transport errors, matching Hermes' existing slash-command UX.
+    """
+
+    raw = str(command or "").strip()
+    if not raw:
+        raise ValueError("command is required")
+
+    cmd_text = raw[1:] if raw.startswith("/") else raw
+    cmd_parts = cmd_text.split(maxsplit=1)
+    cmd_base = (cmd_parts[0] if cmd_parts else "").strip().lower()
+    cmd_arg = cmd_parts[1] if len(cmd_parts) > 1 else ""
+    if not cmd_base:
+        raise ValueError("command is required")
+
+    try:
+        from hermes_cli.plugins import (
+            get_plugin_command_handler,
+            resolve_plugin_command_result,
+        )
+    except ImportError as exc:
+        raise RuntimeError("plugin command runtime unavailable") from exc
+
+    try:
+        handler = get_plugin_command_handler(cmd_base)
+    except Exception as exc:
+        raise RuntimeError(f"plugin command lookup failed: {exc}") from exc
+
+    if not handler:
+        raise KeyError(cmd_base)
+
+    try:
+        result = resolve_plugin_command_result(handler(cmd_arg))
+        return str(result or "(no output)")
+    except Exception as exc:
+        # Don't leak raw exception str (paths, env, internal state) to the
+        # user-facing chat. Type name is enough for the user to know what
+        # class of failure occurred; full traceback lives in the server log.
+        logger.warning("Plugin command %r failed", cmd_base, exc_info=exc)
+        return f"Plugin command error: {type(exc).__name__}"

api/compression_anchor.py

@@ -0,0 +1,133 @@
+"""
+Shared helpers for session compression anchor metadata.
+
+Manual compression anchoring versus automatic compression paths
+===============================================================
+
+When ``auto_compression=True`` is passed to ``visible_messages_for_anchor()``,
+the function accepts a broader set of message content types (including
+provider-style ``input_text`` / ``output_text`` parts) and metadata markers
+(``reasoning``, ``thinking``, etc.) from any non-tool role. This enables the
+streaming auto-compression path to determine which messages should anchor
+compression UI metadata without being limited to the legacy manual-compression
+rules.
+
+When ``auto_compression=False`` (the default), the function applies the
+historical manual-compression rules: only plain ``text`` content parts from
+non-assistant roles are counted.
+
+Why this module exists
+======================
+
+Compression anchoring needs to identify which messages in a session transcript
+are semantically significant enough to seed the compression UI metadata (e.g.,
+message count, token budget display). The original implementation hard-coded
+these rules in multiple places. This module consolidates the logic so that:
+
+1. Manual compression anchoring (CLI/legacy path) uses the stricter ruleset.
+2. Automatic compression (streaming/agent path) can leverage the relaxed ruleset
+   when it knows it is handling provider-style messages.
+
+Callers specify ``auto_compression=True`` when the messages may originate from
+an automatic/compression-aware pipeline, and ``False`` (default) for manual
+compression contexts.
+"""
+
+
+def _content_text(content, *, part_types):
+    if isinstance(content, list):
+        return "\n".join(
+            str(part.get("text") or part.get("content") or "")
+            for part in content
+            if isinstance(part, dict) and part.get("type") in part_types
+        ).strip()
+    return str(content or "").strip()
+
+
+def _content_has_part_type(content, part_types):
+    if not isinstance(content, list):
+        return False
+    return any(
+        isinstance(part, dict) and part.get("type") in part_types
+        for part in content
+    )
+
+
+def is_context_compression_marker(message):
+    """Return true for synthetic compression/reference cards, not user turns."""
+    if not isinstance(message, dict):
+        return False
+    role = message.get("role")
+    if not role or role == "tool":
+        return False
+    text = _content_text(
+        message.get("content", ""),
+        part_types={"text", "input_text", "output_text"},
+    ).lower().lstrip()
+    return (
+        text.startswith("[context compaction")
+        or text.startswith("context compaction")
+        or text.startswith("[your active task list was preserved across context compression]")
+    )
+
+
+def _is_context_compression_marker(message):
+    """Backward-compatible alias for callers that have not switched yet."""
+    return is_context_compression_marker(message)
+
+
+def visible_messages_for_anchor(messages, *, auto_compression: bool = False):
+    """Return transcript messages that can anchor compression UI metadata.
+
+    Manual compression historically only counted plain ``text`` content parts
+    for non-assistant messages, while the streaming auto-compression path also
+    accepted provider-style ``input_text`` / ``output_text`` parts and metadata
+    markers on any non-tool role. Keep that difference explicit at the call site
+    instead of carrying two near-identical helper implementations.
+    """
+    out = []
+    text_part_types = {"text", "input_text", "output_text"} if auto_compression else {"text"}
+    for message in messages or []:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        if not role or role == "tool":
+            continue
+        if _is_context_compression_marker(message):
+            continue
+
+        content = message.get("content", "")
+        has_attachments = bool(message.get("attachments"))
+        text = _content_text(content, part_types=text_part_types)
+
+        if auto_compression:
+            has_tool_calls = bool(
+                isinstance(message.get("tool_calls"), list) and message.get("tool_calls")
+            )
+            has_tool_use = _content_has_part_type(content, {"tool_use"})
+            has_reasoning = bool(message.get("reasoning"))
+            if not text:
+                has_reasoning = has_reasoning or _content_has_part_type(
+                    content,
+                    {"thinking", "reasoning"},
+                )
+            if text or has_attachments or has_tool_calls or has_tool_use or has_reasoning:
+                out.append(message)
+            continue
+
+        if role == "assistant":
+            has_tool_calls = bool(
+                isinstance(message.get("tool_calls"), list) and message.get("tool_calls")
+            )
+            has_tool_use = _content_has_part_type(content, {"tool_use"})
+            has_reasoning = bool(message.get("reasoning")) or _content_has_part_type(
+                content,
+                {"thinking", "reasoning"},
+            )
+            if text or has_attachments or has_tool_calls or has_tool_use or has_reasoning:
+                out.append(message)
+            continue
+
+        if text or has_attachments:
+            out.append(message)
+    return out

api/dashboard_probe.py

@@ -0,0 +1,255 @@
+"""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, urlunparse
+
+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 normalize_dashboard_browser_url(raw_url: str | None) -> str:
+    """Return a safe browser-only dashboard link URL.
+
+    Unlike the server-side probe target, this value is only returned to the
+    browser for navigation.  It may point at a public reverse-proxy hostname, but
+    it still rejects credentials, paths, query strings, fragments, and non-HTTP
+    schemes so it cannot hide secrets or script URLs in config.
+    """
+    raw = str(raw_url or "").strip()
+    if not raw:
+        return ""
+    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")
+    if not parsed.hostname:
+        raise ValueError("invalid dashboard URL host")
+    if parsed.params or parsed.query or parsed.fragment:
+        raise ValueError("invalid dashboard URL path")
+    path = parsed.path or ""
+    if path not in ("", "/"):
+        raise ValueError("invalid dashboard URL path")
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("invalid dashboard URL port") from exc
+    host = parsed.hostname.lower()
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    netloc = host
+    if port is not None:
+        if not (1 <= port <= 65535):
+            raise ValueError("invalid dashboard URL port")
+        netloc = f"{netloc}:{port}"
+    return urlunparse((parsed.scheme, netloc, "", "", "", ""))
+
+
+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:
+        raw_url = normalize_dashboard_browser_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 = normalize_dashboard_browser_url(raw_url) if raw_url else ""
+
+    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:
+        browser_url = normalize_dashboard_browser_url(raw_url) if raw_url else ""
+    except ValueError:
+        return {"running": False, "enabled": enabled, "error": "invalid dashboard url"}
+    try:
+        override = normalize_dashboard_url(raw_url)
+    except ValueError:
+        override = None
+
+    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":
+        if browser_url and not override:
+            return {"running": True, "enabled": enabled, "url": browser_url, "browser_url": browser_url}
+        host, port, scheme, base = targets[0]
+        return {"running": True, "enabled": enabled, "host": host, "port": port, "url": browser_url or base, "browser_url": browser_url or 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
+            if browser_url:
+                result["browser_url"] = browser_url
+                result["url"] = browser_url
+            return result
+    return {"running": False, "enabled": enabled}

api/goals.py

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

api/helpers.py

@@ -2,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
@@ -45,7 +46,7 @@ def _security_headers(handler):
         "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'; "
+        "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'"
     )
@@ -111,7 +112,8 @@ MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
 
 def _build_redact_fn():
     """Return a redactor backed by hermes-agent plus local fallback patterns."""
-    # Minimal fallback covering the most common credential prefixes.
+    # Fallback mirrors the agent's known credential prefixes so WebUI API
+    # responses remain a hard redaction boundary even without hermes-agent.
     # 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(
@@ -123,10 +125,34 @@ def _build_redact_fn():
         r"|ghu_[A-Za-z0-9]{10,}"          # GitHub user-to-server token
         r"|ghs_[A-Za-z0-9]{10,}"          # GitHub server-to-server token
         r"|ghr_[A-Za-z0-9]{10,}"          # GitHub refresh token
+        r"|xox[baprs]-[A-Za-z0-9-]{10,}"  # Slack tokens
+        r"|AIza[A-Za-z0-9_-]{30,}"        # Google API keys
+        r"|pplx-[A-Za-z0-9]{10,}"         # Perplexity
+        r"|fal_[A-Za-z0-9_-]{10,}"        # Fal.ai
+        r"|fc-[A-Za-z0-9]{10,}"           # Firecrawl
+        r"|bb_live_[A-Za-z0-9_-]{10,}"    # BrowserBase
+        r"|gAAAA[A-Za-z0-9_=-]{20,}"      # Codex encrypted tokens
         r"|AKIA[A-Z0-9]{16}"              # AWS Access Key ID
-        r"|xox[baprs]-[A-Za-z0-9-]{10,}" # Slack tokens
-        r"|hf_[A-Za-z0-9]{10,}"          # HuggingFace token
-        r"|SG\.[A-Za-z0-9_-]{10,}"       # SendGrid API key
+        r"|sk_live_[A-Za-z0-9]{10,}"      # Stripe secret key (live)
+        r"|sk_test_[A-Za-z0-9]{10,}"      # Stripe secret key (test)
+        r"|rk_live_[A-Za-z0-9]{10,}"      # Stripe restricted key
+        r"|SG\.[A-Za-z0-9_-]{10,}"        # SendGrid API key
+        r"|hf_[A-Za-z0-9]{10,}"           # HuggingFace token
+        r"|r8_[A-Za-z0-9]{10,}"           # Replicate API token
+        r"|npm_[A-Za-z0-9]{10,}"          # npm access token
+        r"|pypi-[A-Za-z0-9_-]{10,}"       # PyPI API token
+        r"|dop_v1_[A-Za-z0-9]{10,}"       # DigitalOcean PAT
+        r"|doo_v1_[A-Za-z0-9]{10,}"       # DigitalOcean OAuth
+        r"|am_[A-Za-z0-9_-]{10,}"         # AgentMail API key
+        r"|sk_[A-Za-z0-9_]{10,}"          # ElevenLabs TTS key
+        r"|tvly-[A-Za-z0-9]{10,}"         # Tavily search API key
+        r"|exa_[A-Za-z0-9]{10,}"          # Exa search API key
+        r"|gsk_[A-Za-z0-9]{10,}"          # Groq Cloud API key
+        r"|syt_[A-Za-z0-9]{10,}"          # Matrix access token
+        r"|retaindb_[A-Za-z0-9]{10,}"     # RetainDB API key
+        r"|hsk-[A-Za-z0-9]{10,}"          # Hindsight API key
+        r"|mem0_[A-Za-z0-9]{10,}"         # Mem0 Platform API key
+        r"|brv_[A-Za-z0-9]{10,}"          # ByteRover API key
         r")(?![A-Za-z0-9_-])"
     )
     _AUTH_HDR_RE = _re.compile(r"(Authorization:\s*Bearer\s+)(\S+)", _re.IGNORECASE)
@@ -178,6 +204,103 @@ def _build_redact_fn():
 _redact_fn_cached = _build_redact_fn()
 
 
+_SENSITIVE_CASE_MARKERS = (
+    "sk-",
+    "ghp_",
+    "github_pat_",
+    "gho_",
+    "ghu_",
+    "ghs_",
+    "ghr_",
+    "AKIA",
+    "xoxb-",
+    "xoxa-",
+    "xoxp-",
+    "xoxr-",
+    "xoxs-",
+    "AIza",
+    "pplx-",
+    "fal_",
+    "fc-",
+    "bb_live_",
+    "gAAAA",
+    "sk_live_",
+    "sk_test_",
+    "rk_live_",
+    "SG.",
+    "hf_",
+    "r8_",
+    "npm_",
+    "pypi-",
+    "dop_v1_",
+    "doo_v1_",
+    "am_",
+    "sk_",
+    "tvly-",
+    "exa_",
+    "gsk_",
+    "syt_",
+    "retaindb_",
+    "hsk-",
+    "mem0_",
+    "brv_",
+    "eyJ",
+    "-----BEGIN",
+)
+_SENSITIVE_LOWER_MARKERS = (
+    "authorization: bearer ",
+    "private key",
+    "postgres://",
+    "postgresql://",
+    "mysql://",
+    "mongodb://",
+    "redis://",
+    "amqp://",
+    "://",  # stage-348 Opus SHOULD-FIX: catch http(s)/ws(s)/ftp URL userinfo + sensitive query params (#2171 follow-up)
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "api_key",
+    "apikey",
+    "client_secret",
+    "auth_token",
+    "raw_secret",
+    "secret_input",
+    "key_material",
+    "x-amz-signature",
+    "token=",
+    "secret=",
+    "password=",
+    "authorization=",
+    "key=",
+    '"token"',
+    '"secret"',
+    '"password"',
+    '"bearer"',
+)
+_SENSITIVE_TELEGRAM_MARKER_RE = _re.compile(r"(?:bot)?\d{8,}:[-A-Za-z0-9_]{30,}")
+_SENSITIVE_DISCORD_MARKER_RE = _re.compile(r"<@!?\d{17,20}>")
+_SENSITIVE_PHONE_MARKER_RE = _re.compile(r"(?<![A-Za-z0-9])\+[1-9]\d{6,14}(?![A-Za-z0-9])")
+
+
+def _might_contain_sensitive_text(text: str) -> bool:
+    """Cheap prefilter before the full agent+fallback redaction pass."""
+    if not isinstance(text, str) or not text:
+        return False
+    if any(marker in text for marker in _SENSITIVE_CASE_MARKERS):
+        return True
+    lower = text.lower()
+    if any(marker in lower for marker in _SENSITIVE_LOWER_MARKERS):
+        return True
+    if ":" in text and _SENSITIVE_TELEGRAM_MARKER_RE.search(text):
+        return True
+    if "<@" in text and _SENSITIVE_DISCORD_MARKER_RE.search(text):
+        return True
+    if "+" in text and _SENSITIVE_PHONE_MARKER_RE.search(text):
+        return True
+    return False
+
+
 def _redact_text(text: str, *, _enabled: bool | None = None) -> str:
     """Redact sensitive text from API responses. Respects api_redact_enabled setting.
 
@@ -193,6 +316,8 @@ def _redact_text(text: str, *, _enabled: bool | None = None) -> str:
         _enabled = bool(load_settings().get("api_redact_enabled", True))
     if not _enabled:
         return text
+    if not _might_contain_sensitive_text(text):
+        return text
     return _redact_fn_cached(text)
 
 
@@ -252,8 +377,13 @@ def read_body(handler) -> dict:
 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 hermes_profile cookie value from the request, or None."""
+    """Extract the active-profile cookie value from the request, or None."""
     cookie_header = handler.headers.get('Cookie', '')
     if not cookie_header:
         return None
@@ -263,7 +393,8 @@ def get_profile_cookie(handler) -> str | None:
         cookie.load(cookie_header)
     except _hc.CookieError:
         return None
-    morsel = cookie.get(PROFILE_COOKIE_NAME)
+    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
@@ -274,7 +405,7 @@ def get_profile_cookie(handler) -> str | None:
 
 
 def build_profile_cookie(name: str) -> str:
-    """Build a Set-Cookie header value for the hermes_profile cookie.
+    """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
@@ -287,8 +418,9 @@ def build_profile_cookie(name: str) -> str:
     """
     import http.cookies as _hc
     cookie = _hc.SimpleCookie()
-    cookie[PROFILE_COOKIE_NAME] = name
-    cookie[PROFILE_COOKIE_NAME]['path'] = '/'
-    cookie[PROFILE_COOKIE_NAME]['httponly'] = True
-    cookie[PROFILE_COOKIE_NAME]['samesite'] = 'Lax'
-    return cookie[PROFILE_COOKIE_NAME].OutputString()
+    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

@@ -1,17 +1,17 @@
 """
 Hermes Web UI -- Streaming performance metering.
 
-Tracks Tokens Per Second (TPS) across all active WebUI sessions, and the
-HIGH/LOW TPS values observed over the past 60 minutes.  Metering data is
-emitted via SSE events so the header label can update live during a stream.
+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 session is:
+Each streaming session is tracked independently.  TPS per stream is:
 
-    session_tps = total_tokens / (last_token_ts - first_token_ts)
+    stream_tps = total_stream_deltas / (last_delta_ts - first_delta_ts)
 
-The global tps is the average of all currently active sessions' TPS values.
+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.
 
@@ -19,8 +19,8 @@ For HIGH/LOW tracking, every stats snapshot records the current global tps
 (only when > 0 — idle periods are skipped) into a rolling 60-minute history.
 The max/min of that history gives the peak throughput observed over the past hour.
 
-The ticker in streaming.py calls get_interval() — it returns 1.0 when sessions
-are actively receiving tokens so the header updates at 1 Hz, and 10.0 when idle
+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
@@ -28,15 +28,17 @@ Usage from api/streaming.py
   from api.metering import meter
 
   meter().begin_session(stream_id)                     # stream starts
-  meter().record_token(stream_id, running_output)     # per output token
-  meter().record_reasoning(stream_id, running_reasoning_len)  # per reasoning token
+  meter().record_token(stream_id, running_output_deltas)
+  meter().record_reasoning(stream_id, running_reasoning_deltas)
 
 The SSE `metering` event payload:
   {
-    "tps": 47.3,    # average TPS across active sessions (real-time)
-    "high": 52.1,   # highest average TPS observed in the past 60 minutes
-    "low":  31.4,   # lowest average TPS (excl. readings < 1 tps, to ignore idle)
-    "active": 1,    # sessions currently streaming
+    "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,
   }
 """
 
@@ -60,9 +62,9 @@ class _SessionMeter:
     def total_tokens(self) -> int:
         return self.output_tokens + self.reasoning_tokens
 
-    def tps(self) -> float:
+    def tps(self) -> float | None:
         if self.first_token_ts == 0.0 or self.last_token_ts <= self.first_token_ts:
-            return 0.0
+            return None
         return self.total_tokens() / (self.last_token_ts - self.first_token_ts)
 
 
@@ -148,12 +150,15 @@ class GlobalMeter:
             if not self._sessions:
                 self._window_start = now
 
-            # Compute global tps: average of per-session TPS values
+            # 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]
-            if active:
-                global_tps = sum(s.tps() for s in active) / len(active)
+            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 = 0.0
+                global_tps = None
 
             # Prune readings older than 1 hour
             cutoff = now - _HOUR_SECS
@@ -162,7 +167,7 @@ class GlobalMeter:
             # Only record this snapshot for HIGH/LOW if there is active work.
             # This prevents idle periods from flooding the history and keeps
             # HIGH/LOW meaningful for the past hour of actual throughput.
-            if global_tps > 0:
+            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)
@@ -171,9 +176,11 @@ class GlobalMeter:
             low = min(active_readings) if active_readings else 0.0
 
             return {
-                'tps': round(global_tps, 1),
-                'high': round(high, 1),
-                'low': round(low, 1),
+                '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),
             }
 

api/oauth.py

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

api/onboarding.py

@@ -53,6 +53,8 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "requires_base_url": False,
         "models": list(_PROVIDER_MODELS.get("anthropic", [])),
         "category": "easy_start",
+        "oauth_provider": "anthropic",
+        "oauth_label": "Claude Code OAuth",
     },
     "openai": {
         "label": "OpenAI",
@@ -137,6 +139,15 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "models": list(_PROVIDER_MODELS.get("deepseek", [])),
         "category": "specialized",
     },
+    "xiaomi": {
+        "label": "Xiaomi MiMo",
+        "env_var": "XIAOMI_API_KEY",
+        "default_model": "mimo-v2.5-pro",
+        "default_base_url": "https://api.xiaomimimo.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("xiaomi", [])),
+        "category": "specialized",
+    },
     "zai": {
         "label": "Z.AI / GLM (智谱)",
         "env_var": "GLM_API_KEY",
@@ -185,8 +196,9 @@ _PROVIDER_CATEGORIES = [
 ]
 
 _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."
 )
 
 
@@ -300,6 +312,44 @@ class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
 
 
 _PROBE_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+_DNS_ONLY_TEST_TLDS = frozenset({"invalid", "test", "example"})
+
+
+def _hostname_uses_reserved_dns_tld(hostname: str | None) -> bool:
+    host = str(hostname or "").strip().rstrip(".").lower()
+    if not host or "." not in host:
+        return False
+    return host.rsplit(".", 1)[-1] in _DNS_ONLY_TEST_TLDS
+
+
+def _exception_chain_text(exc) -> str:
+    parts: list[str] = []
+    seen: set[int] = set()
+    cur = exc
+    while cur is not None and id(cur) not in seen:
+        seen.add(id(cur))
+        parts.append(str(cur))
+        cur = getattr(cur, "__cause__", None) or getattr(cur, "__context__", None)
+    return " ".join(parts).lower()
+
+
+def _probe_failure_is_dns(exc, hostname: str | None) -> bool:
+    if isinstance(exc, socket.gaierror):
+        return True
+    text = _exception_chain_text(exc)
+    if any(
+        marker in text
+        for marker in (
+            "getaddrinfo",
+            "gaierror",
+            "name or service not known",
+            "temporary failure in name resolution",
+            "nodename nor servname provided",
+            "no address associated with hostname",
+        )
+    ):
+        return True
+    return _hostname_uses_reserved_dns_tld(hostname)
 
 
 def probe_provider_endpoint(
@@ -404,7 +454,7 @@ def probe_provider_endpoint(
         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):
+        if _probe_failure_is_dns(reason, parsed.hostname):
             return {
                 "ok": False,
                 "error": "dns",
@@ -421,6 +471,12 @@ def probe_provider_endpoint(
     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
+        if _probe_failure_is_dns(exc, parsed.hostname):
+            return {
+                "ok": False,
+                "error": "dns",
+                "detail": f"could not resolve host '{parsed.hostname}'",
+            }
         logger.debug("probe_provider_endpoint unexpected error", exc_info=True)
         return {"ok": False, "error": "unreachable", "detail": str(exc)[:200]}
 
@@ -537,7 +593,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
@@ -581,10 +637,11 @@ def _provider_oauth_authenticated(provider: str, hermes_home: "Path") -> bool:
     used by current Hermes runtime auth resolution.
     """
     provider = (provider or "").strip().lower()
+    provider = {"claude": "anthropic", "claude-code": "anthropic"}.get(provider, provider)
     if not provider:
         return False
 
-    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous"}
+    _known_oauth_providers = {"openai-codex", "copilot", "copilot-acp", "qwen-oauth", "nous", "anthropic"}
     if provider not in _known_oauth_providers:
         return False
 
@@ -606,7 +663,16 @@ def _provider_oauth_authenticated(provider: str, hermes_home: "Path") -> bool:
         if isinstance(pool_store, dict):
             entries = pool_store.get(provider)
             if isinstance(entries, list):
-                return any(_oauth_payload_has_token(entry) for entry in entries)
+                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:
@@ -647,6 +713,10 @@ def _status_from_runtime(cfg: dict, imports_ok: bool) -> dict:
                     )
                 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,
@@ -729,6 +799,8 @@ def _build_setup_catalog(cfg: dict) -> dict:
                 "models": list(meta.get("models", [])),
                 "category": meta.get("category", "easy_start"),
                 "quick": meta.get("quick", False),
+                "oauth_provider": meta.get("oauth_provider") or "",
+                "oauth_label": meta.get("oauth_label") or "",
             }
         )
 
@@ -748,9 +820,9 @@ def _build_setup_catalog(cfg: dict) -> dict:
     # 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,
@@ -915,11 +987,13 @@ def apply_onboarding_setup(body: dict) -> dict:
     if not api_key and not _provider_api_key_present(provider, cfg, env_values):
         # Providers that may run keyless (lmstudio, ollama, custom — gated by
         # `key_optional` in _SUPPORTED_PROVIDER_SETUPS) are allowed to onboard
-        # with no api_key.  The agent runtime substitutes a placeholder
-        # (LMSTUDIO_NOAUTH_PLACEHOLDER) for those, and the probe (#1499) gives
-        # the user immediate feedback if their server actually does require
-        # auth (http_4xx with status 401).  See #1499 third sub-bug from #1420.
-        if not provider_meta.get("key_optional"):
+        # 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", {})

api/profiles.py

@@ -5,16 +5,21 @@ Wraps hermes_cli.profiles to provide profile switching for the web UI.
 The web UI maintains a process-level "active profile" that determines which
 HERMES_HOME directory is used for config, skills, memory, cron, and API keys.
 Profile switches update os.environ['HERMES_HOME'] and monkey-patch module-level
-cached paths in hermes-agent modules (skills_tool, cron/jobs) that snapshot
-HERMES_HOME at import time.
+cached paths in hermes-agent modules (skills_tool, skill_manager_tool,
+cron/jobs) that snapshot HERMES_HOME at import time.
 """
 import json
 import logging
 import os
 import re
 import shutil
+import sys
 import threading
+from contextlib import contextmanager
 from pathlib import Path
+from typing import Optional
+
+from api.session_events import publish_session_list_changed
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +42,78 @@ _loaded_profile_env_keys: set[str] = set()
 # process-global _active_profile.
 _tls = threading.local()
 
+_SKILL_HOME_MODULES = ("tools.skills_tool", "tools.skill_manager_tool")
+
+
+def snapshot_skill_home_modules() -> dict[str, dict[str, object]]:
+    """Snapshot imported skill-module path globals before a temporary patch."""
+    snapshot: dict[str, dict[str, object]] = {}
+    for module_name in _SKILL_HOME_MODULES:
+        module = sys.modules.get(module_name)
+        if module is None:
+            snapshot[module_name] = {"module_present": False}
+            continue
+        snapshot[module_name] = {
+            "module_present": True,
+            "has_HERMES_HOME": hasattr(module, "HERMES_HOME"),
+            "HERMES_HOME": getattr(module, "HERMES_HOME", None),
+            "has_SKILLS_DIR": hasattr(module, "SKILLS_DIR"),
+            "SKILLS_DIR": getattr(module, "SKILLS_DIR", None),
+        }
+    return snapshot
+
+
+def patch_skill_home_modules(home: Path) -> None:
+    """Patch imported skill modules that cache HERMES_HOME at import time."""
+    for module_name in _SKILL_HOME_MODULES:
+        module = sys.modules.get(module_name)
+        if module is None:
+            continue
+        try:
+            module.HERMES_HOME = home
+            module.SKILLS_DIR = home / "skills"
+        except AttributeError:
+            logger.debug("Failed to patch %s module", module_name)
+
+
+def restore_skill_home_modules(snapshot: dict[str, dict[str, object]]) -> None:
+    """Restore skill-module globals captured by snapshot_skill_home_modules()."""
+    for module_name, values in snapshot.items():
+        module = sys.modules.get(module_name)
+        if not values.get("module_present"):
+            if module is not None:
+                sys.modules.pop(module_name, None)
+                parent_name, _, child_name = module_name.rpartition(".")
+                parent = sys.modules.get(parent_name)
+                if parent is not None:
+                    try:
+                        delattr(parent, child_name)
+                    except AttributeError:
+                        pass
+            continue
+        if module is None:
+            continue
+        for attr in ("HERMES_HOME", "SKILLS_DIR"):
+            has_attr = bool(values.get(f"has_{attr}"))
+            try:
+                if has_attr:
+                    setattr(module, attr, values.get(attr))
+                else:
+                    try:
+                        delattr(module, attr)
+                    except AttributeError:
+                        pass
+            except AttributeError:
+                logger.debug("Failed to restore %s.%s", module_name, attr)
+
+
+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/.
 
@@ -56,20 +133,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'
 
@@ -91,6 +170,103 @@ 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.
 
@@ -123,22 +299,290 @@ def clear_request_profile() -> None:
     _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
+    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.
     """
-    name = get_active_profile_name()
-    if name == 'default':
-        return _DEFAULT_HERMES_HOME
-    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / name
-    if profile_dir.is_dir():
-        return profile_dir
-    return _DEFAULT_HERMES_HOME
+    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)
+        try:
+            with cron_profile_context_for_home(_home_for_scheduled_cron_job(job)):
+                return original(job, *args, **kwargs)
+        finally:
+            publish_session_list_changed("cron_complete")
+
+    _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.
 
@@ -150,10 +594,7 @@ def get_hermes_home_for_profile(name: str) -> Path:
     empty, 'default', or does not match the profile-name format (rejects path
     traversal such as '../../etc').
     """
-    if not name or name == 'default' or not _PROFILE_ID_RE.fullmatch(name):
-        return _DEFAULT_HERMES_HOME
-    profile_dir = _DEFAULT_HERMES_HOME / 'profiles' / name
-    return profile_dir
+    return _resolve_profile_home_for_name(name)
 
 
 _TERMINAL_ENV_MAPPINGS = {
@@ -239,17 +680,99 @@ def get_profile_runtime_env(home: Path) -> dict[str, str]:
     return env
 
 
+@contextmanager
+def profile_env_for_background_worker(
+    session,
+    purpose: str = "background worker",
+    logger_override: Optional[logging.Logger] = None,
+):
+    """Temporarily route detached worker config reads through a profile.
+
+    Background WebUI workers run outside the request/streaming thread that
+    established the profile-scoped environment.  Workers that read agent config,
+    runtime provider settings, or skill paths must temporarily apply the
+    session/request profile env or they can fall back to the server-default
+    profile. Pass either a session-like object with `.profile` or a profile name.
+    """
+    log = logger_override or logger
+    raw_profile = session if isinstance(session, str) else getattr(session, "profile", "")
+    profile = str(raw_profile or "").strip()
+    if not profile or profile == "default":
+        yield
+        return
+
+    try:
+        # Lazy imports avoid a module-load cycle: streaming imports this helper.
+        from api.config import _clear_thread_env, _set_thread_env, _thread_ctx
+        from api.streaming import _ENV_LOCK
+
+        profile_home_path = Path(get_hermes_home_for_profile(profile))
+        runtime_env = get_profile_runtime_env(profile_home_path)
+    except Exception:
+        log.debug(
+            "Failed to resolve profile env for %s profile %s; falling back to current env",
+            purpose,
+            profile,
+            exc_info=True,
+        )
+        yield
+        return
+
+    thread_env = dict(runtime_env)
+    thread_env["HERMES_HOME"] = str(profile_home_path)
+    # Hybrid profile routing: keep the broad runtime env in WebUI's thread-local
+    # channel for WebUI helpers, and also mirror it into process env for the
+    # worker body because several production Hermes readers still call
+    # os.getenv() directly for provider credentials.  Keep the _ENV_LOCK scope
+    # narrow: serialize only setup/restore, not the whole worker body.
+    skill_home_snapshot = None
+    old_runtime_env: dict[str, Optional[str]] = {}
+    old_hermes_home = None
+    had_hermes_home = False
+    previous_thread_env = getattr(_thread_ctx, "env", {}).copy()
+    try:
+        _set_thread_env(**thread_env)
+        with _ENV_LOCK:
+            old_runtime_env = {key: os.environ.get(key) for key in runtime_env}
+            had_hermes_home = "HERMES_HOME" in os.environ
+            old_hermes_home = os.environ.get("HERMES_HOME")
+            skill_home_snapshot = snapshot_skill_home_modules()
+            os.environ.update(runtime_env)
+            os.environ["HERMES_HOME"] = str(profile_home_path)
+            try:
+                patch_skill_home_modules(profile_home_path)
+            except Exception:
+                log.debug(
+                    "Failed to patch skill modules for %s profile %s",
+                    purpose,
+                    profile,
+                    exc_info=True,
+                )
+        yield
+    finally:
+        if previous_thread_env:
+            _set_thread_env(**previous_thread_env)
+        else:
+            _clear_thread_env()
+        with _ENV_LOCK:
+            for key, old_value in old_runtime_env.items():
+                if old_value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old_value
+            if had_hermes_home:
+                os.environ["HERMES_HOME"] = old_hermes_home or ""
+            else:
+                os.environ.pop("HERMES_HOME", None)
+            if skill_home_snapshot is not None:
+                restore_skill_home_modules(skill_home_snapshot)
+
+
 def _set_hermes_home(home: Path):
     """Set HERMES_HOME env var and monkey-patch cached module-level paths."""
     os.environ['HERMES_HOME'] = str(home)
 
-    # Patch skills_tool module-level cache (snapshots HERMES_HOME at import)
-    try:
-        import tools.skills_tool as _sk
-        _sk.HERMES_HOME = home
-        _sk.SKILLS_DIR = home / 'skills'
-    except (ImportError, AttributeError):
-        logger.debug("Failed to patch skills_tool module")
+    patch_skill_home_modules(home)
 
     # Patch cron/jobs module-level cache
     try:
@@ -261,6 +784,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.
@@ -306,6 +837,7 @@ 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)
 
 
@@ -329,16 +861,21 @@ def switch_profile(name: str, *, process_wide: bool = True) -> 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)
@@ -356,7 +893,7 @@ def switch_profile(name: str, *, process_wide: bool = True) -> dict:
         # 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')
+            ap_file.write_text('' if _is_root_profile(name) else name, encoding='utf-8')
         except Exception:
             logger.debug("Failed to write active profile file")
 
@@ -382,10 +919,12 @@ def switch_profile(name: str, *, process_wide: bool = True) -> dict:
             cfg = {}
     model_cfg = cfg.get('model', {})
     default_model = None
+    default_model_provider = None
     if isinstance(model_cfg, str):
         default_model = model_cfg
     elif isinstance(model_cfg, dict):
         default_model = model_cfg.get('default')
+        default_model_provider = model_cfg.get('provider')
 
     # Read the target profile's workspace directly from *home* rather than via
     # get_last_workspace() which routes through the thread-local/process-global active
@@ -437,6 +976,7 @@ def switch_profile(name: str, *, process_wide: bool = True) -> dict:
         'profiles': list_profiles_api(),
         'active': name,
         'default_model': default_model,
+        'default_model_provider': default_model_provider,
         'default_workspace': default_workspace,
     }
 
@@ -526,7 +1066,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
@@ -567,16 +1107,158 @@ def _write_endpoint_to_config(profile_dir: Path, base_url: str = None, api_key:
     config_path.write_text(_yaml.dump(cfg, default_flow_style=False, allow_unicode=True), encoding='utf-8')
 
 
+def _clean_profile_config_value(value: Optional[str], field: str) -> Optional[str]:
+    """Return a safe single-line config value or raise ValueError."""
+    if value is None:
+        return None
+    cleaned = str(value).strip()
+    if not cleaned:
+        return None
+    if any(ch in cleaned for ch in ("\x00", "\r", "\n")):
+        raise ValueError(f"{field} must be a single-line value")
+    if len(cleaned) > 512:
+        raise ValueError(f"{field} is too long")
+    return cleaned
+
+
+def _split_webui_provider_model_value(default_model: Optional[str], model_provider: Optional[str]) -> tuple[Optional[str], Optional[str]]:
+    """Normalize WebUI-internal @provider:model picker values for config.yaml."""
+    model = _clean_profile_config_value(default_model, "default_model")
+    provider = _clean_profile_config_value(model_provider, "model_provider")
+    if model and model.startswith("@") and ":" in model:
+        provider_part, model_part = model[1:].rsplit(":", 1)
+        provider = provider or _clean_profile_config_value(provider_part, "model_provider")
+        model = _clean_profile_config_value(model_part, "default_model")
+    return model, provider
+
+
+def _strip_webui_provider_prefix(model_id: object) -> str:
+    value = str(model_id or "").strip()
+    if value.startswith("@") and ":" in value:
+        return value.rsplit(":", 1)[1]
+    return value
+
+
+def _profile_model_selection_exists(
+    available_models: object,
+    default_model: Optional[str],
+    model_provider: Optional[str],
+) -> bool:
+    """Return True when a profile default model/provider exists in /api/models."""
+    if not default_model and not model_provider:
+        return True
+    if not isinstance(available_models, dict):
+        return False
+
+    provider_seen = False
+    model_seen = False
+    for group in available_models.get("groups", []) or []:
+        if not isinstance(group, dict):
+            continue
+        provider_id = str(group.get("provider_id") or "").strip()
+        if model_provider and provider_id != model_provider:
+            continue
+        if model_provider and provider_id == model_provider:
+            provider_seen = True
+        for model in group.get("models", []) or []:
+            if not isinstance(model, dict):
+                continue
+            model_id = str(model.get("id") or "").strip()
+            if not model_id:
+                continue
+            if default_model and (
+                model_id == default_model
+                or _strip_webui_provider_prefix(model_id) == default_model
+            ):
+                model_seen = True
+                if model_provider:
+                    return True
+        if not default_model and provider_seen:
+            return True
+
+    if model_provider and not provider_seen:
+        return False
+    return bool(model_seen)
+
+
+def _get_available_models_for_profile_validation() -> dict:
+    from api.config import get_available_models
+
+    return get_available_models()
+
+
+def _validate_profile_model_selection(
+    default_model: Optional[str],
+    model_provider: Optional[str],
+    available_models: Optional[dict] = None,
+) -> None:
+    """Reject profile model defaults that do not exist in the server catalog."""
+    if not default_model and not model_provider:
+        return
+    catalog = (
+        available_models
+        if available_models is not None
+        else _get_available_models_for_profile_validation()
+    )
+    if _profile_model_selection_exists(catalog, default_model, model_provider):
+        return
+    if default_model and model_provider:
+        raise ValueError(
+            f"Selected model '{default_model}' is not available for provider '{model_provider}'"
+        )
+    if default_model:
+        raise ValueError(f"Selected model '{default_model}' is not available")
+    raise ValueError(f"Selected model provider '{model_provider}' is not available")
+
+
+def _write_model_defaults_to_config(
+    profile_dir: Path,
+    *,
+    default_model: Optional[str] = None,
+    model_provider: Optional[str] = None,
+) -> None:
+    """Write model default/provider fields into config.yaml for a profile."""
+    default_model, model_provider = _split_webui_provider_model_value(default_model, model_provider)
+    if not default_model and not model_provider:
+        return
+    config_path = profile_dir / 'config.yaml'
+    try:
+        import yaml as _yaml
+    except ImportError:
+        return
+    cfg = {}
+    if config_path.exists():
+        try:
+            loaded = _yaml.safe_load(config_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                cfg = loaded
+        except Exception:
+            logger.debug("Failed to load config from %s", config_path)
+    model_section = cfg.get('model', {})
+    if not isinstance(model_section, dict):
+        model_section = {}
+    if default_model:
+        model_section['default'] = default_model
+    if model_provider:
+        model_section['provider'] = model_provider
+    cfg['model'] = model_section
+    config_path.write_text(_yaml.dump(cfg, default_flow_style=False, allow_unicode=True), encoding='utf-8')
+
+
 def create_profile_api(name: str, clone_from: str = None,
                        clone_config: bool = False,
                        base_url: str = None,
-                       api_key: str = None) -> dict:
+                       api_key: str = None,
+                       default_model: str = None,
+                       model_provider: str = None) -> dict:
     """Create a new profile. Returns the new profile info dict."""
     _validate_profile_name(name)
     # Defense-in-depth: validate clone_from here too, even though routes.py
     # 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)
+    default_model, model_provider = _split_webui_provider_model_value(default_model, model_provider)
+    _validate_profile_model_selection(default_model, model_provider)
 
     try:
         from hermes_cli.profiles import create_profile
@@ -604,7 +1286,38 @@ def create_profile_api(name: str, clone_from: str = None,
             break
 
     profile_path.mkdir(parents=True, exist_ok=True)
+
+    # Seed bundled skills for non-cloned profiles (#2305).
+    # Cloned profiles should preserve the clone-source behaviour and must not
+    # receive a second bundled-skill overlay.
+    if clone_from is None:
+        try:
+            from hermes_cli.profiles import seed_profile_skills
+            seed_profile_skills(profile_path, quiet=True)
+        except ImportError:
+            logger.debug(
+                'seed_profile_skills unavailable — bundled skills not seeded '
+                'for profile %s (hermes_cli not in path)',
+                name,
+            )
+        except Exception:
+            logger.warning(
+                'Bundled skills could not be seeded for profile %s; '
+                'profile created successfully anyway',
+                name,
+                exc_info=True,
+            )
+
     _write_endpoint_to_config(profile_path, base_url=base_url, api_key=api_key)
+    _write_model_defaults_to_config(
+        profile_path,
+        default_model=default_model,
+        model_provider=model_provider,
+    )
+
+    # 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
@@ -628,7 +1341,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)
 
@@ -654,4 +1367,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/run_journal.py

@@ -0,0 +1,284 @@
+"""Append-only WebUI run event journal helpers.
+
+This is the first #1925 journal/replay slice.  It mirrors SSE events emitted by
+the existing in-process streaming path without changing execution ownership.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Iterable
+
+RUN_JOURNAL_DIR_NAME = "_run_journal"
+_SAFE_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+_WRITER_LOCKS: dict[tuple[str, str, str], threading.Lock] = {}
+_WRITER_LOCKS_GUARD = threading.Lock()
+_TERMINAL_SSE_EVENTS = {"done", "cancel", "apperror", "error", "stream_end"}
+_FSYNC_MODE_ENV = "HERMES_WEBUI_RUN_JOURNAL_FSYNC"
+_FSYNC_MODE_EAGER = "eager"
+_FSYNC_MODE_TERMINAL_ONLY = "terminal-only"
+
+
+def _default_session_dir() -> Path:
+    from api.models import SESSION_DIR
+
+    return Path(SESSION_DIR)
+
+
+def _validate_id(value: str, field: str) -> str:
+    cleaned = str(value or "").strip()
+    if not cleaned or "/" in cleaned or "\\" in cleaned or not _SAFE_ID_RE.fullmatch(cleaned):
+        raise ValueError(f"invalid {field}")
+    return cleaned
+
+
+def _run_path(session_id: str, run_id: str, session_dir: Path | None = None) -> Path:
+    sid = _validate_id(session_id, "session_id")
+    rid = _validate_id(run_id, "run_id")
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    return root / RUN_JOURNAL_DIR_NAME / sid / f"{rid}.jsonl"
+
+
+def _lock_for(path: Path) -> threading.Lock:
+    key = (str(path.parent), path.name, str(os.getpid()))
+    with _WRITER_LOCKS_GUARD:
+        lock = _WRITER_LOCKS.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _WRITER_LOCKS[key] = lock
+        return lock
+
+
+def _read_jsonl(path: Path) -> tuple[list[dict], list[dict]]:
+    events: list[dict] = []
+    malformed: list[dict] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except FileNotFoundError:
+        return events, malformed
+    for line_no, raw in enumerate(lines, start=1):
+        if not raw.strip():
+            continue
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            malformed.append({"line": line_no, "raw": raw})
+            continue
+        if isinstance(parsed, dict):
+            events.append(parsed)
+        else:
+            malformed.append({"line": line_no, "raw": raw})
+    return events, malformed
+
+
+def _next_seq(path: Path) -> int:
+    events, _malformed = _read_jsonl(path)
+    seqs = [int(event.get("seq") or 0) for event in events if isinstance(event.get("seq"), int)]
+    return (max(seqs) + 1) if seqs else 1
+
+
+def _terminal_state_for_event(event_name: str, payload) -> str | None:
+    name = str(event_name or "")
+    if name == "done" or name == "stream_end":
+        return "completed"
+    if name == "cancel":
+        return "interrupted-by-user"
+    if name in {"apperror", "error"}:
+        err_type = str((payload or {}).get("type") or "").strip().lower() if isinstance(payload, dict) else ""
+        if err_type in {"cancelled", "canceled"}:
+            return "interrupted-by-user"
+        if err_type == "interrupted":
+            return "interrupted-by-crash"
+        return "errored"
+    return None
+
+
+def _run_journal_fsync_mode() -> str:
+    raw = os.environ.get(_FSYNC_MODE_ENV, _FSYNC_MODE_TERMINAL_ONLY)
+    mode = str(raw or "").strip().lower()
+    if mode in {_FSYNC_MODE_EAGER, _FSYNC_MODE_TERMINAL_ONLY}:
+        return mode
+    return _FSYNC_MODE_TERMINAL_ONLY
+
+
+def _should_fsync_event(terminal_state: str | None) -> bool:
+    if _run_journal_fsync_mode() == _FSYNC_MODE_EAGER:
+        return True
+    return bool(terminal_state)
+
+
+def _fsync_parent_dir(path: Path) -> None:
+    try:
+        dir_fd = os.open(path.parent, getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except OSError:
+        pass
+
+
+def append_run_event(
+    session_id: str,
+    run_id: str,
+    event_name: str,
+    payload=None,
+    *,
+    session_dir: Path | None = None,
+    seq: int | None = None,
+    created_at: float | None = None,
+) -> dict:
+    """Append one durable run event and fsync it according to the journal policy."""
+    path = _run_path(session_id, run_id, session_dir=session_dir)
+    payload = payload if payload is not None else {}
+    event_name = str(event_name or "").strip()
+    if not event_name:
+        raise ValueError("event_name is required")
+    with _lock_for(path):
+        assigned_seq = int(seq) if seq is not None else _next_seq(path)
+        terminal_state = _terminal_state_for_event(event_name, payload)
+        event = {
+            "version": 1,
+            "event_id": f"{run_id}:{assigned_seq}",
+            "seq": assigned_seq,
+            "run_id": str(run_id),
+            "session_id": str(session_id),
+            "event": event_name,
+            "type": event_name,
+            "created_at": float(created_at if created_at is not None else time.time()),
+            "terminal": bool(terminal_state),
+            "terminal_state": terminal_state,
+            "payload": payload,
+        }
+        path.parent.mkdir(parents=True, exist_ok=True)
+        created_file = not path.exists()
+        line = json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+        fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+        with os.fdopen(fd, "a", encoding="utf-8") as fh:
+            fh.write(line)
+            fh.flush()
+            if _should_fsync_event(terminal_state):
+                os.fsync(fh.fileno())
+        if created_file:
+            _fsync_parent_dir(path)
+        return event
+
+
+class RunJournalWriter:
+    """Stateful writer for one WebUI stream/run."""
+
+    def __init__(self, session_id: str, run_id: str, *, session_dir: Path | None = None):
+        self.session_id = _validate_id(session_id, "session_id")
+        self.run_id = _validate_id(run_id, "run_id")
+        self.session_dir = Path(session_dir) if session_dir is not None else None
+        self._path = _run_path(self.session_id, self.run_id, session_dir=self.session_dir)
+        self._lock = _lock_for(self._path)
+        with self._lock:
+            self._next_seq = _next_seq(self._path)
+
+    def append_sse_event(self, event_name: str, payload=None) -> dict:
+        with self._lock:
+            seq = self._next_seq
+            self._next_seq += 1
+        return append_run_event(
+            self.session_id,
+            self.run_id,
+            event_name,
+            payload or {},
+            session_dir=self.session_dir,
+            seq=seq,
+        )
+
+
+def read_run_events(
+    session_id: str,
+    run_id: str,
+    *,
+    after_seq: int | None = None,
+    session_dir: Path | None = None,
+) -> dict:
+    path = _run_path(session_id, run_id, session_dir=session_dir)
+    events, malformed = _read_jsonl(path)
+    if after_seq is not None:
+        events = [event for event in events if int(event.get("seq") or 0) > int(after_seq)]
+    return {
+        "session_id": str(session_id),
+        "run_id": str(run_id),
+        "events": events,
+        "malformed": malformed,
+    }
+
+
+def _summary_from_events(session_id: str, run_id: str, events: Iterable[dict]) -> dict:
+    ordered = [event for event in events if isinstance(event, dict)]
+    last = ordered[-1] if ordered else None
+    terminal_events = [event for event in ordered if event.get("terminal")]
+    terminal = next(
+        (event for event in reversed(terminal_events) if event.get("event") != "stream_end"),
+        terminal_events[-1] if terminal_events else None,
+    )
+    status = terminal.get("terminal_state") if terminal else ("running" if ordered else "unknown")
+    return {
+        "session_id": str(session_id),
+        "run_id": str(run_id),
+        "stream_id": str(run_id),
+        "event_count": len(ordered),
+        "last_seq": int((last or {}).get("seq") or 0),
+        "last_event_id": (last or {}).get("event_id"),
+        "terminal": bool(terminal),
+        "terminal_state": status,
+        "last_event": (last or {}).get("event"),
+    }
+
+
+def latest_run_summary(session_id: str, run_id: str, *, session_dir: Path | None = None) -> dict:
+    journal = read_run_events(session_id, run_id, session_dir=session_dir)
+    return _summary_from_events(session_id, run_id, journal.get("events") or [])
+
+
+def find_run_summary(run_id: str, *, session_dir: Path | None = None) -> dict | None:
+    rid = _validate_id(run_id, "run_id")
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    journal_root = root / RUN_JOURNAL_DIR_NAME
+    for path in journal_root.glob(f"*/{rid}.jsonl"):
+        session_id = path.parent.name
+        events, _malformed = _read_jsonl(path)
+        summary = _summary_from_events(session_id, rid, events)
+        summary["path"] = str(path)
+        return summary
+    return None
+
+
+def stale_interrupted_event(session_id: str, run_id: str, *, after_seq: int | None = None) -> dict | None:
+    summary = latest_run_summary(session_id, run_id)
+    if summary.get("terminal") or not summary.get("event_count"):
+        return None
+    seq = int(summary.get("last_seq") or 0) + 1
+    if after_seq is not None and seq <= int(after_seq):
+        return None
+    payload = {
+        "type": "interrupted",
+        "message": "WebUI restarted or lost the live worker before this run finished.",
+        "hint": "The transcript was restored to the last journaled event. Start a new turn if you still need the task to continue.",
+        "session_id": session_id,
+        "stream_id": run_id,
+        "journal_last_seq": summary.get("last_seq"),
+    }
+    return {
+        "version": 1,
+        "event_id": f"{run_id}:{seq}",
+        "seq": seq,
+        "run_id": run_id,
+        "session_id": session_id,
+        "event": "apperror",
+        "type": "apperror",
+        "created_at": time.time(),
+        "terminal": True,
+        "terminal_state": "stale-from-restart",
+        "payload": payload,
+        "synthetic": True,
+    }

api/runtime_adapter.py

@@ -0,0 +1,431 @@
+"""RuntimeAdapter seam for WebUI-owned run execution.
+
+This is the #1925 RuntimeAdapter seam.  The default WebUI chat path remains the
+legacy direct route; enabling ``HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal``
+routes through this protocol-translator facade over the same legacy execution
+path plus the Slice 1 run journal.  Slice 4 adds a default-off runner-local
+selection point for tests and future runner backends, but live chat routes still
+stay on the legacy path until a separate route-wiring slice is reviewed.  This
+module intentionally does not own AIAgent instances, cancellation flags,
+approval callbacks, clarify callbacks, or new long-lived queues.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+from typing import Any, Callable, Iterable, Literal, Protocol
+
+_RUNTIME_ADAPTER_ENV = "HERMES_WEBUI_RUNTIME_ADAPTER"
+_RUNTIME_ADAPTER_DIRECT = "legacy-direct"
+_RUNTIME_ADAPTER_JOURNAL = "legacy-journal"
+_RUNTIME_ADAPTER_RUNNER_LOCAL = "runner-local"
+_VALID_RUNTIME_ADAPTER_MODES = {
+    _RUNTIME_ADAPTER_DIRECT,
+    _RUNTIME_ADAPTER_JOURNAL,
+    _RUNTIME_ADAPTER_RUNNER_LOCAL,
+}
+
+
+@dataclass(frozen=True)
+class StartRunRequest:
+    session_id: str
+    message: str
+    attachments: list[dict[str, Any]] = field(default_factory=list)
+    workspace: str | None = None
+    profile: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    toolsets: list[str] = field(default_factory=list)
+    source: str = "webui"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RunStartResult:
+    run_id: str
+    session_id: str
+    stream_id: str
+    status: str = "started"
+    started_at: float | None = None
+    cursor: str | None = None
+    active_controls: list[str] = field(default_factory=list)
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RunEventStream:
+    run_id: str
+    events: list[dict[str, Any]] = field(default_factory=list)
+    cursor: str | None = None
+    last_event_id: str | None = None
+
+
+@dataclass(frozen=True)
+class RunStatus:
+    run_id: str
+    session_id: str | None = None
+    status: str = "unknown"
+    last_event_id: str | None = None
+    terminal_state: str | None = None
+    active_controls: list[str] = field(default_factory=list)
+    pending_approval_id: str | None = None
+    pending_clarify_id: str | None = None
+
+
+@dataclass(frozen=True, eq=True, unsafe_hash=False)
+class ControlResult:
+    # NOTE: `payload: dict` makes this dataclass unhashable by design.
+    # `unsafe_hash=False` makes that explicit so future maintainers don't try
+    # to add `frozen=True`-implied hashability back (would silently break the
+    # moment any caller adds dict / list fields). Opus advisor stage-384 followup.
+    accepted: bool
+    status: str = "accepted"
+    event_id: str | None = None
+    safe_message: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+class RuntimeAdapter(Protocol):
+    def start_run(self, request: StartRunRequest) -> RunStartResult: ...
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream: ...
+    def get_run(self, run_id: str) -> RunStatus: ...
+    def cancel_run(self, run_id: str) -> ControlResult: ...
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult: ...
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult: ...
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> ControlResult: ...
+    def update_goal(
+        self,
+        session_id: str,
+        action: Literal["set", "pause", "resume", "clear", "status", "edit"],
+        text: str = "",
+    ) -> ControlResult: ...
+
+
+def runtime_adapter_mode(environ: dict[str, str] | None = None) -> str:
+    """Return the configured adapter mode, defaulting safely to legacy-direct."""
+    source = os.environ if environ is None else environ
+    raw = str(source.get(_RUNTIME_ADAPTER_ENV, _RUNTIME_ADAPTER_DIRECT) or "").strip().lower()
+    return raw if raw in _VALID_RUNTIME_ADAPTER_MODES else _RUNTIME_ADAPTER_DIRECT
+
+
+def runtime_adapter_enabled(environ: dict[str, str] | None = None) -> bool:
+    return runtime_adapter_mode(environ) == _RUNTIME_ADAPTER_JOURNAL
+
+
+def runtime_adapter_runner_enabled(environ: dict[str, str] | None = None) -> bool:
+    return runtime_adapter_mode(environ) == _RUNTIME_ADAPTER_RUNNER_LOCAL
+
+
+def build_runtime_adapter(
+    *,
+    environ: dict[str, str] | None = None,
+    legacy_adapter_factory: Callable[[], RuntimeAdapter] | None = None,
+    runner_client_factory: Callable[[], Any] | None = None,
+) -> RuntimeAdapter | None:
+    """Build the configured RuntimeAdapter without changing route behavior.
+
+    ``None`` means the safe default ``legacy-direct`` path should keep using the
+    existing direct route.  ``legacy-journal`` is opt-in and delegates to the
+    supplied legacy factory.  ``runner-local`` is also opt-in and only constructs
+    a ``RunnerRuntimeAdapter`` around an injected client; this function does not
+    create process-global runner state or wire live chat to the runner backend.
+    """
+    mode = runtime_adapter_mode(environ)
+    if mode == _RUNTIME_ADAPTER_DIRECT:
+        return None
+    if mode == _RUNTIME_ADAPTER_JOURNAL:
+        if legacy_adapter_factory is None:
+            raise NotImplementedError("legacy-journal mode requires a legacy adapter factory")
+        return legacy_adapter_factory()
+    if runner_client_factory is None:
+        raise NotImplementedError("runner-local mode requires a runner client factory")
+    return RunnerRuntimeAdapter(client=runner_client_factory())
+
+
+def _cursor_to_after_seq(cursor: str | None) -> int | None:
+    if cursor in (None, ""):
+        return None
+    try:
+        text = str(cursor)
+        if ":" in text:
+            text = text.rsplit(":", 1)[-1]
+        return max(0, int(text))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _active_control_result(value: Any) -> ControlResult:
+    """Normalize legacy delegate responses without changing their payloads.
+
+    ``status`` is an adapter-level summary used by current control tests and
+    future runtime backends.  For legacy goal payloads it may mirror the goal
+    action (``set`` / ``pause`` / ``status``), while public route behavior keeps
+    using the payload itself to preserve existing HTTP response shapes.
+    """
+    if isinstance(value, ControlResult):
+        return value
+    if isinstance(value, dict):
+        accepted = bool(value.get("ok", True))
+        return ControlResult(
+            accepted=accepted,
+            status=str(value.get("status") or value.get("action") or ("accepted" if accepted else "not-active")),
+            safe_message=value.get("message") if not accepted else None,
+            payload=dict(value),
+        )
+    accepted = bool(value)
+    return ControlResult(
+        accepted=accepted,
+        status="accepted" if accepted else "not-active",
+        safe_message=None if accepted else "Legacy control did not accept the request.",
+    )
+
+
+def _runner_unsupported_control(name: str) -> ControlResult:
+    return ControlResult(
+        False,
+        status="unsupported",
+        safe_message=f"{name} is not supported by this runner backend.",
+    )
+
+
+class RunnerRuntimeAdapter:
+    """Protocol-translator facade for a future runner/sidecar backend.
+
+    Slice 4 moves runtime ownership behind a runner boundary, but the WebUI
+    adapter must remain a translator.  This class deliberately delegates to an
+    injected client instead of owning process-local streams, cancellation flags,
+    approval queues, clarify queues, or cached agent instances itself.
+    """
+
+    def __init__(self, *, client: Any):
+        self._client = client
+
+    def start_run(self, request: StartRunRequest) -> RunStartResult:
+        start_run = getattr(self._client, "start_run", None)
+        if start_run is None:
+            raise NotImplementedError("RunnerRuntimeAdapter.start_run requires a runner client")
+        payload = start_run(request)
+        if isinstance(payload, RunStartResult):
+            return payload
+        payload = dict(payload or {})
+        run_id = str(payload.get("run_id") or payload.get("stream_id") or "")
+        stream_id = str(payload.get("stream_id") or run_id)
+        session_id = str(payload.get("session_id") or request.session_id)
+        active_controls = payload.get("active_controls")
+        if not isinstance(active_controls, list):
+            active_controls = []
+        return RunStartResult(
+            run_id=run_id,
+            session_id=session_id,
+            stream_id=stream_id,
+            status=str(payload.get("status") or "started"),
+            started_at=payload.get("started_at"),
+            cursor=payload.get("cursor"),
+            active_controls=active_controls,
+            payload=payload,
+        )
+
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream:
+        observe_run = getattr(self._client, "observe_run", None)
+        if observe_run is None:
+            return RunEventStream(run_id=run_id, events=[], cursor=cursor, last_event_id=None)
+        result = observe_run(run_id, cursor=cursor)
+        if isinstance(result, RunEventStream):
+            return result
+        payload = dict(result or {})
+        events = list(payload.get("events") or [])
+        last_event_id = payload.get("last_event_id") or (events[-1].get("event_id") if events else None)
+        next_cursor = payload.get("cursor")
+        if next_cursor is None and events:
+            next_cursor = str(events[-1].get("seq") or "")
+        return RunEventStream(
+            run_id=str(payload.get("run_id") or run_id),
+            events=events,
+            cursor=str(next_cursor) if next_cursor is not None else cursor,
+            last_event_id=last_event_id,
+        )
+
+    def get_run(self, run_id: str) -> RunStatus:
+        get_run = getattr(self._client, "get_run", None)
+        if get_run is None:
+            return RunStatus(run_id=run_id)
+        result = get_run(run_id)
+        if isinstance(result, RunStatus):
+            return result
+        payload = dict(result or {})
+        active_controls = payload.get("active_controls")
+        if not isinstance(active_controls, list):
+            active_controls = []
+        return RunStatus(
+            run_id=str(payload.get("run_id") or run_id),
+            session_id=str(payload.get("session_id") or "") or None,
+            status=str(payload.get("status") or "unknown"),
+            last_event_id=payload.get("last_event_id"),
+            terminal_state=payload.get("terminal_state"),
+            active_controls=active_controls,
+            pending_approval_id=payload.get("pending_approval_id"),
+            pending_clarify_id=payload.get("pending_clarify_id"),
+        )
+
+    def cancel_run(self, run_id: str) -> ControlResult:
+        cancel_run = getattr(self._client, "cancel_run", None)
+        if cancel_run is None:
+            return _runner_unsupported_control("Cancel")
+        return _active_control_result(cancel_run(run_id))
+
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult:
+        respond_approval = getattr(self._client, "respond_approval", None)
+        if respond_approval is None:
+            return _runner_unsupported_control("Approval")
+        return _active_control_result(respond_approval(run_id, approval_id, choice))
+
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult:
+        respond_clarify = getattr(self._client, "respond_clarify", None)
+        if respond_clarify is None:
+            return _runner_unsupported_control("Clarify")
+        return _active_control_result(respond_clarify(run_id, clarify_id, response))
+
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> ControlResult:
+        queue_message = getattr(self._client, "queue_message", None)
+        if queue_message is None:
+            return _runner_unsupported_control("Queue")
+        return _active_control_result(queue_message(run_id, message, mode=mode))
+
+    def update_goal(
+        self,
+        session_id: str,
+        action: Literal["set", "pause", "resume", "clear", "status", "edit"],
+        text: str = "",
+    ) -> ControlResult:
+        update_goal = getattr(self._client, "update_goal", None)
+        if update_goal is None:
+            return _runner_unsupported_control("Goal")
+        return _active_control_result(update_goal(session_id, action, text))
+
+
+class LegacyJournalRuntimeAdapter:
+    """Protocol-translator facade over the current legacy streaming path.
+
+    Delegates keep Slice 2 honest: this adapter has no worker thread, AIAgent
+    cache, cancellation registry, approval queue, or clarify queue of its own.
+    """
+
+    def __init__(
+        self,
+        *,
+        start_run_delegate: Callable[[StartRunRequest], dict[str, Any]] | None = None,
+        cancel_delegate: Callable[[str], Any] | None = None,
+        approval_delegate: Callable[[str, str, str], Any] | None = None,
+        clarify_delegate: Callable[[str, str, str], Any] | None = None,
+        queue_delegate: Callable[[str, str, str], Any] | None = None,
+        goal_delegate: Callable[[str, str, str], Any] | None = None,
+        live_stream_lookup: Callable[[str], bool] | None = None,
+        session_dir: Path | None = None,
+    ):
+        self._start_run_delegate = start_run_delegate
+        self._cancel_delegate = cancel_delegate
+        self._approval_delegate = approval_delegate
+        self._clarify_delegate = clarify_delegate
+        self._queue_delegate = queue_delegate
+        self._goal_delegate = goal_delegate
+        self._live_stream_lookup = live_stream_lookup or (lambda _run_id: False)
+        self._session_dir = Path(session_dir) if session_dir is not None else None
+
+    def start_run(self, request: StartRunRequest) -> RunStartResult:
+        if self._start_run_delegate is None:
+            raise NotImplementedError("LegacyJournalRuntimeAdapter.start_run requires a legacy delegate")
+        payload = dict(self._start_run_delegate(request) or {})
+        stream_id = str(payload.get("stream_id") or payload.get("run_id") or "")
+        run_id = str(payload.get("run_id") or stream_id)
+        session_id = str(payload.get("session_id") or request.session_id)
+        active_controls = payload.get("active_controls")
+        if not isinstance(active_controls, list):
+            active_controls = ["cancel"] if stream_id else []
+        return RunStartResult(
+            run_id=run_id,
+            session_id=session_id,
+            stream_id=stream_id,
+            status=str(payload.get("status") or "started"),
+            started_at=payload.get("started_at"),
+            cursor=payload.get("cursor"),
+            active_controls=active_controls,
+            payload=payload,
+        )
+
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream:
+        from api.run_journal import find_run_summary, read_run_events
+
+        summary = find_run_summary(run_id, session_dir=self._session_dir)
+        if not summary:
+            return RunEventStream(run_id=run_id, events=[], cursor=cursor, last_event_id=None)
+        journal = read_run_events(
+            str(summary.get("session_id") or ""),
+            run_id,
+            after_seq=_cursor_to_after_seq(cursor),
+            session_dir=self._session_dir,
+        )
+        events = list(journal.get("events") or [])
+        last_event_id = events[-1].get("event_id") if events else summary.get("last_event_id")
+        return RunEventStream(
+            run_id=run_id,
+            events=events,
+            cursor=str(events[-1].get("seq")) if events else cursor,
+            last_event_id=last_event_id,
+        )
+
+    def get_run(self, run_id: str) -> RunStatus:
+        from api.run_journal import find_run_summary
+
+        live = bool(self._live_stream_lookup(run_id))
+        summary = find_run_summary(run_id, session_dir=self._session_dir)
+        if live:
+            return RunStatus(
+                run_id=run_id,
+                session_id=str((summary or {}).get("session_id") or "") or None,
+                status="running",
+                last_event_id=(summary or {}).get("last_event_id"),
+                terminal_state=None,
+                active_controls=["cancel"],
+            )
+        if summary:
+            terminal_state = summary.get("terminal_state")
+            return RunStatus(
+                run_id=run_id,
+                session_id=str(summary.get("session_id") or "") or None,
+                status=str(terminal_state or "unknown"),
+                last_event_id=summary.get("last_event_id"),
+                terminal_state=terminal_state,
+                active_controls=[],
+            )
+        return RunStatus(run_id=run_id)
+
+    def cancel_run(self, run_id: str) -> ControlResult:
+        if self._cancel_delegate is None:
+            return ControlResult(False, status="unsupported", safe_message="Cancel is not wired for this adapter.")
+        return _active_control_result(self._cancel_delegate(run_id))
+
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult:
+        if self._approval_delegate is None:
+            return ControlResult(False, status="unsupported", safe_message="Approval is delegated to the legacy path.")
+        return _active_control_result(self._approval_delegate(run_id, approval_id, choice))
+
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult:
+        if self._clarify_delegate is None:
+            return ControlResult(False, status="unsupported", safe_message="Clarify is delegated to the legacy path.")
+        return _active_control_result(self._clarify_delegate(run_id, clarify_id, response))
+
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> ControlResult:
+        if self._queue_delegate is None:
+            return ControlResult(False, status="unsupported", safe_message="Queue is delegated to the legacy path.")
+        return _active_control_result(self._queue_delegate(run_id, message, mode))
+
+    def update_goal(
+        self,
+        session_id: str,
+        action: Literal["set", "pause", "resume", "clear", "status", "edit"],
+        text: str = "",
+    ) -> ControlResult:
+        if self._goal_delegate is None:
+            return ControlResult(False, status="unsupported", safe_message="Goal is delegated to the legacy path.")
+        return _active_control_result(self._goal_delegate(session_id, action, text))

api/session_events.py

@@ -0,0 +1,45 @@
+"""Lightweight in-process invalidation events for session sidebar state."""
+
+import queue
+import threading
+
+_SESSION_EVENTS_LOCK = threading.Lock()
+_SESSION_EVENTS_SUBSCRIBERS: set[queue.Queue] = set()
+_SESSION_EVENTS_VERSION = 0
+
+
+def publish_session_list_changed(reason: str = "session_changed") -> None:
+    """Notify connected browsers that the session sidebar may be stale."""
+    global _SESSION_EVENTS_VERSION
+    with _SESSION_EVENTS_LOCK:
+        _SESSION_EVENTS_VERSION += 1
+        payload = {
+            "type": "sessions_changed",
+            "version": _SESSION_EVENTS_VERSION,
+            "reason": reason,
+        }
+        subscribers = list(_SESSION_EVENTS_SUBSCRIBERS)
+    for q in subscribers:
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            try:
+                q.get_nowait()
+            except queue.Empty:
+                pass
+            try:
+                q.put_nowait(payload)
+            except queue.Full:
+                pass
+
+
+def subscribe_session_events() -> queue.Queue:
+    q: queue.Queue = queue.Queue(maxsize=1)
+    with _SESSION_EVENTS_LOCK:
+        _SESSION_EVENTS_SUBSCRIBERS.add(q)
+    return q
+
+
+def unsubscribe_session_events(q: queue.Queue) -> None:
+    with _SESSION_EVENTS_LOCK:
+        _SESSION_EVENTS_SUBSCRIBERS.discard(q)

api/session_lifecycle.py

@@ -0,0 +1,208 @@
+"""
+Hermes WebUI memory-provider session lifecycle.
+
+Batch-extraction memory providers (OpenViking, Holographic) only extract memories
+when AIAgent.commit_memory_session() invokes provider on_session_end(). WebUI
+sessions can be reopened and continued many times, so the lifecycle must guarantee:
+
+1. Only completed, non-ephemeral turns are committable.
+2. A commit finishing late must not erase work completed while it was in flight.
+3. A failed commit preserves the uncommitted generation and owning agent handle.
+4. Replacement/reopened agents cannot steal older dirty generations.
+5. Overlapping commits are serialised via a per-session in-flight guard.
+
+CLI-parity semantics — post-turn marking, boundary extraction/commit:
+
+- Completed turn: Hermes core still mirrors the exchange through
+  run_agent.py::_sync_external_memory_for_turn(), MemoryManager sync_all(), and
+  provider sync_turn() WITHOUT triggering extraction.  WebUI then calls
+  mark_turn_completed() after the saved/completed-turn boundary so later drains
+  know the synced session has uncommitted work and which agent owns it.
+
+- Session boundary: commit_session_memory() triggers
+  AIAgent.commit_memory_session(), which calls provider on_session_end(),
+  posting /api/v1/sessions/<sid>/commit and triggering extraction. This is
+  called only at boundaries — /api/session/new with prev_session_id, explicit
+  agent eviction, LRU cache eviction, and shutdown drain — matching the CLI's
+  AIAgent.commit_memory_session()/shutdown_memory_provider() boundary.
+
+The design uses a monotonic generation counter per session plus per-generation
+agent ownership segments. mark_turn_completed() records which agent owns the new
+generation. commit_session_memory() commits the earliest uncommitted segment and
+compare-and-clears only that captured segment after success.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+_condition = threading.Condition(_lock)
+
+_sessions: dict[str, dict] = {}
+
+
+def _new_entry() -> dict:
+    return {
+        "generation": 0,
+        "committed_generation": 0,
+        "agent": None,
+        "in_flight": False,
+        "segments": [],
+    }
+
+
+def _reset_for_tests() -> None:
+    with _condition:
+        _sessions.clear()
+        _condition.notify_all()
+
+
+def register_agent(session_id: str, agent) -> None:
+    """Register the current agent handle for future completed generations.
+
+    Existing dirty generations keep their original segment owner. This prevents
+    a rebuilt/reopened agent from overwriting the handle needed to retry older
+    failed memory-provider work.
+    """
+    if not session_id:
+        return
+    with _condition:
+        entry = _sessions.setdefault(session_id, _new_entry())
+        entry["agent"] = agent
+        _condition.notify_all()
+
+
+def unregister_agent(session_id: str) -> None:
+    """Clear the current future-generation agent handle.
+
+    Dirty segment owners are intentionally preserved so failed work remains
+    retryable even if the cache drops the current agent reference.
+    """
+    if not session_id:
+        return
+    with _condition:
+        entry = _sessions.get(session_id)
+        if entry is not None:
+            entry["agent"] = None
+        _condition.notify_all()
+
+
+def mark_turn_completed(session_id: str, *, agent=None) -> int:
+    if not session_id:
+        return 0
+    with _condition:
+        entry = _sessions.setdefault(session_id, _new_entry())
+        if agent is not None:
+            entry["agent"] = agent
+        owner = agent if agent is not None else entry.get("agent")
+        entry["generation"] += 1
+        generation = entry["generation"]
+        segments = entry["segments"]
+        if segments and not entry["in_flight"] and segments[-1].get("agent") is owner:
+            segments[-1]["end"] = generation
+        else:
+            segments.append({"start": generation, "end": generation, "agent": owner})
+        _condition.notify_all()
+        return generation
+
+
+def has_uncommitted_work(session_id: str) -> bool:
+    if not session_id:
+        return False
+    with _lock:
+        entry = _sessions.get(session_id)
+        if entry is None:
+            return False
+        return entry["generation"] > entry["committed_generation"]
+
+
+def _first_uncommitted_segment(entry: dict) -> dict | None:
+    committed = entry["committed_generation"]
+    for segment in entry["segments"]:
+        if segment["end"] > committed:
+            return segment
+    return None
+
+
+def commit_session_memory(session_id: str, agent=None, *, wait: bool = False, timeout: float | None = None) -> bool:
+    if not session_id:
+        return False
+    deadline = time.monotonic() + timeout if timeout is not None else None
+    with _condition:
+        entry = _sessions.get(session_id)
+        if entry is None:
+            return False
+        while entry["in_flight"]:
+            if not wait:
+                return False
+            if deadline is None:
+                _condition.wait()
+            else:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return False
+                _condition.wait(remaining)
+            entry = _sessions.get(session_id)
+            if entry is None:
+                return False
+        if entry["generation"] <= entry["committed_generation"]:
+            return False
+        segment = _first_uncommitted_segment(entry)
+        if segment is None:
+            return False
+        effective_agent = segment.get("agent")
+        if effective_agent is None:
+            effective_agent = agent if agent is not None else entry.get("agent")
+            if effective_agent is not None:
+                segment["agent"] = effective_agent
+        if effective_agent is None:
+            return False
+        captured_generation = segment["end"]
+        entry["in_flight"] = True
+
+    try:
+        effective_agent.commit_memory_session()
+    except Exception:
+        logger.exception("commit_memory_session() failed for session %s", session_id)
+        with _condition:
+            re_entry = _sessions.get(session_id)
+            if re_entry is not None:
+                re_entry["in_flight"] = False
+            _condition.notify_all()
+        return False
+
+    with _condition:
+        re_entry = _sessions.get(session_id)
+        if re_entry is not None:
+            re_entry["in_flight"] = False
+            if captured_generation > re_entry["committed_generation"]:
+                re_entry["committed_generation"] = captured_generation
+            committed = re_entry["committed_generation"]
+            segments = re_entry["segments"]
+            while segments and segments[0]["end"] <= committed:
+                segments.pop(0)
+            if segments and segments[0]["start"] <= committed:
+                segments[0]["start"] = committed + 1
+        _condition.notify_all()
+    return True
+
+
+def drain_all_on_shutdown() -> None:
+    while True:
+        with _lock:
+            snapshot = [sid for sid, entry in _sessions.items() if entry["generation"] > entry["committed_generation"]]
+        if not snapshot:
+            return
+
+        made_progress = False
+        for sid in snapshot:
+            if commit_session_memory(sid, wait=True):
+                made_progress = True
+        if not made_progress:
+            logger.debug("drain_all_on_shutdown: stopped with uncommitted sessions: %s", sorted(snapshot))
+            return

api/session_recovery.py

@@ -5,13 +5,16 @@ 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.
+file has fewer messages than its backup, or whose live file is missing
+while a valid backup remains.
 
 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.
+   messages than its .bak, and recreates a missing ``<sid>.json`` from an
+   orphaned ``<sid>.json.bak`` when the canonical state DB still has that
+   session. 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
@@ -22,11 +25,22 @@ Three integration points:
 """
 from __future__ import annotations
 
+import argparse
 import json
 import logging
+import os
 import shutil
+import sqlite3
+import threading
 from pathlib import Path
 
+from api.turn_journal import (
+    derive_turn_journal_states,
+    is_terminal_turn_event,
+    iter_turn_journal_session_ids,
+    read_turn_journal,
+)
+
 logger = logging.getLogger(__name__)
 
 
@@ -117,24 +131,474 @@ def recover_session(session_path: Path) -> dict:
     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.
+def _state_db_has_session(session_id: str, state_db_path: Path | None) -> bool:
+    """Return whether state.db still knows this session.
 
-    Returns {"scanned": N, "restored": M, "details": [...]}.
+    The check is deliberately fail-open: recovery must not be prevented by a
+    locked, absent, or older-schema state DB. When a DB is readable and has no
+    row, treat the orphan backup as a tombstoned/deleted session and skip it.
+    """
+    if state_db_path is None or not state_db_path.exists():
+        return True
+    try:
+        with sqlite3.connect(f"file:{state_db_path}?mode=ro", uri=True) as conn:
+            cur = conn.execute(
+                "select 1 from sqlite_master where type='table' and name='sessions'"
+            )
+            if cur.fetchone() is None:
+                return True
+            cur = conn.execute("select 1 from sessions where id = ? limit 1", (session_id,))
+            return cur.fetchone() is not None
+    except Exception as exc:
+        logger.debug("state_db session tombstone check failed for %s: %s", session_id, exc)
+        return True
+
+
+def _orphaned_backup_live_paths(
+    session_dir: Path,
+    state_db_path: Path | None = None,
+) -> list[Path]:
+    """Return live ``<sid>.json`` paths whose ``<sid>.json.bak`` exists.
+
+    ``Path.glob('*.json')`` does not see orphan backups because their suffix is
+    ``.bak``. Existing startup recovery only handled shrunken live files; this
+    helper covers the crash shape where the live sidecar is gone but the rescue
+    copy remains.
+    """
+    paths: list[Path] = []
+    for bak_path in sorted(session_dir.glob('*.json.bak')):
+        live_path = bak_path.with_suffix('')
+        if live_path.name.startswith('_') or live_path.exists():
+            continue
+        if _msg_count(bak_path) < 0:
+            continue
+        session_id = live_path.stem
+        if not _state_db_has_session(session_id, state_db_path):
+            logger.info(
+                "recover_all_sessions_on_startup: skipped orphan backup %s; "
+                "state.db has no live session row",
+                bak_path.name,
+            )
+            continue
+        paths.append(live_path)
+    return paths
+
+
+def _read_state_db_missing_sidecar_rows(
+    session_dir: Path,
+    state_db_path: Path | None,
+    *,
+    include_empty: bool = False,
+) -> list[dict]:
+    """Return WebUI-origin state.db rows whose JSON sidecar is missing."""
+    if state_db_path is None or not state_db_path.exists():
+        return []
+    try:
+        with sqlite3.connect(f"file:{state_db_path}?mode=ro", uri=True) as conn:
+            conn.row_factory = sqlite3.Row
+            session_cols = {row[1] for row in conn.execute("PRAGMA table_info(sessions)").fetchall()}
+            message_cols = {row[1] for row in conn.execute("PRAGMA table_info(messages)").fetchall()}
+            if not {'id', 'source'}.issubset(session_cols):
+                return []
+            title_expr = _sql_optional_col('title', session_cols)
+            model_expr = _sql_optional_col('model', session_cols)
+            started_expr = _sql_optional_col('started_at', session_cols, '0')
+            parent_expr = _sql_optional_col('parent_session_id', session_cols)
+            msg_count_expr = _sql_optional_col('message_count', session_cols, '0')
+            workspace_expr = _sql_optional_col('workspace', session_cols)
+            worktree_path_expr = _sql_optional_col('worktree_path', session_cols)
+            worktree_branch_expr = _sql_optional_col('worktree_branch', session_cols)
+            worktree_repo_root_expr = _sql_optional_col('worktree_repo_root', session_cols)
+            worktree_created_at_expr = _sql_optional_col('worktree_created_at', session_cols)
+            rows = []
+            for row in conn.execute(
+                f"""
+                SELECT id, source, {title_expr}, {model_expr}, {started_expr},
+                       {parent_expr}, {msg_count_expr}, {workspace_expr},
+                       {worktree_path_expr}, {worktree_branch_expr},
+                       {worktree_repo_root_expr}, {worktree_created_at_expr}
+                FROM sessions
+                WHERE source = 'webui'
+                ORDER BY COALESCE(started_at, 0) DESC
+                """
+            ).fetchall():
+                data = dict(row)
+                sid = str(data.get('id') or '').strip()
+                if not sid or (session_dir / f"{sid}.json").exists():
+                    continue
+                message_rows: list[dict] = []
+                if {'session_id', 'role', 'content'}.issubset(message_cols):
+                    order = "timestamp, id" if 'timestamp' in message_cols and 'id' in message_cols else "rowid"
+                    ts_expr = 'timestamp' if 'timestamp' in message_cols else 'NULL AS timestamp'
+                    for msg in conn.execute(
+                        f"SELECT role, content, {ts_expr} FROM messages WHERE session_id = ? ORDER BY {order}",
+                        (sid,),
+                    ).fetchall():
+                        message = {
+                            'role': msg['role'],
+                            'content': msg['content'] or '',
+                        }
+                        if msg['timestamp'] is not None:
+                            message['timestamp'] = msg['timestamp']
+                        message_rows.append(message)
+                if not message_rows and not include_empty:
+                    continue
+                data['messages'] = message_rows
+                data['_state_db_empty_messages'] = not message_rows
+                rows.append(data)
+            return rows
+    except Exception as exc:
+        logger.debug("state_db sidecar reconciliation scan failed for %s: %s", state_db_path, exc)
+        return []
+
+
+def _sql_optional_col(name: str, columns: set[str], fallback: str = "NULL") -> str:
+    return name if name in columns else f"{fallback} AS {name}"
+
+
+def _state_db_row_to_sidecar(row: dict) -> dict:
+    try:
+        from api.agent_sessions import normalize_agent_session_source
+    except Exception:
+        normalize_agent_session_source = None
+    source = str(row.get('source') or '').strip().lower()
+    source_meta = normalize_agent_session_source(source) if normalize_agent_session_source else {
+        'raw_source': source or None,
+        'session_source': source or None,
+        'source_label': source.title() if source else None,
+    }
+    started_at = row.get('started_at') or 0
+    messages = row.get('messages') if isinstance(row.get('messages'), list) else []
+    last_ts = messages[-1].get('timestamp') if messages and isinstance(messages[-1], dict) else started_at
+    workspace_value = row.get('workspace') or ''
+    return {
+        'session_id': row.get('id'),
+        'title': row.get('title') or 'Recovered WebUI Session',
+        'workspace': workspace_value if isinstance(workspace_value, str) else '',
+        'message_count': row.get('message_count') if isinstance(row.get('message_count'), int) else len(messages),
+        'worktree_path': row.get('worktree_path') or None,
+        'worktree_branch': row.get('worktree_branch') or None,
+        'worktree_repo_root': row.get('worktree_repo_root') or None,
+        'worktree_created_at': row.get('worktree_created_at') or None,
+        'model': row.get('model') or 'unknown',
+        'model_provider': None,
+        'created_at': started_at,
+        'updated_at': last_ts or started_at,
+        'pinned': False,
+        'archived': False,
+        'project_id': None,
+        'profile': None,
+        'input_tokens': 0,
+        'output_tokens': 0,
+        'estimated_cost': None,
+        'personality': None,
+        'active_stream_id': None,
+        'pending_user_message': None,
+        'pending_attachments': [],
+        'pending_started_at': None,
+        'compression_anchor_visible_idx': None,
+        'compression_anchor_message_key': None,
+        'compression_anchor_summary': None,
+        'context_length': None,
+        'threshold_tokens': None,
+        'last_prompt_tokens': None,
+        'gateway_routing': None,
+        'gateway_routing_history': [],
+        'llm_title_generated': False,
+        'parent_session_id': row.get('parent_session_id'),
+        'is_cli_session': False,
+        'source_tag': source or None,
+        **source_meta,
+        'enabled_toolsets': None,
+        'composer_draft': {},
+        'messages': messages,
+        'tool_calls': [],
+        '_recovered_from_state_db': True,
+    }
+
+
+def recover_missing_sidecars_from_state_db(session_dir: Path, state_db_path: Path | None) -> dict:
+    """Materialize missing WebUI JSON sidecars from canonical state.db rows."""
+    rows = _read_state_db_missing_sidecar_rows(session_dir, state_db_path)
+    materialized = 0
+    details: list[dict] = []
+    session_dir.mkdir(parents=True, exist_ok=True)
+    for row in rows:
+        sid = str(row.get('id') or '').strip()
+        if not sid:
+            continue
+        target = session_dir / f"{sid}.json"
+        if target.exists():
+            continue
+        payload = _state_db_row_to_sidecar(row)
+        # Per-process/per-thread tmp suffix to avoid corruption under
+        # concurrent reconciliation calls (matches api/models.py:484
+        # Session.save() convention).
+        tmp_suffix = f".json.reconcile.tmp.{os.getpid()}.{threading.current_thread().ident}"
+        tmp = target.with_suffix(tmp_suffix)
+        detail_recorded = False
+        try:
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding='utf-8')
+        except OSError as exc:
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:
+                pass
+            details.append({'session_id': sid, 'materialized': False, 'error': str(exc)})
+            continue
+        # Atomic create-or-fail: os.link() refuses to overwrite an existing
+        # target. Closes the TOCTOU window between the target.exists() check
+        # above and the rename — a concurrent Session.save() for the same SID
+        # will win and we silently skip rather than overwrite a live sidecar.
+        materialized_now = False
+        try:
+            os.link(str(tmp), str(target))
+            materialized_now = True
+        except FileExistsError:
+            # Live sidecar appeared between the check and the link — keep it.
+            pass
+        except OSError as exc:
+            details.append({'session_id': sid, 'materialized': False, 'error': str(exc)})
+            detail_recorded = True
+        finally:
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:
+                pass
+        if materialized_now:
+            materialized += 1
+            details.append({'session_id': sid, 'materialized': True, 'messages': len(payload.get('messages') or [])})
+        elif not detail_recorded:
+            details.append({'session_id': sid, 'materialized': False, 'skipped': 'sidecar_appeared_during_reconcile'})
+    return {'scanned': len(rows), 'materialized': materialized, 'details': details}
+
+
+def _new_audit_item(
+    session_id: str,
+    kind: str,
+    category: str,
+    recommendation: str,
+    live_messages: int = -1,
+    bak_messages: int = -1,
+    **extra,
+) -> dict:
+    item = {
+        "session_id": session_id,
+        "kind": kind,
+        "category": category,
+        "recommendation": recommendation,
+        "live_messages": live_messages,
+        "bak_messages": bak_messages,
+    }
+    item.update(extra)
+    return item
+
+
+def _read_index_session_ids(index_path: Path) -> set[str]:
+    try:
+        data = json.loads(index_path.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return set()
+    if not isinstance(data, list):
+        return set()
+    ids: set[str] = set()
+    for entry in data:
+        if isinstance(entry, dict) and isinstance(entry.get('session_id'), str):
+            ids.add(entry['session_id'])
+    return ids
+
+
+def audit_session_recovery(session_dir: Path, state_db_path: Path | None = None) -> dict:
+    """Read-only audit of session recovery state.
+
+    The audit intentionally does not mutate files. It classifies only the safe
+    recovery primitives this module knows how to perform: backup restores and
+    derived index rebuilds. Call ``recover_all_sessions_on_startup`` separately
+    for safe repairs.
     """
     if not session_dir.exists():
-        return {"scanned": 0, "restored": 0, "details": []}
+        return {
+            "status": "ok",
+            "summary": {"ok": 0, "repairable": 0, "unsafe_to_repair": 0},
+            "items": [],
+        }
+
+    items: list[dict] = []
+    live_paths = sorted(p for p in session_dir.glob('*.json') if not p.name.startswith('_'))
+    live_ids = {p.stem for p in live_paths}
+
+    for live_path in live_paths:
+        status = inspect_session_recovery_status(live_path)
+        if status.get('recommend') == 'restore':
+            items.append(_new_audit_item(
+                status['session_id'],
+                "shrunken_live",
+                "repairable",
+                "restore_from_bak",
+                status.get('live_messages', -1),
+                status.get('bak_messages', -1),
+            ))
+
+    for bak_path in sorted(session_dir.glob('*.json.bak')):
+        live_path = bak_path.with_suffix('')
+        if live_path.exists() or live_path.name.startswith('_'):
+            continue
+        bak_messages = _msg_count(bak_path)
+        session_id = live_path.stem
+        if bak_messages < 0:
+            items.append(_new_audit_item(
+                session_id, "malformed_orphan_backup", "unsafe_to_repair", "manual_review", -1, bak_messages
+            ))
+        elif _state_db_has_session(session_id, state_db_path):
+            items.append(_new_audit_item(
+                session_id, "orphan_backup", "repairable", "restore_from_bak", -1, bak_messages
+            ))
+        else:
+            items.append(_new_audit_item(
+                session_id,
+                "orphan_backup_without_state_row",
+                "unsafe_to_repair",
+                "manual_review",
+                -1,
+                bak_messages,
+            ))
+
+    index_path = session_dir / '_index.json'
+    if index_path.exists():
+        index_ids = _read_index_session_ids(index_path)
+        for session_id in sorted(index_ids - live_ids):
+            items.append(_new_audit_item(
+                session_id, "index_missing_file", "repairable", "rebuild_index"
+            ))
+        for session_id in sorted(live_ids - index_ids):
+            items.append(_new_audit_item(
+                session_id, "index_missing_entry", "repairable", "rebuild_index",
+                _msg_count(session_dir / f"{session_id}.json"), -1,
+            ))
+
+    for row in _read_state_db_missing_sidecar_rows(session_dir, state_db_path, include_empty=True):
+        sid = str(row.get('id') or '')
+        if row.get('_state_db_empty_messages'):
+            items.append(_new_audit_item(
+                sid,
+                "state_db_orphan_webui_row",
+                "unsafe_to_repair",
+                "manual_review",
+                -1,
+                -1,
+            ))
+            continue
+        items.append(_new_audit_item(
+            sid,
+            "state_db_missing_sidecar",
+            "repairable",
+            "materialize_from_state_db",
+            -1,
+            -1,
+        ))
+
+    for session_id in iter_turn_journal_session_ids(session_dir):
+        journal = read_turn_journal(session_id, session_dir=session_dir)
+        states, _ = derive_turn_journal_states(journal.get('events') or [])
+        live_path = session_dir / f"{session_id}.json"
+        live_messages = _msg_count(live_path)
+        existing_user_messages: set[str] = set()
+        try:
+            payload = json.loads(live_path.read_text(encoding='utf-8'))
+            if isinstance(payload, dict):
+                for message in payload.get('messages') or []:
+                    if isinstance(message, dict) and message.get('role') == 'user':
+                        existing_user_messages.add(str(message.get('content') or '').strip())
+        except (OSError, json.JSONDecodeError, ValueError):
+            pass
+        for turn_id, event in sorted(states.items()):
+            if is_terminal_turn_event(event):
+                continue
+            content = str(event.get('content') or '').strip()
+            if not content or content in existing_user_messages:
+                continue
+            items.append(_new_audit_item(
+                session_id,
+                "turn_journal_pending_turn",
+                "repairable",
+                "audit_only_pending_turn_journal",
+                live_messages,
+                -1,
+                turn_id=turn_id,
+                event=str(event.get('event') or ''),
+            ))
+
+    summary = {"ok": len(live_paths), "repairable": 0, "unsafe_to_repair": 0}
+    for item in items:
+        category = item.get('category')
+        if category in summary:
+            summary[category] += 1
+    if summary["unsafe_to_repair"]:
+        overall = "needs_manual_review"
+    elif summary["repairable"]:
+        overall = "warn"
+    else:
+        overall = "ok"
+    return {"status": overall, "summary": summary, "items": items}
+
+
+def repair_safe_session_recovery(session_dir: Path, state_db_path: Path | None = None) -> dict:
+    """Run safe, deterministic session recovery repairs.
+
+    This mutates only repairable classes already handled by startup recovery:
+    shrunken live sidecars and orphan backups that are not tombstoned by a
+    readable state.db. Unsafe audit findings remain for manual review.
+    """
+    before = audit_session_recovery(session_dir, state_db_path=state_db_path)
+    backup_repair = recover_all_sessions_on_startup(
+        session_dir,
+        rebuild_index=True,
+        state_db_path=state_db_path,
+    )
+    sidecar_repair = recover_missing_sidecars_from_state_db(session_dir, state_db_path)
+    if sidecar_repair.get('materialized'):
+        try:
+            from api.models import _write_session_index
+            _write_session_index(updates=None)
+        except Exception as exc:
+            logger.warning("repair_safe_session_recovery: index rebuild after state.db reconciliation failed: %s", exc)
+    after = audit_session_recovery(session_dir, state_db_path=state_db_path)
+    unsafe_remaining = int((after.get("summary") or {}).get("unsafe_to_repair") or 0)
+    repairable_remaining = int((after.get("summary") or {}).get("repairable") or 0)
+    clean = unsafe_remaining == 0 and repairable_remaining == 0
+    return {
+        "clean": clean,
+        "ok": clean,
+        "repaired": int(backup_repair.get("restored") or 0) + int(sidecar_repair.get("materialized") or 0),
+        "before": before,
+        "backup_repair": backup_repair,
+        "sidecar_repair": sidecar_repair,
+        "after": after,
+    }
+
+
+def recover_all_sessions_on_startup(
+    session_dir: Path,
+    rebuild_index: bool = False,
+    state_db_path: Path | None = None,
+) -> dict:
+    """Scan session_dir for shrunken/orphaned sessions and restore from .bak.
+
+    Returns {"scanned": N, "restored": M, "orphaned_backups": K, "details": [...]}.
+    """
+    if not session_dir.exists():
+        return {"scanned": 0, "restored": 0, "orphaned_backups": 0, "details": []}
     scanned = 0
     restored = 0
     details: list[dict] = []
-    for path in session_dir.glob('*.json'):
+    live_paths = [path for path in sorted(session_dir.glob('*.json')) if not path.name.startswith('_')]
+    orphan_paths = _orphaned_backup_live_paths(session_dir, state_db_path=state_db_path)
+    for path in [*live_paths, *orphan_paths]:
         # 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)
@@ -155,4 +619,37 @@ def recover_all_sessions_on_startup(session_dir: Path) -> dict:
             "If you weren't expecting this, check the session list for missing "
             "messages — see #1558.", restored, scanned,
         )
-    return {"scanned": scanned, "restored": restored, "details": details}
+    if rebuild_index:
+        try:
+            from api.models import SESSION_INDEX_FILE, _write_session_index
+            if restored or not SESSION_INDEX_FILE.exists():
+                _write_session_index(updates=None)
+        except Exception as exc:
+            logger.warning("recover_all_sessions_on_startup: index rebuild failed: %s", exc)
+    return {
+        "scanned": scanned,
+        "restored": restored,
+        "orphaned_backups": len(orphan_paths),
+        "details": details,
+    }
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description="Audit Hermes WebUI session recovery state")
+    parser.add_argument("--audit", action="store_true", help="run a read-only recovery audit")
+    parser.add_argument("--session-dir", type=Path, required=True, help="path to WebUI sessions directory")
+    parser.add_argument("--state-db", type=Path, default=None, help="optional Hermes state.db path")
+    parser.add_argument("--repair-safe", action="store_true", help="run safe deterministic repairs after auditing")
+    args = parser.parse_args()
+    if args.repair_safe:
+        report = repair_safe_session_recovery(args.session_dir, state_db_path=args.state_db)
+    elif args.audit:
+        report = audit_session_recovery(args.session_dir, state_db_path=args.state_db)
+    else:
+        parser.error("choose --audit or --repair-safe")
+    print(json.dumps(report, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

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

@@ -9,6 +9,7 @@ in the agent execution layer.
 from __future__ import annotations
 
 import errno
+import atexit
 import codecs
 import fcntl
 import os
@@ -69,6 +70,19 @@ _TERMINALS: dict[str, TerminalSession] = {}
 _LOCK = threading.RLock()
 
 
+# NOTE on parent-death-signal: a previous version of this module set
+# PR_SET_PDEATHSIG via a preexec_fn to terminate orphaned PTY shells when the
+# WebUI process crashed.  That broke every Linux user (#2853): WebUI runs a
+# ThreadingHTTPServer, so the Popen call happens on a short-lived per-request
+# thread, and PR_SET_PDEATHSIG is per-thread.  The PTY shell registered the
+# spawning thread as its "parent" and was killed with SIGTERM the instant that
+# thread joined — within ~10 ms of opening the terminal — surfacing as the
+# `[terminal closed]` banner.  The graceful path is covered by
+# `atexit.register(close_all_terminals)` and the explicit `close_terminal`
+# call sites; hard kills of the WebUI process leak the shell, which is the
+# tradeoff for working on Linux at all.
+
+
 def _decode_terminal_output(decoder, data: bytes) -> str:
     """Decode PTY bytes without stripping terminal control sequences."""
     return decoder.decode(data)
@@ -240,9 +254,24 @@ def close_terminal(session_id: str) -> bool:
                     os.killpg(term.proc.pid, signal.SIGKILL)
                 except ProcessLookupError:
                     pass
+                try:
+                    term.proc.wait(timeout=1.0)
+                except (subprocess.TimeoutExpired, ProcessLookupError):
+                    pass
     finally:
         try:
             os.close(term.master_fd)
         except OSError:
             pass
     return True
+
+
+def close_all_terminals() -> None:
+    """Best-effort reap of embedded shells during graceful WebUI shutdown."""
+    with _LOCK:
+        session_ids = list(_TERMINALS)
+    for session_id in session_ids:
+        close_terminal(session_id)
+
+
+atexit.register(close_all_terminals)

api/turn_journal.py

@@ -0,0 +1,212 @@
+"""Crash-safe WebUI turn journal helpers.
+
+The journal is deliberately tiny: one JSONL file per session, append-only events,
+and read helpers that tolerate malformed lines. Recovery and repair can then
+reason about submitted turns without depending on in-memory stream state.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterable
+
+try:  # pragma: no cover - fcntl is unavailable on Windows.
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover
+    _fcntl = None
+
+TURN_JOURNAL_DIR_NAME = "_turn_journal"
+_TERMINAL_EVENTS = {"completed", "interrupted"}
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def _default_session_dir() -> Path:
+    from api.models import SESSION_DIR
+
+    return Path(SESSION_DIR)
+
+
+def _journal_path(session_id: str, session_dir: Path | None = None) -> Path:
+    sid = str(session_id or "").strip()
+    if not sid or "/" in sid or "\\" in sid or not _SESSION_ID_RE.fullmatch(sid):
+        raise ValueError("invalid session_id")
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    return root / TURN_JOURNAL_DIR_NAME / f"{sid}.jsonl"
+
+
+def _make_turn_id() -> str:
+    return f"{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())}-{uuid.uuid4().hex[:12]}"
+
+
+@contextmanager
+def _journal_file_lock(file_obj):
+    """Serialize multi-process journal writes when advisory locks exist.
+
+    ``O_APPEND`` keeps normal same-process appends simple, but a long JSONL event
+    can exceed POSIX's small atomic-write boundary.  On Unix, take an advisory
+    lock around the single event write+fsync so two WebUI worker processes cannot
+    interleave large submitted-message payloads into corrupted JSONL.  Platforms
+    without ``fcntl`` keep the previous best-effort append behavior.
+    """
+    if _fcntl is None:
+        yield
+        return
+    _fcntl.flock(file_obj.fileno(), _fcntl.LOCK_EX)
+    try:
+        yield
+    finally:
+        _fcntl.flock(file_obj.fileno(), _fcntl.LOCK_UN)
+
+
+def append_turn_journal_event(
+    session_id: str,
+    event: dict,
+    *,
+    session_dir: Path | None = None,
+) -> dict:
+    """Append one turn journal event and fsync it before returning.
+
+    The returned event is the exact payload written, with default ``version``,
+    ``session_id``, ``turn_id``, and ``created_at`` fields filled in.
+    """
+    if not isinstance(event, dict):
+        raise TypeError("event must be a dict")
+    event_name = str(event.get("event") or "").strip()
+    if not event_name:
+        raise ValueError("event is required")
+    payload = dict(event)
+    payload.setdefault("version", 1)
+    payload["session_id"] = str(session_id)
+    payload.setdefault("turn_id", _make_turn_id())
+    payload.setdefault("created_at", time.time())
+
+    path = _journal_path(session_id, session_dir=session_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+    with os.fdopen(fd, "a", encoding="utf-8") as fh:
+        with _journal_file_lock(fh):
+            fh.write(line)
+            fh.flush()
+            os.fsync(fh.fileno())
+    try:
+        dir_fd = os.open(path.parent, os.O_DIRECTORY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except OSError:
+        pass
+    return payload
+
+
+def read_turn_journal(session_id: str, *, session_dir: Path | None = None) -> dict:
+    """Read a session journal, returning valid events plus malformed lines."""
+    path = _journal_path(session_id, session_dir=session_dir)
+    events: list[dict] = []
+    malformed: list[dict] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except FileNotFoundError:
+        return {"session_id": str(session_id), "events": [], "malformed": []}
+    for line_no, raw in enumerate(lines, start=1):
+        if not raw.strip():
+            continue
+        try:
+            event = json.loads(raw)
+        except json.JSONDecodeError:
+            malformed.append({"line": line_no, "raw": raw})
+            continue
+        if isinstance(event, dict):
+            events.append(event)
+        else:
+            malformed.append({"line": line_no, "raw": raw})
+    return {"session_id": str(session_id), "events": events, "malformed": malformed}
+
+
+def derive_turn_journal_states(events: Iterable[dict]) -> tuple[dict[str, dict], list[dict]]:
+    '''Return the latest event per ``turn_id`` and any terminal-collision entries.
+
+    The first element is the latest event per turn_id (same overwrite-by-timestamp
+    behaviour as before).  The second element is a list of collision records, one
+    per turn_id that had more than one terminal event.  Each collision record
+    contains ``turn_id`` and the ``events`` list (in ascending created_at order).
+
+    A collision means the same logical turn recorded both ``completed`` and
+    ``interrupted`` terminal events -- the derived state still picks the latest
+    by timestamp, but callers can now detect and audit the double-terminal
+    situation explicitly rather than having it silently collapse.
+    '''
+    states: dict[str, dict] = {}
+    # Collect all terminal events per turn_id to detect collisions
+    terminal_events: dict[str, list[dict]] = {}
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        turn_id = str(event.get('turn_id') or '').strip()
+        if not turn_id:
+            continue
+        # Track terminal events for collision detection
+        if is_terminal_turn_event(event):
+            terminal_events.setdefault(turn_id, []).append(event)
+        # Existing latest-by-timestamp derivation
+        previous = states.get(turn_id)
+        if previous is None or float(event.get('created_at') or 0) >= float(previous.get('created_at') or 0):
+            states[turn_id] = event
+
+    # Build collision list: turn_ids with more than one terminal event
+    collisions = [
+        {'turn_id': tid, 'events': sorted(evts, key=lambda e: float(e.get('created_at') or 0))}
+        for tid, evts in terminal_events.items()
+        if len(evts) > 1
+    ]
+    return states, collisions
+
+def _latest_turn_id_for_stream(events: Iterable[dict], stream_id: str) -> str | None:
+    stream = str(stream_id or "").strip()
+    if not stream:
+        return None
+    latest: str | None = None
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        if str(event.get("stream_id") or "") != stream:
+            continue
+        turn_id = str(event.get("turn_id") or "").strip()
+        if turn_id:
+            latest = turn_id
+    return latest
+
+
+def append_turn_journal_event_for_stream(
+    session_id: str,
+    stream_id: str,
+    event: dict,
+    *,
+    session_dir: Path | None = None,
+) -> dict:
+    """Append a lifecycle event for the turn associated with ``stream_id``."""
+    payload = dict(event)
+    payload["stream_id"] = str(stream_id)
+    if not payload.get("turn_id"):
+        journal = read_turn_journal(session_id, session_dir=session_dir)
+        turn_id = _latest_turn_id_for_stream(journal.get("events") or [], stream_id)
+        if turn_id:
+            payload["turn_id"] = turn_id
+    return append_turn_journal_event(session_id, payload, session_dir=session_dir)
+
+
+def iter_turn_journal_session_ids(session_dir: Path) -> list[str]:
+    journal_dir = Path(session_dir) / TURN_JOURNAL_DIR_NAME
+    if not journal_dir.exists():
+        return []
+    return sorted(path.stem for path in journal_dir.glob("*.jsonl") if path.is_file())
+
+
+def is_terminal_turn_event(event: dict) -> bool:
+    return str((event or {}).get("event") or "") in _TERMINAL_EVENTS

api/updates.py

@@ -1,17 +1,25 @@
 """
 Hermes Web UI -- Self-update checker.
 
-Checks if the webui and hermes-agent git repos are behind their upstream
-branches. Results are cached server-side (30-min TTL) so git fetch runs
+Checks if the webui and hermes-agent git repos are behind their latest
+release tags. Results are cached server-side (30-min TTL) so git fetch runs
 at most twice per hour regardless of client count.
 
 Skips repos that are not git checkouts (e.g. Docker baked images where
 .git does not exist).
 """
+import hashlib
+import json
+import os
+import re
 import subprocess
 import threading
 import time
+import urllib.error
+import urllib.request
+from collections import OrderedDict
 from pathlib import Path
+from urllib.parse import urlparse
 
 from api.config import REPO_ROOT, STREAMS, STREAMS_LOCK
 
@@ -21,11 +29,35 @@ try:
 except ImportError:
     _AGENT_DIR = None
 
-_update_cache = {'webui': None, 'agent': None, 'checked_at': 0}
+_update_cache = {'webui': None, 'agent': None, 'checked_at': 0, 'include_agent': True}
+_SUMMARY_CACHE_MAX = 16
+_summary_cache: OrderedDict = OrderedDict()
 _cache_lock = threading.Lock()
 _check_in_progress = False
 _apply_lock = threading.Lock()   # prevents concurrent stash/pull/pop on same repo
 CACHE_TTL = 1800  # 30 minutes
+_GIT_DIAGNOSTIC_MAX_CHARS = 300
+_CREDENTIAL_IN_URL_RE = re.compile(r"([a-zA-Z][a-zA-Z0-9+.-]*://)([^/@\s'\"]+)@")
+_GITHUB_TOKEN_RE = re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,})\b")
+_QUERY_SECRET_RE = re.compile(r"([?&](?:access_token|token|password|auth|key)=)[^&\s'\"]+", re.IGNORECASE)
+
+
+def _sanitize_git_diagnostic(output: str, *, limit: int = _GIT_DIAGNOSTIC_MAX_CHARS) -> str:
+    """Return a user-facing git diagnostic with credentials removed.
+
+    Git can echo remote URLs in failure output.  Keep the actionable error text,
+    but strip URL userinfo, common GitHub token shapes, and secret-looking query
+    parameter values before any message reaches the update-check API/UI.
+    """
+    if not output:
+        return ""
+    sanitized = _CREDENTIAL_IN_URL_RE.sub(r"\1<redacted>@", str(output))
+    sanitized = _GITHUB_TOKEN_RE.sub("<redacted>", sanitized)
+    sanitized = _QUERY_SECRET_RE.sub(r"\1<redacted>", sanitized)
+    sanitized = sanitized.strip()
+    if len(sanitized) > limit:
+        sanitized = sanitized[:limit].rstrip() + "…"
+    return sanitized
 
 
 def _active_stream_count() -> int:
@@ -79,6 +111,24 @@ def _run_git(args, cwd, timeout=10):
         return f'git failed to start: {exc}', False
 
 
+def _dirty_suffix(path: Path, timeout=1) -> str:
+    """Return a best-effort ``-dirty`` suffix without blocking version display."""
+    out, ok = _run_git(['diff-index', '--quiet', 'HEAD', '--'], path, timeout=timeout)
+    if ok:
+        return ""
+    # diff-index exits 1 with no output for a dirty tree. Timeouts and real git
+    # failures include a diagnostic; skip the suffix so the base version remains.
+    return "-dirty" if not out else ""
+
+
+def _describe_git_version(path: Path, *, timeout=5, dirty_timeout=1) -> str | None:
+    """Return a fast git version string for a checkout, if available."""
+    out, ok = _run_git(['describe', '--tags', '--always'], path, timeout=timeout)
+    if not (ok and out):
+        return None
+    return out + _dirty_suffix(path, timeout=dirty_timeout)
+
+
 def _detect_webui_version() -> str:
     """Detect the running WebUI version from git or a baked-in fallback file.
 
@@ -94,8 +144,8 @@ def _detect_webui_version() -> str:
     """
     # 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:
+    out = _describe_git_version(REPO_ROOT)
+    if out:
         return out
 
     # Docker / baked-image fallback: api/_version.py written by CI at build time.
@@ -117,8 +167,140 @@ def _detect_webui_version() -> str:
     return 'unknown'
 
 
+def _read_agent_source_version(agent_dir: Path) -> str | None:
+    """Read Hermes Agent's package version from a copied source tree."""
+    init_file = agent_dir / 'hermes_cli' / '__init__.py'
+    try:
+        text = init_file.read_text(encoding='utf-8')
+    except (OSError, UnicodeDecodeError):
+        return None
+    m = re.search(r"""__version__\s*=\s*['"]([^'"]+)['"]""", text)
+    if m and m.group(1).strip():
+        return m.group(1).strip()
+    return None
+
+
+def _gateway_health_base_url() -> str:
+    """Return the configured/default Hermes Agent gateway base URL."""
+    raw = (
+        os.environ.get('GATEWAY_HEALTH_URL')
+        or os.environ.get('HERMES_GATEWAY_HEALTH_URL')
+        or 'http://hermes-agent:8642'
+    ).strip()
+    if raw.endswith('/health/detailed'):
+        raw = raw[: -len('/health/detailed')]
+    elif raw.endswith('/health'):
+        raw = raw[: -len('/health')]
+    return raw.rstrip('/')
+
+
+def _version_from_gateway_health_payload(payload: object) -> str | None:
+    """Extract a version string from a Hermes Agent gateway health payload."""
+    if not isinstance(payload, dict):
+        return None
+    for key in ('version', 'agent_version', 'hermes_version'):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    nested = payload.get('agent')
+    if isinstance(nested, dict):
+        value = nested.get('version')
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _detect_agent_version_from_gateway_health(timeout: float = 0.75) -> str | None:
+    """Best-effort cross-container gateway API fallback for Agent version."""
+    base = _gateway_health_base_url()
+    if not base:
+        return None
+    parsed = urlparse(base)
+    if parsed.scheme not in ('http', 'https') or not parsed.netloc:
+        return None
+    for path in ('/health', '/health/detailed'):
+        try:
+            with urllib.request.urlopen(f'{base}{path}', timeout=timeout) as resp:
+                payload = json.loads(resp.read().decode('utf-8'))
+        except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError, UnicodeDecodeError):
+            continue
+        version = _version_from_gateway_health_payload(payload)
+        if version:
+            return version
+    return None
+
+
+def _detect_agent_version() -> str:
+    """Detect the running Hermes Agent version for UI display."""
+    agent_dir = Path(_AGENT_DIR) if _AGENT_DIR is not None else None
+
+    if agent_dir is not None:
+        version_file = 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 agent_dir.exists():
+            # 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 = _describe_git_version(agent_dir)
+            if out:
+                return out
+
+            # Docker two-container deployments often mount a copied agent source
+            # tree without .git metadata or a VERSION file.  The package version
+            # still lives in hermes_cli/__init__.py, so prefer that before giving
+            # up or relying on a live gateway probe.
+            source_version = _read_agent_source_version(agent_dir)
+            if source_version:
+                return source_version
+
+    gateway_version = _detect_agent_version_from_gateway_health()
+    if gateway_version:
+        return gateway_version
+
+    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 _build_compare_url(repo_url, current_sha, latest_sha):
+    """Return a safe browser compare URL, or None when any piece is missing."""
+    if not (repo_url and current_sha and latest_sha):
+        return None
+    parsed = urlparse(repo_url)
+    if parsed.scheme not in ('http', 'https') or not parsed.netloc:
+        return None
+    return f"{repo_url}/compare/{current_sha}...{latest_sha}"
 
 
 def _split_remote_ref(ref):
@@ -146,15 +328,130 @@ def _detect_default_branch(path):
     return 'master'
 
 
-def _check_repo(path, name):
-    """Check if a git repo is behind its upstream. Returns dict or None."""
-    if path is None or not (path / '.git').exists():
+def _release_tags(path):
+    """Return release tags newest-first, using the repo's version-sort order."""
+    out, ok = _run_git(['tag', '--list', 'v*', '--sort=-v:refname'], path)
+    if not (ok and out):
+        return []
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def _current_release_tag(path):
+    """Return the latest release tag reachable from HEAD, if one exists."""
+    out, ok = _run_git(['describe', '--tags', '--abbrev=0'], path)
+    return out if ok and out else None
+
+
+def _release_gap(tags, current, latest):
+    """Count release tags between current and latest in a newest-first list."""
+    if not latest or current == latest:
+        return 0
+    if current in tags:
+        return tags.index(current)
+    return 1
+
+
+def _head_is_past_latest_tag(path, current_tag):
+    """Return True when HEAD has moved past the latest reachable release tag.
+
+    `git describe --tags --always` returns the bare tag name (e.g. ``v2026.5.16``)
+    when HEAD is exactly on the tag, and a ``v2026.5.16-608-g1d22b9c2`` suffix
+    when HEAD has moved 608 commits past it. Used by both the update check and
+    the update apply path so they agree on which ref to advance to — see #2653
+    (check side) and #2846 (apply side).
+    """
+    if not current_tag:
+        return False
+    full_desc, ok = _run_git(['describe', '--tags', '--always'], path)
+    return bool(ok and full_desc and full_desc != current_tag)
+
+
+def _select_apply_compare_ref(path):
+    """Return the same remote ref family that the update check reports.
+
+    The update banner prefers published release tags when they exist. Applying
+    an update must therefore advance to the latest release tag too; otherwise a
+    checkout on a local/fork tracking branch can report release updates, pull a
+    different branch that is already current, restart, and still remain behind.
+
+    When HEAD is past the latest tag (the agent repo's day-to-day state between
+    tagged releases), the check side falls through to the branch comparison via
+    `_check_repo_release` returning None. The apply side must mirror that
+    decision — otherwise we run `git pull --ff-only <latest-tag>` against a
+    checkout that's already past the tag, no-op, restart, and the banner
+    re-appears with the same N commits available. See #2846.
+    """
+    tags = _release_tags(path)
+    if tags:
+        latest_tag = tags[0]
+        current_tag = _current_release_tag(path)
+        behind = _release_gap(tags, current_tag, latest_tag)
+        # Mirror the check side exactly: only fall through when behind == 0
+        # AND HEAD has moved past its nearest tag (case A: bench between
+        # tagged releases). Otherwise the tag is correct — including the
+        # case where HEAD is on an older release tag with commits on top
+        # AND a newer tag exists (case D), where `behind > 0` means the
+        # user is genuinely behind the latest release and should advance
+        # to it. Pre-#2855 the apply path only consulted `latest_tag`
+        # without the `behind`/`current_tag` predicate, so case D fell
+        # through to `origin/<branch>` and the pull landed past the
+        # advertised tag. See #2846 + Opus pre-release review for #2855.
+        if not (behind == 0 and _head_is_past_latest_tag(path, current_tag)):
+            return latest_tag
+
+    upstream, ok = _run_git(['rev-parse', '--abbrev-ref', '@{upstream}'], path)
+    if ok and upstream:
+        return upstream
+
+    branch = _detect_default_branch(path)
+    return f'origin/{branch}'
+
+
+def _check_repo_release(path, name):
+    """Check if a git repo is behind its latest published release tag."""
+    tags = _release_tags(path)
+    if not tags:
         return None
 
+    latest_tag = tags[0]
+    current_tag = _current_release_tag(path)
+    behind = _release_gap(tags, current_tag, latest_tag)
+
+    # If behind == 0 but HEAD has moved past the tag (e.g. the agent repo
+    # keeps committing to master between tagged releases), the release check
+    # would report "Up to date" even though hundreds of commits are missing.
+    # Fall through to _check_repo_branch so the real commit count is reported
+    # instead. The same predicate is used by _select_apply_compare_ref so the
+    # check and apply sides cannot drift again. See #2653 (check), #2846 (apply).
+    if behind == 0 and _head_is_past_latest_tag(path, current_tag):
+        return None
+
+    remote_url, _ = _run_git(['remote', 'get-url', 'origin'], path)
+    remote_url = _normalize_remote_url(remote_url)
+
+    return {
+        'name': name,
+        'behind': behind,
+        # GitHub compare URLs accept tag names, and tag-to-tag links are the
+        # clearest "what changed in this release?" view for operators.
+        'current_sha': current_tag,
+        'latest_sha': latest_tag,
+        'branch': latest_tag,
+        'repo_url': remote_url,
+        'release_based': True,
+        'current_version': current_tag,
+        'latest_version': latest_tag,
+    }
+
+
+def _check_repo_branch(path, name, *, fetch=True):
+    """Fallback: check if a git repo is behind its upstream branch."""
+
     # Fetch latest from origin (network call, cached by TTL)
-    _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
-    if not fetch_ok:
-        return {'name': name, 'behind': 0, 'error': 'fetch failed'}
+    if fetch:
+        _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
+        if not fetch_ok:
+            return {'name': name, 'behind': 0, 'error': 'fetch failed'}
 
     # Use the current branch's upstream tracking branch, not the repo default.
     # This avoids false "N updates behind" alerts when the user is on a feature
@@ -172,17 +469,40 @@ 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)
-    # Convert SSH URLs (git@github.com:org/repo.git) to HTTPS
-    if remote_url and remote_url.startswith('git@'):
-        remote_url = remote_url.replace(':', '/', 1).replace('git@', 'https://', 1).rstrip('.git')
-    elif remote_url:
-        remote_url = remote_url.rstrip('.git')
+    remote_url = _normalize_remote_url(remote_url)
 
     return {
         'name': name,
@@ -191,14 +511,64 @@ def _check_repo(path, name):
         'latest_sha': latest,
         'branch': compare_ref,
         'repo_url': remote_url,
+        'compare_url': _build_compare_url(remote_url, current, latest),
     }
 
 
-def check_for_updates(force=False):
+def _check_repo(path, name):
+    """Check if a git repo is behind its latest release. Returns dict or None."""
+    if path is None or not (path / '.git').exists():
+        return None
+
+    # Fetch tags first so update prompts track published releases, not every
+    # development commit that lands on master/main after the latest release.
+    #
+    # --force is required because the WebUI is a release-tracking consumer:
+    # it never pushes tags, so it should always defer to whatever the remote
+    # says a release tag points to. Without --force, a remote re-tag (e.g.
+    # after a squash-merge that re-points a release tag at a new SHA) jams
+    # the update path indefinitely with "would clobber existing tag" errors.
+    # See #2756.
+    fetch_out, fetch_ok = _run_git(['fetch', 'origin', '--tags', '--force'], path, timeout=15)
+    if not fetch_ok:
+        release_info = _check_repo_release(path, name)
+        message = 'fetch failed'
+        if fetch_out:
+            message = f'{message}: {_sanitize_git_diagnostic(fetch_out)}'
+        if release_info is not None:
+            release_info = dict(release_info)
+            release_info['error'] = message
+            release_info['stale_check'] = True
+            return release_info
+        return {
+            'name': name,
+            'behind': None,
+            'error': message,
+            'stale_check': True,
+        }
+
+    release_info = _check_repo_release(path, name)
+    if release_info is not None:
+        return release_info
+
+    return _check_repo_branch(path, name, fetch=False)
+
+
+def _ignored_agent_update_info() -> dict:
+    """Return a stable update-check payload for intentionally ignored Agent updates."""
+    return {'name': 'agent', 'behind': 0, 'ignored': True}
+
+
+def check_for_updates(force=False, *, include_agent=True):
     """Return cached update status for webui and agent repos."""
     global _check_in_progress
+    include_agent = bool(include_agent)
     with _cache_lock:
-        if not force and time.time() - _update_cache['checked_at'] < CACHE_TTL:
+        if (
+            not force
+            and _update_cache.get('include_agent') == include_agent
+            and time.time() - _update_cache['checked_at'] < CACHE_TTL
+        ):
             return dict(_update_cache)
         if _check_in_progress:
             return dict(_update_cache)  # another thread is already checking
@@ -207,17 +577,314 @@ def check_for_updates(force=False):
     try:
         # Run checks outside the lock (network I/O)
         webui_info = _check_repo(REPO_ROOT, 'webui')
-        agent_info = _check_repo(_AGENT_DIR, 'agent')
+        agent_info = _check_repo(_AGENT_DIR, 'agent') if include_agent else _ignored_agent_update_info()
 
         with _cache_lock:
             _update_cache['webui'] = webui_info
             _update_cache['agent'] = agent_info
             _update_cache['checked_at'] = time.time()
+            _update_cache['include_agent'] = include_agent
             return dict(_update_cache)
     finally:
         _check_in_progress = False
 
 
+def _repo_path_for_update_target(target: str):
+    if target == 'webui':
+        return REPO_ROOT
+    if target == 'agent':
+        return _AGENT_DIR
+    return None
+
+
+def _commit_subjects_for_update(info: dict, *, limit: int = 24) -> list[str]:
+    """Return commit subjects for an update range, if the local git refs exist."""
+    subjects, _truncated = _commit_subjects_for_update_with_limit(info, limit=limit)
+    return subjects
+
+
+def _commit_subjects_for_update_with_limit(info: dict, *, limit: int = 24) -> tuple[list[str], bool]:
+    """Return recent commit subjects plus whether the local list was capped."""
+    if not isinstance(info, dict):
+        return [], False
+    target = info.get('name')
+    if target not in ('webui', 'agent'):
+        target = 'webui' if info.get('repo_url', '').endswith('hermes-webui') else target
+    path = _repo_path_for_update_target(target)
+    if path is None or not (Path(path) / '.git').exists():
+        return [], False
+    current = str(info.get('current_sha') or '').strip()
+    latest = str(info.get('latest_sha') or '').strip()
+    if not (current and latest):
+        return [], False
+    probe_limit = max(1, int(limit)) + 1
+    out, ok = _run_git(['log', '--format=%s', f'{current}..{latest}', f'-n{probe_limit}'], path, timeout=5)
+    if not ok or not out:
+        return [], False
+    subjects = [line.strip() for line in out.splitlines() if line.strip()]
+    truncated = len(subjects) > limit
+    return subjects[:limit], truncated
+
+
+def _summary_cache_key(updates: dict, details: list[dict]) -> str:
+    """Stable key for the exact update range being summarized."""
+    payload = []
+    for item in details:
+        payload.append({
+            'name': item.get('name'),
+            'behind': item.get('behind'),
+            'current_sha': item.get('current_sha'),
+            'latest_sha': item.get('latest_sha'),
+            'compare_url': item.get('compare_url'),
+        })
+    blob = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+    return hashlib.sha256(blob.encode('utf-8')).hexdigest()
+
+
+def _clean_summary_bullet(line: str) -> str:
+    line = re.sub(r'^\s*(?:[-*•]+|\d+[.)])\s*', '', str(line or '')).strip()
+    line = re.sub(r'\s+', ' ', line)
+    if not line:
+        return ''
+    if line[-1] not in '.!?':
+        line += '.'
+    return line[:240]
+
+
+def _split_summary_category(line: str) -> tuple[str | None, str]:
+    raw = str(line or '').strip()
+    match = re.match(r'^\s*(?:[-*•]+|\d+[.)])?\s*(notice|what you(?:ll|\'ll| will) notice|user(?:s)? will notice|worth knowing|worth|note)\s*:\s*(.+)$', raw, re.I)
+    if not match:
+        return None, raw
+    label = match.group(1).lower()
+    category = 'worth' if label in {'worth knowing', 'worth', 'note'} else 'notice'
+    return category, match.group(2)
+
+
+def _unique_summary_bullets(items: list[str]) -> list[str]:
+    seen = set()
+    bullets = []
+    for item in items:
+        cleaned = _clean_summary_bullet(item)
+        key = cleaned.lower()
+        if cleaned and key not in seen:
+            bullets.append(cleaned)
+            seen.add(key)
+    return bullets
+
+
+def _summary_bullets_from_text(text: str, *, fallback_items: list[str]) -> list[str]:
+    raw = str(text or '').strip()
+    candidates = []
+    for line in raw.splitlines():
+        _category, body = _split_summary_category(line)
+        cleaned = _clean_summary_bullet(body)
+        if cleaned:
+            candidates.append(cleaned)
+    if len(candidates) <= 1 and raw:
+        candidates = [_clean_summary_bullet(part) for part in re.split(r'(?<=[.!?])\s+', raw)]
+        candidates = [item for item in candidates if item]
+    if not candidates:
+        candidates = [_clean_summary_bullet(item) for item in fallback_items]
+    bullets = _unique_summary_bullets(candidates)
+    return bullets or ['Updates are available.']
+
+
+def _categorized_summary_bullets_from_text(text: str) -> tuple[list[str], list[str]]:
+    notice_items: list[str] = []
+    worth_items: list[str] = []
+    for line in str(text or '').splitlines():
+        category, body = _split_summary_category(line)
+        if category == 'notice':
+            notice_items.append(body)
+        elif category == 'worth':
+            worth_items.append(body)
+        elif re.match(r'^\s*(?:[-*•]+|\d+[.)])?\s*[A-Za-z][A-Za-z ]{1,32}\s*:', str(line or '')):
+            notice_items.append(body)
+    return _unique_summary_bullets(notice_items), _unique_summary_bullets(worth_items)
+
+
+def _fallback_update_bullets(details: list[dict]) -> list[str]:
+    bullets = []
+    for item in details:
+        label = item.get('label') or item.get('name') or 'Hermes'
+        behind = item.get('behind') or 0
+        commits = item.get('commits') or []
+        if commits:
+            highlights = '; '.join(commits[:3])
+            qualifier = 'recent updates' if item.get('commits_truncated') else 'updates'
+            bullets.append(f"{label} has {behind} update(s), including {qualifier}: {highlights}.")
+        else:
+            bullets.append(f"{label} has {behind} update(s) available.")
+    return bullets or ['Updates are available.']
+
+
+def _worth_knowing_bullets(details: list[dict]) -> list[str]:
+    items = []
+    truncated = [item for item in details if item.get('commits_truncated') and item.get('commits_limit')]
+    for item in truncated[:2]:
+        label = item.get('label') or item.get('name') or 'Hermes'
+        behind = item.get('behind') or 0
+        limit = item.get('commits_limit') or len(item.get('commits') or [])
+        items.append(
+            f"{label} has {behind} updates; this summary uses the latest {limit} commit subjects, with the full comparison still available in the diff link."
+        )
+    if items:
+        return items
+    targets = [
+        f"{item.get('label') or item.get('name') or 'Hermes'} ({item.get('behind') or 0} update{'s' if (item.get('behind') or 0) != 1 else ''})"
+        for item in details
+        if item.get('behind')
+    ]
+    if len(targets) > 1:
+        return ['This summary combines updates from ' + ' and '.join(targets) + '.']
+    return []
+
+
+def _format_update_summary_sections(summary_text: str, details: list[dict]) -> tuple[list[dict], str]:
+    notice_items, worth_items = _categorized_summary_bullets_from_text(summary_text)
+    if not notice_items:
+        notice_items = _summary_bullets_from_text(summary_text, fallback_items=_fallback_update_bullets(details))
+    notice_keys = {item.lower() for item in notice_items}
+    worth_items = [item for item in worth_items if item.lower() not in notice_keys]
+    worth_items.extend(
+        item for item in _worth_knowing_bullets(details)
+        if item.lower() not in notice_keys and item.lower() not in {existing.lower() for existing in worth_items}
+    )
+    sections = [
+        {
+            'title': "What you'll notice",
+            'items': notice_items,
+        },
+    ]
+    if worth_items:
+        sections.append(
+            {
+                'title': 'Worth knowing',
+                'items': worth_items,
+            }
+        )
+    lines = []
+    for section in sections:
+        lines.append(section['title'])
+        lines.extend(f"- {item}" for item in section['items'])
+        lines.append('')
+    return sections, '\n'.join(lines).strip()
+
+
+def _fallback_update_summary(updates: dict, details: list[dict]) -> str:
+    _sections, summary = _format_update_summary_sections('', details)
+    return summary
+
+
+def _update_summary_prompt(details: list[dict]) -> tuple[str, str]:
+    system = (
+        "You write human-readable release summaries for Hermes users. "
+        "Focus on what the user will notice in the product. Keep it simple, specific, and short. "
+        "avoid technical jargon, implementation details, SHA names, branch names, and file paths unless necessary. "
+        "Return only bullets. Do not include headings, markdown tables, intro paragraphs, or closing notes."
+    )
+    user_lines = [
+        "Summarize these available updates as concise bullets.",
+        "Prefix each bullet with `Notice:` for user-visible behavior changes or `Worth knowing:` for useful context.",
+        "Put user-visible Notice bullets first and include every meaningful user-facing change from the available commit subjects.",
+        "Use Worth knowing only for helpful context that is not a duplicate of a Notice bullet.",
+        "Use everyday language and explain visible behavior changes, not code mechanics.",
+        "Return only prefixed bullets; the WebUI will add the fixed section headings separately.",
+        "",
+    ]
+    for item in details:
+        user_lines.append(f"{item['label']}: {item['behind']} commit(s) behind")
+        commits = item.get('commits') or []
+        if commits:
+            if item.get('commits_truncated'):
+                user_lines.append(
+                    f"- Showing latest {len(commits)} of {item['behind']} commit subjects; summarize trends, not every commit."
+                )
+            user_lines.extend(f"- {subject}" for subject in commits)
+        else:
+            user_lines.append("- No local commit subjects available; summarize only the update count.")
+        user_lines.append("")
+    return system, '\n'.join(user_lines)
+
+
+def summarize_update_payload(updates: dict, llm_callback=None, *, target: str | None = None, use_cache: bool = True) -> dict:
+    """Build a human-readable What's New summary and keep regular diff comparison links.
+
+    ``llm_callback`` receives ``(system_prompt, user_prompt)`` and returns text.
+    The caller may wire that to AIAgent; this module keeps a deterministic
+    fallback so the banner remains useful when no LLM provider is configured.
+    Summaries are cached per exact update range so refreshes do not generate
+    slightly different wording for the same available updates.
+    """
+    if not isinstance(updates, dict):
+        updates = {}
+    requested_target = target if target in ('webui', 'agent') else None
+    details = []
+    for key, label in (('webui', 'WebUI'), ('agent', 'Agent')):
+        if requested_target and key != requested_target:
+            continue
+        info = updates.get(key)
+        if not isinstance(info, dict) or int(info.get('behind') or 0) <= 0:
+            continue
+        commit_limit = 24
+        commits, commits_truncated = _commit_subjects_for_update_with_limit({'name': key, **info}, limit=commit_limit)
+        behind = int(info.get('behind') or 0)
+        item = {
+            'name': key,
+            'label': label,
+            'behind': behind,
+            'current_sha': info.get('current_sha'),
+            'latest_sha': info.get('latest_sha'),
+            'compare_url': info.get('compare_url'),
+            'commits': commits,
+            'commits_limit': commit_limit,
+            'commits_truncated': bool(commits_truncated or (commits and behind > len(commits))),
+        }
+        details.append(item)
+    cache_key = _summary_cache_key(updates, details)
+    if use_cache:
+        with _cache_lock:
+            cached = _summary_cache.get(cache_key)
+            if cached:
+                _summary_cache.move_to_end(cache_key)
+        if cached:
+            result = dict(cached)
+            result['cached'] = True
+            return result
+
+    generated_by = 'fallback'
+    candidate = ''
+    if details and callable(llm_callback):
+        system, prompt = _update_summary_prompt(details)
+        try:
+            candidate = (llm_callback(system, prompt) or '').strip()
+            if candidate:
+                generated_by = 'llm'
+        except Exception:
+            candidate = ''
+    sections, summary = _format_update_summary_sections(candidate, details)
+    result = {
+        'ok': True,
+        'summary': summary,
+        'summary_sections': sections,
+        'generated_by': generated_by,
+        'cached': False,
+        'cache_key': cache_key,
+        'target': requested_target,
+        'targets': details,
+    }
+    if use_cache:
+        with _cache_lock:
+            if len(_summary_cache) >= _SUMMARY_CACHE_MAX and cache_key not in _summary_cache:
+                _summary_cache.popitem(last=False)
+            _summary_cache[cache_key] = dict(result)
+    return result
+
+
+# ── Self-update application ───────────────────────────────────────────────────
+
+
 def _schedule_restart(delay: float = 2.0) -> None:
     """Re-exec this process after *delay* seconds.
 
@@ -292,19 +959,17 @@ def apply_force_update(target: str) -> dict:
         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)
+        # --force so a remote re-tag (e.g. squash-merge that re-points an
+        # existing release tag) doesn't jam the apply path with "would clobber
+        # existing tag". See #2756.
+        _, fetch_ok = _run_git(['fetch', 'origin', '--quiet', '--tags', '--force'], 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}'
+        compare_ref = _select_apply_compare_ref(path)
 
         # Discard local modifications then reset to remote HEAD
         _run_git(['checkout', '.'], path)
@@ -353,17 +1018,9 @@ def _apply_update_inner(target):
     if path is None or not (path / '.git').exists():
         return {'ok': False, 'message': 'Not a git repository'}
 
-    # Use the current branch's upstream for pull, matching the behaviour
-    # of _check_repo. Falls back to default branch if no upstream is set.
-    upstream, ok = _run_git(['rev-parse', '--abbrev-ref', '@{upstream}'], path)
-    if ok and upstream:
-        compare_ref = upstream
-    else:
-        branch = _detect_default_branch(path)
-        compare_ref = f'origin/{branch}'
-
     # Fetch before attempting pull, so the remote ref is current.
-    _, fetch_ok = _run_git(['fetch', 'origin', '--quiet'], path, timeout=15)
+    # --force so a remote re-tag doesn't block the update path (see #2756).
+    _, fetch_ok = _run_git(['fetch', 'origin', '--quiet', '--tags', '--force'], path, timeout=15)
     if not fetch_ok:
         return {
             'ok': False,
@@ -373,6 +1030,8 @@ def _apply_update_inner(target):
             ),
         }
 
+    compare_ref = _select_apply_compare_ref(path)
+
     # Check for dirty working tree (ignore untracked files — git stash
     # doesn't include them, so stashing on '??' alone leaves nothing to pop)
     status_out, status_ok = _run_git(
@@ -408,7 +1067,7 @@ def _apply_update_inner(target):
     if remote:
         pull_args.extend([remote, branch])
     else:
-        pull_args.append(compare_ref)
+        pull_args.extend(['origin', compare_ref])
     pull_out, pull_ok = _run_git(pull_args, path, timeout=30)
     if not pull_ok:
         if stashed:

api/upload.py

@@ -2,16 +2,19 @@
 Hermes Web UI -- File upload: multipart parser and upload handler.
 """
 import mimetypes
+import os
 import re as _re
 import email.parser
 import tempfile
 from pathlib import Path
 
-from api.config import MAX_UPLOAD_BYTES
+from api.config import MAX_UPLOAD_BYTES, STATE_DIR
 from api.helpers import j, bad
 from api.models import get_session
 from api.workspace import safe_resolve_ws
 
+_MAX_EXTRACTED_BYTES = 10 * MAX_UPLOAD_BYTES
+
 
 def parse_multipart(rfile, content_type, content_length) -> tuple:
     import re as _re, email.parser as _ep
@@ -59,6 +62,36 @@ def _sanitize_upload_name(filename: str) -> str:
     return safe_name
 
 
+def _attachment_root() -> Path:
+    """Return the configured upload inbox root.
+
+    Plain chat attachments are transient context for the agent, not project
+    source files.  Keep them out of the active workspace by default while still
+    allowing operators to move the inbox with HERMES_WEBUI_ATTACHMENT_DIR.
+    """
+    override = os.getenv('HERMES_WEBUI_ATTACHMENT_DIR', '').strip()
+    if override:
+        return Path(override).expanduser().resolve()
+    return (STATE_DIR / 'attachments').resolve()
+
+
+def _upload_destination(session_id: str, safe_name: str) -> Path:
+    dest_dir = _session_attachment_dir(session_id)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = (dest_dir / safe_name).resolve()
+    if not dest.is_relative_to(dest_dir):
+        raise ValueError('Invalid upload destination')
+    return dest
+
+
+def _session_attachment_dir(session_id: str, *, root: Path | None = None) -> Path:
+    root = (root or _attachment_root()).resolve()
+    dest_dir = (root / _re.sub(r'[^\w.\-]', '_', str(session_id or 'session'))[:120]).resolve()
+    if not dest_dir.is_relative_to(root):
+        raise ValueError('Invalid attachment directory')
+    return dest_dir
+
+
 def handle_upload(handler):
     import traceback as _tb
     try:
@@ -77,9 +110,8 @@ def handle_upload(handler):
             s = get_session(session_id)
         except KeyError:
             return j(handler, {'error': 'Session not found'}, status=404)
-        workspace = Path(s.workspace)
         safe_name = _sanitize_upload_name(filename)
-        dest = safe_resolve_ws(workspace, safe_name)
+        dest = _upload_destination(session_id, safe_name)
         dest.write_bytes(file_bytes)
         mime = mimetypes.guess_type(safe_name)[0] or 'application/octet-stream'
         return j(handler, {
@@ -96,11 +128,6 @@ 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.
 
@@ -231,8 +258,9 @@ def handle_upload_extract(handler):
             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)
+        session_dir = _session_attachment_dir(session_id)
+        session_dir.mkdir(parents=True, exist_ok=True)
+        result = extract_archive(file_bytes, filename, session_dir)
         return j(handler, {'ok': True, **result})
     except ValueError as e:
         return j(handler, {'error': str(e)}, status=400)

api/usage.py

@@ -0,0 +1,26 @@
+"""Usage metric helpers for WebUI display payloads.
+
+Prompt-cache hit percentage is cached prompt reads over the full prompt total
+(input + cache reads + cache writes). Keep this calculation in the backend so
+browser display code cannot drift across context indicator and per-turn labels.
+"""
+
+
+def _to_int(value) -> int:
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def prompt_cache_hit_percent(cache_read_tokens, prompt_tokens):
+    """Return cached reads as a percent of full prompt-token total.
+
+    ``prompt_tokens`` must include ordinary input, cache reads, and cache writes
+    (matching Agent's ``session_prompt_tokens`` value).
+    """
+    cache_read = _to_int(cache_read_tokens)
+    prompt = _to_int(prompt_tokens)
+    if cache_read <= 0 or prompt <= 0:
+        return None
+    return min(100, round((cache_read / prompt) * 100))

api/workspace.py

@@ -7,9 +7,11 @@ profile has its own workspace configuration.  State files live at
 ``{profile_home}/webui_state/last_workspace.txt``.  The global STATE_DIR
 paths are used as fallback when no profile module is available.
 """
+import hashlib
 import json
 import logging
 import os
+import stat
 import subprocess
 import concurrent.futures
 from pathlib import Path
@@ -63,7 +65,7 @@ def _profile_default_workspace() -> str:
       2. 'default_workspace' — alternate explicit key
       3. 'terminal.cwd'      — hermes-agent terminal working dir (most common)
 
-    Falls back to the boot-time DEFAULT_WORKSPACE constant.
+    Falls back to the live DEFAULT_WORKSPACE from api.config.
     """
     try:
         from api.config import get_config
@@ -85,14 +87,20 @@ def _profile_default_workspace() -> str:
                     return str(p)
     except (ImportError, Exception):
         logger.debug("Failed to load profile default workspace config")
-    return str(_BOOT_DEFAULT_WORKSPACE)
+    try:
+        from api.config import DEFAULT_WORKSPACE as _LIVE_DEFAULT_WORKSPACE
+
+        return str(Path(_LIVE_DEFAULT_WORKSPACE).expanduser().resolve())
+    except Exception:
+        return str(Path(_BOOT_DEFAULT_WORKSPACE).expanduser().resolve())
 
 
 # ── Public API ──────────────────────────────────────────────────────────────
 
 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
@@ -104,10 +112,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/).
@@ -130,6 +137,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.
 
@@ -517,10 +550,9 @@ def resolve_trusted_workspace(path: str | Path | None = None) -> Path:
 
     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}")
+    access_error = _workspace_access_error(candidate)
+    if access_error:
+        raise ValueError(access_error)
 
     # (A) Trusted if under the user's home directory — cross-platform via Path.home()
     # Must be checked before system roots to allow symlinks like /var/home.
@@ -566,6 +598,25 @@ 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).
 
@@ -575,13 +626,17 @@ def validate_workspace_to_add(path: str) -> Path:
 
     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()
 
-    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}")
+    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).
@@ -660,12 +715,18 @@ def list_dir(workspace: Path, rel: str='.'):
             display_path = str(Path(item.name))
             if rel and rel != '.':
                 display_path = rel + '/' + display_path
+            try:
+                item_stat = item.lstat()
+                mtime_ns = item_stat.st_mtime_ns
+            except OSError:
+                mtime_ns = None
             entry = {
                 'name': item.name,
                 'path': display_path,
                 'type': 'symlink',
                 'target': str(link_target),
                 'is_dir': is_dir,
+                'mtime_ns': mtime_ns,
             }
             if not is_dir:
                 try:
@@ -679,17 +740,49 @@ def list_dir(workspace: Path, rel: str='.'):
             entry_path = item.name
             if rel and rel != '.':
                 entry_path = rel + '/' + item.name
+            try:
+                item_stat = item.stat()
+                size = item_stat.st_size if item.is_file() else None
+                mtime_ns = item_stat.st_mtime_ns
+            except OSError:
+                size = None
+                mtime_ns = None
             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,
+                'size': size,
+                'mtime_ns': mtime_ns,
             })
         if len(entries) >= 200:
             break
     return entries
 
 
+def dir_signature(workspace: Path, rel: str = '.', entries: list[dict] | None = None) -> str:
+    """Return a cheap, stable signature for a listed workspace directory.
+
+    The signature is based only on bounded directory-entry metadata already used
+    by the workspace tree: names, displayed paths, entry type, file sizes,
+    mtimes, and symlink targets. It intentionally does not read file contents.
+    """
+    if entries is None:
+        entries = list_dir(workspace, rel)
+    payload = []
+    for entry in entries:
+        payload.append({
+            'name': entry.get('name'),
+            'path': entry.get('path'),
+            'type': entry.get('type'),
+            'is_dir': entry.get('is_dir'),
+            'size': entry.get('size'),
+            'mtime_ns': entry.get('mtime_ns'),
+            'target': entry.get('target'),
+        })
+    raw = json.dumps(payload, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
+    return hashlib.sha256(raw.encode('utf-8')).hexdigest()
+
+
 def read_file_content(workspace: Path, rel: str) -> dict:
     target = safe_resolve_ws(workspace, rel)
     if not target.is_file():

api/worktrees.py

@@ -0,0 +1,357 @@
+"""Helpers for WebUI-managed Hermes Agent git worktrees."""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from contextlib import redirect_stderr, redirect_stdout
+from io import StringIO
+from pathlib import Path
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _run_git(args: list[str], cwd: str | Path, timeout: float = 2) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args],
+        cwd=str(cwd),
+        text=True,
+        capture_output=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def _resolve_path(path: str | Path | None) -> Path | None:
+    if not path:
+        return None
+    try:
+        return Path(path).expanduser().resolve(strict=False)
+    except (OSError, RuntimeError):
+        return Path(path).expanduser()
+
+
+def _worktree_list_cwd(worktree_path: Path, repo_root: str | Path | None) -> Path | None:
+    repo = _resolve_path(repo_root)
+    if repo and repo.is_dir():
+        return repo
+    if worktree_path.is_dir():
+        return worktree_path
+    return None
+
+
+def _parse_worktree_list_porcelain(output: str) -> set[str]:
+    paths: set[str] = set()
+    for line in str(output or "").splitlines():
+        if not line.startswith("worktree "):
+            continue
+        path = line[len("worktree "):].strip()
+        if not path:
+            continue
+        resolved = _resolve_path(path)
+        paths.add(str(resolved or Path(path).expanduser()))
+    return paths
+
+
+def _worktree_listed(worktree_path: Path, repo_root: str | Path | None) -> bool:
+    """Return whether git currently lists the worktree.
+
+    False is a safe fallback for probe failures, not definitive orphan proof.
+    Future cleanup UI must combine this with the rest of the status payload.
+    """
+    cwd = _worktree_list_cwd(worktree_path, repo_root)
+    if cwd is None:
+        return False
+    try:
+        result = _run_git(["worktree", "list", "--porcelain"], cwd)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    if result.returncode != 0:
+        return False
+    return str(worktree_path) in _parse_worktree_list_porcelain(result.stdout)
+
+
+def _status_porcelain(worktree_path: Path) -> tuple[bool, int]:
+    try:
+        result = _run_git(
+            ["status", "--porcelain", "--untracked-files=normal"],
+            worktree_path,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False, 0
+    if result.returncode != 0:
+        return False, 0
+    lines = [line for line in result.stdout.splitlines() if line]
+    return bool(lines), sum(1 for line in lines if line.startswith("??"))
+
+
+def _ahead_behind(worktree_path: Path) -> dict:
+    payload = {
+        "ahead": 0,
+        "behind": 0,
+        "available": False,
+        "upstream": None,
+    }
+    try:
+        upstream = _run_git(
+            ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+            worktree_path,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return payload
+    if upstream.returncode != 0:
+        return payload
+    upstream_ref = upstream.stdout.strip()
+    if not upstream_ref:
+        return payload
+    payload["upstream"] = upstream_ref
+    try:
+        counts = _run_git(
+            ["rev-list", "--left-right", "--count", "HEAD...@{u}"],
+            worktree_path,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return payload
+    if counts.returncode != 0:
+        return payload
+    parts = counts.stdout.strip().split()
+    if len(parts) != 2:
+        return payload
+    try:
+        payload["ahead"] = max(0, int(parts[0]))
+        payload["behind"] = max(0, int(parts[1]))
+        payload["available"] = True
+    except ValueError:
+        pass
+    return payload
+
+
+def _locked_by_stream(session) -> bool:
+    stream_id = getattr(session, "active_stream_id", None)
+    if not stream_id:
+        return False
+    try:
+        from api.config import STREAMS, STREAMS_LOCK
+
+        with STREAMS_LOCK:
+            return stream_id in STREAMS
+    except Exception:
+        return False
+
+
+def _locked_by_terminal(session_id: str, worktree_path: Path) -> bool:
+    try:
+        from api.terminal import get_terminal
+
+        term = get_terminal(session_id)
+    except Exception:
+        return False
+    if not term:
+        return False
+    try:
+        if not term.is_alive():
+            return False
+        terminal_workspace = _resolve_path(getattr(term, "workspace", None))
+        return terminal_workspace == worktree_path
+    except Exception:
+        return False
+
+
+def worktree_status_for_session(session) -> dict:
+    """Return a read-only worktree status snapshot for a WebUI session."""
+    raw_path = getattr(session, "worktree_path", None)
+    if not raw_path:
+        raise ValueError("Session is not worktree-backed")
+
+    worktree_path = _resolve_path(raw_path)
+    if worktree_path is None:
+        raise ValueError("Session is not worktree-backed")
+
+    exists = worktree_path.is_dir()
+    status = {
+        "path": str(worktree_path),
+        "exists": bool(exists),
+        "dirty": False,
+        "untracked_count": 0,
+        "ahead_behind": {
+            "ahead": 0,
+            "behind": 0,
+            "available": False,
+            "upstream": None,
+        },
+        "locked_by_stream": _locked_by_stream(session),
+        "locked_by_terminal": _locked_by_terminal(
+            getattr(session, "session_id", ""),
+            worktree_path,
+        ),
+        "listed": _worktree_listed(
+            worktree_path,
+            getattr(session, "worktree_repo_root", None),
+        ),
+    }
+    if not exists:
+        return status
+
+    dirty, untracked_count = _status_porcelain(worktree_path)
+    status["dirty"] = dirty
+    status["untracked_count"] = untracked_count
+    status["ahead_behind"] = _ahead_behind(worktree_path)
+    return status
+
+
+def remove_worktree_for_session(session, *, force: bool = False) -> dict:
+    """Remove a session's git worktree from disk.
+
+    Returns status dict with keys: ok, removed_path, warnings.
+    Raises ValueError for terminal blockers (locked by stream/terminal,
+    dirty with force=False).
+    """
+    raw_path = getattr(session, "worktree_path", None)
+    if not raw_path:
+        raise ValueError("Session is not worktree-backed")
+
+    worktree_path = _resolve_path(raw_path)
+    if worktree_path is None:
+        raise ValueError("Session is not worktree-backed")
+
+    # Read current status before removal
+    status = worktree_status_for_session(session)
+
+    if not status["exists"]:
+        return {
+            "ok": True,
+            "removed_path": str(worktree_path),
+            "warnings": ["Worktree directory no longer exists on disk."],
+        }
+
+    warnings = []
+
+    # Guard: locked by stream
+    if status["locked_by_stream"]:
+        raise ValueError("Worktree is locked by an active streaming session")
+
+    # Guard: locked by terminal
+    if status["locked_by_terminal"]:
+        raise ValueError("Worktree is locked by an active terminal session")
+
+    # Guard: local changes and unpushed commits without explicit force.
+    if status["dirty"] and not force:
+        raise ValueError(
+            "Worktree has uncommitted changes. Use force=true to override."
+        )
+    if status["untracked_count"] > 0:
+        if force:
+            warnings.append(
+                f"{status['untracked_count']} untracked file(s) will be removed."
+            )
+        else:
+            raise ValueError(
+                f"Worktree has {status['untracked_count']} untracked file(s). "
+                "Use force=true to override."
+            )
+    ahead = int((status.get("ahead_behind") or {}).get("ahead") or 0)
+    if ahead > 0:
+        if force:
+            warnings.append(f"{ahead} unpushed commit(s) will be removed.")
+        else:
+            raise ValueError(
+                f"Worktree has {ahead} unpushed commit(s). "
+                "Use force=true to override."
+            )
+
+    # Remove the worktree — must run from the repo root, not the worktree dir
+    repo_root = getattr(session, "worktree_repo_root", None)
+    if not repo_root:
+        raise ValueError("Session missing worktree_repo_root")
+    try:
+        remove_args = ["worktree", "remove"]
+        if force:
+            remove_args.append("--force")
+        remove_args.append(str(worktree_path))
+        result = _run_git(remove_args, str(repo_root), timeout=10)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ValueError(f"Failed to remove worktree: {exc}") from exc
+
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip().split("\n")[-1]
+        raise ValueError(
+            f"git worktree remove failed: {stderr or result.stdout.strip()}"
+        )
+
+    # Prune in case the worktree dir was already gone
+    try:
+        _run_git(
+            ["worktree", "prune"],
+            str(repo_root),
+            timeout=5,
+        )
+    except Exception:
+        pass
+
+    return {
+        "ok": True,
+        "removed_path": str(worktree_path),
+        "warnings": warnings or None,
+    }
+
+
+def find_git_repo_root(workspace: str | Path) -> Path:
+    """Return the enclosing git repo root for *workspace*.
+
+    Use git itself instead of checking ``workspace/.git`` so nested workspaces
+    and linked git worktrees are both handled correctly.
+    """
+    ws = Path(workspace).expanduser().resolve()
+    if not ws.is_dir():
+        raise ValueError("Workspace path does not exist or is not a directory")
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=ws,
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ValueError("Workspace is not inside a git repository") from exc
+    if result.returncode != 0:
+        raise ValueError("Workspace is not inside a git repository")
+    root = result.stdout.strip()
+    if not root:
+        raise ValueError("Workspace is not inside a git repository")
+    return Path(root).expanduser().resolve()
+
+
+def _setup_agent_worktree(repo_root: str) -> dict:
+    try:
+        import api.config  # noqa: F401  # ensure Hermes Agent dir is on sys.path
+        from cli import _setup_worktree
+    except Exception as exc:
+        raise RuntimeError("Hermes Agent worktree helper is unavailable") from exc
+    output = StringIO()
+    with redirect_stdout(output), redirect_stderr(output):
+        info = _setup_worktree(repo_root)
+    emitted = output.getvalue().strip()
+    if emitted:
+        logger.debug("Hermes Agent worktree helper output: %s", emitted)
+    if not info:
+        raise RuntimeError("Hermes Agent failed to create a git worktree")
+    return info
+
+
+def create_worktree_for_workspace(workspace: str | Path) -> dict:
+    repo_root = find_git_repo_root(workspace)
+    info = _setup_agent_worktree(str(repo_root))
+    path = info.get("path")
+    branch = info.get("branch")
+    if not path or not branch:
+        raise RuntimeError("Hermes Agent returned incomplete worktree metadata")
+    return {
+        "path": str(Path(path).expanduser().resolve()),
+        "branch": str(branch),
+        "repo_root": str(Path(info.get("repo_root") or repo_root).expanduser().resolve()),
+        "created_at": time.time(),
+    }

bootstrap.py

@@ -90,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 = [
@@ -105,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:
@@ -179,7 +220,16 @@ def ensure_python_has_webui_deps(python_exe: str, agent_dir: Path | None = None)
     )
     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(

ctl.sh

@@ -0,0 +1,371 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HERMES_HOME="${HERMES_HOME:-${HOME}/.hermes}"
+PID_FILE="${HERMES_WEBUI_PID_FILE:-${HERMES_HOME}/webui.pid}"
+LOG_FILE="${HERMES_WEBUI_LOG_FILE:-${HERMES_HOME}/webui.log}"
+STATE_FILE="${HERMES_WEBUI_CTL_STATE_FILE:-${HERMES_HOME}/webui.ctl.env}"
+DEFAULT_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${HERMES_HOME}/webui}"
+
+usage() {
+  cat <<'EOF'
+Usage: ./ctl.sh <command> [args]
+
+Commands:
+  start [bootstrap args...]   Start Hermes WebUI as a background daemon
+  stop                        Stop the daemon started by ctl.sh
+  restart [bootstrap args...] Stop, then start again
+  status                      Show daemon, host/port, log, and health status
+  logs [--lines N] [--follow|--no-follow]
+                              Show the daemon log (defaults to tail -n 100 -f)
+EOF
+}
+
+ensure_home() {
+  mkdir -p "${HERMES_HOME}" "${DEFAULT_STATE_DIR}"
+}
+
+_load_repo_dotenv_preserving_env() {
+  local env_file="${REPO_ROOT}/.env"
+  [[ -f "${env_file}" ]] || return 0
+
+  local -a preserved=()
+  local line key value
+  while IFS= read -r line || [[ -n "${line}" ]]; do
+    line="${line#${line%%[![:space:]]*}}"
+    [[ -z "${line}" || "${line}" == \#* || "${line}" != *=* ]] && continue
+    key="${line%%=*}"
+    key="${key#export }"
+    key="${key//[[:space:]]/}"
+    [[ "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    if [[ -n "${!key+x}" ]]; then
+      value="${!key}"
+      preserved+=("${key}=${value}")
+    fi
+  done < "${env_file}"
+
+  set -a
+  # shellcheck source=/dev/null
+  source "${env_file}"
+  set +a
+
+  local assignment
+  if [[ ${#preserved[@]} -gt 0 ]]; then
+    for assignment in "${preserved[@]}"; do
+      export "${assignment}"
+    done
+  fi
+}
+
+_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" python_exe="${4:-}"
+  local state_dir="${HERMES_WEBUI_STATE_DIR:-${DEFAULT_STATE_DIR}}"
+  {
+    printf 'PID=%q\n' "${pid}"
+    printf 'REPO_ROOT=%q\n' "${REPO_ROOT}"
+    printf 'PYTHON_EXE=%q\n' "${python_exe}"
+    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="" state_python=""
+  [[ -f "${STATE_FILE}" ]] || return 1
+  _load_state_if_present
+  state_repo="${REPO_ROOT:-}"
+  state_python="${PYTHON_EXE:-}"
+  [[ "${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"* || ( -n "${state_python}" && "${args}" == *"${state_python}"* ) ]]
+}
+
+_current_pid() {
+  local pid
+  pid="$(_pid_from_file)" || return 1
+  if _is_alive "${pid}" && _is_owned_webui_pid "${pid}"; then
+    printf '%s\n' "${pid}"
+    return 0
+  fi
+  return 1
+}
+
+_clear_stale_pid() {
+  if [[ -f "${PID_FILE}" ]]; then
+    rm -f "${PID_FILE}" "${STATE_FILE}"
+    echo "[ctl] Removed stale PID file: ${PID_FILE}"
+  fi
+}
+
+start_cmd() {
+  ensure_home
+  _load_repo_dotenv_preserving_env
+  export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${DEFAULT_STATE_DIR}}"
+  mkdir -p "${HERMES_WEBUI_STATE_DIR}"
+  _parse_launch_binding "$@"
+  _build_bootstrap_args "$@"
+  export HERMES_WEBUI_HOST="${CTL_HOST}"
+  export HERMES_WEBUI_PORT="${CTL_PORT}"
+
+  local existing_pid
+  if existing_pid="$(_current_pid 2>/dev/null)"; then
+    echo "[ctl] Hermes WebUI is already running (PID ${existing_pid})"
+    return 0
+  fi
+  _clear_stale_pid >/dev/null 2>&1 || true
+
+  local python_exe pid
+  python_exe="$(_find_python)"
+  : >> "${LOG_FILE}"
+  (
+    cd "${REPO_ROOT}"
+    exec "${python_exe}" "${REPO_ROOT}/bootstrap.py" --no-browser --foreground --host "${CTL_HOST}" "${CTL_PORT}" ${CTL_BOOTSTRAP_ARGS[@]+"${CTL_BOOTSTRAP_ARGS[@]}"}
+  ) >> "${LOG_FILE}" 2>&1 &
+  pid=$!
+
+  printf '%s\n' "${pid}" > "${PID_FILE}"
+  _write_state "${pid}" "${CTL_HOST}" "${CTL_PORT}" "${python_exe}"
+  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

@@ -109,13 +109,15 @@ services:
       # Same hermes home as the agent — shares config, sessions, state
       - hermes-home:/home/hermeswebui/.hermes
       # Agent source mounted where docker_init.bash expects it.
-      # At startup the init script runs:
-      #   uv pip install /home/hermeswebui/.hermes/hermes-agent
-      # which installs the agent and all its Python dependencies.
-      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
+      # Mounted read-only — the WebUI only reads this volume to install
+      # the agent's Python dependencies at startup (`uv pip install`).
+      # Read-only enforces that defence-in-depth at the kernel layer.
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro
       # Workspace directory — browse and edit files from the WebUI.
       # Adapt the host path to your project directory.
-      - ${HERMES_WORKSPACE:-~/workspace}:/workspace
+      # ${HOME} is used rather than `~` so the default resolves the same way
+      # across Linux, macOS, WSL2, and Docker Desktop on Windows.
+      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
     environment:
       - HERMES_WEBUI_HOST=0.0.0.0
       - HERMES_WEBUI_PORT=8787
@@ -150,5 +152,17 @@ networks:
     driver: bridge
 
 volumes:
+  # IMPORTANT — upgrading the agent image:
+  #   The `hermes-agent-src` volume is initialised from the agent image's
+  #   `/opt/hermes` on first `up`, and Docker reuses the volume verbatim on
+  #   later runs — even after `docker pull` of a newer agent image. After
+  #   upgrading the agent image, run:
+  #
+  #     docker compose -f docker-compose.three-container.yml down
+  #     docker volume rm <project>_hermes-agent-src
+  #     docker compose -f docker-compose.three-container.yml pull
+  #     docker compose -f docker-compose.three-container.yml up -d
+  #
+  #   The full procedure (and why) is documented in docs/docker.md.
   hermes-home:
   hermes-agent-src:

docker-compose.two-container.yml

@@ -91,14 +91,16 @@ services:
       # Same hermes home as the agent — shares config, sessions, state
       - hermes-home:/home/hermeswebui/.hermes
       # Agent source mounted where docker_init.bash expects it.
-      # At startup the init script runs:
-      #   uv pip install /home/hermeswebui/.hermes/hermes-agent
-      # which installs the agent and all its Python dependencies.
-      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
+      # Mounted read-only — the WebUI only reads this volume to install
+      # the agent's Python dependencies at startup (`uv pip install`).
+      # Read-only enforces that defence-in-depth at the kernel layer.
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro
       # Workspace directory — browse and edit files from the WebUI.
       # Adapt the host path to your project directory.
       # Override with: HERMES_WORKSPACE=/your/path docker compose up
-      - ${HERMES_WORKSPACE:-~/workspace}:/workspace
+      # ${HOME} is used rather than `~` so the default resolves the same way
+      # across Linux, macOS, WSL2, and Docker Desktop on Windows.
+      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
     environment:
       - HERMES_WEBUI_HOST=0.0.0.0
       - HERMES_WEBUI_PORT=8787
@@ -129,5 +131,17 @@ networks:
     driver: bridge
 
 volumes:
+  # IMPORTANT — upgrading the agent image:
+  #   The `hermes-agent-src` volume is initialised from the agent image's
+  #   `/opt/hermes` on first `up`, and Docker reuses the volume verbatim on
+  #   later runs — even after `docker pull` of a newer agent image. After
+  #   upgrading the agent image, run:
+  #
+  #     docker compose down
+  #     docker volume rm <project>_hermes-agent-src
+  #     docker compose pull
+  #     docker compose up -d
+  #
+  #   The full procedure (and why) is documented in docs/docker.md.
   hermes-home:
   hermes-agent-src:

docker_init.bash

@@ -25,7 +25,8 @@ export ENV_OBFUSCATE_PART="TOKEN API KEY"
 if [ -z "${ENV_IGNORELIST+x}" ]; then error_exit "ENV_IGNORELIST not set"; fi
 if [ -z "${ENV_OBFUSCATE_PART+x}" ]; then error_exit "ENV_OBFUSCATE_PART not set"; fi
 
-whoami=`whoami`
+# whoami fails under set -e if the UID has no /etc/passwd entry (k8s runAsUser).
+whoami=$(whoami 2>/dev/null || echo "uid-$(id -u)")
 script_dir=$(dirname $0)
 script_name=$(basename $0)
 echo ""; echo ""
@@ -36,25 +37,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 +89,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 +121,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 +181,96 @@ 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
+chown_home_hermeswebui() {
+  # macOS Docker bind mounts can expose hermes-agent git object packs as
+  # read-only host files. The runtime only needs to read those existing objects;
+  # requiring chown on them makes startup fail before WebUI can run (#2237).
+  #
+  # Multi-container compose (#2470) additionally mounts the entire
+  # hermes-agent-src volume read-only on the WebUI side because the WebUI only
+  # reads it for `uv pip install`. On a :ro mount, chown returns EROFS for any
+  # file inside the subtree, which would propagate to `set -e` and kill startup
+  # before the WebUI can run. Either way, the WebUI never writes to the agent
+  # source — prune the entire hermes-agent path from the chown walk so a
+  # read-only or partially-read-only mount doesn't break the rest of the home
+  # ownership alignment.
+  find /home/hermeswebui \
+    -path "/home/hermeswebui/.hermes/hermes-agent" -prune \
+    -o -exec chown -h "${WANTED_UID}:${WANTED_GID}" {} +
+}
+
+# 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_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"
+  # Issue #2010 — Railway / user-namespaced runtimes: in-container UID 0 may map
+  # to a host UID outside the writable subuid range, so /tmp writes fail despite
+  # id -u == 0. Probe writability and fall back through $itdir → /app.
+  ENV_FILE="/tmp/hermeswebui_root_env.txt"
+  if ! ( : > "$ENV_FILE" ) 2>/dev/null; then
+    ENV_FILE="${itdir:-/tmp/hermeswebui_init}/hermeswebui_root_env.txt"
+    mkdir -p "$(dirname "$ENV_FILE")" 2>/dev/null
+    if ! ( : > "$ENV_FILE" ) 2>/dev/null; then
+      ENV_FILE="/app/.hermeswebui_root_env"
+    fi
+    echo "  !! /tmp not writable by root — falling back to $ENV_FILE (user-namespaced runtime?)"
+  fi
+  save_env "$ENV_FILE"
+  chown "${WANTED_UID}:${WANTED_GID}" "$ENV_FILE" || error_exit "Failed to set owner of $ENV_FILE"
+  chmod 600 "$ENV_FILE" || error_exit "Failed to secure $ENV_FILE"
+  export _HW_ROOT_ENV_PATH="$ENV_FILE"
+
   # 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 +279,21 @@ 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="${_HW_ROOT_ENV_PATH:-/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"
+if [ ! -f /app/server.py ] && [ -d /apptoo ]; then
+  echo ""; echo "-- Seeding /app from /apptoo (rootless startup)"
+  cp -a /apptoo/. /app/ || error_exit "Failed to seed /app from /apptoo (is /app writable by the runtime user?)"
+fi
+
+echo ""; echo "-- Verifying /app is writable by the hermeswebui runtime user"
+if [ ! -d /app ]; then error_exit "/app directory does not exist"; fi
 it=/app/.testfile; touch $it || error_exit "Failed to verify /app directory"
 rm -f $it || error_exit "Failed to delete test file in /app"
 
@@ -228,7 +301,7 @@ rm -f $it || error_exit "Failed to delete test file in /app"
 
 echo ""; echo "== Checking required environment variables for hermes-webui"
 
-echo ""; echo "-- HERMES_WEBUI_VERSION: Where to store sessions, workspaces, and other state (default: ~/.hermes/webui-mvp)"
+echo ""; echo "-- HERMES_WEBUI_STATE_DIR: Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)"
 if [ -z "${HERMES_WEBUI_STATE_DIR+x}" ]; then error_exit "HERMES_WEBUI_STATE_DIR not set"; fi; 
 echo "-- HERMES_WEBUI_STATE_DIR: $HERMES_WEBUI_STATE_DIR"
 if [ ! -d "$HERMES_WEBUI_STATE_DIR" ]; then mkdir -p $HERMES_WEBUI_STATE_DIR || error_exit "Failed to create state directory at $HERMES_WEBUI_STATE_DIR"; fi
@@ -239,19 +312,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 +338,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
@@ -319,7 +391,49 @@ else
     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"
+    if [ -w "$_agent_src" ]; then
+      echo ""
+      echo "!! WARNING: hermes-agent source mount is writable from the WebUI container."
+      echo "!!   Path: $_agent_src"
+      echo "!! The multi-container compose defaults use a read-only mount for defence-in-depth."
+      echo "!! If this is not an intentional local development checkout, switch the WebUI"
+      echo "!! agent source volume/bind mount to read-only. See docs/rfcs/agent-source-boundary.md."
+      echo ""
+    fi
+    # The agent source can be mounted read-only (see docker-compose.two-container.yml
+    # / docker-compose.three-container.yml — the WebUI only reads this volume to
+    # install the agent's Python dependencies and never writes to it). setuptools'
+    # `egg_info` build step, however, touches `hermes_agent.egg-info/` inside the
+    # source tree even under PEP 517 build isolation, which `EROFS`-fails on a
+    # `:ro` mount and (under `set -e`) kills startup of every multi-container
+    # deploy. Stage the source into a writable tmpfs copy so the build can write
+    # its metadata side-by-side without touching the underlying mount.
+    #
+    # The copy excludes any pre-baked `*.egg-info` / `build` / `dist` artifacts
+    # to avoid the timestamp-update path setuptools takes when one is present,
+    # and `--reflink=auto` makes the copy near-free on overlay2/btrfs where
+    # supported. We rebuild on every container start (the agent source can
+    # change across volume re-init); cost is one rsync of ~10MB of Python source.
+    _stage_src="/tmp/hermes-agent-build"
+    rm -rf "$_stage_src"
+    mkdir -p "$_stage_src"
+    if command -v rsync >/dev/null 2>&1; then
+      rsync -a \
+        --exclude='*.egg-info' --exclude='build' --exclude='dist' \
+        --exclude='__pycache__' --exclude='.git' \
+        "$_agent_src"/ "$_stage_src"/ \
+        || error_exit "Failed to stage hermes-agent source to writable build dir"
+    else
+      # Fallback when rsync isn't in the image — straight cp -a, then drop
+      # the build artifacts that would trip setuptools.
+      cp -a "$_agent_src"/. "$_stage_src"/ \
+        || error_exit "Failed to copy hermes-agent source to writable build dir"
+      rm -rf "$_stage_src"/*.egg-info "$_stage_src"/build "$_stage_src"/dist 2>/dev/null || true
+      find "$_stage_src" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+    fi
+    uv pip install "$_stage_src[all]" --trusted-host pypi.org --trusted-host files.pythonhosted.org \
+      || error_exit "Failed to install hermes-agent's requirements"
+    rm -rf "$_stage_src"
   else
     echo ""
     echo "!! WARNING: hermes-agent source not found."

docs/CONTRACTS.md

@@ -0,0 +1,173 @@
+# Project Contracts
+
+This document is a contributor-facing index for existing Hermes WebUI contracts,
+RFCs, design constraints, and review expectations. It does not replace the
+source documents and it does not mark proposals as implemented. Follow each
+linked document's status and scope.
+
+Use this file when starting a change so the relevant public contract is visible
+before code is edited. This first version focuses on documentation routing; it
+does not change runtime behavior, maintainer policy, bot behavior, or CI gates.
+
+## Start here
+
+- [`AGENTS.md`](../AGENTS.md): repository entry point for AI assistants,
+  public-safety rules, and the short redline checklist.
+- [`CONTRIBUTING.md`](../CONTRIBUTING.md): contribution style, verification,
+  PR description expectations, UI evidence, and project-specific constraints.
+- [`README.md`](../README.md): product overview, quick start, architecture map,
+  feature inventory, and docs index.
+- [`CHANGELOG.md`](../CHANGELOG.md): release-note-ready history. Update it when
+  maintainers should carry the change into release notes.
+
+## Runtime, durability, and state contracts
+
+- [`docs/rfcs/webui-run-state-consistency-contract.md`](rfcs/webui-run-state-consistency-contract.md):
+  proposed consistency rules for current WebUI streaming, recovery, replay,
+  model-context reconstruction, compression, UI scene/cache, and sidebar metadata
+  repairs. Start here for narrow fixes that keep the existing WebUI execution
+  path.
+- [`docs/rfcs/hermes-run-adapter-contract.md`](rfcs/hermes-run-adapter-contract.md):
+  proposed event/control contract, runtime-state ownership matrix,
+  acceptance-test catalog, and reversible migration gates for moving WebUI
+  execution behind an adapter boundary. Use this for adapter-seam, control-plane,
+  runner, sidecar, or execution-ownership work; do not treat it as authorization
+  to implement those slices.
+- [`docs/rfcs/turn-journal.md`](rfcs/turn-journal.md): proposed crash-safe
+  write-ahead journal for browser-originated chat turns.
+- [`docs/rfcs/README.md`](rfcs/README.md): RFC conventions and current RFC index.
+
+When a change touches streaming, recovery, replay, compression, context
+reconstruction, cancellation, approval/clarify, session metadata, or run state,
+read the relevant RFC before editing. In the PR description, name the state layer
+or event/control surface affected and include a regression test or manual
+verification for the relevant invariant.
+
+Proposed RFCs are review guardrails, not implementation authorization. Do not
+implement RFC fragments unless the task or tracking issue explicitly asks for
+that slice.
+
+## UI, UX, and theme contracts
+
+- [`DESIGN.md`](../DESIGN.md): design tokens and the current calm-console
+  direction: conversation first, quiet metadata, restrained accents, and
+  progressive disclosure for debugging detail.
+- [`docs/UIUX-GUIDE.md`](UIUX-GUIDE.md): contributor-facing synthesis of the
+  repository's UI/UX principles, sourced from existing project docs and code
+  comments.
+- [`docs/ui-ux/index.html`](ui-ux/index.html): message-area inventory wired to
+  the real app stylesheet.
+- [`docs/ui-ux/two-stage-proposal.html`](ui-ux/two-stage-proposal.html):
+  existing two-stage chat UX proposal for issue #536.
+- [`THEMES.md`](../THEMES.md): theme and skin guidance; the core palette
+  variable contract lives in `static/style.css`.
+
+Current appearance has a theme axis (`light`, `dark`, `system`) and a separate
+skin axis (`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`,
+`charizard`, `sienna`, `catppuccin`, `nous`, `geist-contrast`) in
+`static/boot.js` and `static/style.css`. Do not follow stale `data-theme`-only theme guidance unless
+the current code and tests prove that model still applies.
+
+For UI or UX work, include before/after evidence, verify relevant responsive
+states, and prefer stable class/data hooks over one-off visual behavior.
+
+## Choosing the relevant contract
+
+Before editing, identify which contract family the task exercises. This is a
+routing check, not a request to read every document in the repository. Read the
+documents that match the touched subsystem.
+
+Use this lightweight note in an issue comment, draft PR, task note, or AI-agent
+handoff when it helps clarify scope:
+
+```markdown
+## Contract Routing
+
+Task type:
+Touched areas:
+Relevant public docs:
+- `AGENTS.md`
+- `CONTRIBUTING.md`
+- `docs/CONTRACTS.md`
+- <subsystem-specific documents>
+Scope boundaries:
+Evidence needed before claiming done:
+```
+
+For small, obvious fixes, keep this short. The goal is to avoid routing mistakes,
+not to create process overhead.
+
+## PR preparation checklist
+
+Before opening or updating a PR, verify `CONTRIBUTING.md` against the actual PR
+body. This checklist applies even when code and tests are already done.
+
+Required checks:
+
+- The PR solves one logical problem.
+- The PR body contains all required sections from `CONTRIBUTING.md`:
+  `Thinking Path`, `What Changed`, `Why It Matters`, `Verification`,
+  `Risks / Follow-ups`, and `Model Used`.
+- `Model Used` discloses provider/model and notable agent/tool use, or says
+  `None -- human-authored`.
+- UI/UX changes include before/after evidence and responsive-state coverage.
+- Runtime/streaming changes name the state layer or invariant being changed and
+  list the regression or manual invariant check.
+- Onboarding/setup validation used isolated `HERMES_HOME` and
+  `HERMES_WEBUI_STATE_DIR`, unless the human operator explicitly requested real
+  state.
+- Docs and `CHANGELOG.md` updates are either included or explicitly not needed.
+- After the GitHub write, read the PR back and verify the headings rendered as
+  intended.
+
+Green CI plus a focused diff is not sufficient if the PR description or evidence
+does not match the touched subsystem.
+
+## Setup, onboarding, and operational references
+
+- [`TESTING.md`](../TESTING.md): automated test command and manual browser test
+  plan.
+- [`ARCHITECTURE.md`](../ARCHITECTURE.md): API, module layout, and design
+  constraints.
+- [`docs/onboarding.md`](onboarding.md): first-run wizard and provider setup.
+- [`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md): safety
+  rules for assistant-led install, reinstall, bootstrap, provider setup, local
+  model setup, Docker onboarding, and WSL onboarding.
+- [`docs/docker.md`](docker.md): Docker compose setup, common failures, and
+  bind-mount migration.
+- [`docs/troubleshooting.md`](troubleshooting.md): diagnostic flows for common
+  failures.
+- [`docs/EXTENSIONS.md`](EXTENSIONS.md): administrator-controlled WebUI
+  extension injection.
+
+## Quick redline checklist
+
+Before opening a change for review, confirm:
+
+- The change solves one logical problem; unrelated refactors are split out.
+- `AGENTS.md`, this index, and any linked contract for the touched subsystem were
+  read before editing.
+- Behavior, setup, architecture, testing, or workflow changes update the relevant
+  docs; release-note-ready changes update `CHANGELOG.md`.
+- UI/UX changes include before/after evidence and cover relevant desktop,
+  narrow, and mobile states.
+- Runtime, streaming, recovery, replay, compression, or sidebar changes state
+  which layer they mutate and include a regression for the invariant.
+- New dependencies, build tools, frameworks, or long-lived processes are avoided
+  unless the benefit and rollback story are explicit.
+- Onboarding/setup validation uses isolated `HERMES_HOME` and
+  `HERMES_WEBUI_STATE_DIR` unless the human operator explicitly asks to use real
+  state.
+- Secrets, private paths, local-only workflows, and personal notes stay out of
+  tracked docs and examples.
+
+## Future evolution
+
+This index is not intended to make the first contract set final. Future PRs may
+add, revise, split, or retire contracts when real issues, implementation changes,
+RFC decisions, contributor feedback, or review experience show that guidance is
+incomplete or stale.
+
+Potential follow-up areas include session import/export, cron, extensions,
+security boundaries, Docker/runtime isolation, and lightweight checks that keep
+key contract links from drifting.

docs/UIUX-GUIDE.md

@@ -0,0 +1,191 @@
+# UI/UX Guide
+
+This document summarizes UI/UX principles that are already visible in the
+repository. It is a contributor guide, not a new design proposal. Source
+documents include [`DESIGN.md`](../DESIGN.md), [`README.md`](../README.md),
+[`THEMES.md`](../THEMES.md), [`docs/ui-ux/index.html`](ui-ux/index.html),
+[`docs/ui-ux/two-stage-proposal.html`](ui-ux/two-stage-proposal.html), and
+design comments in `static/style.css`.
+
+Use this guide when a change touches layout, chat rendering, composer chrome,
+navigation, theme/skin behavior, responsive behavior, or visual hierarchy. For
+purely backend changes, use the runtime/state contracts instead.
+
+## Product shape
+
+Hermes WebUI is a browser workbench for Hermes Agent with near-CLI parity and a
+simple implementation shape: Python on the server, vanilla JavaScript in the
+browser, no build step, no bundler, and no frontend framework.
+
+The primary layout is three-panel:
+
+- left sidebar for sessions and navigation,
+- center panel for chat,
+- right panel for workspace file browsing and previews.
+
+Model, profile, workspace, attachments, voice input, context usage, Stop, and
+Send controls live in the composer footer. Settings and session-level tools live
+in the Hermes Control Center. Preserve this shape unless the change explicitly
+justifies a different interaction model.
+
+## Core feeling: calm developer console
+
+The main artifact is the conversation. Tool calls, thinking traces, context
+compaction records, token usage, runtime status, and other internals are useful,
+but they are transcript metadata. They should sit below user and assistant prose
+in visual priority.
+
+Prefer:
+
+- quiet surfaces,
+- clear spacing,
+- restrained accent use,
+- progressive disclosure for debugging detail,
+- legible text over decorative chrome.
+
+Avoid turning the interface into a demo page of colorful cards. Errors,
+approvals, and other action-required states may be prominent because the user
+must notice and respond to them.
+
+## Conversation hierarchy
+
+A chat turn should read as one coherent story:
+
+1. User message: right-aligned, compact bubble.
+2. Assistant content: left-aligned, prose-first, not a heavy bubble.
+3. Tool, thinking, progress, and context traces: quiet disclosure rows inside or
+   adjacent to the assistant turn.
+4. Raw logs and verbose details: hidden until explicitly expanded.
+
+Do not render every internal event as a first-class chat card. A turn that used
+many tools should summarize the work as inspectable activity, not make the user
+read a stack of unrelated-looking cards.
+
+## Tool, thinking, and activity traces
+
+Tool cards are debug event rows, not chat messages. Show the icon, name, short
+target or preview, and status first. Arguments, result snippets, and long logs
+belong behind expansion, with result snippets truncated and full output behind a
+show-more affordance where needed.
+
+Thinking and context cards should share the quiet metadata visual family. They
+should not overpower assistant prose. Collapsed activity summaries should be
+terse, for example `Activity: 4 tools`, and should not duplicate the thinking
+area, list every tool name in the summary, or add redundant trailing count
+badges.
+
+The existing two-stage proposal in `docs/ui-ux/two-stage-proposal.html` records a
+compatible direction for long turns: live work can be grouped as a worklog, then
+settled history can collapse while the final answer reads as the calm
+conclusion. Treat that page as an existing proposal, not as shipped behavior
+unless the code and tests prove it is implemented.
+
+## Typography and content
+
+Use split typography intentionally:
+
+- assistant prose uses the same system sans stack as the rest of the UI by
+  default (`--font-ui` in `static/style.css`),
+- editorial serif assistant prose is historical/proposal or skin-scoped only;
+  do not reintroduce a global assistant serif without explicit design approval
+  plus code and test evidence,
+- user bubbles and functional UI also use the system sans stack unless a scoped
+  skin intentionally overrides typography,
+- monospace is for code, file paths, commands, tool names, and compact metadata.
+
+Keep scale tight. Avoid introducing near-duplicate one-off font sizes, colors,
+radius values, or spacing values when an existing token works.
+
+## Color, depth, and shape
+
+Use one accent at a time. Semantic colors are for semantic state: success,
+warning, error, and info. Do not mix many bright colors decoratively in the same
+viewport.
+
+Use almost no shadows in the transcript. Reserve shadows for popovers,
+dropdowns, modals, and floating controls. Chat cards should usually use either a
+subtle border or a subtle tint, not aggressive combinations of both.
+
+Avoid stacks of nested rounded rectangles. Rows and list items should feel
+compact; panels and cards may be slightly rounder; true pills are reserved for
+chips and badges.
+
+## Composer and controls
+
+The composer is the command surface. Keep it legible, stable, and focused:
+
+- no theatrical hover scaling for routine controls,
+- no ambient chrome that crowds the model/workspace/profile controls,
+- no new footer buttons on tight layouts without a clear value tradeoff,
+- keep Stop/Send and context feedback easy to find while composing.
+
+When adding a control, consider where users will find it on both wide desktop and
+mobile. If a setting or quota/control surface does not fit in the composer, route
+it through the appropriate Control Center panel instead of squeezing the footer.
+
+## Responsive behavior
+
+Mobile is not an afterthought. The repository documents a responsive layout with
+a hamburger sidebar, mobile-accessible top tabs, a right-edge file slide-over,
+full-height chat/composer behavior on phones, and touch-friendly controls.
+
+For UI changes, verify the relevant states:
+
+- wide desktop,
+- ordinary laptop width,
+- narrow/mobile width,
+- open and closed side panels when relevant,
+- long chat content and live streaming when relevant.
+
+Controls should remain usable at touch sizes, and mobile navigation should not
+steal chat height unnecessarily.
+
+## Themes and skins
+
+Theme and skin work should use the existing variable system. `THEMES.md` points
+to the core palette variables in `static/style.css`; skin comments in the CSS
+show the expected pattern for full palette rewrites and accent-only changes.
+
+Current implementation has two appearance axes, sourced from `static/boot.js`:
+`theme` is only `light`, `dark`, or `system` and resolves to the `.dark` class
+for dark mode; `skin` is a separate axis applied with `data-skin` and currently
+includes `default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`,
+`charizard`, `sienna`, `catppuccin`, `nous`, and `geist-contrast` / Geist Contrast. `slate` is both an active skin
+and a legacy theme-name migration target; `solarized`, `monokai`, `nord`, and
+`oled` are legacy theme names mapped to current theme/skin pairs. Do not follow
+stale `data-theme`-only guidance without first proving the current
+`static/boot.js`, `static/index.html`, and `static/style.css` contracts still
+support it.
+
+Do not hardcode new colors, radii, shadows, or typography values into isolated
+components when a token or existing variable can carry the intent. If a token is
+missing, explain why a new one is needed.
+
+## Evidence expected for UI changes
+
+For any interface or interaction change:
+
+- include before/after images or a short video,
+- mention the tested viewport sizes and responsive states,
+- reference the affected visual inventory or design source when applicable,
+- add or update tests for behavior, state persistence, or regression-prone DOM
+  structure where practical,
+- keep stable class or data hooks when they help future visual regression tests.
+
+## Do / don't summary
+
+Do:
+
+- keep the conversation primary,
+- collapse noisy internals by default when settled,
+- make debugging details accessible without making them visually dominant,
+- use existing tokens, variables, and component patterns,
+- protect action-required states such as errors and approvals.
+
+Don't:
+
+- make every tool call look like a separate chat message,
+- add decorative color or motion without a user-facing reason,
+- introduce a frontend framework, bundler, or build step for ordinary UI work,
+- hide important recovery, error, or approval state,
+- treat proposal mockups as shipped behavior without code/test evidence.

docs/docker.md

@@ -13,6 +13,24 @@ This is the comprehensive Docker reference. For a 5-minute quickstart, see the [
 
 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
@@ -24,7 +42,21 @@ 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.
+That's it for a real personal Docker install. Your existing `~/.hermes`
+directory is mounted, your `~/workspace` is browsable, and the WebUI
+auto-detects your UID/GID from the mounted volume.
+
+The single-container setup runs the WebUI only. It can create cron jobs and run
+them manually from the Tasks panel. In Docker, scheduled jobs require the Hermes gateway daemon
+to tick while you are away. If System Settings shows `Gateway not configured`,
+use `docker-compose.two-container.yml`,
+`docker-compose.three-container.yml`, or run `hermes gateway` separately before
+relying on offline scheduled runs.
+
+For troubleshooting, reinstall, or onboarding reproduction trials, do not mount
+your real `~/.hermes` unless you intentionally want to test real state. Use an
+isolated Hermes home and follow
+[`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md) instead.
 
 ## What goes wrong (and how to fix it)
 
@@ -148,7 +180,52 @@ The two- and three-container setups use **named Docker volumes** (not bind mount
       └─────────────────────────┘
 ```
 
-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.
+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. The WebUI mount is read-only; the agent container is the only writer.
+
+## Upgrading the agent container
+
+The `hermes-agent-src` named volume is initialised from the agent image's `/opt/hermes` on first `up`. Docker reuses the volume verbatim on every subsequent `up` — **even after `docker pull` of a newer agent image**. The cached volume content masks the new image's source tree, so a fresh `docker pull` of `nousresearch/hermes-agent:latest` does not by itself give you the new agent code, dependencies, or entrypoint.
+
+This is the root cause of [#1416](https://github.com/nesquena/hermes-webui/issues/1416): the symptom looked like a missing entrypoint, but the entrypoint was actually present in the new image and hidden behind the stale named volume.
+
+To upgrade the agent image cleanly, drop the source volume before recreating:
+
+```bash
+# Two-container setup
+docker compose -f docker-compose.two-container.yml down
+docker volume rm <project>_hermes-agent-src
+docker compose -f docker-compose.two-container.yml pull
+docker compose -f docker-compose.two-container.yml up -d
+
+# Three-container setup
+docker compose -f docker-compose.three-container.yml down
+docker volume rm <project>_hermes-agent-src
+docker compose -f docker-compose.three-container.yml pull
+docker compose -f docker-compose.three-container.yml up -d
+```
+
+Replace `<project>` with your Compose project name (the parent directory by default; check with `docker volume ls`). The `hermes-home` volume (config, sessions, state) is left untouched — only `hermes-agent-src` (the agent's installed Python source) is recreated.
+
+> The single-container setup (`docker-compose.yml`) does not use `hermes-agent-src` and is not affected by this upgrade pattern — pulling a newer WebUI image and `docker compose up -d --force-recreate` is sufficient.
+
+## What the multi-container setup isolates (and what it doesn't)
+
+The two- and three-container setups give you **process, network, and resource isolation** between the gateway and the chat UI:
+
+- Each service has its own PID namespace and lifecycle — the agent process can crash without taking down the chat UI and vice versa.
+- The gateway API (port 8642) is bound by the agent service only; the WebUI cannot bind it. Other containers reach the gateway via the `hermes-net` Docker network.
+- Resource limits (`deploy.resources.limits` in `docker-compose.three-container.yml`) apply per service, so you can cap the agent independently of the dashboard.
+- Restart policies, log streams, and container health checks are scoped per service.
+
+What multi-container does **not** isolate:
+
+- **Filesystem boundary.** Both services share `hermes-home` (config, sessions, state), and the WebUI mounts the agent's installed source from `hermes-agent-src`. The WebUI mount is read-only (since v0.51.84), but the agent service still has write access, and both services share the home volume.
+- **UID/GID boundary.** Both services default to `${UID:-1000}` so files written by one are readable by the other. If you align them to different UIDs you'll get permission errors on the shared volume.
+- **Trust boundary on the agent source.** The WebUI installs Python dependencies from the shared `hermes-agent-src` volume at startup. The read-only mount means a compromised WebUI cannot rewrite the agent source, but it does run code from that volume.
+
+If you need **filesystem isolation** between the chat UI and the agent (e.g. you don't trust the WebUI to read agent state), the multi-container setup is not enough — run the agent on a separate host and connect the WebUI to it via the gateway HTTP API. If you don't need any boundary, the single-container setup is simpler.
+
+The direct source mount is a compatibility bridge, not the long-term API contract. The current source/API boundary inventory and decoupling task list live in [`docs/rfcs/agent-source-boundary.md`](rfcs/agent-source-boundary.md) for [#2453](https://github.com/nesquena/hermes-webui/issues/2453). If you customize the compose files with bind mounts, keep the WebUI-side agent source mount read-only unless you are intentionally doing local development; `docker_init.bash` warns at startup when that path is writable.
 
 ## Bind-mount migration (advanced)
 
@@ -187,6 +264,7 @@ volumes:
 
 ## Related issues
 
+- #1416 — agent-image upgrade requires removing `hermes-agent-src` named volume (see [Upgrading the agent container](#upgrading-the-agent-container))
 - #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

docs/onboarding-agent-checklist.md

@@ -0,0 +1,207 @@
+# Agent-assisted onboarding checklist
+
+This checklist is for an AI assistant helping a human install, reinstall, or
+debug Hermes WebUI onboarding. It does not replace the human first-run wizard.
+Use it before running bootstrap commands, inspecting logs, or recommending a
+cleanup path.
+
+If you are an AI assistant, read this file before assisting with onboarding,
+bootstrap, provider setup, reinstall, or first-run support.
+
+## Role split
+
+The human operator owns:
+
+- choosing the install path
+- choosing the provider and model
+- entering API keys, OAuth codes, and passwords
+- approving any cleanup of a real Hermes home
+- approving any external exposure outside localhost
+
+The assistant owns:
+
+- using isolated trial directories unless the human explicitly says otherwise
+- checking non-secret status endpoints and logs
+- explaining which step passed or failed
+- collecting redacted evidence for Discord or GitHub support
+- stopping before destructive cleanup, credential handling, or public exposure
+
+## Hard safety rules
+
+- Do not delete, move, or overwrite the real `~/.hermes` directory unless the
+  human explicitly asks for that exact action.
+- Do not print API keys, OAuth tokens, cookies, full `.env` files, full
+  `auth.json` files, or password hashes.
+- Do not modify real cron jobs, real sessions, real profiles, or real memory
+  files during an onboarding trial.
+- Do not expose WebUI on a public interface without password protection and
+  explicit human approval.
+- Do not proxy or tunnel local service checks such as `localhost`,
+  `127.0.0.1`, private LAN addresses, or Docker container loopback paths.
+
+## Pre-flight
+
+Confirm the basic context:
+
+```bash
+pwd
+git branch --show-current
+git rev-parse --short HEAD
+python3 --version
+```
+
+Check whether repo-local environment overrides will affect bootstrap:
+
+```bash
+test -f .env && grep -n 'HERMES_HOME\|HERMES_WEBUI_STATE_DIR\|HERMES_WEBUI_PORT\|HERMES_WEBUI_HOST' .env
+```
+
+If `.env` exists, do not print the full file. Inspect only the specific
+non-secret keys needed to understand the active Hermes home, WebUI state
+directory, port, or host.
+
+## Isolated local trial
+
+Use an isolated Hermes home and WebUI state directory for a reinstall or support
+trial. This keeps the test away from the operator's real memory, sessions,
+profiles, credentials, and cron state.
+
+```bash
+mkdir -p ~/hermes-onboarding-test
+HERMES_HOME=~/hermes-onboarding-test/.hermes \
+HERMES_WEBUI_STATE_DIR=~/hermes-onboarding-test/webui \
+HERMES_WEBUI_PORT=8789 \
+python3 bootstrap.py
+```
+
+Open:
+
+```text
+http://127.0.0.1:8789
+```
+
+The bootstrap writes a port-specific log under the selected WebUI state
+directory:
+
+```text
+~/hermes-onboarding-test/webui/bootstrap-8789.log
+```
+
+For daemon-style installs, `ctl.sh` writes the daemon log to the active
+`HERMES_HOME` by default:
+
+```text
+~/.hermes/webui.log
+```
+
+When using the isolated trial environment, prefer the bootstrap command above
+unless the human specifically wants to validate `ctl.sh`.
+
+## Non-secret evidence commands
+
+After the server starts, collect status without secrets:
+
+```bash
+curl -sS http://127.0.0.1:8789/health
+curl -sS http://127.0.0.1:8789/api/onboarding/status
+find ~/hermes-onboarding-test -maxdepth 3 -type f | sort
+tail -n 120 ~/hermes-onboarding-test/webui/bootstrap-8789.log
+```
+
+When summarizing `/api/onboarding/status`, focus on:
+
+- `completed`
+- `system.hermes_found`
+- `system.imports_ok`
+- `system.config_path`
+- `system.config_exists`
+- `system.setup_state`
+- `system.provider_configured`
+- `system.provider_ready`
+- `system.chat_ready`
+- `system.current_provider`
+- `system.current_model`
+- `system.current_base_url`
+- `system.env_path`
+
+Do not paste the full payload if it contains unexpected sensitive local paths
+or values. Redact paths and provider details when the human asks for a public
+GitHub or Discord support report.
+
+## Pass criteria
+
+A local onboarding trial passes when:
+
+- `/health` returns successfully.
+- `/api/onboarding/status` returns JSON.
+- The wizard appears when `completed` is false.
+- The wizard stays out of the way when `completed` is true or
+  `HERMES_WEBUI_SKIP_ONBOARDING=1` is intentionally set.
+- `system.hermes_found` and `system.imports_ok` match the expected bootstrap
+  state.
+- `system.provider_ready` and `system.chat_ready` become true after the human
+  completes a provider path that should support chat.
+- `system.config_path` and `system.env_path` point inside the intended isolated
+  `HERMES_HOME` during a trial.
+- WebUI files are written under the intended `HERMES_WEBUI_STATE_DIR`.
+
+If the human chooses a provider that must be completed in the CLI, passing can
+mean the wizard correctly points them to `hermes model` or `hermes auth` rather
+than trying to collect unsupported credentials in the browser.
+
+## Failure triage
+
+If the server does not start:
+
+- check the bootstrap log
+- check for a port conflict on `8789`
+- confirm Python can run `bootstrap.py`
+- confirm `.env` is not overriding the isolated directories or port
+
+If onboarding reports `agent_unavailable`:
+
+- confirm the bootstrap found or installed Hermes Agent
+- check whether the running Python can import `run_agent.AIAgent`
+- use `docs/troubleshooting.md`, especially the `AIAgent not available` flow
+
+If onboarding reports `provider_incomplete`:
+
+- confirm whether the provider is API-key based, OAuth based, or local
+- let the human enter credentials or run the CLI auth flow
+- do not ask the human to paste secrets into chat
+
+If a local model server does not probe successfully:
+
+- from native macOS/Linux, use `http://127.0.0.1:<port>/v1` when the server is
+  on the same host
+- from Docker Desktop, use `http://host.docker.internal:<port>/v1`
+- from another LAN machine, use the server's LAN IP and `/v1`
+- remember that `localhost` inside a container is the container itself
+
+If password or reverse-proxy behavior is confusing:
+
+- keep the first pass on `127.0.0.1`
+- require password protection before exposing WebUI beyond localhost
+- include the reverse proxy shape in the support report without pasting tokens
+  or cookies
+
+## Final support report
+
+Use this shape when reporting results to the human, Discord, or GitHub:
+
+```text
+Install path:
+OS / Python:
+Repo commit:
+Command used:
+WebUI URL:
+State isolation:
+Health result:
+Onboarding status summary:
+Files created or changed:
+Log excerpt:
+Pass/fail:
+Next recommended action:
+```
+
+Redact secrets and private paths before posting publicly.

docs/onboarding.md

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

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