fix: record fallback routing metadata

Release MY (v0.51.386): voice mode survives dropped speechSynthesis onend (#3983)

.env.docker.example

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

.env.example

@@ -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)
-# HERMES_WEBUI_STATE_DIR=~/.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/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: nesquena

.github/workflows/browser-smoke.yml

@@ -0,0 +1,42 @@
+name: Browser smoke
+
+# Headless page-load smoke: boots the real server.py (agent-free) and loads the
+# key pages in Chromium, failing on any console error or uncaught JS exception.
+# This catches the runtime-JS brick class (const-reassign, function/window
+# collision) that `node --check`, ESLint, and the mocked pytest suite cannot
+# see — they only manifest when a real browser executes the page.
+#
+# No secrets, no credentials: the server boots agent-free and the smoke script
+# strips every *_API_KEY from the environment before launch.
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  browser-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: |
+            **/requirements*.txt
+            **/pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "pyyaml>=6.0" playwright
+          # Install only the Chromium browser + its system deps.
+          python -m playwright install --with-deps chromium
+
+      - name: Run browser smoke
+        run: python tests/browser_smoke.py

.github/workflows/docker-smoke.yml

@@ -0,0 +1,233 @@
+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
+
+  # Build the Docker image once and cache layers via GHA cache.
+  # The smoke matrix jobs then pull from this cache instead of rebuilding
+  # from scratch, saving ~1-3 minutes per variant.
+  build-image:
+    name: Build Docker image (cache layers)
+    runs-on: ubuntu-latest
+    needs: compose-config
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build and cache Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ghcr.io/nesquena/hermes-webui:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  smoke:
+    name: Smoke ${{ matrix.variant }}
+    runs-on: ubuntu-latest
+    needs: [compose-config, build-image]
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        variant:
+          - single
+          - two-container
+          - three-container
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      # Restore the cached Docker image from the build-image job.
+      # Read-only: the build-image job already populated the GHA cache, so the
+      # smoke variants only need cache-from (no redundant cache-to re-export).
+      - name: Restore Docker image from cache
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ghcr.io/nesquena/hermes-webui:latest
+          cache-from: type=gha
+
+      - 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: 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

@@ -7,11 +7,73 @@ on:
     branches: [master]
 
 jobs:
+  # Forward-looking Python lint gate (ruff). The Python twin of the ESLint runtime
+  # guard. Runs the curated [tool.ruff] ruleset (E9 + F + B) but only on lines this
+  # PR adds/modifies vs the merge-base — so it keeps NEW code clean without demanding
+  # a reformat of the existing tree's cosmetic backlog (#3273). Fast, fails early.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Need history so the gate can diff against the merge-base with master.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Ensure origin/master ref is available for the diff gate
+        run: git fetch --no-tags --depth=1 origin master || true
+
+      - name: Ruff forward gate (new/changed lines only)
+        run: python3 scripts/ruff_lint.py --diff origin/master
+
+      - name: Ruff whole-tree report (informational — never blocks)
+        if: always()
+        run: python3 scripts/ruff_lint.py --all
+
+      # Static-JS runtime-error guards. These catch brick-class bugs that throw only
+      # when the browser executes the code — node --check, source-presence tests, and
+      # the mocked pytest suite all miss them. Two complementary ESLint passes:
+      #   * runtime-guard config: no-const-assign / no-import-assign (#3162 class)
+      #   * scope_undef_gate.py: no-undef across the shared classic-<script> global
+      #     scope, catching a function defined nested but called from a sibling
+      #     scope (#3696 — ReferenceError: _sessionAttentionState is not defined).
+      - name: Set up Node for ESLint runtime guards
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install ESLint
+        run: npm install --no-save eslint@^10
+
+      - name: ESLint runtime-error gate (no-const-assign / no-import-assign, #3162)
+        run: npx eslint --no-config-lookup -c eslint.runtime-guard.config.mjs "static/**/*.js"
+
+      - name: Scope / undefined-reference gate (#3696)
+        run: python3 scripts/scope_undef_gate.py
+
   test:
     runs-on: ubuntu-latest
     strategy:
+      # Don't cancel the other shards/versions when one fails — we want the full
+      # failure picture across the matrix in a single run.
+      fail-fast: false
       matrix:
         python-version: ['3.11', '3.12', '3.13']
+        # Split the suite across 3 parallel shards per Python version. pytest-shard
+        # partitions tests deterministically by test-id hash; the suite was made
+        # shard-safe (no cross-test state leakage) so every shard passes
+        # independently. See docs/agent-memory note on test-suite shard-safety.
+        # NOTE: pytest-shard is 0-indexed — shard ids must be 0..num_shards-1.
+        # Using 1-based ids would crash the out-of-range job AND silently skip
+        # shard 0's tests.
+        shard: [0, 1, 2]
 
     steps:
       - uses: actions/checkout@v4
@@ -20,11 +82,28 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: |
+            **/setup.cfg
+            **/requirements*.txt
+            **/pyproject.toml
 
       - 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 pytest-shard
+          # ruff is installed so tests/test_ruff_forward_lint.py runs its E9/F821
+          # tree-clean assertions in-suite (mirrors how eslint is available for
+          # tests/test_static_js_runtime_lint.py). If install fails the test
+          # skips cleanly — it never blocks the matrix.
+          pip install ruff || echo "ruff install failed — test_ruff_forward_lint.py will skip"
+          # 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
+      - name: Run tests (shard ${{ matrix.shard }} of 3)
+        run: pytest tests/ -v --timeout=60 --shard-id=${{ matrix.shard }} --num-shards=3

.gitignore

@@ -12,13 +12,14 @@ __pycache__/
 # Archive directory (pre-git backups, kept on disk but not tracked)
 archive/
 
-# Local environment and secrets (but keep the example template)
+# Local environment and secrets (but keep the example templates)
 .env
 .env.*
 !.env.example
+!.env.docker.example
 .claude/
 CLAUDE.md
-AGENTS.md
+AGENTS.local.md
 .cursorrules
 .windsurfrules
 .aider*
@@ -35,7 +36,37 @@ 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/rfcs/
+!docs/rfcs/**
+!docs/architecture/
+!docs/architecture/**
+
+# Local-only AI assistant context — never committed even under docs/.
+docs/AGENTS.md
+docs/CLAUDE.md
+docs/.cursorrules
+docs/.windsurfrules
+.specify/
+AGENT_TRACE.yaml
+EXECUTION_LOG.md
+
+# Local-only PR review harness: rendering drivers, sample bank, fixtures.
+# Used by Claude during deep reviews; never shared in the repo.
+.local-review/
+.review-crops/
+graphify-out/
+.graphify_cached.json
+.graphify_uncached.txt
+
+.venv/
+
+# Dev-only lint tooling (ESLint runtime-error guard) — see TESTING.md
+node_modules/
+package-lock.json
+docs/ui-ux/review-shots/

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,12 @@
 >
 > Keep this document updated as architecture changes are made.
 
-> Current shipped build: `v0.50.36-local.1` (April 16, 2026).
-> Baseline: upstream `nesquena/hermes-webui` `v0.50.36`.
-> Intentional local delta: first-time password enablement from Settings immediately issues a `hermes_session` cookie so the current browser remains signed in. The previous `Assistant Reply Language` customization has been removed, legacy `assistant_language` settings are filtered out on load/save, the workspace panel closed/open state is preloaded via a `documentElement` dataset marker before `style.css` paints to avoid a first-load desktop flash, transcript disclosure cards now animate caret rotation and body expansion with transitionable `max-height`/`opacity` states instead of `display:none/block`, and thinking cards now share the same rounded bordered card chrome as tool cards while keeping their gold palette.
-> Automated coverage: 1353 tests collected (`pytest tests/ --collect-only -q`).
+> Current shipped build: `v0.51.192` (May 31, 2026).
+> Automated coverage: ~7,150 tests via `pytest tests/ --collect-only -q`. CI runs on
+> Python 3.11, 3.12, and 3.13 (3 parallel shards each) against every PR, plus a ruff
+> lint gate, a headless browser smoke test, and a Docker smoke test.
+>
+> Notable architecture state: 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. (Version/test-count numbers above are a periodic snapshot — the authoritative source is the latest git tag and `pytest --collect-only`.)
 
 ---
 
@@ -33,11 +35,6 @@ frontend framework. The Python server is split into a routing shell (server.py)
 business logic modules (api/). The frontend is seven vanilla JS modules loaded from static/.
 This makes the code easy to modify from a terminal or by an agent.
 
-For the current local build, the codebase is intentionally as close to upstream as possible:
-the app now tracks upstream `v0.50.36`, keeps the password-session continuity patch in the
-settings/onboarding flow, and does not carry forward the prior reply-language preference
-feature.
-
 Hermes-level chrome is intentionally consolidated: the sidebar has no dedicated brand header.
 Instead, the footer exposes a single "Hermes WebUI" launch button that opens one tabbed
 control-center modal for global preferences, conversation import/export, and clear-conversation
@@ -48,54 +45,66 @@ 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.
                            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)
+    ctl.sh                 Daemon lifecycle wrapper (start/stop/restart/status/logs) for homelab installs.
+    pyproject.toml         Tooling config (ruff lint gate). NOT a packaged distribution.
+    Dockerfile             python:3.12-slim container image
+    docker-compose.yml     Compose config with named volume and optional auth
     .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, passkeys/WebAuthn
+      config.py            Discovery, globals, model detection, reloadable config
+      helpers.py           HTTP helpers: j(), bad(), require(), safe_resolve(), security headers
+      models.py            Session model + CRUD, per-session profile tracking, CLI/state.db bridge
+      profiles.py          Profile state management, hermes_cli wrapper
+      onboarding.py        First-run onboarding status, real provider config writes, OAuth linking, readiness detection
+      routes.py            All GET + POST route handlers (if/elif dispatch, no decorators)
+      startup.py           Startup helpers: auto_install_agent_deps()
+      state_sync.py        /insights sync — message_count to the agent's state.db
+      streaming.py         SSE engine, run_agent, cancel, compression, HERMES_HOME save/restore
+      updates.py           Self-update check and release notes
+      upload.py            Multipart parser, file upload handler
+      workspace.py         File ops: list_dir, read_file_content, git detection, workspace helpers
     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)
-      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)
+      index.html           HTML template
+      style.css            All CSS incl. mobile responsive, themes + skins, KaTeX
+      ui.js                DOM helpers, renderMd, tool cards, context indicator, file tree
+      workspace.js         File preview, file ops, git badge, central api() fetch wrapper
+      sessions.js          Session CRUD, list rendering, collapsible groups, search, SSE sync
+      messages.js          send(), SSE event handlers, approval/clarify, transcript, recovery
+      panels.js            Cron, skills, memory, profiles, todo, settings (Control Center)
+      commands.js          Slash command registry, parser, autocomplete dropdown
+      boot.js              Event wiring, mobile nav, voice input, theme/skin boot, bfcache handler
+      onboarding.js        First-run wizard overlay, provider setup flow
+      i18n.js              Localization catalog (en, es, de, zh, zh-Hant, ru, …)
+      login.js             Login page + open-redirect guard
+      icons.js             Lucide icon path registry
+      sw.js                Service worker: offline shell cache, version-pinned assets
     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
+      ~700 test files      ~7,150 tests collected via pytest (run `pytest --collect-only -q` for exact)
+      test_regressions.py  Permanent regression gate
+    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.
     TESTING.md             Manual browser test plan and automated coverage reference.
-    CHANGELOG.md           Release notes per sprint.
-    BUGS.md                Bug backlog and fixed items tracker.
+    CHANGELOG.md           Release notes per version.
+    CONTRIBUTORS.md        Community credit roll (regenerated via the maintainer workspace script).
     requirements.txt       Python dependencies.
     .env.example           Sample environment variable overrides.
 
+> Per-file line counts intentionally omitted — they drift every release. Use
+> `git ls-files | xargs wc -l` (or your editor) for current sizes; the role of
+> each file above is the durable part.
+
 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
@@ -104,7 +113,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
 
 ---
 
@@ -123,15 +133,20 @@ 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_PREFILL_MESSAGES_FILE   Optional JSON message list for browser-turn prefill context
+    HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT Optional command that prints JSON messages or plain-text user prefill context
+    HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT Optional script timeout in seconds (default 5, max 30)
+    HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS Optional parsed prefill budget in characters (default 12000, 0 disables)
     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.
@@ -161,10 +176,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.
 
@@ -324,7 +340,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
@@ -367,16 +383,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
@@ -684,27 +702,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)
 
@@ -783,7 +802,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.
 
@@ -799,13 +818,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)
 
@@ -893,7 +912,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
@@ -903,15 +923,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']))"
@@ -924,9 +944,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
 
@@ -1199,31 +1219,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)
 
@@ -1325,7 +1336,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
 
@@ -1460,7 +1471,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)
 
@@ -1471,7 +1482,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
 
@@ -1629,3 +1640,19 @@ and #rightpanelResize. On mousemove: computes delta and clamps to min/max. On mo
 saves width to localStorage. Widths restored at boot via localStorage.getItem().
 CSS: .resize-handle with position:absolute, width:5px, cursor:col-resize.
 body.resizing added during drag to suppress text selection.
+
+
+## Workspace path trust levels
+
+`api/workspace.py` has two distinct trust functions — do not collapse them:
+
+**`validate_workspace_to_add(path)`** — used by `/api/workspaces/add` (explicit user registration).
+Permissive: blocks only non-existent, non-directory, and system root paths. The user is
+consciously registering an external path (e.g. `/mnt/d/Projects` in WSL), so we trust intent.
+
+**`resolve_trusted_workspace(path)`** — used for actual file read/write operations inside
+an existing workspace. Strict: path must be under home, in the saved workspace list, or under
+`BOOT_DEFAULT_WORKSPACE`. Prevents path traversal and unauthorized file access.
+
+The distinction matters because add uses permissive validation to avoid the circular
+dependency: you cannot get a path into the saved list if you need the saved list to add it.

BUGS.md

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

CONTRIBUTING.md

@@ -4,6 +4,40 @@ 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.
+
+### Contract-affecting PRs
+
+A contract-affecting PR is any change that updates a public contract document,
+an RFC, a contributor guide, a product-semantics test, or behavior that those
+documents already describe. These PRs need an explicit `Contract Routing` section
+in the PR body that names the touched contract family and the evidence used.
+See [`docs/CONTRACTS.md#contract-routing`](docs/CONTRACTS.md#contract-routing)
+for the short routing shape and [`docs/CONTRACTS.md#contract-changes`](docs/CONTRACTS.md#contract-changes)
+for intentional contract changes.
+
+If the PR intentionally changes an existing contract, add a `Contract Change`
+section that states the old rule, the new rule, and why the change is justified.
+Do not silently redefine product behavior by changing tests alone; update the
+corresponding docs in the same PR.
+
+A release batch should call out included contract-affecting PRs separately
+from ordinary fixes, even when the code diff is small and CI is green.
+
 ## Two Paths to a Strong Pull Request
 
 ### Path 1: Small, Focused Changes
@@ -60,7 +94,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
 

DESIGN.md

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

Dockerfile

@@ -21,13 +21,35 @@ 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/*
 
+# Optional GPU user-space acceleration libraries for users who pass through
+# host GPU devices. The default image remains CPU-only.
+ARG INSTALL_GPU_LIBS=0
+RUN if [ "$INSTALL_GPU_LIBS" = "1" ]; then \
+        apt-get update -y --fix-missing --no-install-recommends \
+        && apt-get install -y --no-install-recommends \
+            libva2 \
+            vainfo \
+            mesa-va-drivers \
+        && if apt-cache show intel-media-va-driver-non-free >/dev/null 2>&1; then \
+            apt-get install -y --no-install-recommends intel-media-va-driver-non-free; \
+        else \
+            echo "intel-media-va-driver-non-free is not available from the configured Debian repositories; skipping Intel non-free VA-API driver."; \
+        fi \
+        && apt-get clean \
+        && rm -rf /var/lib/apt/lists/*; \
+    else \
+        echo "Skipping optional GPU user-space acceleration libraries (INSTALL_GPU_LIBS=0)."; \
+    fi
+
 # UTF-8
 RUN localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
 ENV LANG=en_US.utf8
@@ -40,24 +62,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
 
@@ -74,9 +86,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).
@@ -91,5 +101,11 @@ ENV HERMES_WEBUI_PORT=8787
 
 EXPOSE 8787
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8787/health || exit 1
+
+# docker_init.bash performs root-only bind-mount setup, then drops to hermeswebui
+# before starting the WebUI server. The production image does not ship sudo.
+USER root
 CMD ["/hermeswebui_init.bash"]
 

ROADMAP.md

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

TESTING.md

@@ -1,20 +1,109 @@
 # Hermes Web UI: Browser Testing Plan
 
 > This document is for manual browser testing by you or by a Claude browser agent.
-> It covers user-facing features of the UI through v0.50.21 and later releases.
+> It covers user-facing features of the UI across current releases.
 > Each section is written as a step-by-step test procedure with expected outcomes.
 > A browser agent (e.g. Claude with Chrome access) can execute this plan directly.
 >
 > Prerequisites: SSH tunnel is active on port 8787. Open http://localhost:8787 in browser.
 > Server health check: curl http://127.0.0.1:8787/health should return {"status":"ok"}.
 >
-> Automated coverage: 1777 tests collected via `pytest tests/ --collect-only -q`. Includes onboarding coverage for bootstrap/static wizard presence, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, and CSS regression coverage for smooth thinking/tool card disclosure animation.
+> Automated coverage: ~7,150 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 (3 parallel shards each), alongside a ruff lint gate, a headless browser smoke test, and a Docker smoke test. 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.
 
 ---
 
+## Static JS runtime lint (brick-class regression guard)
+
+Some JS bugs throw a `TypeError`/`ReferenceError` only when a specific function
+actually runs in the browser — `node --check` (lazy syntax check), source-presence
+tests, and even executing the file all miss them. Issue **#3162** was exactly this:
+a `const` binding reassigned inside `_ensureMessagesLoaded` bricked "load conversation
+messages" on every mobile message (v0.51.161–166).
+
+The guard is a curated, zero-false-positive ESLint config (`eslint.runtime-guard.config.mjs`)
+that runs ONLY runtime-error rules (`no-const-assign`, `no-import-assign`) over
+`static/**/*.js`. It is NOT a style linter and has no formatting rules.
+
+```bash
+# one-time dev setup (ESLint is a dev-only tool; the app stays pure Python + vanilla JS):
+npm install --no-save --before=<a-date-≥48h-ago> eslint   # package-age guard
+# run the guard:
+npm run lint:runtime
+# or directly:
+npx eslint --no-config-lookup -c eslint.runtime-guard.config.mjs "static/**/*.js"
+```
+
+## Python lint gate (ruff) — forward-looking, new-code-only
+
+The Python twin of the ESLint runtime guard. A curated `ruff` ruleset
+(`[tool.ruff]` in `pyproject.toml`) catches latent-bug shapes — unused imports
+(F401), undefined/unused names (F841/F821), redefinitions (F811), mutable default
+args (B006), raise-without-from (B904), loop-variable capture in closures (B023) —
+**plus** real syntax/runtime errors (E9). It is **not** a style/formatting linter:
+the pure-style families (line-length, whitespace) are intentionally OFF so the gate
+never demands a reformat of existing code.
+
+The existing tree carries a cosmetic backlog (mostly unused-import F401) that is
+deliberately **not** reformatted. So the gate is enforced **only on the lines a
+change adds or modifies** (`scripts/ruff_lint.py --diff`), which keeps new code
+clean without touching the backlog. Cleaning the backlog is a separate,
+maintainer-run, safe-fixes-only decision (tracked in #3273).
+
+```bash
+# one-time dev setup (ruff is a dev-only tool):
+pip install ruff            # or: uv tool install ruff / uvx ruff ...
+# the gate (only flags violations on lines you added/changed vs origin/master):
+python3 scripts/ruff_lint.py --diff origin/master
+# whole-tree backlog report (informational — never blocks):
+python3 scripts/ruff_lint.py --all
+```
+
+`tests/test_ruff_forward_lint.py` holds the **whole tree** free of E9 (real
+syntax/runtime) findings and verifies the curated config shape; it runs in-suite
+when ruff is present and **skips gracefully** when it isn't — so environments
+without ruff aren't blocked, while CI (which installs ruff) enforces it. The
+diff-scoped gate runs as the `lint` job in `.github/workflows/tests.yml` and is
+also part of the maintainer pre-release pre-gate.
+
+## Automated browser smoke (runtime brick-class gate)
+
+The ESLint guard above catches `const`-reassign / import-assign statically. The
+**browser smoke** catches the same brick class *dynamically* — plus anything else
+that throws only when a real browser executes the page (e.g. a `function X(){}` /
+`window.X = {}` name collision like #2715/#2771, which ESLint can't see).
+
+`tests/browser_smoke.py` boots the real `server.py` (agent-free, on an ephemeral
+port, with an isolated temp state dir) and loads the key pages in headless
+Chromium, failing if **any** console error or uncaught JS exception fires on load.
+It runs in CI (`.github/workflows/browser-smoke.yml`) on every PR and push to
+master, and locally:
+
+```bash
+pip install playwright && python -m playwright install chromium
+python tests/browser_smoke.py
+```
+
+It is intentionally **credential-free**: it strips every `*_API_KEY` from the
+environment before launching the server, needs no secrets, and does not drive a
+real model (it verifies the app *loads and initializes* cleanly — the brick class
+that breaks the page for everyone). A full chat golden-path E2E (send → stream →
+render → switch → reload) lives in the maintainer's private QA harness, which has
+the agent + a mock LLM provider available.
+
+
+`tests/test_static_js_runtime_lint.py` runs this automatically when eslint is present
+and **skips gracefully** (clear message) when it isn't — so environments without the
+node toolchain aren't blocked, while the release gate (which installs eslint) enforces it.
+
+To widen the guard, fix the pre-existing intentional hits first (as of 2026-05-30:
+`no-dupe-keys` ×92 i18n locale-fallback, `no-func-assign` ×2 panel override,
+`no-redeclare` ×1) then promote the rule into the config.
+
+---
+
 ## How to Use This Document
 
 Each test has:
@@ -240,6 +329,32 @@ EXPECT:
   - If it was the only file, tray collapses
 FAIL: File not removed, error.
 
+### T4.6: Inline Audio Attachment Editor with Variable Speed
+SETUP: Active session, an audio file ready locally (`.mp3`, `.wav`, `.m4a`, `.ogg`, or `.flac`).
+STEPS:
+  1. Attach the audio file with the paperclip or drag/drop
+  2. Confirm the tray shows an audio media chip, then send the message
+  3. In the sent user message, press Play on the inline audio player
+  4. Click 0.5×, 1.25×, 1.5×, and 2× speed buttons
+EXPECT:
+  - The audio renders inline in the chat instead of only as a download/file badge
+  - Native audio controls are visible and usable
+  - The clicked speed button becomes active and playback speed changes immediately
+  - Download/open behavior for non-media files is unchanged
+FAIL: Audio only downloads, no speed buttons appear, or speed buttons do not affect playback.
+
+### T4.7: Inline Video Attachment Editor with Variable Speed
+SETUP: Active session, a video file ready locally (`.mp4`, `.mov`, `.webm`, or `.m4v`).
+STEPS:
+  1. Attach and send the video file
+  2. In the sent user message, play the inline video
+  3. Switch among 0.75×, 1×, 1.5×, and 2× speed controls
+EXPECT:
+  - The video renders inline, contained within the message width
+  - Native video controls are visible and usable
+  - Speed selection updates the video `playbackRate` without reloading the media
+FAIL: Video only shows a generic badge, overflows the chat column, or speed controls fail.
+
 ---
 
 ## Section 5: Workspace File Browser
@@ -306,6 +421,33 @@ EXPECT:
   - Image maintains aspect ratio
 FAIL: Raw binary text displayed, broken image icon, error message, or nothing happens.
 
+### T5.5b: Preview Audio/Video Files Inline
+SETUP: Workspace contains at least one audio file (`.mp3`, `.wav`, `.m4a`) and one video file (`.mp4`, `.mov`, `.webm`).
+STEPS:
+  1. Click the audio file in the workspace file tree
+  2. Play it and select 1.5× or 2× speed
+  3. Close preview, then click the video file
+  4. Play it and select 0.75× or 1.25× speed
+EXPECT:
+  - Audio/video open in the workspace preview panel instead of downloading immediately
+  - Path badge shows `audio` or `video`
+  - Native media controls and the variable-speed buttons are visible
+  - Video scales to the preview panel without overflowing
+FAIL: Browser downloads the media immediately, raw binary appears, or speed controls are missing/broken.
+
+### T5.5c: Preview PDF Files Inline
+SETUP: Workspace contains at least one `.pdf` file.
+STEPS:
+  1. Click the PDF file in the workspace file tree
+  2. Use the browser/PDF viewer scroll and zoom controls if available
+  3. Click "Open in browser" as a fallback
+EXPECT:
+  - PDF opens in the workspace preview panel instead of downloading immediately
+  - Path badge shows `pdf`
+  - PDF iframe fills the preview area
+  - "Open in browser" opens the same raw file endpoint in a new tab
+FAIL: Browser downloads the PDF immediately, raw binary appears, or the preview panel is blank without an open fallback.
+
 ### T5.6: Preview a Markdown File (Sprint 2)
 SETUP: Workspace has a .md file (or create one: upload a file named README.md with some markdown content).
 STEPS:
@@ -480,7 +622,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}
@@ -504,7 +647,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)
@@ -524,7 +667,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)
@@ -1782,8 +1925,8 @@ Bridged CLI sessions:
 
 ---
 
-*Last updated: v0.50.91, April 19, 2026*
-*Total automated tests collected: 1777*
+*Last updated: v0.51.192, May 31, 2026*
+*Total automated tests collected: ~7,150 (run `pytest tests/ --collect-only -q` for the exact current count)*
 *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`, `zeus`). 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,138 @@ 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. |
+| **Zeus** | OLED-near-black dark surfaces that keep the default gold accent. Dark-focused; falls back to the default light palette in light mode. |
+
+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,569 @@
+"""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
+import os
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+
+_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>.
+
+    When the root-level gateway.pid is absent (profile-scoped gateway
+    deployments write it under <root>/profiles/<name>/), fall back to the
+    active profile's directory so the gateway is detected correctly.
+    """
+    try:
+        from hermes_constants import get_default_hermes_root
+        root_pid = get_default_hermes_root() / _GATEWAY_PID_FILE
+        if root_pid.exists():
+            return root_pid
+        try:
+            from api.profiles import get_active_hermes_home
+            profile_pid = Path(get_active_hermes_home()) / _GATEWAY_PID_FILE
+            if profile_pid.exists():
+                return profile_pid
+        except Exception:
+            pass
+        return root_pid
+    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
+
+
+# Remote-gateway probe (#3281)
+# ------------------------------------------------------------------
+# In multi-container Docker deployments the WebUI container does not ship the
+# ``gateway`` Python package. The lazy ``importlib.import_module("gateway.status")``
+# therefore raises ``ModuleNotFoundError`` and the payload falls through to
+# ``gateway_not_configured`` even though ``HERMES_API_URL`` points at a perfectly
+# reachable remote gateway. The Tasks/Cron banner then shows a spurious amber
+# "Gateway not configured" warning.
+#
+# When a gateway base URL is set in any supported env var, we treat that as an
+# explicit declaration that the gateway lives elsewhere, and probe it over HTTP
+# before touching any local filesystem / module signal. The probe result is
+# cached briefly so a dashboard rerender that fans out to multiple panels does
+# not hammer the gateway.
+
+_REMOTE_PROBE_TIMEOUT_S: float = 2.0
+_REMOTE_PROBE_CACHE_TTL_S: float = 5.0
+_REMOTE_PROBE_PATHS: tuple[str, ...] = ("/health/detailed", "/health", "/v1/health")
+# A gateway health payload is small JSON; cap the 2xx body read so a large or
+# slow-trickled remote response can't hang /api/health/agent or balloon memory.
+_REMOTE_PROBE_BODY_LIMIT_BYTES: int = 64 * 1024
+
+_remote_probe_lock = threading.Lock()
+_remote_probe_cache: dict[str, Any] = {"url": None, "expires_at": 0.0, "result": None}
+
+
+def _remote_gateway_base_url() -> str | None:
+    """Return an explicit remote gateway base URL, or None for local-only setups.
+
+    Priority: GATEWAY_HEALTH_URL > HERMES_GATEWAY_HEALTH_URL > HERMES_API_URL
+    > HERMES_WEBUI_GATEWAY_BASE_URL.
+    Returns ``None`` when no env var is set so the caller falls through to
+    local PID/state checks.
+
+    Any of these env vars may legitimately point AT a health endpoint
+    (e.g. ``GATEWAY_HEALTH_URL=http://host:8642/health``). Since the probe
+    appends ``/health/detailed`` etc. to the returned base, strip a trailing
+    health-path suffix first so we don't build ``/health/health/detailed``
+    (mirrors the normalization in api/updates.py).
+    """
+    for var in (
+        "GATEWAY_HEALTH_URL",
+        "HERMES_GATEWAY_HEALTH_URL",
+        "HERMES_API_URL",
+        "HERMES_WEBUI_GATEWAY_BASE_URL",
+    ):
+        val = os.environ.get(var, "").strip()
+        if val:
+            base = val.rstrip("/")
+            for suffix in ("/health/detailed", "/health", "/v1/health", "/status"):
+                if base.endswith(suffix):
+                    base = base[: -len(suffix)].rstrip("/")
+                    break
+            return base
+    return None
+
+
+def _http_probe(url: str, timeout_s: float) -> tuple[bool, int | None, str | None, bytes | None]:
+    """GET ``url`` and return (ok, status_code, error_name, body).
+
+    ``ok`` is True only for a 2xx response. 5xx and network errors are not OK.
+    4xx is also treated as "responded" (the gateway is up, just answering 404
+    on this particular path) so the caller can move on to the next path.
+    ``body`` is the raw response bytes for 2xx responses, None otherwise.
+    """
+    req = urllib_request.Request(url, method="GET")
+    try:
+        with urllib_request.urlopen(req, timeout=timeout_s) as resp:  # noqa: S310 - trusted env var URL
+            status = getattr(resp, "status", None) or resp.getcode()
+            ok = 200 <= int(status) < 300
+            # Cap the body read: we only need a small JSON health payload, and an
+            # unbounded resp.read() on a large/trickled 2xx body could hang the
+            # /api/health/agent handler or balloon memory. Read one byte over the
+            # cap so the caller can detect (and skip) an oversized body.
+            body = resp.read(_REMOTE_PROBE_BODY_LIMIT_BYTES + 1) if ok else None
+            return (ok, int(status), None, body)
+    except urllib_error.HTTPError as exc:
+        return (False, int(exc.code), "HTTPError", None)
+    except Exception as exc:  # urllib_error.URLError, socket.timeout, ssl, etc.
+        return (False, None, type(exc).__name__, None)
+
+
+def _probe_remote_gateway(base_url: str, *, now: float | None = None) -> dict[str, Any]:
+    """Return an agent-health payload dict for a remote gateway base URL.
+
+    Result is cached for ``_REMOTE_PROBE_CACHE_TTL_S`` seconds per base_url.
+    """
+    current = time.monotonic() if now is None else now
+    with _remote_probe_lock:
+        if (
+            _remote_probe_cache.get("url") == base_url
+            and _remote_probe_cache.get("expires_at", 0.0) > current
+            and _remote_probe_cache.get("result") is not None
+        ):
+            cached = _remote_probe_cache["result"]
+            # Refresh checked_at so the UI shows a current timestamp without
+            # actually re-hitting the gateway.
+            return {**cached, "checked_at": _checked_at()}
+
+    last_status: int | None = None
+    last_error: str | None = None
+    for path in _REMOTE_PROBE_PATHS:
+        ok, status, err, body = _http_probe(base_url + path, _REMOTE_PROBE_TIMEOUT_S)
+        if ok:
+            details: dict[str, Any] = {
+                "state": "alive",
+                "reason": "remote_gateway",
+                "endpoint": base_url + path,
+                "status_code": status,
+            }
+            if body and len(body) <= _REMOTE_PROBE_BODY_LIMIT_BYTES:
+                try:
+                    data = json.loads(body)
+                    if isinstance(data, dict) and "gateway_state" in data:
+                        details["gateway_state"] = data["gateway_state"]
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    pass
+            # An over-cap body (len > limit, i.e. the +1 sentinel byte was read)
+            # is treated as "alive but no parseable gateway_state" — we still
+            # report the gateway as up, just without the detailed state.
+            payload = {
+                "alive": True,
+                "checked_at": _checked_at(),
+                "details": details,
+            }
+            break
+        # Remember the most informative failure signal we saw.
+        if status is not None:
+            last_status = status
+        if err is not None:
+            last_error = err
+    else:
+        details: dict[str, Any] = {
+            "state": "down",
+            "reason": "remote_gateway_unreachable",
+            "endpoint": base_url,
+        }
+        if last_status is not None:
+            details["status_code"] = last_status
+        if last_error is not None:
+            details["error"] = last_error
+        payload = {
+            "alive": False,
+            "checked_at": _checked_at(),
+            "details": details,
+        }
+
+    with _remote_probe_lock:
+        _remote_probe_cache["url"] = base_url
+        _remote_probe_cache["expires_at"] = current + _REMOTE_PROBE_CACHE_TTL_S
+        _remote_probe_cache["result"] = payload
+    return payload
+
+
+def _reset_remote_probe_cache_for_tests() -> None:
+    """Test hook: clear the in-process remote-probe cache."""
+    with _remote_probe_lock:
+        _remote_probe_cache["url"] = None
+        _remote_probe_cache["expires_at"] = 0.0
+        _remote_probe_cache["result"] = None
+
+
+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()
+
+    # Multi-container deployments (#3281): when HERMES_API_URL is set the
+    # gateway lives in another container/host. Probe it over HTTP before
+    # touching local module/pid/state-file signals, otherwise a missing
+    # ``gateway`` Python package in this image masquerades as
+    # "gateway_not_configured" and produces a spurious banner.
+    remote_base = _remote_gateway_base_url()
+    if remote_base is not None:
+        return _probe_remote_gateway(remote_base)
+
+    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/auth.py

@@ -1,144 +1,550 @@
 """
-Hermes Web UI -- Optional password authentication.
-Off by default. Enable by setting HERMES_WEBUI_PASSWORD env var
-or configuring a password in the Settings panel.
+Hermes Web UI -- optional authentication.
+Off by default. Enable by setting HERMES_WEBUI_PASSWORD, configuring a
+password in Settings, or registering passkeys and then going passwordless.
 """
 import hashlib
 import hmac
 import http.cookies
+import json
 import logging
 import os
+import re
 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',
+    '/api/auth/passkey/options', '/api/auth/passkey/login',
+    '/manifest.json', '/manifest.webmanifest',
+    '/session/manifest.json', '/session/manifest.webmanifest',
 })
 
 COOKIE_NAME = 'hermes_session'
-SESSION_TTL = 86400  # 24 hours
+CSRF_HEADER_NAME = 'X-Hermes-CSRF-Token'
 
-# Active sessions: token -> expiry timestamp
-_sessions = {}
+
+# RFC 6265 cookie-name token: a non-empty run of token chars
+# (no controls, whitespace, or separators such as ';', '=', ',').
+_COOKIE_NAME_RE = re.compile(r"^[-!#$%&'*+.^_`|~0-9A-Za-z]+$")
+
+
+def _resolve_cookie_name() -> str:
+    """Resolve the auth session cookie name from env > default.
+
+    Honours ``HERMES_WEBUI_COOKIE_NAME`` so multiple WebUI instances sharing a
+    hostname (different ports) can use distinct cookie names instead of
+    trampling each other's session — browsers scope cookies by host, not
+    host+port (RFC 6265). Falls back to ``COOKIE_NAME`` when the env var is
+    unset, empty, or not a valid RFC 6265 token.
+    """
+    name = os.getenv('HERMES_WEBUI_COOKIE_NAME', '').strip()
+    if not name:
+        return COOKIE_NAME
+    if _COOKIE_NAME_RE.match(name):
+        return name
+    logger.warning(
+        'Ignoring invalid HERMES_WEBUI_COOKIE_NAME=%r; falling back to %r '
+        '(name must be a valid RFC 6265 token)', name, COOKIE_NAME,
+    )
+    return COOKIE_NAME
+
+
+_SESSIONS_FILE = STATE_DIR / '.sessions.json'
+
+
+def _load_sessions() -> dict[str, float]:
+    """Load persisted sessions from STATE_DIR, pruning expired entries.
+
+    Returns an empty dict on any read or parse error so startup is never
+    blocked by a corrupt or missing sessions file.
+    """
+    try:
+        if _SESSIONS_FILE.exists():
+            data = json.loads(_SESSIONS_FILE.read_text(encoding='utf-8'))
+            if not isinstance(data, dict):
+                raise ValueError('malformed sessions file — expected dict')
+            now = time.time()
+            return {t: exp for t, exp in data.items()
+                    if isinstance(t, str) and isinstance(exp, (int, float)) and exp > now}
+    except Exception as e:
+        logger.debug("Failed to load sessions file, starting fresh: %s", e)
+    return {}
+
+
+def _save_sessions(sessions: dict[str, float]) -> None:
+    """Atomically persist sessions to STATE_DIR/.sessions.json (0600).
+
+    Uses a temp file + os.replace() so a crash mid-write never leaves a
+    truncated file.  Mirrors the same pattern as .signing_key persistence.
+    """
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=STATE_DIR, suffix='.sessions.tmp')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(sessions, f)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, _SESSIONS_FILE)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception as e:
+        logger.debug("Failed to persist sessions: %s", e)
+
+
+# Active sessions: token -> expiry timestamp (persisted across restarts via STATE_DIR)
+_sessions = _load_sessions()
+_SESSIONS_LOCK = threading.Lock()
 
 # ── 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 _clear_login_attempts(ip: str) -> None:
+    """Clear failed login attempts after a successful login (thread-safe)."""
+    with _LOGIN_ATTEMPTS_LOCK:
+        if ip in _login_attempts:
+            _login_attempts.pop(ip, None)
+            _save_login_attempts(_login_attempts)
+
+
+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:
+def is_password_auth_enabled() -> bool:
     """True if a password is configured (env var or settings)."""
     return get_password_hash() is not None
 
 
-def verify_password(plain) -> bool:
-    """Verify a plaintext password against the stored hash."""
+def _passkey_feature_flag_enabled() -> bool:
+    """Return True if the passkey/WebAuthn surface is enabled for this deployment.
+
+    Passkey support is opt-in default-off behind a feature flag so deployments
+    that don't want the WebAuthn surface (or whose RP-ID setup isn't ready for
+    non-localhost hosts) can disable it entirely with no UI surface, no
+    endpoints, no credential storage. To enable:
+
+      - Set ``HERMES_WEBUI_PASSKEY=1`` in the environment, OR
+      - Set ``webui_passkey_enabled: true`` in the per-profile config.yaml
+
+    With the flag off, ``are_passkeys_enabled()`` always returns False even if
+    credentials were registered in the past, and ``/login`` shows password-only.
+    """
+    env_value = os.getenv("HERMES_WEBUI_PASSKEY", "")
+    if env_value:
+        return env_value.strip().lower() in {"1", "true", "yes", "on"}
+    try:
+        from api.config import get_config
+
+        cfg = get_config()
+        if isinstance(cfg, dict):
+            raw = cfg.get("webui_passkey_enabled")
+            if isinstance(raw, bool):
+                return raw
+            if isinstance(raw, str):
+                return raw.strip().lower() in {"1", "true", "yes", "on"}
+    except Exception:
+        pass
+    return False
+
+
+def are_passkeys_enabled() -> bool:
+    """True if the passkey feature flag is on AND at least one local passkey credential is registered."""
+    if not _passkey_feature_flag_enabled():
+        return False
+    try:
+        from api.passkeys import passkeys_available
+
+        return passkeys_available()
+    except Exception as exc:
+        logger.debug("Failed to inspect passkey availability: %s", exc)
+        return False
+
+
+def is_auth_enabled() -> bool:
+    """True if password auth or passkey-only auth is configured."""
+    return is_password_auth_enabled() or are_passkeys_enabled()
+
+
+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
-    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()[:32]
+    with _SESSIONS_LOCK:
+        _sessions[token] = time.time() + _resolve_session_ttl()
+        _save_sessions(_sessions)
+    sig = hmac.new(_signing_key(), token.encode(), hashlib.sha256).hexdigest()
     return f"{token}.{sig}"
 
 
 def _prune_expired_sessions():
     """Remove all expired session entries to prevent unbounded memory growth."""
     now = time.time()
-    for token in [t for t, exp in _sessions.items() if now > exp]:
-        _sessions.pop(token, None)
+    with _SESSIONS_LOCK:
+        expired = [t for t, exp in _sessions.items() if now > exp]
+        if expired:
+            for token in expired:
+                _sessions.pop(token, None)
+            _save_sessions(_sessions)
 
 
-def verify_session(cookie_value) -> bool:
+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):
-        return False
-    expiry = _sessions.get(token)
-    if not expiry or time.time() > expiry:
-        _sessions.pop(token, None)
+    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
+    with _SESSIONS_LOCK:
+        expiry = _sessions.get(token)
+        if not expiry or time.time() > expiry:
+            _sessions.pop(token, None)
+            _save_sessions(_sessions)
+            return False
     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 sign_profile_cookie_value(profile_name: str, session_cookie_value: str | None) -> str:
+    """Return a profile cookie value authenticated for one WebUI session.
+
+    The active-profile cookie is client-controlled, so when auth is enabled it
+    must not be trusted as a bare profile name. Binding the selected profile to
+    the HttpOnly session token prevents a client from forging
+    ``hermes_profile=<other-profile>`` and bypassing profile visibility guards.
+    """
+    if not session_cookie_value or not verify_session(session_cookie_value):
+        raise ValueError("active auth session is required to sign profile cookie")
+    token = _session_token_from_cookie_value(session_cookie_value)
+    if not token:
+        raise ValueError("active auth session is required to sign profile cookie")
+    sig = hmac.new(
+        _signing_key(),
+        f"profile:{token}:{profile_name}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+    return f"{profile_name}.{sig}"
+
+
+def verify_profile_cookie_value(cookie_value: str, session_cookie_value: str | None) -> str | None:
+    """Verify a session-bound profile cookie and return its profile name."""
+    if not cookie_value or '.' not in cookie_value:
+        return None
+    if not session_cookie_value or not verify_session(session_cookie_value):
+        return None
+    profile_name, sig = cookie_value.rsplit('.', 1)
+    token = _session_token_from_cookie_value(session_cookie_value)
+    if not profile_name or not token or not sig:
+        return None
+    # Defense-in-depth: validate the profile-name pattern here too, not only in
+    # get_profile_cookie(), so any future caller of this verifier can't return an
+    # unvalidated name. (#4023 Opus hardening.)
+    from api.profiles import _PROFILE_ID_RE
+    if profile_name != 'default' and not _PROFILE_ID_RE.fullmatch(profile_name):
+        return None
+    expected = hmac.new(
+        _signing_key(),
+        f"profile:{token}:{profile_name}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+    if hmac.compare_digest(str(sig), expected):
+        return profile_name
+    return 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:
         token = cookie_value.rsplit('.', 1)[0]
-        _sessions.pop(token, None)
+        with _SESSIONS_LOCK:
+            if token in _sessions:
+                _sessions.pop(token, None)
+                _save_sessions(_sessions)
 
 
 def parse_cookie(handler) -> str | None:
@@ -151,7 +557,7 @@ def parse_cookie(handler) -> str | None:
         cookie.load(cookie_header)
     except http.cookies.CookieError:
         return None
-    morsel = cookie.get(COOKIE_NAME)
+    morsel = cookie.get(_resolve_cookie_name())
     return morsel.value if morsel else None
 
 
@@ -161,7 +567,7 @@ def check_auth(handler, parsed) -> bool:
     if not is_auth_enabled():
         return True
     # Public paths don't require auth
-    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/'):
+    if parsed.path in PUBLIC_PATHS or parsed.path.startswith('/static/') or parsed.path.startswith('/session/static/'):
         return True
     # Check session cookie
     cookie_val = parse_cookie(handler)
@@ -169,36 +575,112 @@ 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)
-        handler.send_header('Location', '/login')
+        # Pass the original path as ?next= so login.js redirects back after auth.
+        # SECURITY/CORRECTNESS: the inner `?` and `&` MUST be percent-encoded
+        # when stuffed into the outer `?next=` parameter, otherwise:
+        #   (a) multi-param query strings get truncated at the first inner `&`
+        #       (e.g. `/api/sessions?limit=50&offset=0` would round-trip as
+        #       just `/api/sessions?limit=50` after the browser parses the
+        #       outer URL — `offset=0` becomes a separate top-level query
+        #       parameter that the login page ignores).
+        #   (b) attacker-controlled paths could inject a second `next=`
+        #       parameter; per RFC 3986 the duplicate behaviour is undefined
+        #       and parsers diverge (Python's parse_qs returns last-match,
+        #       URLSearchParams returns first-match), opening a query-pollution
+        #       footgun even though _safeNextPath() rejects most malicious
+        #       shapes downstream.
+        # Encoding the entire `path?query` blob with quote(safe='/') turns
+        # `?` → `%3F` and `&` → `%26`, so the outer parameter holds exactly
+        # one path-with-query string and `searchParams.get('next')` returns
+        # the full original URL (the browser auto-decodes once).
+        # (Opus pre-release advisor finding for v0.50.258.)
+        import urllib.parse as _urlparse
+        _path_with_query = parsed.path or '/'
+        if parsed.query:
+            _path_with_query += '?' + parsed.query
+        # safe='/' keeps path separators readable; everything else (including
+        # `?`, `&`, `=`) gets percent-encoded.
+        _next = _urlparse.quote(_path_with_query, safe='/')
+        handler.send_header('Location', 'login?next=' + _next)
+        handler.send_header('Content-Length', '0')
         handler.end_headers()
     return False
 
 
+def _is_loopback(addr: str) -> bool:
+    """Return True if *addr* is a loopback address (127.x.x.x, ::1, or ::ffff:127.x.x.x)."""
+    import ipaddress as _ipaddress
+    try:
+        ip = _ipaddress.ip_address(addr)
+        if ip.is_loopback:
+            return True
+        # Python < 3.12: is_loopback is False for ::ffff:127.x.x.x (gh-117566)
+        if hasattr(ip, 'ipv4_mapped') and ip.ipv4_mapped is not None:
+            return ip.ipv4_mapped.is_loopback
+        return False
+    except ValueError:
+        return False
+
+
+def _is_secure_context(handler=None) -> bool:
+    """Return True if cookies should carry the Secure flag.
+
+    Priority order:
+    1. ``HERMES_WEBUI_SECURE`` env var: 1/true/yes -> True; 0/false/no -> False.
+    2. Direct TLS socket (handler.request.getpeercert present) -> True.
+    3. ``HERMES_WEBUI_TRUST_FORWARDED_PROTO=1`` opt-in: trust
+       ``X-Forwarded-Proto: https`` header from a known reverse proxy.
+    4. Otherwise -> False (loopback or non-loopback, plain HTTP is not secure).
+
+    .. warning::
+       ``X-Forwarded-Proto`` is only trustworthy behind a reverse proxy.
+       It is ignored unless ``HERMES_WEBUI_TRUST_FORWARDED_PROTO=1`` is
+       set explicitly, preventing header-injection attacks on plain-HTTP
+       deployments.
+    """
+    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
+        trust_fwd = os.getenv('HERMES_WEBUI_TRUST_FORWARDED_PROTO', '').strip().lower()
+        if trust_fwd in ('1', 'true', 'yes'):
+            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()
-    cookie[COOKIE_NAME] = cookie_value
-    cookie[COOKIE_NAME]['httponly'] = True
-    cookie[COOKIE_NAME]['samesite'] = 'Lax'
-    cookie[COOKIE_NAME]['path'] = '/'
-    cookie[COOKIE_NAME]['max-age'] = str(SESSION_TTL)
-    # Set Secure flag when connection is HTTPS
-    if getattr(handler.request, 'getpeercert', None) is not None or handler.headers.get('X-Forwarded-Proto', '') == 'https':
-        cookie[COOKIE_NAME]['secure'] = True
-    handler.send_header('Set-Cookie', cookie[COOKIE_NAME].OutputString())
+    name = _resolve_cookie_name()
+    cookie[name] = cookie_value
+    cookie[name]['httponly'] = True
+    cookie[name]['samesite'] = 'Lax'
+    cookie[name]['path'] = '/'
+    cookie[name]['max-age'] = str(_resolve_session_ttl())
+    if _is_secure_context(handler):
+        cookie[name]['secure'] = True
+    handler.send_header('Set-Cookie', cookie[name].OutputString())
 
 
 def clear_auth_cookie(handler) -> None:
     """Clear the auth cookie on the response."""
     cookie = http.cookies.SimpleCookie()
-    cookie[COOKIE_NAME] = ''
-    cookie[COOKIE_NAME]['httponly'] = True
-    cookie[COOKIE_NAME]['path'] = '/'
-    cookie[COOKIE_NAME]['max-age'] = '0'
-    handler.send_header('Set-Cookie', cookie[COOKIE_NAME].OutputString())
+    name = _resolve_cookie_name()
+    cookie[name] = ''
+    cookie[name]['httponly'] = True
+    cookie[name]['path'] = '/'
+    cookie[name]['max-age'] = '0'
+    handler.send_header('Set-Cookie', cookie[name].OutputString())

api/background.py

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

api/clarify.py

@@ -6,25 +6,35 @@ clarification string instead of an approval decision.
 
 from __future__ import annotations
 
+import queue
 import threading
+import time
+import uuid
 from typing import Optional
 
+from api.session_events import publish_session_list_changed
 
+
+DEFAULT_TIMEOUT_SECONDS = 120
 _lock = threading.Lock()
 _pending: dict[str, dict] = {}
 _gateway_queues: dict[str, list] = {}
 _gateway_notify_cbs: dict[str, object] = {}
 
+# ── SSE subscriber registry ─────────────────────────────────────────────
+_clarify_sse_subscribers: dict[str, list[queue.Queue]] = {}
+
 
 class _ClarifyEntry:
     """One pending clarify request inside a session."""
 
-    __slots__ = ("event", "data", "result")
+    __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:
@@ -44,6 +54,8 @@ def unregister_gateway_notify(session_key: str) -> None:
     with _lock:
         _gateway_notify_cbs.pop(session_key, None)
         entries = _clear_queue_locked(session_key)
+    if entries:
+        publish_session_list_changed("attention_cleared")
     for entry in entries:
         entry.event.set()
 
@@ -52,39 +64,97 @@ def clear_pending(session_key: str) -> int:
     """Clear any pending clarify prompts for the session without removing the callback."""
     with _lock:
         entries = _clear_queue_locked(session_key)
+    if entries:
+        publish_session_list_changed("attention_cleared")
     for entry in entries:
         entry.event.set()
     return len(entries)
 
 
+def _with_timeout_metadata(data: dict) -> dict:
+    item = dict(data or {})
+    requested_at = float(item.get("requested_at") or time.time())
+    timeout_seconds = int(item.get("timeout_seconds") or DEFAULT_TIMEOUT_SECONDS)
+    expires_at = float(item.get("expires_at") or requested_at + timeout_seconds)
+    item["requested_at"] = requested_at
+    item["timeout_seconds"] = timeout_seconds
+    item["expires_at"] = expires_at
+    return item
+
+
+def _clarify_sse_notify(session_id: str, head: dict | None, total: int) -> None:
+    """Push a clarify event to all SSE subscribers for a session."""
+    payload = {"pending": dict(head) if head else None, "pending_count": total}
+    for q in _clarify_sse_subscribers.get(session_id, ()):
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            pass  # drop if subscriber is slow
+
+
+def sse_subscribe(session_id: str) -> queue.Queue:
+    """Register a bounded Queue for SSE push to a given session."""
+    q: queue.Queue = queue.Queue(maxsize=16)
+    with _lock:
+        _clarify_sse_subscribers.setdefault(session_id, []).append(q)
+    return q
+
+
+def sse_unsubscribe(session_id: str, q: queue.Queue) -> None:
+    """Remove a subscriber Queue; clean up empty session entries."""
+    with _lock:
+        subs = _clarify_sse_subscribers.get(session_id)
+        if subs:
+            try:
+                subs.remove(q)
+            except ValueError:
+                pass
+            if not subs:
+                _clarify_sse_subscribers.pop(session_id, None)
+
+
 def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
     """Queue a pending clarify request and notify the UI callback if registered."""
+    data = _with_timeout_metadata(data)
     with _lock:
-        queue = _gateway_queues.setdefault(session_key, [])
+        gw_queue = _gateway_queues.setdefault(session_key, [])
         # De-duplicate while unresolved: if the most recent pending clarify is
         # semantically identical, reuse it instead of stacking duplicates.
-        if queue:
-            last = queue[-1]
+        if gw_queue:
+            last = gw_queue[-1]
             if (
                 str(last.data.get("question", "")) == str(data.get("question", ""))
                 and list(last.data.get("choices_offered") or [])
                 == 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] = queue[0].data
+                _pending[session_key] = gw_queue[0].data
                 if cb:
                     try:
                         cb(dict(entry.data))
                     except Exception:
                         pass
+                # Safe to call while holding _lock: publish() only takes the
+                # leaf _SESSION_EVENTS_LOCK and never re-acquires this lock.
+                publish_session_list_changed("attention_pending")
                 return entry
 
         entry = _ClarifyEntry(data)
-        queue.append(entry)
-        _pending[session_key] = queue[0].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)
+        # Notify SSE subscribers from inside _lock for ordering guarantees.
+        _clarify_sse_notify(session_key, dict(gw_queue[0].data), len(gw_queue))
+    publish_session_list_changed("attention_pending")
     if cb:
         try:
             cb(data)
@@ -108,21 +178,61 @@ def has_pending(session_key: str) -> bool:
         return bool(_gateway_queues.get(session_key))
 
 
+def pending_count(session_key: str) -> int:
+    """Return the number of unresolved clarify prompts for a session."""
+    with _lock:
+        queue = _gateway_queues.get(session_key) or []
+        if queue:
+            return len(queue)
+        return 1 if _pending.get(session_key) else 0
+
+
 def resolve_clarify(session_key: str, response: str, resolve_all: bool = False) -> int:
     """Resolve the oldest pending clarify request for a session."""
     with _lock:
-        queue = _gateway_queues.get(session_key)
-        if not queue:
+        q = _gateway_queues.get(session_key)
+        if not q:
             _pending.pop(session_key, None)
             return 0
-        entries = list(queue) if resolve_all else [queue.pop(0)]
-        if queue:
-            _pending[session_key] = queue[0].data
+        entries = list(q) if resolve_all else [q.pop(0)]
+        if q:
+            _pending[session_key] = q[0].data
+            _clarify_sse_notify(session_key, dict(q[0].data), len(q))
         else:
             _clear_queue_locked(session_key)
+            _clarify_sse_notify(session_key, None, 0)
+    publish_session_list_changed("attention_resolved")
     count = 0
     for entry in entries:
         entry.result = response
         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)
+                # Safe to call while holding _lock: publish() only takes the
+                # leaf _SESSION_EVENTS_LOCK and never re-acquires this lock.
+                publish_session_list_changed("attention_resolved")
+                entry.result = response
+                entry.event.set()
+                return True
+        return False

api/commands.py

@@ -6,6 +6,7 @@ so the frontend can still load with WEBUI_ONLY commands.
 """
 from __future__ import annotations
 import logging
+import threading
 from typing import Any
 
 logger = logging.getLogger(__name__)
@@ -20,6 +21,41 @@ _NEVER_EXPOSE: frozenset[str] = frozenset({
 })
 
 
+# Narrow agent-side execution allowlist for /api/commands/exec.
+_AGENT_COMMAND_ALIASES = {
+    'reload_mcp': 'reload-mcp',
+    'reload_skills': 'reload-skills',
+    'codex_runtime': 'codex-runtime',
+}
+_ALLOWED_AGENT_COMMANDS = frozenset({'reload-mcp', 'reload-skills', 'codex-runtime'})
+_RELOAD_MCP_LOCK = threading.Lock()
+_RELOAD_SKILLS_LOCK = threading.Lock()
+_CODEX_RUNTIME_LOCK = threading.Lock()
+
+
+def _parse_agent_command(command: str) -> tuple[str, str]:
+    """Return ``(canonical_name, arg_string)`` from slash-command text."""
+
+    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()
+    if not cmd_base:
+        raise ValueError("command is required")
+
+    return _AGENT_COMMAND_ALIASES.get(cmd_base, cmd_base), cmd_parts[1] if len(cmd_parts) > 1 else ""
+
+
+def _normalize_agent_command_name(command: str) -> str:
+    """Normalize slash text to a canonical command name."""
+
+    canonical, _arg_string = _parse_agent_command(command)
+    return canonical
+
+
 def list_commands(_registry=None) -> list[dict[str, Any]]:
     """Return COMMAND_REGISTRY entries as JSON-friendly dicts.
 
@@ -53,4 +89,216 @@ 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_agent_command(command: str) -> str:
+    """Execute a narrow allowlist of agent-side runtime commands."""
+
+    canonical, arg_string = _parse_agent_command(command)
+    if canonical not in _ALLOWED_AGENT_COMMANDS:
+        raise KeyError(canonical)
+
+    if canonical == 'reload-mcp':
+        return _run_reload_mcp_command()
+    if canonical == 'reload-skills':
+        return _run_reload_skills_command()
+    if canonical == 'codex-runtime':
+        return _run_codex_runtime_command(arg_string)
+
+    raise KeyError(canonical)
+
+
+def _run_codex_runtime_command(arg_string: str) -> str:
+    """Execute Hermes' shared Codex runtime switch for the active profile."""
+    try:
+        from hermes_cli.codex_runtime_switch import apply, parse_args
+    except Exception as exc:
+        logger.warning("Codex runtime switch unavailable", exc_info=True)
+        raise RuntimeError("Codex runtime switch unavailable") from exc
+
+    new_value, errors = parse_args(arg_string)
+    if errors:
+        return "\n".join(str(error) for error in errors)
+
+    with _CODEX_RUNTIME_LOCK:
+        try:
+            from api import config as webui_config
+
+            active_config = webui_config.get_config()
+
+            def _persist_config(config_data: dict) -> None:
+                webui_config._save_yaml_config_file(
+                    webui_config._get_config_path(),
+                    config_data,
+                )
+                webui_config.reload_config()
+
+            status = apply(active_config, new_value, persist_callback=_persist_config)
+        except Exception as exc:
+            logger.warning("Failed to execute /codex-runtime", exc_info=True)
+            raise RuntimeError("Failed to update Codex runtime") from exc
+
+    return str(getattr(status, "message", "") or "(no output)")
+
+
+def _run_reload_mcp_command() -> str:
+    """Execute the MCP reconnect path and return a short user-facing summary."""
+    with _RELOAD_MCP_LOCK:
+        try:
+            from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _servers, _lock
+        except Exception as exc:
+            logger.warning("Failed to import MCP runtime for /reload-mcp", exc_info=True)
+            raise RuntimeError("MCP runtime unavailable") from exc
+
+        try:
+            with _lock:
+                old_servers = set(_servers.keys())
+
+            shutdown_mcp_servers()
+            new_tools = discover_mcp_tools()
+
+            with _lock:
+                connected_servers = set(_servers.keys())
+        except Exception as exc:
+            logger.warning("Failed to reload MCP servers", exc_info=True)
+            raise RuntimeError("Failed to reload MCP servers") from exc
+
+    added = connected_servers - old_servers
+    removed = old_servers - connected_servers
+    reconnected = connected_servers & old_servers
+
+    lines = ["Reloaded MCP servers from configuration."]
+    if reconnected:
+        lines.append(f"Reconnected: {', '.join(sorted(reconnected))}")
+    if added:
+        lines.append(f"Added: {', '.join(sorted(added))}")
+    if removed:
+        lines.append(f"Removed: {', '.join(sorted(removed))}")
+
+    if connected_servers:
+        lines.append(f"{len(new_tools or [])} tool(s) available across {len(connected_servers)} server(s)")
+    else:
+        lines.append("No MCP servers connected")
+
+    if not reconnected and not added and not removed:
+        lines.append("Tooling state was already current")
+
+    return "\n".join(lines)
+
+
+def _run_reload_skills_command() -> str:
+    """Re-scan the installed skills directory and summarize the diff."""
+    with _RELOAD_SKILLS_LOCK:
+        try:
+            from agent.skill_commands import reload_skills
+        except Exception as exc:
+            logger.warning("Failed to import skills runtime for /reload-skills", exc_info=True)
+            raise RuntimeError("Skills runtime unavailable") from exc
+
+        try:
+            result = reload_skills() or {}
+        except Exception as exc:
+            logger.warning("Failed to reload skills", exc_info=True)
+            raise RuntimeError("Failed to reload skills") from exc
+
+    added = result.get("added", [])
+    removed = result.get("removed", [])
+    unchanged = result.get("unchanged", [])
+    total = int(result.get("total", 0) or 0)
+
+    def _names(items: Any) -> list[str]:
+        out: list[str] = []
+        for item in items or []:
+            if isinstance(item, dict):
+                name = str(item.get("name", "")).strip()
+            else:
+                name = str(item).strip()
+            if name:
+                out.append(name)
+        return out
+
+    added_names = _names(added)
+    removed_names = _names(removed)
+
+    lines = [
+        "Reloaded skills from disk.",
+        f"Added: {len(added_names)}",
+        f"Removed: {len(removed_names)}",
+        f"Unchanged: {len(list(unchanged or []))}",
+        f"Total skills: {total}",
+    ]
+    if added_names:
+        lines.append(f"Added skills: {', '.join(sorted(added_names))}")
+    if removed_names:
+        lines.append(f"Removed skills: {', '.join(sorted(removed_names))}")
+    return "\n".join(lines)
+
+
+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:
+        logger.warning("Plugin command runtime unavailable", exc_info=True)
+        raise RuntimeError("plugin command runtime unavailable") from exc
+
+    try:
+        handler = get_plugin_command_handler(cmd_base)
+    except Exception as exc:
+        logger.warning("Plugin command lookup failed for %r", cmd_base, exc_info=True)
+        raise RuntimeError("plugin command lookup failed") 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 execution failed", cmd_base, exc_info=True)
+        return f"Plugin command error: {type(exc).__name__}"

api/compression_anchor.py

@@ -0,0 +1,134 @@
+"""
+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]")
+        or text.startswith("[session arc summary")
+    )
+
+
+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/extensions.py

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

api/gateway_chat.py

@@ -0,0 +1,489 @@
+"""Default-off Hermes Gateway bridge for browser-originated chat turns."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from api.config import (
+    CANCEL_FLAGS,
+    STREAMS,
+    STREAMS_LOCK,
+    STREAM_LAST_EVENT_ID,
+    STREAM_LIVE_TOOL_CALLS,
+    STREAM_PARTIAL_TEXT,
+    STREAM_REASONING_TEXT,
+    _get_session_agent_lock,
+    register_active_run,
+    unregister_active_run,
+    update_active_run,
+)
+from api.helpers import _redact_text, redact_session_data
+from api.models import get_session, merge_session_messages_append_only
+from api.run_journal import RunJournalWriter
+
+logger = logging.getLogger(__name__)
+
+_WEBUI_CHAT_BACKEND_ENV = "HERMES_WEBUI_CHAT_BACKEND"
+_WEBUI_GATEWAY_BASE_URL_ENV = "HERMES_WEBUI_GATEWAY_BASE_URL"
+_WEBUI_GATEWAY_API_KEY_ENV = "HERMES_WEBUI_GATEWAY_API_KEY"
+_GATEWAY_CHAT_BACKENDS = {"gateway", "api_server", "api-server"}
+
+
+def webui_chat_backend_mode(config_data=None, environ: dict[str, str] | None = None) -> str:
+    """Return the explicitly selected browser chat backend.
+
+    The default remains the in-process WebUI runtime. Only explicit gateway
+    values opt browser chat into the Hermes API server bridge; generic truthy
+    strings are deliberately ignored so deployments do not change execution
+    ownership by accident.
+    """
+    source = os.environ if environ is None else environ
+    cfg = config_data if isinstance(config_data, dict) else {}
+    raw = str(
+        source.get(_WEBUI_CHAT_BACKEND_ENV)
+        or cfg.get("webui_chat_backend")
+        or ""
+    ).strip().lower()
+    if raw in _GATEWAY_CHAT_BACKENDS:
+        return "gateway"
+    return "legacy"
+
+
+def webui_gateway_chat_enabled(config_data=None, environ: dict[str, str] | None = None) -> bool:
+    return webui_chat_backend_mode(config_data, environ) == "gateway"
+
+
+def _gateway_base_url(config_data=None, environ: dict[str, str] | None = None) -> str:
+    source = os.environ if environ is None else environ
+    cfg = config_data if isinstance(config_data, dict) else {}
+    raw = str(
+        source.get(_WEBUI_GATEWAY_BASE_URL_ENV)
+        or cfg.get("webui_gateway_base_url")
+        or "http://127.0.0.1:8642"
+    ).strip()
+    return raw.rstrip("/") or "http://127.0.0.1:8642"
+
+
+def _gateway_api_key(environ: dict[str, str] | None = None) -> str:
+    source = os.environ if environ is None else environ
+    return str(
+        source.get(_WEBUI_GATEWAY_API_KEY_ENV)
+        or source.get("API_SERVER_KEY")
+        or ""
+    ).strip()
+
+
+def gateway_chat_config_status(config_data=None, environ: dict[str, str] | None = None) -> dict:
+    """Return redacted Gateway-backed chat configuration status."""
+    mode = webui_chat_backend_mode(config_data, environ)
+    base_url = _gateway_base_url(config_data, environ)
+    return {
+        "enabled": mode == "gateway",
+        "backend": mode,
+        "base_url_configured": bool(base_url),
+        "api_key_configured": bool(_gateway_api_key(environ)),
+    }
+
+
+def _gateway_http_error_event(exc: urllib.error.HTTPError, err_body: str, *, api_key_configured: bool) -> dict:
+    safe = _redact_text(err_body or str(exc))[:500]
+    if exc.code == 401:
+        return {
+            "label": "Gateway authentication failed",
+            "type": "gateway_auth_error",
+            "message": "Gateway rejected the WebUI API key (HTTP 401).",
+            "hint": (
+                "Set HERMES_WEBUI_GATEWAY_API_KEY to the same value as the Hermes Gateway "
+                "API_SERVER_KEY, or disable HERMES_WEBUI_CHAT_BACKEND=gateway."
+                if not api_key_configured
+                else "Check that HERMES_WEBUI_GATEWAY_API_KEY matches the Hermes Gateway API_SERVER_KEY."
+            ),
+        }
+    return {
+        "label": "Gateway request failed",
+        "type": "gateway_http_error",
+        "message": f"Gateway returned HTTP {exc.code}.",
+        "hint": safe or "Check the configured Gateway API server.",
+    }
+
+
+def _gateway_sse_delta(payload: dict) -> str:
+    """Extract assistant text from an OpenAI-compatible streaming chunk."""
+    try:
+        choices = payload.get("choices") or []
+        if not choices:
+            return ""
+        choice = choices[0] or {}
+        delta = choice.get("delta") or {}
+        content = delta.get("content")
+        if isinstance(content, str):
+            return content
+        message = choice.get("message") or {}
+        content = message.get("content")
+        return content if isinstance(content, str) else ""
+    except Exception:
+        return ""
+
+
+def _gateway_stream_usage(payload: dict) -> dict:
+    usage = payload.get("usage") if isinstance(payload, dict) else None
+    if not isinstance(usage, dict):
+        return {}
+    return {
+        "input_tokens": int(usage.get("prompt_tokens") or usage.get("input_tokens") or 0),
+        "output_tokens": int(usage.get("completion_tokens") or usage.get("output_tokens") or 0),
+        "estimated_cost": usage.get("estimated_cost") or usage.get("estimated_cost_usd") or 0,
+    }
+
+
+def _gateway_tool_progress_event(payload: dict) -> tuple[str, dict] | None:
+    """Translate Hermes Gateway tool-progress SSE payloads to WebUI events."""
+    if not isinstance(payload, dict):
+        return None
+    name = str(payload.get("tool") or payload.get("name") or payload.get("function_name") or "").strip()
+    if not name or name.startswith("_"):
+        return None
+    status = str(payload.get("status") or "running").strip().lower()
+    tid = payload.get("toolCallId") or payload.get("tool_call_id") or payload.get("id")
+    is_complete = status in {"completed", "complete", "success", "error", "failed"}
+    event_payload = {
+        "event_type": "tool.completed" if is_complete else "tool.started",
+        "name": name,
+        "preview": payload.get("label") or payload.get("preview"),
+        "args": payload.get("args") if isinstance(payload.get("args"), dict) else {},
+        "is_error": status in {"error", "failed"},
+    }
+    if tid:
+        event_payload["tid"] = str(tid)
+    return ("tool_complete" if is_complete else "tool"), event_payload
+
+
+def _stream_writeback_is_current(session: Any, stream_id: str) -> bool:
+    return bool(stream_id and getattr(session, "active_stream_id", None) == stream_id)
+
+
+def _clear_gateway_pending_state(session: Any, stream_id: str) -> None:
+    if not _stream_writeback_is_current(session, stream_id):
+        return
+    session.active_stream_id = None
+    session.pending_user_message = None
+    session.pending_attachments = None
+    session.pending_started_at = None
+    session.save()
+
+
+def _run_gateway_chat_streaming(
+    session_id,
+    msg_text,
+    model,
+    workspace,
+    stream_id,
+    attachments=None,
+    *,
+    model_provider=None,
+):
+    """Bridge a WebUI chat turn through Hermes Gateway's API server.
+
+    This default-off path keeps the browser contract unchanged: /api/chat/start
+    still returns a local stream_id and /api/chat/stream still receives WebUI SSE
+    event names. The worker translates OpenAI-compatible streaming chunks from
+    the configured Gateway API server into those local events and persists the
+    final user/assistant turn back into the WebUI session.
+    """
+    q = STREAMS.get(stream_id)
+    if q is None:
+        return
+    register_active_run(
+        stream_id,
+        session_id=session_id,
+        started_at=time.time(),
+        phase="gateway-starting",
+        workspace=str(workspace),
+        model=model,
+        provider=model_provider,
+        backend="gateway",
+    )
+    try:
+        run_journal = RunJournalWriter(session_id, stream_id)
+    except Exception:
+        run_journal = None
+        logger.debug("Failed to initialize gateway run journal for stream %s", stream_id, exc_info=True)
+    cancel_event = threading.Event()
+    with STREAMS_LOCK:
+        CANCEL_FLAGS[stream_id] = cancel_event
+        STREAM_PARTIAL_TEXT[stream_id] = ""
+        STREAM_REASONING_TEXT[stream_id] = ""
+        STREAM_LIVE_TOOL_CALLS[stream_id] = []
+
+    def put_gateway_event(event, data):
+        if cancel_event.is_set() and event not in ("cancel", "error", "apperror"):
+            return
+        event_id = None
+        if run_journal is not None:
+            try:
+                journaled = run_journal.append_sse_event(event, data)
+                event_id = (journaled or {}).get("event_id") if isinstance(journaled, dict) else None
+                if event_id:
+                    STREAM_LAST_EVENT_ID[stream_id] = event_id
+            except Exception:
+                logger.debug("Failed to append gateway event %s for stream %s", event, stream_id, exc_info=True)
+        if event_id and hasattr(q, "note_last_event_id"):
+            try:
+                q.note_last_event_id(event_id)
+            except Exception:
+                logger.debug("Failed to note gateway event_id %s for stream %s", event_id, stream_id, exc_info=True)
+        try:
+            queue_item = (event, data, event_id) if event_id and hasattr(q, "subscribe_with_snapshot") else (event, data)
+            q.put_nowait(queue_item)
+        except Exception:
+            logger.debug("Failed to put gateway event to queue")
+
+    s = None
+    final_text = ""
+    usage = {"input_tokens": 0, "output_tokens": 0, "estimated_cost": 0}
+    try:
+        s = get_session(session_id)
+        from api.config import get_config  # imported lazily to avoid config-cycle churn
+
+        cfg = get_config()
+        try:
+            from api.streaming import (
+                _load_webui_prefill_context,
+                _prefill_messages_with_webui_context,
+                _normalize_prefill_messages_before_user_turn,
+                _public_prefill_context_status,
+                _webui_ephemeral_system_prompt,
+            )
+
+            prefill_context = _load_webui_prefill_context(cfg)
+            # #3324: the WebUI session/delivery context (connected platforms,
+            # home channels, delivery hints, session framing) is now carried in
+            # the ephemeral system prompt rather than a prefill `user` message.
+            # The gateway-backed path must build the SAME system prompt so that
+            # context is not silently dropped on Gateway-routed WebUI chats.
+            _gateway_system_prompt = _webui_ephemeral_system_prompt(
+                None,
+                surface_context={
+                    "source": "webui",
+                    "session_id": session_id,
+                    "profile": getattr(s, "profile", None),
+                    "workspace": s.workspace if s is not None else str(workspace),
+                },
+                config_data=cfg,
+            )
+            prefill_messages = _prefill_messages_with_webui_context(prefill_context, cfg)
+            prefill_messages = _normalize_prefill_messages_before_user_turn(prefill_messages)
+            prefill_messages = [
+                {"role": "system", "content": _gateway_system_prompt},
+                *prefill_messages,
+            ]
+            put_gateway_event("context_status", {
+                "session_id": session_id,
+                "prefill": _public_prefill_context_status(prefill_context),
+            })
+        except Exception:
+            logger.debug("Failed to load WebUI gateway prefill context", exc_info=True)
+            prefill_messages = []
+        base_url = _gateway_base_url(cfg)
+        api_key = _gateway_api_key()
+        url = f"{base_url}/v1/chat/completions"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+            "X-Hermes-Session-Id": session_id,
+        }
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+            # Scope Gateway long-term continuity to this WebUI conversation
+            # without exposing the browser's auth cookie or CSRF material.
+            headers["X-Hermes-Session-Key"] = f"webui:{session_id}"
+        message_content: Any = str(msg_text or "")
+        if attachments:
+            try:
+                from api.streaming import _build_native_multimodal_message
+
+                message_content = _build_native_multimodal_message("", str(msg_text or ""), attachments, str(workspace), cfg=cfg)
+            except Exception:
+                logger.debug("Failed to build gateway multimodal attachment payload", exc_info=True)
+                message_content = str(msg_text or "")
+        body = {
+            "model": model or "default",
+            "stream": True,
+            "messages": [*prefill_messages, {"role": "user", "content": message_content}],
+        }
+        if model_provider:
+            body["provider"] = model_provider
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        update_active_run(stream_id, phase="gateway-request")
+        last_payload = {}
+        sse_event = "message"
+        with urllib.request.urlopen(req, timeout=600) as resp:
+            for raw_line in resp:
+                if cancel_event.is_set():
+                    put_gateway_event("cancel", {"message": "Cancelled by user"})
+                    return
+                line = raw_line.decode("utf-8", errors="replace").strip()
+                if not line:
+                    sse_event = "message"
+                    continue
+                if line.startswith("event:"):
+                    sse_event = line[6:].strip() or "message"
+                    continue
+                if not line.startswith("data:"):
+                    continue
+                data = line[5:].strip()
+                if data == "[DONE]":
+                    break
+                try:
+                    payload = json.loads(data)
+                except json.JSONDecodeError:
+                    continue
+                if sse_event == "hermes.tool.progress":
+                    translated = _gateway_tool_progress_event(payload)
+                    if translated:
+                        event_name, event_payload = translated
+                        if stream_id in STREAM_LIVE_TOOL_CALLS:
+                            if event_name == "tool":
+                                STREAM_LIVE_TOOL_CALLS[stream_id].append({
+                                    "name": event_payload.get("name"),
+                                    "args": event_payload.get("args") or {},
+                                    "done": False,
+                                    **({"tid": event_payload.get("tid")} if event_payload.get("tid") else {}),
+                                })
+                            else:
+                                for shared_tc in reversed(STREAM_LIVE_TOOL_CALLS[stream_id]):
+                                    if shared_tc.get("done"):
+                                        continue
+                                    if (
+                                        event_payload.get("tid") and shared_tc.get("tid") == event_payload.get("tid")
+                                    ) or shared_tc.get("name") == event_payload.get("name"):
+                                        shared_tc["done"] = True
+                                        shared_tc["is_error"] = bool(event_payload.get("is_error"))
+                                        break
+                        put_gateway_event(event_name, event_payload)
+                        update_active_run(stream_id, phase="gateway-tool", latest_tool=event_payload.get("name"))
+                    sse_event = "message"
+                    continue
+                last_payload = payload
+                delta = _gateway_sse_delta(payload)
+                if delta:
+                    final_text += delta
+                    if stream_id in STREAM_PARTIAL_TEXT:
+                        STREAM_PARTIAL_TEXT[stream_id] += delta
+                    put_gateway_event("token", {"text": delta})
+                usage.update({k: v for k, v in _gateway_stream_usage(payload).items() if v})
+        usage.update({k: v for k, v in _gateway_stream_usage(last_payload).items() if v})
+        assistant_text = final_text.strip()
+        if not assistant_text:
+            put_gateway_event("apperror", {
+                "label": "Gateway returned no response",
+                "type": "gateway_empty_response",
+                "message": "Gateway returned no assistant message for this turn.",
+                "hint": "Check that Hermes Gateway API server is running and reachable.",
+            })
+            return
+        with _get_session_agent_lock(session_id):
+            s = get_session(session_id)
+            if not _stream_writeback_is_current(s, stream_id):
+                return
+            now = time.time()
+            # Preserve subsecond ordering for gateway-backed turns. Using an
+            # integer seconds timestamp gives the user and assistant rows the
+            # same sort key; later transcript merges can then fall back to
+            # role/content ordering instead of turn order.
+            assistant_ts = now + 0.000001
+            user_msg = {"role": "user", "content": str(msg_text or ""), "timestamp": now}
+            if attachments:
+                user_msg["attachments"] = list(attachments)
+            assistant_msg = {"role": "assistant", "content": assistant_text, "timestamp": assistant_ts}
+            previous_context = list(getattr(s, "context_messages", None) or getattr(s, "messages", None) or [])
+            s.context_messages = previous_context + [user_msg, assistant_msg]
+            try:
+                from api.streaming import _is_context_compression_marker
+
+                display_context = [
+                    msg
+                    for msg in previous_context
+                    if not _is_context_compression_marker(msg)
+                ]
+            except Exception:
+                logger.debug("Failed to filter gateway display context markers", exc_info=True)
+                display_context = previous_context
+            display = merge_session_messages_append_only(
+                list(getattr(s, "messages", None) or []),
+                display_context,
+            )
+            try:
+                from api.streaming import _merge_display_messages_after_agent_result
+
+                s.messages = _merge_display_messages_after_agent_result(
+                    display,
+                    previous_context,
+                    s.context_messages,
+                    str(msg_text or ""),
+                )
+            except Exception:
+                logger.debug("Failed to merge gateway display transcript", exc_info=True)
+                # Avoid duplicating the eager-save checkpointed user message.
+                if display:
+                    latest = display[-1]
+                    if isinstance(latest, dict) and latest.get("role") == "user":
+                        latest_text = " ".join(str(latest.get("content") or "").split())
+                        msg_norm = " ".join(str(msg_text or "").split())
+                        if latest_text == msg_norm:
+                            display = display[:-1]
+                s.messages = display + [user_msg, assistant_msg]
+            s.active_stream_id = None
+            s.pending_user_message = None
+            s.pending_attachments = None
+            s.pending_started_at = None
+            s.workspace = str(workspace)
+            s.model = model
+            s.model_provider = model_provider
+            s.save()
+        gateway_session_payload = s.compact() | {"messages": s.messages, "tool_calls": []}
+        put_gateway_event("done", {"session": redact_session_data(gateway_session_payload), "usage": usage})
+        put_gateway_event("stream_end", {"session_id": session_id})
+    except urllib.error.HTTPError as exc:
+        try:
+            err_body = exc.read(2048).decode("utf-8", errors="replace")
+        except Exception:
+            err_body = ""
+        put_gateway_event(
+            "apperror",
+            _gateway_http_error_event(exc, err_body, api_key_configured=bool(_gateway_api_key())),
+        )
+    except Exception as exc:
+        safe = _redact_text(str(exc))[:500]
+        put_gateway_event("apperror", {
+            "label": "Gateway request failed",
+            "type": "gateway_error",
+            "message": safe or "Gateway request failed.",
+            "hint": "Check HERMES_WEBUI_GATEWAY_BASE_URL and Gateway API server health.",
+        })
+    finally:
+        if s is not None:
+            try:
+                with _get_session_agent_lock(session_id):
+                    _clear_gateway_pending_state(get_session(session_id), stream_id)
+            except Exception:
+                logger.debug("Failed to clear gateway stream state", exc_info=True)
+        with STREAMS_LOCK:
+            CANCEL_FLAGS.pop(stream_id, None)
+            STREAM_PARTIAL_TEXT.pop(stream_id, None)
+            STREAM_REASONING_TEXT.pop(stream_id, None)
+            STREAM_LIVE_TOOL_CALLS.pop(stream_id, None)
+            STREAM_LAST_EVENT_ID.pop(stream_id, None)
+            STREAMS.pop(stream_id, None)
+        unregister_active_run(stream_id)

api/gateway_watcher.py

@@ -16,9 +16,11 @@ import queue
 import sqlite3
 import threading
 import time
+from contextlib import closing
 from pathlib import Path
 
 from api.config import HOME
+from api.agent_sessions import read_importable_agent_session_rows
 
 logger = logging.getLogger(__name__)
 
@@ -34,6 +36,113 @@ def _snapshot_hash(sessions: list) -> str:
     return hashlib.md5(key.encode(), usedforsecurity=False).hexdigest()
 
 
+# Sources excluded from the WebUI sidebar projection. Must match the default
+# ``exclude_sources`` used by ``read_importable_agent_session_rows`` so the
+# cheap change-detection scan below sees exactly the same row set as the
+# expensive projection (otherwise cron message churn would defeat the gate).
+_WATCHER_EXCLUDED_SOURCES = ("cron", "webui")
+
+
+def _cheap_change_fingerprint(db_path: Path) -> str | None:
+    """Compute a cheap change-detection fingerprint without the messages JOIN.
+
+    The expensive projection (``read_importable_agent_session_rows``) runs a CTE
+    plus a per-session ``MAX(messages.timestamp)`` aggregation over an oversampled
+    candidate set every poll. On a large ``state.db`` (hundreds of sessions, tens
+    of thousands of messages) that is ~10x the cost of a single ``sessions``-table
+    scan, and the watcher runs it forever on a 5s timer even when nothing changed
+    (issue #3506).
+
+    This computes a fingerprint from a ``sessions``-table-only scan (no messages
+    JOIN), scoped to the same non-cron/webui rows as the projection. To guarantee
+    it never skips a change the projection would reflect, it hashes **every
+    sessions-table column the projection reads or uses for visibility/collapse**
+    -- not just the columns surfaced to the sidebar. That matters because the
+    projection collapses compression lineage and hides/shows rows based on
+    ``parent_session_id`` / ``ended_at`` / ``end_reason`` / ``source``, so a change
+    to one of those alters *which rows* appear even when no displayed field on a
+    given row moved.
+
+    The one projection input that does not live in the ``sessions`` table is the
+    per-session message aggregate (``COUNT`` / ``MAX(messages.timestamp)`` ->
+    ``last_activity``). That is fully proxied by ``sessions.message_count``: the
+    agent's state layer bumps ``message_count`` on every appended message and
+    rewrites it to the absolute count on truncate/rewind/compaction, so a message
+    insert or delete (the only events that can move ``MAX(timestamp)``) always
+    changes ``message_count``. The fingerprint is therefore a strict superset of
+    the projection's change surface (it also fires on out-of-order inserts that
+    would not raise ``MAX(timestamp)``).
+
+    Returns the fingerprint string, or ``None`` on any error / a pre-source
+    schema so the caller falls back to running the expensive projection rather
+    than risk skipping a change.
+    """
+    # Columns the projection reads from the ``sessions`` table. ``id``/``source``
+    # are always present (``source`` is required for the projection to run at
+    # all); the rest are optional on older agent schemas and filtered below.
+    _PROJECTION_SESSION_COLS = (
+        'id', 'source', 'session_source', 'title', 'model', 'message_count',
+        'started_at', 'ended_at', 'end_reason', 'parent_session_id', 'archived',
+        'user_id', 'chat_id', 'chat_type', 'thread_id', 'session_key',
+        'origin_chat_id', 'origin_user_id', 'platform',
+    )
+    try:
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            cur = conn.cursor()
+            cur.execute("PRAGMA table_info(sessions)")
+            cols = {row[1] for row in cur.fetchall()}
+            if 'source' not in cols:
+                return None
+            selectable = [c for c in _PROJECTION_SESSION_COLS if c in cols]
+            placeholders = ", ".join("?" for _ in _WATCHER_EXCLUDED_SOURCES)
+            cur.execute(
+                f"SELECT {', '.join(selectable)} FROM sessions "
+                f"WHERE source IS NOT NULL AND source NOT IN ({placeholders}) "
+                f"ORDER BY id",
+                list(_WATCHER_EXCLUDED_SOURCES),
+            )
+            h = hashlib.md5(usedforsecurity=False)
+            for row in cur.fetchall():
+                h.update(repr(row).encode('utf-8', 'replace'))
+                h.update(b'\x1e')
+            # A same-count transcript rewrite (SessionDB.replace_messages used by
+            # /retry, /undo, /compress) deletes + reinserts messages with new
+            # timestamps but can leave sessions.message_count unchanged — so the
+            # sessions-only scan above would miss it and the watcher would skip a
+            # projection whose last_activity (MAX(messages.timestamp)) actually
+            # moved. Fold in a PER-SESSION message aggregate, scoped to the same
+            # non-excluded sessions as the projection. It must be per-session
+            # (grouped), NOT a single global MAX: rewriting an OLDER, non-newest
+            # session moves that session's last_activity but not the global max,
+            # so a global aggregate would still miss it (#3536 review round 2).
+            # cron/webui churn is excluded by the JOIN filter so it still does
+            # NOT trigger a re-projection. This is one GROUP BY over the already-
+            # filtered set — far cheaper than the projection's oversampled
+            # correlated CTE — so it preserves the cheap-fingerprint property.
+            if 'messages' in {r[0] for r in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'").fetchall()}:
+                try:
+                    msg_rows = conn.execute(
+                        "SELECT s.id, COUNT(m.id), "
+                        "COUNT(CASE WHEN LOWER(m.role) = 'user' THEN 1 END), "
+                        "COALESCE(MAX(m.timestamp), 0) "
+                        "FROM sessions s LEFT JOIN messages m ON m.session_id = s.id "
+                        f"WHERE s.source IS NOT NULL AND s.source NOT IN ({placeholders}) "
+                        "GROUP BY s.id ORDER BY s.id",
+                        list(_WATCHER_EXCLUDED_SOURCES),
+                    ).fetchall()
+                    for mrow in msg_rows:
+                        h.update(repr(mrow).encode('utf-8', 'replace'))
+                        h.update(b'\x1e')
+                except sqlite3.Error:
+                    # messages table shape unknown → don't trust the fingerprint;
+                    # signal the caller to run the full projection.
+                    return None
+            return h.hexdigest()
+    except Exception:
+        return None
+
+
 # ── DB resolution (shared pattern with state_sync.py) ──────────────────────
 
 def _get_state_db_path() -> Path:
@@ -55,33 +164,21 @@ def _get_agent_sessions_from_db() -> list:
         return []
 
     try:
-        with sqlite3.connect(str(db_path)) as conn:
-            conn.row_factory = sqlite3.Row
-            cur = conn.cursor()
-            cur.execute("""
-                SELECT s.id, s.title, s.model, s.message_count,
-                       s.started_at, s.source,
-                       MAX(m.timestamp) AS last_activity
-                FROM sessions s
-                LEFT JOIN messages m ON m.session_id = s.id
-                WHERE s.source IS NOT NULL AND s.source != 'webui'
-                GROUP BY s.id
-                HAVING COUNT(m.id) > 0
-                ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC
-                LIMIT 200
-            """)
-            sessions = []
-            for row in cur.fetchall():
-                sessions.append({
-                    'session_id': row['id'],
-                    'title': row['title'] or 'Agent Session',
-                    'model': row['model'] or None,
-                    'message_count': row['message_count'] or 0,
-                    'created_at': row['started_at'],
-                    'updated_at': row['last_activity'] or row['started_at'],
-                    'source': row['source'] or 'cli',
-                })
-            return sessions
+        sessions = []
+        for row in read_importable_agent_session_rows(db_path, limit=200, log=logger):
+            sessions.append({
+                'session_id': row['id'],
+                'title': row['title'] or 'Agent Session',
+                'model': row['model'] or None,
+                'message_count': row['message_count'] or row['actual_message_count'] or 0,
+                'created_at': row['started_at'],
+                'updated_at': row['last_activity'] or row['started_at'],
+                'source': row['source'] or 'cli',
+                'raw_source': row.get('raw_source'),
+                'session_source': row.get('session_source'),
+                'source_label': row.get('source_label'),
+            })
+        return sessions
     except Exception:
         return []
 
@@ -110,6 +207,10 @@ class GatewayWatcher:
         self._thread: threading.Thread | None = None
         self._last_hash: str = ''
         self._last_sessions: list = []
+        # Cheap sessions-only fingerprint from the previous poll. When it is
+        # unchanged we skip the expensive messages-JOIN projection entirely
+        # (issue #3506). Empty string forces the first poll to run the full read.
+        self._last_cheap_fp: str = ''
 
     def start(self):
         """Start the watcher daemon thread."""
@@ -195,13 +296,30 @@ class GatewayWatcher:
         """Main polling loop. Runs in a daemon thread."""
         while not self._stop_event.is_set():
             try:
-                sessions = _get_agent_sessions_from_db()
-                current_hash = _snapshot_hash(sessions)
+                # Phase 1: cheap sessions-only fingerprint. The expensive
+                # messages-JOIN projection (_get_agent_sessions_from_db) only
+                # runs when this fingerprint actually changes, so an idle server
+                # with a large state.db stops re-aggregating tens of thousands
+                # of message rows every 5 seconds (issue #3506). A None
+                # fingerprint (error / unreadable db) forces the full read so we
+                # never silently skip a real change.
+                db_path = _get_state_db_path()
+                cheap_fp = _cheap_change_fingerprint(db_path) if db_path.exists() else ''
+                if cheap_fp is not None and cheap_fp == self._last_cheap_fp:
+                    # Nothing changed in the sidebar-visible session set; skip
+                    # the expensive projection and the notify entirely.
+                    pass
+                else:
+                    # Phase 2: only now pay for the full projection.
+                    sessions = _get_agent_sessions_from_db()
+                    current_hash = _snapshot_hash(sessions)
+                    if cheap_fp is not None:
+                        self._last_cheap_fp = cheap_fp
 
-                if current_hash != self._last_hash:
-                    self._last_hash = current_hash
-                    self._last_sessions = sessions
-                    self._notify_subscribers(sessions)
+                    if current_hash != self._last_hash:
+                        self._last_hash = current_hash
+                        self._last_sessions = sessions
+                        self._notify_subscribers(sessions)
             except Exception:
                 logger.debug("Error in gateway watcher poll loop", exc_info=True)
 

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,10 +2,27 @@
 Hermes Web UI -- HTTP helper functions.
 """
 import json as _json
+import logging
+import os
 import re as _re
+import ssl
 from pathlib import Path
 from api.config import IMAGE_EXTS, MD_EXTS
 
+logger = logging.getLogger(__name__)
+
+
+# Treat stalled/closed HTTP clients as normal disconnects.  Long-lived SSE
+# connections often end this way when a browser tab sleeps, a phone switches
+# networks, or Tailscale leaves the socket half-closed.
+_CLIENT_DISCONNECT_ERRORS = (
+    BrokenPipeError,
+    ConnectionResetError,
+    ConnectionAbortedError,
+    TimeoutError,
+    ssl.SSLError,
+)
+
 
 def require(body: dict, *fields) -> None:
     """Phase D: Validate required fields. Raises ValueError with clean message."""
@@ -35,25 +52,115 @@ def safe_resolve(root: Path, requested: str) -> Path:
     return resolved
 
 
+_CSP_CONNECT_BASE = (
+    "'self' http://127.0.0.1:* http://localhost:* http://ipc.localhost "
+    "ws://127.0.0.1:* ws://localhost:*"
+)
+_CSP_EXTRA_CONNECT_RE = _re.compile(
+    r"^(?:https?|wss?)://(?:\*\.)?[A-Za-z0-9._~-]+(?::(?P<port>\d{1,5}|\*))?$"
+)
+_CSP_HEADER_NAME = 'Content-Security-Policy'
+_CSP_SHARED_POLICY_TEMPLATE = (
+    "default-src 'self' https://*.cloudflareaccess.com; "
+    "object-src 'none'; "
+    "frame-ancestors 'none'; "
+    "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://static.cloudflareinsights.com blob:; "
+    "worker-src blob: 'self' https://cdn.jsdelivr.net; "
+    "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; "
+    "img-src 'self' data: https: blob:; "
+    "font-src 'self' data: https://fonts.gstatic.com; "
+    "media-src 'self' data: blob:; "
+    "connect-src {connect_src}; "
+    "manifest-src 'self' https://*.cloudflareaccess.com; "
+    "base-uri 'self'; form-action 'self'"
+)
+
+
+def _valid_csp_extra_connect_source(source: str) -> bool:
+    match = _CSP_EXTRA_CONNECT_RE.fullmatch(source)
+    if not match:
+        return False
+    port = match.group("port")
+    if not port or port == "*":
+        return True
+    try:
+        return 1 <= int(port) <= 65535
+    except ValueError:
+        return False
+
+
+def _csp_extra_connect_src() -> str:
+    raw = os.getenv("HERMES_WEBUI_CSP_CONNECT_EXTRA", "").strip()
+    if not raw:
+        return ""
+    sources = raw.split()
+    if not sources or any(not _valid_csp_extra_connect_source(src) for src in sources):
+        logger.warning("Ignoring invalid HERMES_WEBUI_CSP_CONNECT_EXTRA value")
+        return ""
+    return " " + " ".join(sources)
+
+
+def _csp_connect_src(extra_connect_src: str = "") -> str:
+    return f"{_CSP_CONNECT_BASE} https://cdn.jsdelivr.net{extra_connect_src}"
+
+
+def _build_csp_enforced_policy(extra_connect_src: str | None = None) -> str:
+    if extra_connect_src is None:
+        extra_connect_src = _csp_extra_connect_src()
+    return _CSP_SHARED_POLICY_TEMPLATE.format(
+        connect_src=_csp_connect_src(extra_connect_src)
+    )
+
+
+def _build_csp_report_only_policy(extra_connect_src: str | None = None) -> str:
+    return (
+        _build_csp_enforced_policy(extra_connect_src)
+        + "; report-uri /api/csp-report; report-to csp-endpoint"
+    )
+
+
 def _security_headers(handler):
     """Add security headers to every response."""
+    extra_connect_src = _csp_extra_connect_src()
+    handler._csp_extra_connect_src = extra_connect_src
     handler.send_header('X-Content-Type-Options', 'nosniff')
     handler.send_header('X-Frame-Options', 'DENY')
     handler.send_header('Referrer-Policy', 'same-origin')
-    handler.send_header(
-        'Content-Security-Policy',
-        "default-src 'self'; "
-        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
-        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
-        "img-src 'self' data: https: blob:; font-src 'self' data: https://cdn.jsdelivr.net; connect-src 'self'; "
-        "base-uri 'self'; form-action 'self'"
-    )
+    handler.send_header(_CSP_HEADER_NAME, _build_csp_enforced_policy(extra_connect_src))
     handler.send_header(
         'Permissions-Policy',
-        'camera=(), microphone=(self), geolocation=()'
+        'camera=(), microphone=(self), geolocation=(), clipboard-write=(self)'
     )
 
 
+def _accepts_gzip(handler) -> bool:
+    """Check if the client accepts gzip encoding."""
+    headers = getattr(handler, 'headers', None)
+    if not headers:
+        return False
+    ae = headers.get('Accept-Encoding', '')
+    return 'gzip' in ae
+
+
+def _safe_write(handler, body: bytes) -> None:
+    """Write response body, ignoring expected client disconnect errors.
+
+    Logs disconnects at debug level so they are observable without
+    polluting stdout/stderr during normal operation (SSE reconnects,
+    tab closes, mobile network switches, etc.).
+    """
+    try:
+        handler.end_headers()
+        handler.wfile.write(body)
+    except _CLIENT_DISCONNECT_ERRORS as exc:
+        import logging
+        logging.getLogger("hermes.webui").debug(
+            "Client disconnected mid-response (%s): %s",
+            type(exc).__name__,
+            getattr(handler, "path", "?"),
+        )
+
+
 def j(handler, payload, status: int=200, extra_headers: dict=None) -> None:
     """Send a JSON response.
 
@@ -63,14 +170,22 @@ def j(handler, payload, status: int=200, extra_headers: dict=None) -> None:
     body = _json.dumps(payload, ensure_ascii=False, indent=2).encode('utf-8')
     handler.send_response(status)
     handler.send_header('Content-Type', 'application/json; charset=utf-8')
+
+    # Gzip-compress responses over 1KB when the client accepts it.
+    # Typical JSON API responses compress 70-80%, giving a big speedup
+    # for large payloads (session history, message lists).
+    if _accepts_gzip(handler) and len(body) > 1024:
+        import gzip
+        body = gzip.compress(body, compresslevel=4)
+        handler.send_header('Content-Encoding', 'gzip')
+
     handler.send_header('Content-Length', str(len(body)))
     handler.send_header('Cache-Control', 'no-store')
     _security_headers(handler)
     if extra_headers:
         for k, v in extra_headers.items():
             handler.send_header(k, v)
-    handler.end_headers()
-    handler.wfile.write(body)
+    _safe_write(handler, body)
 
 
 def t(handler, payload, status: int=200, content_type: str='text/plain; charset=utf-8') -> None:
@@ -81,8 +196,7 @@ def t(handler, payload, status: int=200, content_type: str='text/plain; charset=
     handler.send_header('Content-Length', str(len(body)))
     handler.send_header('Cache-Control', 'no-store')
     _security_headers(handler)
-    handler.end_headers()
-    handler.wfile.write(body)
+    _safe_write(handler, body)
 
 
 MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
@@ -91,14 +205,11 @@ MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
 # ── Credential redaction ──────────────────────────────────────────────────────
 
 def _build_redact_fn():
-    """Return redact_sensitive_text from hermes-agent if available, else a fallback."""
-    try:
-        from agent.redact import redact_sensitive_text
-        return redact_sensitive_text
-    except ImportError:
-        pass
-
-    # Minimal fallback covering the most common credential prefixes
+    """Return a redactor backed by hermes-agent plus local fallback patterns."""
+    # 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(
         r"(?<![A-Za-z0-9_-])("
         r"sk-[A-Za-z0-9_-]{10,}"          # OpenAI / Anthropic / OpenRouter
@@ -108,10 +219,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)
@@ -137,43 +272,218 @@ def _build_redact_fn():
         text = _PRIVKEY_RE.sub("[REDACTED PRIVATE KEY]", text)
         return text
 
-    return _fallback_redact
+    try:
+        from agent.redact import redact_sensitive_text
+    except ImportError:
+        return _fallback_redact
+
+    def _combined_redact(text: str) -> str:
+        if not isinstance(text, str) or not text:
+            return text
+        # WebUI API responses are a hard safety boundary — pass force=True so the
+        # agent's broader patterns (Stripe sk_live_, Google AIza…, JWT eyJ…, DB
+        # connection strings, Telegram bot tokens) run regardless of the user's
+        # HERMES_REDACT_SECRETS opt-in. The local fallback then handles the
+        # common short-prefix shapes the agent omits (ghp_, sk-, hf_, AKIA).
+        try:
+            agent_redacted = redact_sensitive_text(text, force=True)
+        except TypeError:
+            # Older hermes-agent builds that predate the force kwarg.
+            agent_redacted = redact_sensitive_text(text)
+        return _fallback_redact(agent_redacted)
+
+    return _combined_redact
 
 
-_redact_text = _build_redact_fn()
+_redact_fn_cached = _build_redact_fn()
 
 
-def _redact_value(v):
-    """Recursively redact credentials from strings, dicts, and lists."""
+_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.
+
+    The ``_enabled`` parameter is an internal optimization for callers that
+    redact many strings in a single response — `redact_session_data()` reads
+    the setting once and threads it through ``_redact_value`` so we avoid
+    re-loading settings.json from disk per string. (Opus pre-release perf fix.)
+    """
+    if not isinstance(text, str) or not text:
+        return text
+    if _enabled is None:
+        from api.config import load_settings
+        _enabled = bool(load_settings().get("api_redact_enabled", True))
+    if not _enabled:
+        return text
+    if not _might_contain_sensitive_text(text):
+        return text
+    return _redact_fn_cached(text)
+
+
+def _redact_value(v, *, _enabled: bool | None = None):
+    """Recursively redact credentials from strings, dicts, and lists.
+
+    ``_enabled`` is threaded through so a single response-level redact pass
+    only reads settings.json once. (Opus pre-release perf fix.)
+    """
     if isinstance(v, str):
-        return _redact_text(v)
+        return _redact_text(v, _enabled=_enabled)
     if isinstance(v, dict):
-        return {k: _redact_value(val) for k, val in v.items()}
+        return {k: _redact_value(val, _enabled=_enabled) for k, val in v.items()}
     if isinstance(v, list):
-        return [_redact_value(item) for item in v]
+        return [_redact_value(item, _enabled=_enabled) for item in v]
     return v
 
 
 def redact_session_data(session_dict: dict) -> dict:
-    """Redact credentials from message content and tool_call data before API response.
+    """Redact credentials from message content, tool data, and session sidecars.
 
-    Applies to: messages[], tool_calls[], and title.
+    Applies to: messages[], tool_calls[], todo_state, runtime_journal_snapshot,
+    and title.
     The underlying session file is not modified; redaction is response-layer only.
+
+    Reads the ``api_redact_enabled`` setting ONCE for the entire response and
+    threads it through to avoid hundreds of settings.json reads per session
+    payload (a 50-message session has hundreds of nested strings). When the
+    setting is disabled this is also a fast path: the recursion still walks
+    but every string returns early.
     """
+    from api.config import load_settings
+    _enabled = bool(load_settings().get("api_redact_enabled", True))
     result = dict(session_dict)
     if isinstance(result.get('title'), str):
-        result['title'] = _redact_text(result['title'])
+        result['title'] = _redact_text(result['title'], _enabled=_enabled)
     if 'messages' in result:
-        result['messages'] = _redact_value(result['messages'])
+        result['messages'] = _redact_value(result['messages'], _enabled=_enabled)
     if 'tool_calls' in result:
-        result['tool_calls'] = _redact_value(result['tool_calls'])
+        result['tool_calls'] = _redact_value(result['tool_calls'], _enabled=_enabled)
+    if 'todo_state' in result:
+        result['todo_state'] = _redact_value(result['todo_state'], _enabled=_enabled)
+    if 'runtime_journal_snapshot' in result:
+        result['runtime_journal_snapshot'] = _redact_value(
+            result['runtime_journal_snapshot'],
+            _enabled=_enabled,
+        )
     return result
 
 
 def read_body(handler) -> dict:
     """Read and JSON-parse a POST request body (capped at 20MB)."""
-    length = int(handler.headers.get('Content-Length', 0))
+    raw_length = handler.headers.get('Content-Length', 0)
+    try:
+        length = int(raw_length)
+    except (TypeError, ValueError):
+        try:
+            handler.close_connection = True
+        except Exception:
+            pass
+        raise ValueError(f'Invalid Content-Length: {raw_length!r}')
+    if length < 0:
+        try:
+            handler.close_connection = True
+        except Exception:
+            pass
+        raise ValueError(f'Invalid Content-Length: {length}')
     if length > MAX_BODY_BYTES:
+        try:
+            handler.close_connection = True
+        except Exception:
+            pass
         raise ValueError(f'Request body too large ({length} bytes, max {MAX_BODY_BYTES})')
     raw = handler.rfile.read(length) if length else b'{}'
     try:
@@ -185,10 +495,47 @@ def read_body(handler) -> dict:
 # ── Profile cookie helpers (issue #798) ─────────────────────────────────────
 
 PROFILE_COOKIE_NAME = 'hermes_profile'
+_PROFILE_COOKIE_ENV = 'HERMES_WEBUI_PROFILE_COOKIE_NAME'
+_LEGACY_PROFILE_COOKIE_ENV = 'WEBUI_PROFILE_COOKIE_NAME'
+_legacy_profile_cookie_warned = False
+
+
+def get_profile_cookie_name() -> str:
+    """Return the cookie name used to persist the active WebUI profile.
+
+    Honours ``HERMES_WEBUI_PROFILE_COOKIE_NAME`` so multiple WebUI instances
+    sharing a hostname (different ports) can use distinct profile-cookie names
+    instead of trampling each other; browsers scope cookies by host, not
+    host+port (RFC 6265). The original ``WEBUI_PROFILE_COOKIE_NAME`` is still
+    honoured as a deprecated fallback (warned once per process, since this is
+    called on every request).
+    """
+    name = os.getenv(_PROFILE_COOKIE_ENV, '').strip()
+    if name:
+        return name
+    legacy = os.getenv(_LEGACY_PROFILE_COOKIE_ENV, '').strip()
+    if legacy:
+        global _legacy_profile_cookie_warned
+        if not _legacy_profile_cookie_warned:
+            logger.warning(
+                '%s is deprecated; use %s instead.',
+                _LEGACY_PROFILE_COOKIE_ENV,
+                _PROFILE_COOKIE_ENV,
+            )
+            _legacy_profile_cookie_warned = True
+        return legacy
+    return PROFILE_COOKIE_NAME
 
 
 def get_profile_cookie(handler) -> str | None:
-    """Extract the hermes_profile cookie value from the request, or None."""
+    """Extract and authenticate the active-profile cookie value.
+
+    When WebUI auth is enabled, the profile cookie is treated as an
+    authorization input for profile-scoped routes. Require it to be signed for
+    the current auth session so clients cannot forge ``hermes_profile`` to
+    impersonate another profile. In no-auth deployments, keep the historical
+    plain profile-name cookie behavior.
+    """
     cookie_header = handler.headers.get('Cookie', '')
     if not cookie_header:
         return None
@@ -198,30 +545,68 @@ def get_profile_cookie(handler) -> str | None:
         cookie.load(cookie_header)
     except _hc.CookieError:
         return None
-    morsel = cookie.get(PROFILE_COOKIE_NAME)
-    if morsel and morsel.value:
-        # Validate against profile-name pattern before trusting
-        from api.profiles import _PROFILE_ID_RE
-        val = morsel.value
-        if val == 'default' or _PROFILE_ID_RE.fullmatch(val):
-            return val
-    return None
+    cookie_name = get_profile_cookie_name()
+    morsel = cookie.get(cookie_name)
+    if not (morsel and morsel.value):
+        return None
+
+    from api.profiles import _PROFILE_ID_RE
+
+    def _valid_profile_name(val: str) -> bool:
+        return val == 'default' or bool(_PROFILE_ID_RE.fullmatch(val))
+
+    raw_val = morsel.value
+    try:
+        from api.auth import is_auth_enabled, parse_cookie, verify_profile_cookie_value
+        if is_auth_enabled():
+            val = verify_profile_cookie_value(raw_val, parse_cookie(handler))
+            return val if val and _valid_profile_name(val) else None
+    except Exception:
+        logger.warning("Failed to verify active profile cookie", exc_info=True)
+        return None
+
+    # No-auth mode: the cookie is a per-browser UI preference, not an authz
+    # boundary, so retain the legacy plain profile-name format.
+    return raw_val if _valid_profile_name(raw_val) else None
 
 
-def build_profile_cookie(name: str) -> str:
-    """Build a Set-Cookie header value for the hermes_profile cookie.
+def build_profile_cookie(name: str, handler=None) -> str:
+    """Build a Set-Cookie header value for the active-profile cookie.
 
-    name='default' clears the cookie (max-age=0).
-    Any other valid profile name sets it for the browser session.
-    httponly=True: the JS reads profile from /api/profile/active JSON, never
-    from document.cookie, so httponly exposure is unnecessary.
+    Always persist the selected profile in the cookie, including 'default'.
+    Clearing the cookie causes the backend to fall back to process-global
+    _active_profile, which can unexpectedly switch clients back to another
+    profile.
+
+    Set HttpOnly because the UI reads the active profile from
+    /api/profile/active JSON and does not need to access this cookie via
+    document.cookie.
     """
     import http.cookies as _hc
     cookie = _hc.SimpleCookie()
-    cookie[PROFILE_COOKIE_NAME] = '' if name == 'default' else name
-    cookie[PROFILE_COOKIE_NAME]['path'] = '/'
-    cookie[PROFILE_COOKIE_NAME]['httponly'] = True
-    cookie[PROFILE_COOKIE_NAME]['samesite'] = 'Lax'
-    if name == 'default':
-        cookie[PROFILE_COOKIE_NAME]['max-age'] = '0'
-    return cookie[PROFILE_COOKIE_NAME].OutputString()
+    cookie_name = get_profile_cookie_name()
+    value = name
+    # Guard against a future call site silently emitting an UNSIGNED profile
+    # cookie while auth is enabled (which a client could then... not forge, but
+    # it would weaken the binding). If auth is on we require a handler so the
+    # cookie is bound to the session. (#4023 Opus hardening.)
+    try:
+        from api.auth import is_auth_enabled
+        _auth_on = is_auth_enabled()
+    except Exception:
+        _auth_on = False
+    if _auth_on and handler is None:
+        raise RuntimeError("build_profile_cookie requires a request handler when auth is enabled (to bind the profile cookie to the session)")
+    if handler is not None:
+        try:
+            from api.auth import is_auth_enabled, parse_cookie, sign_profile_cookie_value
+            if is_auth_enabled():
+                value = sign_profile_cookie_value(name, parse_cookie(handler))
+        except Exception as exc:
+            logger.warning("Failed to sign active profile cookie", exc_info=True)
+            raise RuntimeError("could not sign active profile cookie") from exc
+    cookie[cookie_name] = value
+    cookie[cookie_name]['path'] = '/'
+    cookie[cookie_name]['httponly'] = True
+    cookie[cookie_name]['samesite'] = 'Lax'
+    return cookie[cookie_name].OutputString()

api/metering.py

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

api/oauth.py

@@ -0,0 +1,794 @@
+"""In-app OAuth flow implementations for onboarding.
+
+The browser receives only WebUI-local flow metadata (flow_id, user_code,
+verification_uri, high-level status). Provider device/auth codes and OAuth
+tokens stay server-side and are persisted to the active Hermes profile's
+``auth.json`` credential_pool.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import stat
+import threading
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Compatibility for older helper tests and self-heal code that import these.
+AUTH_JSON_PATH = Path.home() / ".hermes" / "auth.json"
+
+CODEX_ISSUER = "https://auth.openai.com"
+CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+CODEX_VERIFICATION_URI = f"{CODEX_ISSUER}/codex/device"
+CODEX_USER_CODE_URL = f"{CODEX_ISSUER}/api/accounts/deviceauth/usercode"
+CODEX_DEVICE_TOKEN_URL = f"{CODEX_ISSUER}/api/accounts/deviceauth/token"
+CODEX_TOKEN_URL = f"{CODEX_ISSUER}/oauth/token"
+CODEX_REDIRECT_URI = f"{CODEX_ISSUER}/deviceauth/callback"
+CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
+CODEX_FLOW_MAX_WAIT_SECONDS = 15 * 60
+
+_ALLOWED_ONBOARDING_OAUTH_PROVIDERS = {"openai-codex", "anthropic", "claude", "claude-code"}
+_ANTHROPIC_PROVIDER_ALIASES = {"anthropic", "claude", "claude-code"}
+_REJECTED_ONBOARDING_OAUTH_PROVIDERS = {
+    "nous",
+    "qwen-oauth",
+    "gemini-cli",
+    "google-gemini-cli",
+    "minimax",
+    "minimax-oauth",
+    "copilot",
+    "copilot-acp",
+}
+
+ANTHROPIC_CREDENTIAL_POLL_SECONDS = 5
+ANTHROPIC_FLOW_MAX_WAIT_SECONDS = 15 * 60
+ANTHROPIC_PUBLIC_LINK_ERROR = "Claude Code credential linking failed. Check server logs."
+
+_OAUTH_FLOWS: dict[str, dict[str, Any]] = {}
+_OAUTH_FLOWS_LOCK = threading.Lock()
+_ANTHROPIC_ENV_KEYS = ("ANTHROPIC_TOKEN", "ANTHROPIC_API_KEY")
+
+
+def _clear_process_anthropic_env_values() -> None:
+    """Clear Anthropic process env fallbacks under the streaming env lock."""
+    from api.streaming import _ENV_LOCK
+
+    with _ENV_LOCK:
+        for key in _ANTHROPIC_ENV_KEYS:
+            os.environ.pop(key, None)
+
+
+def resolve_runtime_provider_with_anthropic_env_lock(resolver, *args, **kwargs):
+    """Resolve runtime credentials under the Anthropic onboarding env lock.
+
+    Request paths must resolve Anthropic env fallbacks per outbound request,
+    not cache ANTHROPIC_TOKEN or ANTHROPIC_API_KEY across onboarding. Sharing
+    the process-env lock prevents a chat stream from observing one stale
+    Anthropic env value while onboarding has already cleared the other.
+    """
+    from api.streaming import _ENV_LOCK
+
+    with _ENV_LOCK:
+        return resolver(*args, **kwargs)
+
+
+def _normalize_onboarding_oauth_provider(provider: str) -> str:
+    """Normalize Anthropic aliases (claude, claude-code) to 'anthropic'; defaults to 'openai-codex' when blank."""
+    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:
+    """Return the active Hermes profile home directory, falling back to ~/.hermes when profile resolution fails."""
+    try:
+        from api.profiles import get_active_hermes_home
+
+        return Path(get_active_hermes_home())
+    except Exception as exc:
+        # Per Opus advisor on stage-296: log the silent fallback so a corrupt
+        # profile state ending up writing tokens to ~/.hermes (instead of the
+        # active profile) is observable in logs rather than failing silently.
+        logger.warning(
+            "Falling back to ~/.hermes for OAuth credential storage: "
+            "active-profile resolution failed: %s",
+            exc,
+        )
+        return Path.home() / ".hermes"
+
+
+# ── legacy auth.json helpers ────────────────────────────────────────────────
+
+def _read_auth_json(auth_path: Path | None = None) -> dict[str, Any]:
+    """Read auth.json and return parsed dict, or an empty compatible store."""
+    path = auth_path or AUTH_JSON_PATH
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+            return loaded if isinstance(loaded, dict) else {}
+        except json.JSONDecodeError as exc:
+            logger.warning("Failed to parse %s: %s", path, exc)
+            return {}
+    return {}
+
+
+def read_auth_json():
+    """Public wrapper for streaming credential self-heal code."""
+    return _read_auth_json()
+
+
+def _write_auth_json(data: dict[str, Any], auth_path: Path | None = None) -> Path:
+    """Atomically write auth.json with owner-only permissions.
+
+    OAuth access/refresh tokens live in this file. The temp file is chmod 0600
+    before rename so the final path never inherits a permissive process umask.
+    """
+    path = auth_path or AUTH_JSON_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex}")
+    try:
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        try:
+            tmp.chmod(0o600)
+        except OSError as exc:
+            logger.warning("Failed to chmod 0600 on %s: %s", tmp, exc)
+        tmp.replace(path)
+        try:
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+        return path
+    finally:
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+
+
+def _now_iso() -> str:
+    """Return the current UTC time as an ISO-8601 string ending in Z."""
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _persist_codex_credentials(hermes_home: Path, token_data: dict[str, Any]) -> Path:
+    """Persist Codex OAuth credentials to active-profile auth.json."""
+    access_token = str(token_data.get("access_token") or "").strip()
+    refresh_token = str(token_data.get("refresh_token") or "").strip()
+    if not access_token:
+        raise RuntimeError("Codex token exchange did not return an access_token")
+
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    auth.setdefault("version", 1)
+    pool = auth.setdefault("credential_pool", {})
+    if not isinstance(pool, dict):
+        pool = {}
+        auth["credential_pool"] = pool
+    entries = pool.setdefault("openai-codex", [])
+    if not isinstance(entries, list):
+        entries = []
+        pool["openai-codex"] = entries
+
+    now = _now_iso()
+    entry = None
+    # Per Opus advisor on stage-296: also accept the legacy `source ==
+    # "oauth_device"` value so users with prior Codex OAuth credentials
+    # (written by older WebUI versions before this PR's source-key change)
+    # get their existing entry updated in-place rather than accumulating a
+    # stale duplicate pool entry.
+    _accept_sources = {"manual:device_code", "oauth_device"}
+    for candidate in entries:
+        if isinstance(candidate, dict) and candidate.get("source") in _accept_sources:
+            entry = candidate
+            break
+    if entry is None:
+        entry = {
+            "id": "codex-oauth-" + uuid.uuid4().hex[:12],
+            "label": "Codex OAuth",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "manual:device_code",
+            "base_url": CODEX_BASE_URL,
+            "created_at": now,
+        }
+        entries.insert(0, entry)
+
+    entry.update(
+        {
+            "label": "Codex OAuth",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "manual:device_code",
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "base_url": CODEX_BASE_URL,
+            "last_refresh": now,
+            "updated_at": now,
+        }
+    )
+    auth["updated_at"] = now
+    path = _write_auth_json(auth, auth_path)
+
+    try:
+        from api.config import invalidate_credential_pool_cache
+
+        invalidate_credential_pool_cache("openai-codex")
+    except Exception:
+        logger.debug("Failed to invalidate openai-codex credential cache", exc_info=True)
+
+    return path
+
+
+# Backward-compatible wrapper used by older code/tests.
+def _save_codex_credentials(token_data):
+    """Backward-compatible wrapper: persist Codex OAuth tokens to the active-profile auth.json."""
+    return _persist_codex_credentials(_get_active_hermes_home(), token_data)
+
+
+# ── Anthropic / Claude Code credential linking ─────────────────────────────
+
+def _read_claude_code_credentials() -> dict[str, Any] | None:
+    """Read Claude Code OAuth credentials from the host without exposing them.
+
+    Delegates to the agent adapter which knows about ~/.claude/.credentials.json
+    and macOS Keychain. Returns the credential dict or None.
+    """
+    try:
+        from agent.anthropic_adapter import (
+            is_claude_code_token_valid,
+            read_claude_code_credentials,
+        )
+
+        creds = read_claude_code_credentials()
+        if creds and (
+            is_claude_code_token_valid(creds) or bool(creds.get("refreshToken"))
+        ):
+            return creds
+    except Exception as exc:
+        logger.debug("Could not read Claude Code credentials: %s", exc)
+    return None
+
+
+def _clear_anthropic_env_values(hermes_home: Path) -> None:
+    """Clear Anthropic API/setup-token env values in the active profile only.
+
+    The .env write path already clears os.environ while holding the streaming
+    env lock. Keep a locked process-env clear here too so import/write failures
+    cannot leave or partially clear stale Anthropic fallbacks.
+    """
+    try:
+        from api.providers import _write_env_file
+
+        _write_env_file(
+            Path(hermes_home) / ".env",
+            {key: None for key in _ANTHROPIC_ENV_KEYS},
+        )
+    except Exception as exc:
+        logger.warning("Failed to clear Anthropic env values: %s", exc)
+    _clear_process_anthropic_env_values()
+
+
+def _link_anthropic_credentials(hermes_home: Path) -> None:
+    """Link Hermes to use Claude Code's credential store.
+
+    Clears ANTHROPIC_TOKEN and ANTHROPIC_API_KEY from the Hermes .env so
+    that resolve_anthropic_token() falls through to reading Claude Code's
+    ~/.claude/.credentials.json directly — the same thing the CLI's
+    ``use_anthropic_claude_code_credentials()`` does.
+
+    Also writes a marker entry in auth.json credential_pool so that
+    ``_provider_oauth_authenticated("anthropic", ...)`` can detect the
+    linked state without touching the actual credential files.
+    """
+    _clear_anthropic_env_values(hermes_home)
+
+    # Write a pool marker (no secrets) so onboarding status can detect linkage.
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    auth.setdefault("version", 1)
+    pool = auth.setdefault("credential_pool", {})
+    if not isinstance(pool, dict):
+        pool = {}
+        auth["credential_pool"] = pool
+    entries = pool.setdefault("anthropic", [])
+    if not isinstance(entries, list):
+        entries = []
+        pool["anthropic"] = entries
+
+    now = _now_iso()
+    entry = None
+    for candidate in entries:
+        if isinstance(candidate, dict) and candidate.get("source") == "claude_code_linked":
+            entry = candidate
+            break
+    if entry is None:
+        entry = {
+            "id": "anthropic-claude-code-" + uuid.uuid4().hex[:12],
+            "label": "Claude Code (linked)",
+            "auth_type": "oauth",
+            "priority": 0,
+            "source": "claude_code_linked",
+            "created_at": now,
+        }
+        entries.insert(0, entry)
+
+    entry.update({
+        "label": "Claude Code (linked)",
+        "auth_type": "oauth",
+        "priority": 0,
+        "source": "claude_code_linked",
+        "updated_at": now,
+    })
+    auth["updated_at"] = now
+    _write_auth_json(auth, auth_path)
+
+    try:
+        from api.config import invalidate_credential_pool_cache
+        invalidate_credential_pool_cache("anthropic")
+    except Exception:
+        logger.debug("Failed to invalidate anthropic credential cache", exc_info=True)
+
+
+def _anthropic_public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    """Build the browser-safe start payload for an Anthropic credential-linking flow, omitting server-side secrets."""
+    payload: dict[str, Any] = {
+        "ok": True,
+        "provider": "anthropic",
+        "flow_id": flow_id,
+        "status": flow.get("status", "pending"),
+        "poll_interval_seconds": flow.get("poll_interval_seconds", ANTHROPIC_CREDENTIAL_POLL_SECONDS),
+    }
+    if flow.get("status") == "pending":
+        payload["action_required"] = (
+            "Claude Code credentials were not found on this server. "
+            "Please run 'claude login' or 'claude setup-token' in a terminal "
+            "on the host, then return here — this page will detect the credentials automatically."
+        )
+    if flow.get("expires_at"):
+        payload["expires_at"] = flow["expires_at"]
+    return payload
+
+
+def _anthropic_public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
+    """Build the browser-safe status payload for an Anthropic flow, replacing internal error with a safe string."""
+    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:
+    """Launch a daemon thread that polls for Claude Code credentials and transitions the Anthropic flow to success."""
+    worker = threading.Thread(
+        target=_run_anthropic_credential_worker, args=(flow_id,), daemon=True,
+    )
+    worker.start()
+
+
+def _run_anthropic_credential_worker(flow_id: str) -> None:
+    """Poll for Claude Code credential appearance until found, cancelled, or expired."""
+    while True:
+        with _OAUTH_FLOWS_LOCK:
+            flow = dict(_OAUTH_FLOWS.get(flow_id) or {})
+        if not flow:
+            return
+        if flow.get("status") != "pending":
+            return
+        if float(flow.get("expires_at") or 0) <= time.time():
+            _set_flow_status(flow_id, "expired")
+            return
+
+        time.sleep(max(1, int(flow.get("poll_interval_seconds") or ANTHROPIC_CREDENTIAL_POLL_SECONDS)))
+
+        # Re-check status under lock (cancel may have arrived during sleep)
+        with _OAUTH_FLOWS_LOCK:
+            live = _OAUTH_FLOWS.get(flow_id)
+            if not live or live.get("status") != "pending":
+                return
+
+        try:
+            creds = _read_claude_code_credentials()
+            if creds is None:
+                continue
+
+            # Re-check status under lock before linking — cancel must win
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if not current or current.get("status") != "pending":
+                    return
+
+            hermes_home = Path(flow["hermes_home"])
+            _link_anthropic_credentials(hermes_home)
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if not current or current.get("status") != "pending":
+                    cancelled = bool(current and current.get("status") == "cancelled")
+                else:
+                    current["status"] = "success"
+                    current["updated_at"] = time.time()
+                    _drop_sensitive_flow_fields(current)
+                    cancelled = False
+            if cancelled:
+                _remove_anthropic_link_marker(hermes_home)
+            return
+        except Exception as exc:
+            logger.warning("Anthropic credential polling failed: %s", exc)
+            with _OAUTH_FLOWS_LOCK:
+                current = _OAUTH_FLOWS.get(flow_id)
+                if current and current.get("status") == "pending":
+                    current["status"] = "error"
+                    current["updated_at"] = time.time()
+                    current["error"] = str(exc)
+                    _drop_sensitive_flow_fields(current)
+            return
+
+
+def _remove_anthropic_link_marker(hermes_home: Path) -> None:
+    """Remove the secret-free Claude Code linked marker after a cancelled race."""
+    auth_path = Path(hermes_home) / "auth.json"
+    auth = _read_auth_json(auth_path)
+    pool = auth.get("credential_pool")
+    if not isinstance(pool, dict):
+        return
+    entries = pool.get("anthropic")
+    if not isinstance(entries, list):
+        return
+    kept = [entry for entry in entries if not (isinstance(entry, dict) and entry.get("source") == "claude_code_linked")]
+    if len(kept) == len(entries):
+        return
+    if kept:
+        pool["anthropic"] = kept
+    else:
+        pool.pop("anthropic", None)
+    auth["updated_at"] = _now_iso()
+    _write_auth_json(auth, auth_path)
+    try:
+        from api.config import invalidate_credential_pool_cache
+        invalidate_credential_pool_cache("anthropic")
+    except Exception:
+        logger.debug("Failed to invalidate anthropic credential cache", exc_info=True)
+
+
+# ── Codex protocol ──────────────────────────────────────────────────────────
+
+def _json_request(url: str, payload: dict[str, Any], *, form: bool = False) -> dict[str, Any]:
+    """POST a JSON or form-encoded payload to url and return the parsed JSON response."""
+    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]:
+    """Request a new device-auth user code and device_auth_id from the Codex endpoint."""
+    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:
+    """Poll the Codex device token endpoint; returns None on 403/404 (not yet authorized) or raises otherwise."""
+    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]:
+    """Exchange a Codex authorization code and PKCE verifier for access/refresh tokens."""
+    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]:
+    """Build the browser-safe start payload for a Codex device-code flow, including user_code and verification_uri."""
+    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]:
+    """Build the browser-safe status payload for a Codex flow, capping error strings at 200 characters."""
+    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]:
+    """Dispatch to the provider-specific start payload builder based on flow['provider']."""
+    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]:
+    """Dispatch to the provider-specific status payload builder based on flow['provider']."""
+    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:
+    """Remove device codes, authorization codes, and token material from a flow dict in place."""
+    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:
+    """Expire pending flows past their deadline and purge terminal flows older than 300 seconds from memory."""
+    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:
+    """Launch a daemon thread that drives the Codex device-code polling and token exchange loop."""
+    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:
+    """Update a flow's status under the lock, then strip sensitive fields on terminal transitions."""
+    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:
+    """Drive the Codex device-code polling loop until the user authorizes, the flow cancels, or it expires."""
+    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]:
+    """Return the current browser-safe status for an in-flight OAuth flow, expiring it if past its deadline."""
+    _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]:
+    """Cancel a pending OAuth flow by flow_id and return the final status payload."""
+    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():
+    """Backward-compatible shim: start a Codex device-code flow via start_onboarding_oauth_flow."""
+    return start_onboarding_oauth_flow({"provider": "openai-codex"})
+
+
+def poll_codex_token(device_code, interval=5):
+    """Backward-compatible stub that always yields an error directing callers to the /api/onboarding/oauth/poll endpoint."""
+    yield {"status": "error", "error": "Use /api/onboarding/oauth/poll with flow_id"}

api/onboarding.py

@@ -2,8 +2,12 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import os
+import socket
+import urllib.error
+import urllib.request
 from pathlib import Path
 from urllib.parse import urlparse
 
@@ -23,12 +27,14 @@ from api.config import (
     save_settings,
     verify_hermes_imports,
 )
+from api.providers import _write_env_file  # shared impl with _ENV_LOCK (#1164)
 from api.workspace import get_last_workspace, load_workspaces
 
 logger = logging.getLogger(__name__)
 
 
 _SUPPORTED_PROVIDER_SETUPS = {
+    # ── Easy start ──────────────────────────────────────────────────────
     "openrouter": {
         "label": "OpenRouter",
         "env_var": "OPENROUTER_API_KEY",
@@ -37,6 +43,8 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "models": [
             {"id": model["id"], "label": model["label"]} for model in _FALLBACK_MODELS
         ],
+        "category": "easy_start",
+        "quick": True,
     },
     "anthropic": {
         "label": "Anthropic",
@@ -44,6 +52,9 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "default_model": "claude-sonnet-4.6",
         "requires_base_url": False,
         "models": list(_PROVIDER_MODELS.get("anthropic", [])),
+        "category": "easy_start",
+        "oauth_provider": "anthropic",
+        "oauth_label": "Claude Code OAuth",
     },
     "openai": {
         "label": "OpenAI",
@@ -52,19 +63,142 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "default_base_url": "https://api.openai.com/v1",
         "requires_base_url": False,
         "models": list(_PROVIDER_MODELS.get("openai", [])),
+        "category": "easy_start",
+    },
+    # ── Open / self-hosted ─────────────────────────────────────────────
+    "ollama": {
+        "label": "Ollama",
+        "env_var": "OLLAMA_API_KEY",
+        "default_model": "qwen3:32b",
+        "default_base_url": "http://localhost:11434/v1",
+        "requires_base_url": True,
+        # Local Ollama runs keyless by default — only Ollama Cloud requires
+        # OLLAMA_API_KEY.  The wizard accepts an empty api_key for this
+        # provider; users with auth enabled can still type one.  See #1499.
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
+    },
+    "lmstudio": {
+        "label": "LM Studio",
+        # Canonical env var matches the agent CLI runtime (hermes_cli/auth.py:182,
+        # api_key_env_vars=("LM_API_KEY",)).  Onboarding writes this name so the
+        # agent runtime actually picks up the key on the next chat — pre-#1499/#1500
+        # the WebUI wrote LMSTUDIO_API_KEY which the agent runtime ignored, masked
+        # in practice by the LMSTUDIO_NOAUTH_PLACEHOLDER fallback for keyless installs.
+        "env_var": "LM_API_KEY",
+        # Legacy env var written by older WebUI builds (≤ v0.50.272).  Detection
+        # paths (_provider_api_key_present here, _provider_has_key in providers.py)
+        # also read this name so existing users with the old key in their .env
+        # don't flip to "no key" in Settings → Providers after upgrading.
+        # Onboarding only writes the canonical name going forward.
+        "env_var_aliases": ["LMSTUDIO_API_KEY"],
+        "default_model": "gpt-4o-mini",
+        "default_base_url": "http://localhost:1234/v1",
+        "requires_base_url": True,
+        # Most LM Studio installs run keyless (LMSTUDIO_NOAUTH_PLACEHOLDER on the
+        # agent side handles this).  The wizard accepts an empty api_key; auth-
+        # enabled servers still need one but the user types it in the same field.
+        # See #1499 (third sub-bug from #1420).
+        "key_optional": True,
+        "models": [],
+        "category": "self_hosted",
     },
     "custom": {
         "label": "Custom OpenAI-compatible",
         "env_var": "OPENAI_API_KEY",
         "default_model": "gpt-4o-mini",
         "requires_base_url": True,
+        # Many self-hosted OpenAI-compatible servers (vLLM, llama-server,
+        # TabbyAPI, etc.) run keyless behind a private network.  The wizard
+        # accepts an empty api_key — auth-protected endpoints can still
+        # supply one.  See #1499.
+        "key_optional": True,
         "models": [],
+        "category": "self_hosted",
+    },
+    # ── Specialized / extended ──────────────────────────────────────────
+    "gemini": {
+        "label": "Google Gemini",
+        "env_var": "GOOGLE_API_KEY",
+        "default_model": "gemini-3.1-pro-preview",
+        "default_base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "requires_base_url": False,
+        # _PROVIDER_MODELS in api/config.py is keyed under "google" even though
+        # the agent's alias map normalizes "google" → "gemini".  Use the catalog
+        # key here so the wizard surfaces the actual model list.
+        "models": list(_PROVIDER_MODELS.get("google", [])),
+        "category": "specialized",
+    },
+    "deepseek": {
+        "label": "DeepSeek",
+        "env_var": "DEEPSEEK_API_KEY",
+        "default_model": "deepseek-v4-flash",
+        "default_base_url": "https://api.deepseek.com",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("deepseek", [])),
+        "category": "specialized",
+    },
+    "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",
+        "default_model": "glm-5.1",
+        "default_base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("zai", [])),
+        "category": "specialized",
+    },
+    "nvidia": {
+        "label": "NVIDIA NIM",
+        "env_var": "NVIDIA_API_KEY",
+        "default_model": "nvidia/llama-3.3-nemotron-super-49b-v1.5",
+        "default_base_url": "https://integrate.api.nvidia.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("nvidia", [])),
+        "category": "specialized",
+    },
+    "mistralai": {
+        "label": "Mistral",
+        "env_var": "MISTRAL_API_KEY",
+        "default_model": "mistral-large-latest",
+        "default_base_url": "https://api.mistral.ai/v1",
+        "requires_base_url": False,
+        # No catalog entry for mistralai today — wizard shows a free-text input.
+        "models": list(_PROVIDER_MODELS.get("mistralai", [])),
+        "category": "specialized",
+    },
+    "x-ai": {
+        "label": "xAI (Grok)",
+        "env_var": "XAI_API_KEY",
+        "default_model": "grok-4.20",
+        "default_base_url": "https://api.x.ai/v1",
+        "requires_base_url": False,
+        # Agent normalizes "x-ai" → "xai"; _PROVIDER_MODELS is also keyed "xai"
+        # when populated, so check both keys for forward-compatibility.
+        "models": list(_PROVIDER_MODELS.get("xai", []) or _PROVIDER_MODELS.get("x-ai", [])),
+        "category": "specialized",
     },
 }
 
+_PROVIDER_CATEGORIES = [
+    {"id": "easy_start", "label": "Easy start", "order": 0},
+    {"id": "self_hosted", "label": "Open / self-hosted", "order": 1},
+    {"id": "specialized", "label": "Specialized", "order": 2},
+]
+
 _UNSUPPORTED_PROVIDER_NOTE = (
-    "OAuth and advanced provider flows such as Nous Portal, OpenAI Codex, and GitHub "
-    "Copilot are still terminal-first. Use `hermes model` for those flows."
+    "Advanced provider flows such as Nous Portal and GitHub Copilot are still "
+    "terminal-first. OpenAI Codex and Anthropic Claude Code can be authenticated in this onboarding flow "
+    "when your Hermes config selects the corresponding provider."
 )
 
 
@@ -93,26 +227,6 @@ def _load_env_file(env_path: Path) -> dict[str, str]:
     return values
 
 
-def _write_env_file(env_path: Path, updates: dict[str, str]) -> None:
-    current = _load_env_file(env_path)
-    for key, value in updates.items():
-        if value is None:
-            current.pop(key, None)
-            os.environ.pop(key, None)
-            continue
-        clean = str(value).strip()
-        if not clean:
-            continue
-        # Reject embedded newlines/carriage returns to prevent .env injection
-        if "\n" in clean or "\r" in clean:
-            raise ValueError("API key must not contain newline characters.")
-        current[key] = clean
-        os.environ[key] = clean
-
-    env_path.parent.mkdir(parents=True, exist_ok=True)
-    lines = [f"{key}={current[key]}" for key in sorted(current)]
-    env_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
-
 
 def _load_yaml_config(config_path: Path) -> dict:
     try:
@@ -155,6 +269,260 @@ def _normalize_base_url(base_url: str) -> str:
     return (base_url or "").strip().rstrip("/")
 
 
+# ── Provider endpoint probe (#1499) ─────────────────────────────────────────
+
+# Probe error codes — stable strings the frontend can switch on for inline
+# error rendering.  Add new codes only by extending this set; never reuse.
+PROBE_ERROR_CODES = (
+    "invalid_url",       # base_url failed urlparse / scheme / host check
+    "dns",               # hostname did not resolve
+    "connect_refused",   # TCP RST on connect (server not listening)
+    "timeout",           # exceeded probe timeout
+    "http_4xx",          # endpoint returned 4xx (auth required, wrong path, …)
+    "http_5xx",          # endpoint returned 5xx (server-side fault)
+    "parse",             # body not JSON or not the OpenAI /models shape
+    "unreachable",       # other network / SSL / unknown error
+)
+
+PROBE_TIMEOUT_SECONDS = 5.0
+# OpenAI /models response can list dozens of entries on Ollama / LM Studio.
+# 256 KB is more than enough for any realistic catalog and bounds the worst
+# case for a hostile / mis-pointed endpoint that streams forever.
+PROBE_MAX_BYTES = 256 * 1024
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Refuse to follow HTTP redirects on the probe path.
+
+    `urllib.request.urlopen` follows redirects by default — without this
+    handler, a probe at `http://example.com/v1/models` could be redirected
+    to `http://internal-service:8080/admin`, surfacing internal HTTP services
+    to whatever the probe targets next.  The probe is already gated behind
+    WebUI auth and the local-network check, so the threat model is
+    "authenticated user enumerating internal services" — same as `curl`
+    from their browser DevTools.  Disabling redirects tightens defaults
+    without breaking any legitimate use case (a self-hosted /models endpoint
+    that 3xx-redirects is itself misconfigured).  Redirects surface to the
+    caller as `unreachable` (mapped from `HTTPError(3xx)` in the probe).
+    Reviewer-flagged in PR #1501 (#1499 + #1500).
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # tell urllib to NOT follow; raises HTTPError(3xx) instead
+
+
+_PROBE_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+_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(
+    provider: str,
+    base_url: str,
+    api_key: str | None = None,
+    timeout: float = PROBE_TIMEOUT_SECONDS,
+) -> dict:
+    """Probe `<base_url>/models` for a self-hosted OpenAI-compatible provider.
+
+    Used by the onboarding wizard to validate the user's configured base URL
+    before persisting (#1499).  Distinguishes failure modes so the frontend
+    can render a precise inline error instead of a generic "could not save."
+
+    Returns one of:
+
+      {"ok": True, "models": [{"id": "...", "label": "..."}, ...]}
+      {"ok": False, "error": "<code>", "detail": "<human string>"}
+
+    Where ``<code>`` is one of ``PROBE_ERROR_CODES``.
+
+    The probe is a single HTTP GET — no retries.  The timeout is short by
+    design: the wizard runs the probe synchronously on the user's submit
+    click, and we'd rather report "timeout" quickly than block the UI for
+    the kernel default ~75s.
+
+    The probe response is NOT persisted.  This function returns model IDs
+    so the wizard can populate its dropdown, but ``apply_onboarding_setup``
+    only writes the user's typed selection — never auto-pinning a stale
+    list of models to ``config.yaml``.
+
+    SSRF: ``base_url`` is whatever the user typed in the onboarding form.
+    The wizard is gated behind authentication (post-onboarding, the user
+    has already authenticated to the WebUI), and the legitimate target is
+    a local LM Studio / Ollama / vLLM server, so we deliberately do not
+    block private-IP ranges — that would make the feature useless.  The
+    risk surface is "authenticated user crafts a probe to enumerate
+    internal HTTP services," which is a different threat model from
+    unauthenticated SSRF.
+    """
+    base_url = _normalize_base_url(base_url)
+    if not base_url:
+        return {"ok": False, "error": "invalid_url", "detail": "base_url is required"}
+
+    parsed = urlparse(base_url)
+    if parsed.scheme not in {"http", "https"}:
+        return {
+            "ok": False,
+            "error": "invalid_url",
+            "detail": "base_url must start with http:// or https://",
+        }
+    if not parsed.hostname:
+        return {"ok": False, "error": "invalid_url", "detail": "base_url has no host"}
+
+    # Build the probe URL.  OpenAI-compatible servers expose /v1/models or
+    # /models.  Most users supply a base URL ending in /v1, so we just append
+    # /models to whatever they typed.  Strip the trailing slash and append
+    # rather than urljoin to avoid eating the /v1 segment when there's no
+    # trailing slash.
+    probe_url = f"{base_url}/models"
+
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": "hermes-webui-onboarding-probe",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    req = urllib.request.Request(probe_url, headers=headers, method="GET")
+
+    try:
+        with _PROBE_OPENER.open(req, timeout=timeout) as resp:
+            status = resp.status
+            body = resp.read(PROBE_MAX_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        # 3xx / 4xx / 5xx with a body — categorize.  3xx happens when the
+        # endpoint redirects (we refuse to follow on the probe path — see
+        # _NoRedirectHandler).  Map to `unreachable` rather than introducing a
+        # new error code, since a self-hosted /models endpoint that 3xx-
+        # redirects is itself misconfigured.
+        if 300 <= exc.code < 400:
+            code = "unreachable"
+            detail = (
+                f"HTTP {exc.code} — endpoint returned a redirect "
+                f"(probe does not follow redirects).  Point base_url at the "
+                f"final URL directly."
+            )
+            return {"ok": False, "error": code, "detail": detail, "status": exc.code}
+        code = "http_4xx" if 400 <= exc.code < 500 else "http_5xx"
+        # Try to surface a useful detail (LM Studio sometimes returns text/plain).
+        try:
+            err_body = exc.read(2048).decode("utf-8", errors="replace").strip()
+        except Exception:
+            err_body = ""
+        detail = f"HTTP {exc.code}"
+        if err_body:
+            err_first = err_body.splitlines()[0][:200]
+            detail = f"{detail}: {err_first}"
+        return {"ok": False, "error": code, "detail": detail, "status": exc.code}
+    except urllib.error.URLError as exc:
+        # Distinguish DNS / connect-refused / timeout / generic.
+        reason = exc.reason
+        if isinstance(reason, socket.timeout) or "timed out" in str(reason).lower():
+            return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
+        if _probe_failure_is_dns(reason, parsed.hostname):
+            return {
+                "ok": False,
+                "error": "dns",
+                "detail": f"could not resolve host '{parsed.hostname}'",
+            }
+        if isinstance(reason, ConnectionRefusedError) or "refused" in str(reason).lower():
+            port_hint = parsed.port or ("443" if parsed.scheme == "https" else "80")
+            return {
+                "ok": False,
+                "error": "connect_refused",
+                "detail": f"connection refused at {parsed.hostname}:{port_hint}",
+            }
+        return {"ok": False, "error": "unreachable", "detail": str(reason)[:200]}
+    except (TimeoutError, socket.timeout):
+        return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
+    except Exception as exc:  # pragma: no cover — defensive net
+        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]}
+
+    # If the response was huge, refuse to parse.  256 KB cap is generous;
+    # anything bigger is likely the user pointed us at the wrong service.
+    if len(body) > PROBE_MAX_BYTES:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": f"response exceeded {PROBE_MAX_BYTES // 1024} KB cap",
+        }
+
+    try:
+        payload = json.loads(body.decode("utf-8", errors="replace"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": f"response is not JSON ({exc.__class__.__name__})",
+        }
+
+    # Accept both the OpenAI shape (`{"data": [{"id": ...}, ...]}`) and the
+    # bare-list shape some self-hosted servers return (`[{"id": ...}, ...]`).
+    if isinstance(payload, dict) and isinstance(payload.get("data"), list):
+        entries = payload["data"]
+    elif isinstance(payload, list):
+        entries = payload
+    else:
+        return {
+            "ok": False,
+            "error": "parse",
+            "detail": "response is not in OpenAI /models shape (expected {'data': [...]} or [...])",
+        }
+
+    models = []
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("id"):
+            mid = str(entry["id"]).strip()
+            if mid:
+                models.append({"id": mid, "label": mid})
+        elif isinstance(entry, str) and entry.strip():
+            models.append({"id": entry.strip(), "label": entry.strip()})
+
+    return {"ok": True, "models": models, "status": status}
+
+
 def _extract_current_provider(cfg: dict) -> str:
     model_cfg = cfg.get("model", {})
     if isinstance(model_cfg, dict):
@@ -191,6 +559,15 @@ def _provider_api_key_present(
     if env_var and env_values.get(env_var):
         return True
 
+    # Legacy env-var aliases (read-only fallback for env vars renamed in past
+    # releases — e.g. lmstudio's LM_API_KEY canonical + LMSTUDIO_API_KEY legacy
+    # in #1500).  Canonical name is what onboarding writes going forward;
+    # aliases keep existing users' detection working without forcing an .env
+    # rewrite.
+    for alias in _SUPPORTED_PROVIDER_SETUPS.get(provider, {}).get("env_var_aliases", []) or []:
+        if alias and env_values.get(alias):
+            return True
+
     model_cfg = cfg.get("model", {})
     if isinstance(model_cfg, dict) and str(model_cfg.get("api_key") or "").strip():
         return True
@@ -216,7 +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
@@ -260,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
 
@@ -285,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:
@@ -302,12 +689,34 @@ def _status_from_runtime(cfg: dict, imports_ok: bool) -> dict:
     provider_ready = False
 
     if provider_configured:
-        if provider == "custom":
-            provider_ready = bool(
-                base_url and _provider_api_key_present(provider, cfg, env_values)
-            )
-        elif provider in _SUPPORTED_PROVIDER_SETUPS:
-            provider_ready = _provider_api_key_present(provider, cfg, env_values)
+        meta = _SUPPORTED_PROVIDER_SETUPS.get(provider, {})
+        if provider in _SUPPORTED_PROVIDER_SETUPS:
+            # key_optional providers (lmstudio, ollama, custom) are ready as
+            # soon as the user has saved a provider+model+base_url; an api_key
+            # is allowed but not required.  The agent runtime substitutes a
+            # placeholder for keyless local servers (LMSTUDIO_NOAUTH_PLACEHOLDER
+            # for lmstudio, equivalent paths for ollama / custom).  See #1499
+            # third sub-bug from #1420.
+            if meta.get("key_optional"):
+                if meta.get("requires_base_url"):
+                    provider_ready = bool(base_url)
+                else:
+                    provider_ready = True
+            else:
+                # Standard wizard provider (openrouter, anthropic, openai, gemini,
+                # deepseek, zai, …) — needs an api_key.  Custom historically also
+                # took this branch, but is now key_optional via the meta flag.
+                if meta.get("requires_base_url"):
+                    provider_ready = bool(
+                        base_url
+                        and _provider_api_key_present(provider, cfg, env_values)
+                    )
+                else:
+                    provider_ready = _provider_api_key_present(provider, cfg, env_values)
+                if not provider_ready and meta.get("oauth_provider"):
+                    provider_ready = _provider_oauth_authenticated(
+                        str(meta.get("oauth_provider")), _get_active_hermes_home()
+                    )
         else:
             # Unknown provider — may be an OAuth flow (openai-codex, copilot, etc.)
             # OR an API-key provider not in the quick-setup list (minimax-cn, deepseek,
@@ -383,20 +792,41 @@ def _build_setup_catalog(cfg: dict) -> dict:
                 "default_model": meta["default_model"],
                 "default_base_url": meta.get("default_base_url") or "",
                 "requires_base_url": bool(meta.get("requires_base_url")),
+                # #1499 (third sub-bug from #1420) — providers that may run
+                # keyless (lmstudio, ollama, custom).  Frontend uses this to
+                # show a "(optional)" hint and allow Continue without a key.
+                "key_optional": bool(meta.get("key_optional")),
                 "models": list(meta.get("models", [])),
-                "quick": provider_id == "openrouter",
+                "category": meta.get("category", "easy_start"),
+                "quick": meta.get("quick", False),
+                "oauth_provider": meta.get("oauth_provider") or "",
+                "oauth_label": meta.get("oauth_label") or "",
             }
         )
 
+    # Sort providers by category order, then alphabetically within each category.
+    cat_order = {c["id"]: c["order"] for c in _PROVIDER_CATEGORIES}
+    providers.sort(key=lambda p: (cat_order.get(p["category"], 99), p["label"]))
+
+    # Group providers by category for the frontend.
+    categories = []
+    for cat in sorted(_PROVIDER_CATEGORIES, key=lambda c: c["order"]):
+        categories.append({
+            "id": cat["id"],
+            "label": cat["label"],
+            "providers": [p["id"] for p in providers if p["category"] == cat["id"]],
+        })
+
     # Flag whether the currently-configured provider is OAuth-based (not in the
     # API-key flow).  The frontend uses this to show a confirmation card instead
     # of a key input when the user has already authenticated via 'hermes auth'.
-    current_is_oauth = current_provider not in _SUPPORTED_PROVIDER_SETUPS and bool(
-        current_provider
-    )
+    current_is_oauth = (
+        current_provider not in _SUPPORTED_PROVIDER_SETUPS and bool(current_provider)
+    ) or _provider_oauth_authenticated(current_provider, _get_active_hermes_home())
 
     return {
         "providers": providers,
+        "categories": categories,
         "unsupported_note": _UNSUPPORTED_PROVIDER_NOTE,
         "current_is_oauth": current_is_oauth,
         "current": {
@@ -429,11 +859,52 @@ def get_onboarding_status() -> dict:
     auto_completed = skip_requested  # unconditional: operator says skip, we skip
 
     # Auto-complete for existing Hermes users: if config.yaml already exists
-    # AND the system is chat_ready, treat onboarding as done.  These users
-    # configured Hermes via the CLI before the Web UI existed; they must never
-    # be shown the first-run wizard — it would silently overwrite their config.
+    # AND the provider is configured (or the system is chat_ready), treat onboarding
+    # as done.  These users configured Hermes via the CLI before the Web UI existed;
+    # they must never be shown the first-run wizard — it would silently overwrite their
+    # config.  We use provider_configured (not chat_ready) so that users with
+    # non-wizard providers (ollama-cloud, deepseek, xai, kimi, etc.) are not forced
+    # through the wizard just because their provider doesn't have a detectable API key
+    # — the wizard cannot represent their provider and would overwrite their config
+    # with whichever wizard-supported provider they accidentally select.
     config_exists = Path(_get_config_path()).exists()
-    config_auto_completed = config_exists and bool(runtime.get("chat_ready"))
+
+    # For providers not in the wizard's quick-setup list (e.g. ollama-cloud, deepseek,
+    # xai, kimi-k2.6), the wizard can never help — it only knows how to configure
+    # openrouter/anthropic/openai/google/custom.  If such a user has a configured
+    # provider + model in config.yaml, showing the wizard would only confuse them
+    # (or worse, let them accidentally overwrite their config with gpt-5.4-mini).
+    _current_provider = str(
+        (cfg.get("model", {}) or {}).get("provider", "") if isinstance(cfg.get("model"), dict)
+        else ""
+    ).strip().lower()
+    _is_non_wizard_provider = bool(
+        _current_provider and _current_provider not in _SUPPORTED_PROVIDER_SETUPS
+    )
+
+    config_auto_completed = config_exists and (
+        bool(runtime.get("chat_ready"))
+        or (_is_non_wizard_provider and bool(runtime.get("provider_configured")))
+    )
+
+    # Persist the flag so it survives future transient import failures (e.g. after
+    # a git branch switch in the hermes-agent repo).  Without this, a CLI-configured
+    # user who never ran the wizard has no onboarding_completed flag — any momentary
+    # imports_ok=False during restart makes chat_ready=False, config_auto_completed=False,
+    # and the wizard reappears with a broken dropdown that clobbers their config.
+    #
+    # Best-effort: if save_settings raises (read-only FS, disk full, permission error),
+    # log and continue.  The `config_auto_completed` branch of `completed=` below still
+    # returns True for this request, so the user sees the correct state — only the
+    # persistence-across-restart guarantee is degraded.  Raising here would turn every
+    # /api/onboarding/status call into a 500 until disk was writable, which is worse UX
+    # than losing the next-restart protection.
+    if config_auto_completed and not settings.get("onboarding_completed"):
+        try:
+            save_settings({"onboarding_completed": True})
+            settings["onboarding_completed"] = True
+        except Exception:
+            logger.debug("Failed to persist onboarding_completed", exc_info=True)
 
     return {
         "completed": bool(settings.get("onboarding_completed")) or auto_completed or config_auto_completed,
@@ -514,7 +985,16 @@ def apply_onboarding_setup(body: dict) -> dict:
     env_values = _load_env_file(env_path)
 
     if not api_key and not _provider_api_key_present(provider, cfg, env_values):
-        raise ValueError(f"{provider_meta['env_var']} is required")
+        # Providers that may run keyless (lmstudio, ollama, custom — gated by
+        # `key_optional` in _SUPPORTED_PROVIDER_SETUPS) are allowed to onboard
+        # with no api_key. OAuth-capable wizard providers (currently Anthropic
+        # via Claude Code) are also allowed once their server-side OAuth/link
+        # marker is present.
+        oauth_ready = bool(provider_meta.get("oauth_provider")) and _provider_oauth_authenticated(
+            str(provider_meta.get("oauth_provider")), _get_active_hermes_home()
+        )
+        if not provider_meta.get("key_optional") and not oauth_ready:
+            raise ValueError(f"{provider_meta['env_var']} is required")
 
     model_cfg = cfg.get("model", {})
     if not isinstance(model_cfg, dict):
@@ -523,12 +1003,10 @@ def apply_onboarding_setup(body: dict) -> dict:
     model_cfg["provider"] = provider
     model_cfg["default"] = _normalize_model_for_provider(provider, model)
 
-    if provider == "custom":
+    if provider_meta.get("requires_base_url"):
         model_cfg["base_url"] = base_url
-    elif provider == "openai":
-        model_cfg["base_url"] = (
-            provider_meta.get("default_base_url") or "https://api.openai.com/v1"
-        )
+    elif provider_meta.get("default_base_url"):
+        model_cfg["base_url"] = provider_meta["default_base_url"]
     else:
         model_cfg.pop("base_url", None)
 

api/passkeys.py

@@ -0,0 +1,405 @@
+"""Passkey/WebAuthn helpers for Hermes WebUI.
+
+Default-off: passkeys are only advertised after an authenticated user registers
+one from Settings. Password auth remains the bootstrap/recovery mechanism.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from api.config import STATE_DIR
+
+try:  # optional at import-time; endpoints return a clear error if unavailable
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import ec
+except Exception:  # pragma: no cover - exercised by source tests instead
+    InvalidSignature = Exception  # type: ignore[assignment]
+    hashes = serialization = ec = None  # type: ignore[assignment]
+
+_CREDENTIALS_FILE = STATE_DIR / "passkeys.json"
+_CHALLENGES_FILE = STATE_DIR / ".passkey_challenges.json"
+_CHALLENGE_TTL = 90
+_MAX_CHALLENGES = 128
+_MAX_CHALLENGES_PER_CONTEXT = 8
+_CHALLENGES_LOCK = threading.Lock()
+_RP_NAME = "Hermes WebUI"
+
+
+class PasskeyError(ValueError):
+    """Raised for user-correctable WebAuthn failures."""
+
+
+class PasskeyRateLimitError(PasskeyError):
+    """Raised when too many outstanding WebAuthn challenges are pending."""
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64u_decode(value: str | bytes) -> bytes:
+    if isinstance(value, bytes):
+        value = value.decode("ascii")
+    value = str(value).strip()
+    value += "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode(value.encode("ascii"))
+
+
+def _json_load(path: Path, default: Any) -> Any:
+    try:
+        if path.exists():
+            return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return default
+    return default
+
+
+def _atomic_write_json(path: Path, payload: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2, sort_keys=True)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _load_credentials() -> list[dict[str, Any]]:
+    data = _json_load(_CREDENTIALS_FILE, [])
+    if not isinstance(data, list):
+        return []
+    return [c for c in data if isinstance(c, dict) and isinstance(c.get("id"), str)]
+
+
+def _save_credentials(creds: list[dict[str, Any]]) -> None:
+    _atomic_write_json(_CREDENTIALS_FILE, creds)
+
+
+def registered_credentials() -> list[dict[str, Any]]:
+    """Return public credential metadata only; never expose public keys."""
+    out = []
+    for c in _load_credentials():
+        out.append({
+            "id": c.get("id"),
+            "label": c.get("label") or "Passkey",
+            "created_at": c.get("created_at"),
+            "last_used_at": c.get("last_used_at"),
+            "sign_count": c.get("sign_count", 0),
+        })
+    return out
+
+
+def passkeys_available() -> bool:
+    return bool(_load_credentials())
+
+
+def _load_challenges() -> dict[str, dict[str, Any]]:
+    # May prune and rewrite the challenge file; callers that mutate the store
+    # must hold _CHALLENGES_LOCK across load→mutate→write.
+    raw = _json_load(_CHALLENGES_FILE, {})
+    if not isinstance(raw, dict):
+        return {}
+    now = time.time()
+    clean = {
+        k: v for k, v in raw.items()
+        if isinstance(k, str) and isinstance(v, dict) and now - float(v.get("ts", 0)) < _CHALLENGE_TTL
+    }
+    if clean != raw:
+        _atomic_write_json(_CHALLENGES_FILE, clean)
+    return clean
+
+
+def _oldest_challenge_key(data: dict[str, dict[str, Any]], keys: list[str]) -> str | None:
+    if not keys:
+        return None
+    return min(keys, key=lambda k: float(data.get(k, {}).get("ts", 0)))
+
+
+def _evict_oldest_challenges(data: dict[str, dict[str, Any]], kind: str, rp_id: str, origin: str) -> None:
+    """Keep the challenge store bounded while admitting the newest challenge."""
+    while True:
+        same_context = [
+            k for k, v in data.items()
+            if v.get("kind") == kind and v.get("rp_id") == rp_id and v.get("origin") == origin
+        ]
+        if len(same_context) < _MAX_CHALLENGES_PER_CONTEXT:
+            break
+        oldest = _oldest_challenge_key(data, same_context)
+        if oldest is None:
+            break
+        data.pop(oldest, None)
+
+    while len(data) >= _MAX_CHALLENGES:
+        oldest = _oldest_challenge_key(data, list(data))
+        if oldest is None:
+            break
+        data.pop(oldest, None)
+
+
+def _store_challenge(challenge: str, kind: str, rp_id: str, origin: str) -> None:
+    with _CHALLENGES_LOCK:
+        data = _load_challenges()
+        _evict_oldest_challenges(data, kind, rp_id, origin)
+        data[challenge] = {"kind": kind, "rp_id": rp_id, "origin": origin, "ts": time.time()}
+        _atomic_write_json(_CHALLENGES_FILE, data)
+
+
+def _consume_challenge(challenge: str, kind: str) -> dict[str, Any]:
+    with _CHALLENGES_LOCK:
+        data = _load_challenges()
+        entry = data.pop(challenge, None)
+        _atomic_write_json(_CHALLENGES_FILE, data)
+    if not entry or entry.get("kind") != kind:
+        raise PasskeyError("Passkey challenge expired. Try again.")
+    return entry
+
+
+def _host_without_port(host: str) -> str:
+    host = (host or "localhost").strip().split(",", 1)[0]
+    if host.startswith("[") and "]" in host:
+        return host[1:host.index("]")]
+    return host.rsplit(":", 1)[0] if ":" in host else host
+
+
+def rp_context(handler) -> tuple[str, str]:
+    host = _host_without_port(handler.headers.get("Host", "localhost"))
+    proto = handler.headers.get("X-Forwarded-Proto", "").split(",", 1)[0].strip().lower()
+    if proto not in {"http", "https"}:
+        try:
+            from api.auth import _is_secure_context
+            proto = "https" if _is_secure_context(handler) else "http"
+        except AttributeError:
+            proto = "http"
+    return host, f"{proto}://{handler.headers.get('Host', host)}"
+
+
+def registration_options(handler) -> dict[str, Any]:
+    rp_id, _origin = rp_context(handler)
+    challenge = _b64u(secrets.token_bytes(32))
+    _store_challenge(challenge, "register", rp_id, _origin)
+    return {
+        "challenge": challenge,
+        "rp": {"name": _RP_NAME, "id": rp_id},
+        "user": {"id": _b64u(hashlib.sha256(rp_id.encode()).digest()[:16]), "name": "Hermes WebUI", "displayName": "Hermes WebUI"},
+        "pubKeyCredParams": [{"type": "public-key", "alg": -7}],
+        "authenticatorSelection": {"residentKey": "preferred", "userVerification": "preferred"},
+        "timeout": 60000,
+        "attestation": "none",
+        "excludeCredentials": [{"type": "public-key", "id": c["id"]} for c in registered_credentials()],
+    }
+
+
+def authentication_options(handler) -> dict[str, Any]:
+    creds = registered_credentials()
+    if not creds:
+        raise PasskeyError("No passkeys are registered.")
+    rp_id, origin = rp_context(handler)
+    challenge = _b64u(secrets.token_bytes(32))
+    _store_challenge(challenge, "login", rp_id, origin)
+    return {
+        "challenge": challenge,
+        "rpId": rp_id,
+        "allowCredentials": [{"type": "public-key", "id": c["id"]} for c in creds],
+        "timeout": 60000,
+        "userVerification": "preferred",
+    }
+
+
+@dataclass
+class _Cbor:
+    data: bytes
+    pos: int = 0
+
+    def read(self, n: int) -> bytes:
+        if self.pos + n > len(self.data):
+            raise PasskeyError("Malformed CBOR data")
+        out = self.data[self.pos:self.pos + n]
+        self.pos += n
+        return out
+
+    def item(self) -> Any:
+        initial = self.read(1)[0]
+        major, addl = initial >> 5, initial & 0x1F
+        val = self._val(addl)
+        if major == 0:
+            return val
+        if major == 1:
+            return -1 - val
+        if major == 2:
+            return self.read(val)
+        if major == 3:
+            return self.read(val).decode("utf-8")
+        if major == 4:
+            return [self.item() for _ in range(val)]
+        if major == 5:
+            return {self.item(): self.item() for _ in range(val)}
+        if major == 7:
+            if val == 20:
+                return False
+            if val == 21:
+                return True
+            if val == 22:
+                return None
+        raise PasskeyError("Unsupported CBOR data")
+
+    def _val(self, addl: int) -> int:
+        if addl < 24:
+            return addl
+        if addl == 24:
+            return self.read(1)[0]
+        if addl == 25:
+            return int.from_bytes(self.read(2), "big")
+        if addl == 26:
+            return int.from_bytes(self.read(4), "big")
+        if addl == 27:
+            return int.from_bytes(self.read(8), "big")
+        raise PasskeyError("Indefinite CBOR values are not supported")
+
+
+def _cbor_loads(data: bytes) -> Any:
+    parser = _Cbor(data)
+    value = parser.item()
+    if parser.pos != len(data):
+        raise PasskeyError("Trailing CBOR data")
+    return value
+
+
+def _client_data(encoded: str, expected_type: str, challenge_kind: str) -> tuple[dict[str, Any], dict[str, Any], bytes]:
+    raw = _b64u_decode(encoded)
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except Exception as exc:
+        raise PasskeyError("Malformed client data") from exc
+    if data.get("type") != expected_type:
+        raise PasskeyError("Unexpected passkey response type")
+    challenge = data.get("challenge")
+    if not isinstance(challenge, str):
+        raise PasskeyError("Missing passkey challenge")
+    entry = _consume_challenge(challenge, challenge_kind)
+    if data.get("origin") != entry.get("origin"):
+        raise PasskeyError("Passkey origin mismatch")
+    return data, entry, raw
+
+
+def _parse_auth_data(auth_data: bytes, rp_id: str) -> dict[str, Any]:
+    if len(auth_data) < 37:
+        raise PasskeyError("Malformed authenticator data")
+    rp_hash = auth_data[:32]
+    expected = hashlib.sha256(rp_id.encode("idna")).digest()
+    if not hmac.compare_digest(rp_hash, expected):
+        raise PasskeyError("Passkey RP ID mismatch")
+    flags = auth_data[32]
+    if not (flags & 0x01):
+        raise PasskeyError("Passkey user presence was not verified")
+    sign_count = int.from_bytes(auth_data[33:37], "big")
+    return {"flags": flags, "sign_count": sign_count, "rest": auth_data[37:]}
+
+
+def _public_key_from_cose(cose: dict[Any, Any]):
+    if ec is None or serialization is None:
+        raise PasskeyError("Passkey support requires the cryptography package")
+    alg = cose.get(3)
+    kty = cose.get(1)
+    crv = cose.get(-1)
+    x = cose.get(-2)
+    y = cose.get(-3)
+    if alg != -7 or kty != 2 or crv != 1 or not isinstance(x, bytes) or not isinstance(y, bytes):
+        raise PasskeyError("Only ES256 passkeys are supported")
+    numbers = ec.EllipticCurvePublicNumbers(int.from_bytes(x, "big"), int.from_bytes(y, "big"), ec.SECP256R1())
+    return numbers.public_key()
+
+
+def finish_registration(payload: dict[str, Any], handler) -> dict[str, Any]:
+    response = payload.get("response") or {}
+    _client, entry, _client_raw = _client_data(response.get("clientDataJSON", ""), "webauthn.create", "register")
+    att_obj = _cbor_loads(_b64u_decode(response.get("attestationObject", "")))
+    if not isinstance(att_obj, dict) or not isinstance(att_obj.get("authData"), bytes):
+        raise PasskeyError("Malformed attestation object")
+    parsed = _parse_auth_data(att_obj["authData"], entry["rp_id"])
+    if not (parsed["flags"] & 0x40):
+        raise PasskeyError("Passkey credential data missing")
+    rest = parsed["rest"]
+    if len(rest) < 18:
+        raise PasskeyError("Malformed credential data")
+    cred_len = int.from_bytes(rest[16:18], "big")
+    credential_id = rest[18:18 + cred_len]
+    cose_bytes = rest[18 + cred_len:]
+    cose_key = _cbor_loads(cose_bytes)
+    public_key = _public_key_from_cose(cose_key)
+    pem = public_key.public_bytes(serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo).decode("ascii")
+    cred_id = _b64u(credential_id)
+    label = str(payload.get("label") or "Passkey").strip()[:80] or "Passkey"
+    creds = [c for c in _load_credentials() if c.get("id") != cred_id]
+    creds.append({
+        "id": cred_id,
+        "label": label,
+        "public_key_pem": pem,
+        "sign_count": parsed["sign_count"],
+        "created_at": time.time(),
+        "last_used_at": None,
+    })
+    _save_credentials(creds)
+    return {"ok": True, "credential": {"id": cred_id, "label": label}}
+
+
+def finish_login(payload: dict[str, Any], handler) -> dict[str, Any]:
+    if serialization is None or hashes is None:
+        raise PasskeyError("Passkey support requires the cryptography package")
+    response = payload.get("response") or {}
+    cred_id = payload.get("id") or payload.get("rawId")
+    if not isinstance(cred_id, str):
+        raise PasskeyError("Missing passkey credential id")
+    creds = _load_credentials()
+    idx = next((i for i, c in enumerate(creds) if c.get("id") == cred_id), -1)
+    if idx < 0:
+        raise PasskeyError("Unknown passkey")
+    _client, entry, client_raw = _client_data(response.get("clientDataJSON", ""), "webauthn.get", "login")
+    auth_data = _b64u_decode(response.get("authenticatorData", ""))
+    parsed = _parse_auth_data(auth_data, entry["rp_id"])
+    signature = _b64u_decode(response.get("signature", ""))
+    public_key = serialization.load_pem_public_key(str(creds[idx].get("public_key_pem", "")).encode("ascii"))
+    signed = auth_data + hashlib.sha256(client_raw).digest()
+    try:
+        public_key.verify(signature, signed, ec.ECDSA(hashes.SHA256()))
+    except InvalidSignature as exc:
+        raise PasskeyError("Passkey signature verification failed") from exc
+    old_count = int(creds[idx].get("sign_count") or 0)
+    if parsed["sign_count"] and old_count and parsed["sign_count"] <= old_count:
+        raise PasskeyError("Passkey sign counter did not advance")
+    creds[idx]["sign_count"] = parsed["sign_count"] or old_count
+    creds[idx]["last_used_at"] = time.time()
+    _save_credentials(creds)
+    return {"ok": True, "credential_id": cred_id}
+
+
+def delete_credential(credential_id: str) -> dict[str, Any]:
+    creds = _load_credentials()
+    kept = [c for c in creds if c.get("id") != credential_id]
+    if len(kept) == len(creds):
+        raise PasskeyError("Passkey not found")
+    _save_credentials(kept)
+    return {"ok": True, "credentials": registered_credentials()}
+
+
+def clear_credentials() -> None:
+    """Remove all registered passkeys when the user disables all auth."""
+    if _CREDENTIALS_FILE.exists():
+        _save_credentials([])

api/paths.py

@@ -0,0 +1,77 @@
+"""Shared path helpers for Hermes WebUI.
+
+Keep low-level filesystem defaults here instead of in ``api.config`` so modules
+that need the default Hermes home can import them without triggering config's
+larger startup side effects.
+"""
+
+import os
+from pathlib import Path
+
+HOME = Path.home()
+
+
+def _hermes_home_has_webui_state(base: Path) -> bool:
+    """Return True when *base* holds real WebUI state under its ``webui/`` dir.
+
+    Used only on Windows to detect a pre-v0.51.134 install at the legacy
+    ``%USERPROFILE%\\.hermes`` location so we don't strand the user's existing
+    sessions/pins/settings when the default moved to ``%LOCALAPPDATA%\\hermes``
+    (#2905).
+
+    We intentionally check ONLY WebUI-owned artifacts (the ``webui/`` subtree),
+    NOT agent-owned files like ``config.yaml`` / ``auth.json``.  The agent has
+    defaulted to ``%LOCALAPPDATA%\\hermes`` on Windows since before #2897, so a
+    long-time agent user who never ran WebUI at the legacy location would have a
+    stray ``auth.json`` there — keying on that would wrongly divert a *fresh*
+    WebUI install to the legacy dir.  Only ``webui/`` state is what actually
+    gets stranded by the move, so it is the correct and narrow signal.
+    Cheap stat-only checks; never raises.
+    """
+    try:
+        if not base.is_dir():
+            return False
+        markers = (
+            base / "webui" / "sessions",        # WebUI session store
+            base / "webui" / "settings.json",   # WebUI UI settings + pins
+            base / "webui",                     # WebUI state dir at all
+        )
+        return any(m.exists() for m in markers)
+    except OSError:
+        return False
+
+
+def _platform_default_hermes_home() -> Path:
+    """Return the platform-aware default Hermes home when HERMES_HOME is unset.
+
+    Native Windows Hermes Agent installs default to %LOCALAPPDATA%\\hermes,
+    while POSIX installs use ~/.hermes.
+
+    Windows migration safety (#2905): v0.51.134 moved the Windows default from
+    ``%USERPROFILE%\\.hermes`` to ``%LOCALAPPDATA%\\hermes`` to match the agent.
+    Upgrading users whose WebUI state still lives at the old location saw an
+    empty app (sessions/pins/settings "lost" — actually just at an address the
+    new build no longer reads).  To avoid stranding that data, prefer the
+    legacy ``%USERPROFILE%\\.hermes`` ONLY when it is populated AND the new
+    ``%LOCALAPPDATA%\\hermes`` location is not yet established.  This is a
+    non-destructive, self-healing fallback: no files are moved, and once the
+    new location has state (fresh installs, or users who set HERMES_HOME) the
+    legacy path is never preferred.  Explicit HERMES_HOME / HERMES_WEBUI_STATE_DIR
+    overrides take precedence upstream and are unaffected.
+    """
+    if os.name == "nt":
+        local_app_data = os.getenv("LOCALAPPDATA", "").strip()
+        if local_app_data:
+            new_home = Path(local_app_data) / "hermes"
+            legacy_home = HOME / ".hermes"
+            # Only fall back to the legacy home if it actually holds state and
+            # the new location has not been established yet — the exact
+            # post-upgrade fingerprint from #2905.
+            if (
+                legacy_home != new_home
+                and not _hermes_home_has_webui_state(new_home)
+                and _hermes_home_has_webui_state(legacy_home)
+            ):
+                return legacy_home
+            return new_home
+    return HOME / ".hermes"

api/plugin_providers.py

@@ -0,0 +1,141 @@
+"""Helpers for model-provider plugins (``plugins/model-providers/<name>/``).
+
+The Hermes agent discovers these via ``providers.list_providers()`` and exposes
+them in the CLI model picker.  WebUI must mirror that registry instead of
+relying only on the static ``_PROVIDER_DISPLAY`` / ``_PROVIDER_MODELS`` tables.
+
+Bundled agent profiles (gemini, nous, custom, …) also live in
+``list_providers()``.  WebUI already handles those via static tables and
+dedicated code paths — only *plugin-only* slugs (e.g. user-installed yandex)
+should take the plugin discovery path.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_PROFILES_LOCK = threading.Lock()
+_PROFILES_BY_NAME: dict[str, Any] | None = None
+_WEBUI_STATIC_PROVIDER_IDS: frozenset[str] | None = None
+
+
+def _webui_static_provider_ids() -> frozenset[str]:
+    """Provider slugs already owned by WebUI static tables / special cases."""
+    global _WEBUI_STATIC_PROVIDER_IDS
+    if _WEBUI_STATIC_PROVIDER_IDS is not None:
+        return _WEBUI_STATIC_PROVIDER_IDS
+    try:
+        from api.config import _PROVIDER_DISPLAY, _PROVIDER_MODELS
+
+        static = (
+            frozenset(_PROVIDER_DISPLAY.keys())
+            | frozenset(_PROVIDER_MODELS.keys())
+            | frozenset({"custom"})
+        )
+    except Exception:
+        static = frozenset({"custom"})
+    _WEBUI_STATIC_PROVIDER_IDS = static
+    return static
+
+
+def _load_profiles_by_name() -> dict[str, Any]:
+    try:
+        from providers import list_providers
+    except Exception:
+        logger.debug("providers package unavailable for plugin discovery", exc_info=True)
+        return {}
+
+    result: dict[str, Any] = {}
+    try:
+        for profile in list_providers():
+            name = str(getattr(profile, "name", "") or "").strip().lower()
+            if name:
+                result[name] = profile
+    except Exception:
+        logger.debug("Failed to enumerate model-provider plugins", exc_info=True)
+        return {}
+    return result
+
+
+def plugin_model_provider_profiles() -> dict[str, Any]:
+    """Return registered model-provider profiles keyed by canonical slug."""
+    global _PROFILES_BY_NAME
+    cached = _PROFILES_BY_NAME
+    if cached is not None:
+        return cached
+    with _PROFILES_LOCK:
+        if _PROFILES_BY_NAME is None:
+            _PROFILES_BY_NAME = _load_profiles_by_name()
+        return _PROFILES_BY_NAME
+
+
+def invalidate_plugin_model_provider_cache() -> None:
+    """Clear cached plugin discovery (e.g. after config reload)."""
+    global _PROFILES_BY_NAME
+    with _PROFILES_LOCK:
+        _PROFILES_BY_NAME = None
+
+
+def plugin_model_provider_ids() -> frozenset[str]:
+    """Slugs from ``list_providers()`` that are not already WebUI-static."""
+    static = _webui_static_provider_ids()
+    return frozenset(
+        pid for pid in plugin_model_provider_profiles().keys() if pid not in static
+    )
+
+
+def plugin_model_provider_display_name(provider_id: str) -> str | None:
+    profile = plugin_model_provider_profiles().get((provider_id or "").strip().lower())
+    if profile is None:
+        return None
+    return str(getattr(profile, "display_name", "") or getattr(profile, "name", "") or "").strip() or None
+
+
+def plugin_model_provider_api_key_env_var(provider_id: str) -> str | None:
+    """Return the primary API-key env var for a plugin provider, if any."""
+    profile = plugin_model_provider_profiles().get((provider_id or "").strip().lower())
+    if profile is None:
+        return None
+    env_vars = getattr(profile, "env_vars", ()) or ()
+    for var in env_vars:
+        upper = str(var).upper()
+        if upper.endswith("_BASE_URL") or upper.endswith("_URL"):
+            continue
+        if upper.endswith("_FOLDER_ID"):
+            continue
+        return str(var)
+    return None
+
+
+def effective_provider_env_var(provider_id: str, static_map: dict[str, str]) -> str | None:
+    pid = (provider_id or "").strip().lower()
+    if not pid:
+        return None
+    if pid in static_map:
+        return static_map[pid]
+    if not is_plugin_model_provider(pid):
+        return None
+    return plugin_model_provider_api_key_env_var(pid)
+
+
+def effective_provider_display_name(provider_id: str, static_map: dict[str, str]) -> str:
+    pid = (provider_id or "").strip().lower()
+    if pid in static_map:
+        return static_map[pid]
+    if is_plugin_model_provider(pid):
+        plugin_name = plugin_model_provider_display_name(pid)
+        if plugin_name:
+            return plugin_name
+    return pid.replace("-", " ").title()
+
+
+def is_plugin_model_provider(provider_id: str) -> bool:
+    """True for plugin-only providers (not already in WebUI static tables)."""
+    pid = (provider_id or "").strip().lower()
+    if not pid or pid in _webui_static_provider_ids():
+        return False
+    return pid in plugin_model_provider_profiles()

api/plugins.py

@@ -0,0 +1,185 @@
+"""
+Plugin discovery and static serving for Hermes Web UI.
+
+Scans ~/.hermes/plugins/<name>/dashboard/ for manifest.json files,
+matching the official Hermes dashboard plugin format.
+
+Each plugin may have:
+  dashboard/
+    manifest.json   -- tab definition and entry point
+    dist/
+      index.js      -- plugin JS bundle (IIFE)
+      style.css     -- optional plugin stylesheet
+    plugin_api.py   -- optional backend API (not used in WebUI MVP)
+"""
+import json
+import logging
+import os
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Valid dashboard-plugin name: a safe slug (it becomes a URL path component and
+# a settings key). Lowercase alnum + - / _, 1-64 chars, must start with a letter.
+_VALID_PLUGIN_NAME = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+
+# Valid tab.path: a clean same-origin absolute path. Must start with a single
+# '/' (NOT '//' — a leading '//' is a protocol-relative URL that would resolve
+# to a remote origin when assigned to iframe.src), then only safe path chars —
+# no quotes, whitespace, control chars, query ('?') or fragment ('#').
+_VALID_PLUGIN_TAB_PATH = re.compile(r"^/(?!/)[A-Za-z0-9._~/-]{0,255}$")
+
+# plugin_name -> manifest dict (as loaded from manifest.json)
+PLUGIN_MANIFESTS: dict[str, dict] = {}
+
+# plugin_name -> resolved static root dir
+_PLUGIN_STATIC_ROOTS: dict[str, Path] = {}
+
+
+def _get_plugin_base() -> Path:
+    return Path(os.environ.get("HERMES_WEBUI_PLUGINS_DIR", str(Path.home() / ".hermes" / "plugins")))
+
+
+def load_plugins() -> None:
+    """Scan plugin directories and load manifest.json for each dashboard plugin."""
+    plugin_base = _get_plugin_base()
+    if not plugin_base.is_dir():
+        logger.debug("No plugins directory at %s", plugin_base)
+        return
+
+    for entry in sorted(plugin_base.iterdir()):
+        if not entry.is_dir():
+            continue
+        manifest_path = entry / "dashboard" / "manifest.json"
+        if not manifest_path.is_file():
+            continue
+
+        try:
+            manifest = json.loads(manifest_path.read_text())
+        except Exception:
+            logger.exception("Failed to parse manifest for plugin %s", entry.name)
+            continue
+
+        name = manifest.get("name") or entry.name
+
+        # Validate the plugin name: it becomes a URL path component
+        # (/dashboard-plugins/<name>/...) and a settings key. Restrict to a safe
+        # slug so a manifest like name:"../foo" can't make the URL-space ambiguous.
+        if not _VALID_PLUGIN_NAME.match(str(name)):
+            logger.warning("Skipping plugin with invalid name %r (must match %s)", name, _VALID_PLUGIN_NAME.pattern)
+            continue
+
+        tab = manifest.get("tab", {})
+        tab_path = tab.get("path", f"/{name}")
+
+        # Validate tab.path: it's a same-origin route the plugin page is served
+        # at AND a value passed into client-side navigation. Require a clean
+        # absolute path — no quotes/control chars/query/fragment — so a hostile
+        # manifest can't shadow odd routes or inject via the path.
+        if not _VALID_PLUGIN_TAB_PATH.match(str(tab_path)):
+            logger.warning("Skipping plugin %s with invalid tab.path %r (must match %s)", name, tab_path, _VALID_PLUGIN_TAB_PATH.pattern)
+            continue
+
+        if name in PLUGIN_MANIFESTS:
+            logger.warning("Duplicate plugin name skipped: %s (already loaded)", name)
+            continue
+        if tab_path in (m.get("tab", {}).get("path") for m in PLUGIN_MANIFESTS.values()):
+            logger.warning("Plugin %s tab.path %r conflicts with another plugin; skipped", name, tab_path)
+            continue
+
+        PLUGIN_MANIFESTS[name] = manifest
+        logger.info("Loaded dashboard plugin: %s (label=%s)", name, manifest.get("label", ""))
+
+        # Pre-compute static root for fast serving (points to dashboard/)
+        dashboard_dir = entry / "dashboard"
+        if dashboard_dir.is_dir():
+            _PLUGIN_STATIC_ROOTS[name] = dashboard_dir.resolve()
+
+
+def serve_plugin_static(plugin_name: str, rel_path: str) -> tuple[bytes, str] | None:
+    """
+    Serve a built static asset from a plugin's dashboard/dist/ (or static/) dir.
+
+    Returns (file_bytes, content_type) on success, None on not found.
+
+    Security: _PLUGIN_STATIC_ROOTS points at the plugin's whole dashboard/ dir
+    (the page route needs that), but the asset route must NOT expose plugin
+    source/config — e.g. dashboard/plugin_api.py, manifest.json, .env. So we
+    constrain served files to the built-asset subtrees (dist/ or static/), reject
+    dotfiles, and require a known static extension.
+    """
+    root = _PLUGIN_STATIC_ROOTS.get(plugin_name)
+    if not root:
+        return None
+
+    safe = (root / rel_path.lstrip("/")).resolve()
+    try:
+        safe.relative_to(root)
+    except ValueError:
+        return None  # path traversal attempt
+
+    # Only built-asset subtrees are servable (not the dashboard root itself,
+    # which holds plugin_api.py / manifest.json / config).
+    rel = safe.relative_to(root)
+    if not rel.parts or rel.parts[0] not in ("dist", "static"):
+        return None
+    # No dotfiles (.env, .git, etc.) anywhere in the path.
+    if any(part.startswith(".") for part in rel.parts):
+        return None
+
+    if not safe.is_file():
+        return None
+
+    # Allowlist of static asset extensions — refuse source/config (.py, .json,
+    # .toml, .env, .sh, ...) even if somehow placed under dist/.
+    ext = os.path.splitext(rel_path.lower())[1]
+    _STATIC_EXTS = {
+        ".js", ".css", ".html", ".png", ".jpg", ".jpeg", ".gif", ".svg",
+        ".ico", ".webp", ".woff", ".woff2", ".ttf", ".otf", ".map", ".txt",
+    }
+    if ext not in _STATIC_EXTS:
+        return None
+
+    data = safe.read_bytes()
+    content_type = {
+        ".js": "application/javascript; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".html": "text/html; charset=utf-8",
+        ".json": "application/json; charset=utf-8",
+        ".png": "image/png",
+        ".svg": "image/svg+xml",
+        ".ico": "image/x-icon",
+    }.get(ext, "application/octet-stream")
+
+    return data, content_type
+
+
+def get_plugin_metadata() -> list[dict]:
+    """
+    Return a list of plugin metadata suitable for the Settings → Plugins tab.
+    Each entry includes name, key, version, description, and tab info for linking.
+
+    Per-plugin enabled state is stored in settings.json under `dashboard_plugins`.
+    A plugin is enabled only if the user has explicitly toggled it on (default off).
+    """
+    from api.config import load_settings
+
+    plugin_settings = load_settings().get("dashboard_plugins", {})
+    plugins = []
+    for name, manifest in sorted(PLUGIN_MANIFESTS.items()):
+        tab = manifest.get("tab", {})
+        path = tab.get("path", f"/{name}")
+        plugins.append({
+            "name": manifest.get("label") or manifest.get("name") or name,
+            "key": name,
+            "version": manifest.get("version", "0.0.0"),
+            "description": manifest.get("description", ""),
+            "tab": {
+                "path": path,
+                "label": tab.get("label") or manifest.get("label") or name,
+            },
+            "enabled": bool(plugin_settings.get(name, False)),
+            "hooks": [],
+        })
+    return plugins

api/request_diagnostics.py

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

api/rollback.py

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

api/route_approvals.py

@@ -0,0 +1,136 @@
+"""Approval SSE state and helpers.
+
+State-extraction prelude to the routes.py split tracked in #1907.
+Extracts approval state, not handlers, by design.
+"""
+import queue
+import threading
+import uuid
+
+from api.session_events import publish_session_list_changed
+
+# Approval system (optional -- graceful fallback if agent not available)
+try:
+    from tools.approval import (
+        submit_pending as _submit_pending_raw,
+        approve_session,
+        approve_permanent,
+        save_permanent_allowlist,
+        is_approved,
+        _pending,
+        _lock,
+        _permanent_approved,
+        _gateway_queues,
+        resolve_gateway_approval,
+        enable_session_yolo,
+        disable_session_yolo,
+        is_session_yolo_enabled,
+    )
+except ImportError:
+    _submit_pending_raw = lambda *a, **k: None
+    approve_session = lambda *a, **k: None
+    approve_permanent = lambda *a, **k: None
+    save_permanent_allowlist = lambda *a, **k: None
+    is_approved = lambda *a, **k: True
+    resolve_gateway_approval = lambda *a, **k: 0
+    enable_session_yolo = lambda *a, **k: None
+    disable_session_yolo = lambda *a, **k: None
+    is_session_yolo_enabled = lambda *a, **k: False
+    _pending = {}
+    _lock = threading.Lock()
+    _permanent_approved = set()
+    _gateway_queues = {}
+
+
+# ── Approval SSE subscribers (long-connection push) ──────────────────────────
+_approval_sse_subscribers: dict[str, list[queue.Queue]] = {}
+
+
+def _approval_sse_subscribe(session_id: str) -> queue.Queue:
+    """Register an SSE subscriber for approval events on a given session."""
+    q = queue.Queue(maxsize=16)
+    with _lock:
+        _approval_sse_subscribers.setdefault(session_id, []).append(q)
+    return q
+
+
+def _approval_sse_unsubscribe(session_id: str, q: queue.Queue) -> None:
+    """Remove an SSE subscriber."""
+    with _lock:
+        subs = _approval_sse_subscribers.get(session_id)
+        if subs and q in subs:
+            subs.remove(q)
+            if not subs:
+                _approval_sse_subscribers.pop(session_id, None)
+
+
+def _approval_sse_notify_locked(session_id: str, head: dict | None, total: int) -> None:
+    """Push an approval event to all SSE subscribers for a session.
+
+    CALLER MUST HOLD `_lock`. Snapshots the subscriber list under the held
+    lock and then calls `q.put_nowait()` on each (which is itself thread-safe).
+
+    `head` is the approval entry currently at the head of the queue (the one
+    the UI should display) — NOT the just-appended entry. With multiple
+    parallel approvals (#527), the just-appended entry is at the TAIL, but
+    `/api/approval/pending` always returns the HEAD, so SSE must match.
+
+    `total` is the total number of pending approvals.
+
+    Pass `head=None` and `total=0` when the queue has just been emptied (e.g.
+    `_handle_approval_respond` popped the last entry) so the client knows to
+    hide its approval card.
+    """
+    payload = {"pending": dict(head) if head else None, "pending_count": total}
+    subs = _approval_sse_subscribers.get(session_id, ())
+    for q in subs:
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            pass  # drop if subscriber is slow (bounded queue prevents memory leak)
+
+
+def _approval_sse_notify(session_id: str, head: dict | None, total: int) -> None:
+    """Convenience wrapper that takes `_lock` itself.
+
+    Use only from contexts that don't already hold `_lock`. Production call
+    sites (submit_pending, _handle_approval_respond) MUST hold the lock and
+    call `_approval_sse_notify_locked` directly to avoid a notify-ordering
+    race where a later append's notify can fire before an earlier append's
+    notify (resulting in stale `pending_count`).
+    """
+    with _lock:
+        _approval_sse_notify_locked(session_id, head, total)
+
+
+def submit_pending(session_key: str, approval: dict) -> None:
+    """Append a pending approval to the per-session queue.
+
+    Wraps the agent's submit_pending to:
+    - Add a stable approval_id (uuid4 hex) so the respond endpoint can target
+      a specific entry even when multiple approvals are queued simultaneously.
+    - Change the storage from a single overwriting dict value to a list, so
+      parallel tool calls each get their own approval slot (fixes #527).
+    - Notify any connected SSE subscribers immediately.
+    """
+    entry = dict(approval)
+    entry.setdefault("approval_id", uuid.uuid4().hex)
+    with _lock:
+        queue_list = _pending.setdefault(session_key, [])
+        # Replace a legacy non-list value if the agent version uses the old pattern.
+        if not isinstance(queue_list, list):
+            _pending[session_key] = [queue_list]
+            queue_list = _pending[session_key]
+        queue_list.append(entry)
+        total = len(queue_list)
+        head = queue_list[0]  # /api/approval/pending always returns head
+        # Push to SSE subscribers from inside _lock so two parallel
+        # submit_pending calls can't deliver out-of-order (T2's later
+        # notify arriving before T1's earlier notify with a stale count).
+        _approval_sse_notify_locked(session_key, head, total)
+    publish_session_list_changed("attention_pending")
+    # NOTE: We do NOT call _submit_pending_raw here — that function overwrites
+    # _pending[session_key] with a single dict, which would undo the list we just
+    # built. The gateway blocking path uses _gateway_queues (a separate mechanism
+    # managed by check_all_command_guards / register_gateway_notify), which is
+    # unaffected by _pending. The _pending dict is only used for UI polling.

api/run_journal.py

@@ -0,0 +1,320 @@
+"""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":
+        if isinstance(payload, dict):
+            explicit_state = str(payload.get("terminal_state") or "").strip().lower()
+            if explicit_state in {"tool_limit_reached"}:
+                return explicit_state
+        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 == "tool_limit_reached":
+            return "tool_limit_reached"
+        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,
+    max_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)]
+    if max_seq is not None:
+        events = [event for event in events if int(event.get("seq") or 0) <= int(max_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 delete_run_journal(session_id: str, *, session_dir: Path | None = None) -> bool:
+    """Remove the entire per-session run-journal directory (``_run_journal/{sid}/``).
+
+    The run journal stores one directory per session containing a ``{rid}.jsonl``
+    file per run, so removing the session's directory clears every run's full
+    request/response payloads. Invalid/empty ids and a missing directory are a
+    no-op so callers can invoke this unconditionally on delete. Returns ``True``
+    if a directory was removed, ``False`` otherwise.
+    """
+    import shutil
+
+    sid = str(session_id or "").strip()
+    # Reject path-traversal ids: the regex below permits dots, so a bare "." or
+    # ".." would resolve `root / RUN_JOURNAL_DIR_NAME / sid` to the journal ROOT
+    # (or its parent) and rmtree the wrong directory. The route call site only
+    # passes real sids, but this is a public helper — guard it directly.
+    if sid in (".", "..") or not sid or "/" in sid or "\\" in sid or not _SAFE_ID_RE.fullmatch(sid):
+        return False
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    session_journal_dir = root / RUN_JOURNAL_DIR_NAME / sid
+    if not session_journal_dir.exists():
+        return False
+    shutil.rmtree(session_journal_dir, ignore_errors=True)
+    return not session_journal_dir.exists()
+
+
+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",
+        "recovery_control": True,
+        "message": "The live worker stopped 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": "lost-worker-bookkeeping",
+        "payload": payload,
+        "synthetic": True,
+    }

api/runner_client.py

@@ -0,0 +1,156 @@
+"""HTTP client boundary for a supervised Hermes WebUI runner backend.
+
+This module intentionally contains no process-local run maps, stream queues,
+cancellation registries, approval/clarify queues, or cached agent instances. It
+is only a JSON-over-HTTP transport used by ``RunnerRuntimeAdapter`` when an
+operator explicitly configures a runner endpoint.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+_RUNNER_BASE_URL_ENV = "HERMES_WEBUI_RUNNER_BASE_URL"
+_RUNNER_API_KEY_ENV = "HERMES_WEBUI_RUNNER_API_KEY"
+
+
+class RunnerClientError(RuntimeError):
+    """Raised when a configured runner endpoint rejects or fails a request."""
+
+
+def runner_client_configured(environ: dict[str, str] | None = None) -> bool:
+    source = os.environ if environ is None else environ
+    return bool(str(source.get(_RUNNER_BASE_URL_ENV) or "").strip())
+
+
+class HttpRunnerClient:
+    """Small JSON HTTP client for the external/supervised runner boundary."""
+
+    def __init__(self, *, base_url: str, api_key: str = ""):
+        self.base_url = str(base_url or "").strip().rstrip("/")
+        if not self.base_url:
+            raise ValueError("runner base_url is required")
+        # Hardening: the runner endpoint is operator-configured, but reject any
+        # non-HTTP(S) scheme so a misconfigured HERMES_WEBUI_RUNNER_BASE_URL
+        # (e.g. file:///etc/passwd or ftp://) can never be handed to urlopen.
+        _scheme = urllib.parse.urlsplit(self.base_url).scheme.lower()
+        if _scheme not in ("http", "https"):
+            raise ValueError(
+                f"runner base_url must be http(s); got scheme '{_scheme or '(none)'}'"
+            )
+        self.api_key = str(api_key or "").strip()
+
+    @classmethod
+    def from_env(cls, environ: dict[str, str] | None = None) -> "HttpRunnerClient":
+        source = os.environ if environ is None else environ
+        base_url = str(source.get(_RUNNER_BASE_URL_ENV) or "").strip()
+        if not base_url:
+            raise NotImplementedError("runner-local chat backend is not configured")
+        return cls(base_url=base_url, api_key=str(source.get(_RUNNER_API_KEY_ENV) or ""))
+
+    def start_run(self, request) -> dict[str, Any]:
+        return self._post("/v1/runs", {
+            "session_id": request.session_id,
+            "message": request.message,
+            "attachments": list(request.attachments or []),
+            "workspace": request.workspace,
+            "profile": request.profile,
+            "provider": request.provider,
+            "model": request.model,
+            "toolsets": list(request.toolsets or []),
+            "source": request.source,
+            "metadata": dict(request.metadata or {}),
+        })
+
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> dict[str, Any]:
+        query = ""
+        if cursor not in (None, ""):
+            query = "?cursor=" + urllib.parse.quote(str(cursor), safe="")
+        return self._get(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/events{query}")
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}")
+
+    def cancel_run(self, run_id: str) -> dict[str, Any]:
+        return self._post(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/cancel", {})
+
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/approvals/{urllib.parse.quote(str(approval_id), safe='')}/respond",
+            {"choice": choice},
+        )
+
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/clarifications/{urllib.parse.quote(str(clarify_id), safe='')}/respond",
+            {"response": response},
+        )
+
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/messages",
+            {"message": message, "mode": mode},
+        )
+
+    def update_goal(self, session_id: str, action: str, text: str = "") -> dict[str, Any]:
+        return self._post(
+            f"/v1/sessions/{urllib.parse.quote(str(session_id), safe='')}/goal",
+            {"action": action, "text": text},
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": "Hermes-WebUI-RunnerClient",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _get(self, path: str) -> dict[str, Any]:
+        req = urllib.request.Request(self.base_url + path, headers=self._headers(), method="GET")
+        return self._request_json(req)
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        req = urllib.request.Request(
+            self.base_url + path,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=self._headers(),
+            method="POST",
+        )
+        return self._request_json(req)
+
+    def _opener(self) -> urllib.request.OpenerDirector:
+        # Hardening: do NOT follow redirects. A misbehaving/compromised runner
+        # returning 3xx Location could otherwise smuggle the Bearer token to
+        # another host. Treat any redirect as an error instead.
+        class _NoRedirect(urllib.request.HTTPRedirectHandler):
+            def redirect_request(self, *args, **kwargs):
+                return None
+        return urllib.request.build_opener(_NoRedirect)
+
+    def _request_json(self, req: urllib.request.Request) -> dict[str, Any]:
+        try:
+            with self._opener().open(req, timeout=60) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = exc.read(2048).decode("utf-8", errors="replace")
+            except Exception:
+                detail = ""
+            raise RunnerClientError(f"Runner returned HTTP {exc.code}: {detail[:500]}") from exc
+        except Exception as exc:
+            raise RunnerClientError(f"Runner request failed: {exc}") from exc
+        try:
+            payload = json.loads(raw or "{}")
+        except json.JSONDecodeError as exc:
+            raise RunnerClientError("Runner returned invalid JSON") from exc
+        if not isinstance(payload, dict):
+            raise RunnerClientError("Runner returned a non-object JSON payload")
+        return payload

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_discoverability.py

@@ -0,0 +1,640 @@
+"""Read-only sidebar discoverability audit for Hermes WebUI sessions.
+
+This module does not repair or mutate session state. It cross-checks the four
+places that decide whether a session can be found from the WebUI sidebar:
+
+- JSON sidecars under the WebUI session directory
+- ``_index.json`` sidebar metadata
+- canonical ``state.db`` rows/messages
+- the live ``api.models.all_sessions()`` sidebar response, when available
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sqlite3
+from collections import Counter
+from pathlib import Path
+from typing import Iterable
+
+
+def _safe_int(value, default: int = 0) -> int:
+    try:
+        if value is None:
+            return default
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _read_json(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+
+
+def _message_count_from_payload(payload: dict) -> int:
+    messages = payload.get("messages")
+    if isinstance(messages, list):
+        return len(messages)
+    return _safe_int(payload.get("message_count"), 0)
+
+
+def _record_from_mapping(mapping: dict, source_name: str) -> dict:
+    sid = str(mapping.get("session_id") or mapping.get("id") or "").strip()
+    if not sid:
+        return {}
+    return {
+        "session_id": sid,
+        "title": mapping.get("title"),
+        "message_count": _message_count_from_payload(mapping),
+        "source_tag": mapping.get("source_tag"),
+        "session_source": mapping.get("session_source"),
+        "source": mapping.get("source"),
+        "is_cli_session": mapping.get("is_cli_session"),
+        "parent_session_id": mapping.get("parent_session_id"),
+        "pre_compression_snapshot": bool(mapping.get("pre_compression_snapshot")),
+        "_lineage_root_id": mapping.get("_lineage_root_id"),
+        "archived": bool(mapping.get("archived")),
+        "project_id": mapping.get("project_id"),
+        "workspace": mapping.get("workspace"),
+        "_source_name": source_name,
+    }
+
+
+def _read_sidecars(session_dir: Path) -> dict[str, dict]:
+    records: dict[str, dict] = {}
+    if not session_dir.exists():
+        return records
+    for path in sorted(p for p in session_dir.glob("*.json") if not p.name.startswith("_")):
+        payload = _read_json(path)
+        if not isinstance(payload, dict):
+            continue
+        record = _record_from_mapping(payload, "sidecar")
+        if record:
+            records[record["session_id"]] = record
+    return records
+
+
+def _read_index(session_dir: Path) -> dict[str, dict]:
+    payload = _read_json(session_dir / "_index.json")
+    records: dict[str, dict] = {}
+    if not isinstance(payload, list):
+        return records
+    for entry in payload:
+        if not isinstance(entry, dict):
+            continue
+        record = _record_from_mapping(entry, "index")
+        if record:
+            records[record["session_id"]] = record
+    return records
+
+
+def _optional_expr(name: str, columns: set[str], fallback: str = "NULL") -> str:
+    return name if name in columns else f"{fallback} AS {name}"
+
+
+def _read_state_db(state_db_path: Path | None) -> dict[str, dict]:
+    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
+            tables = {row[0] for row in conn.execute("select name from sqlite_master where type='table'")}
+            if "sessions" not in tables:
+                return {}
+            session_cols = {row[1] for row in conn.execute("pragma table_info(sessions)")}
+            if "id" not in session_cols:
+                return {}
+            message_cols: set[str] = set()
+            if "messages" in tables:
+                message_cols = {row[1] for row in conn.execute("pragma table_info(messages)")}
+            title_expr = _optional_expr("title", session_cols)
+            source_expr = _optional_expr("source", session_cols)
+            parent_expr = _optional_expr("parent_session_id", session_cols)
+            msg_expr = _optional_expr("message_count", session_cols, "0")
+            workspace_expr = _optional_expr("workspace", session_cols)
+            rows = conn.execute(
+                f"""
+                SELECT id, {title_expr}, {source_expr}, {parent_expr}, {msg_expr}, {workspace_expr}
+                FROM sessions
+                """
+            ).fetchall()
+            message_counts: dict[str, int] = {}
+            if {"session_id"}.issubset(message_cols):
+                for row in conn.execute("SELECT session_id, COUNT(*) AS count FROM messages GROUP BY session_id"):
+                    message_counts[str(row["session_id"])] = _safe_int(row["count"], 0)
+            records: dict[str, dict] = {}
+            for row in rows:
+                sid = str(row["id"] or "").strip()
+                if not sid:
+                    continue
+                count = message_counts.get(sid, _safe_int(row["message_count"], 0))
+                records[sid] = {
+                    "session_id": sid,
+                    "title": row["title"],
+                    "message_count": count,
+                    "source": row["source"],
+                    "source_tag": row["source"],
+                    "session_source": row["source"],
+                    "parent_session_id": row["parent_session_id"],
+                    "workspace": row["workspace"],
+                    "_source_name": "state_db",
+                }
+            return records
+    except Exception:
+        return {}
+
+
+def _normalize_api_sessions(api_sessions: Iterable[dict] | None) -> dict[str, dict]:
+    records: dict[str, dict] = {}
+    if api_sessions is None:
+        try:
+            from api.models import all_sessions
+
+            api_sessions = all_sessions()
+        except Exception:
+            api_sessions = []
+    for entry in api_sessions or []:
+        if not isinstance(entry, dict):
+            continue
+        record = _record_from_mapping(entry, "api")
+        if record:
+            records[record["session_id"]] = record
+    return records
+
+
+def _merged_field(sid: str, stores: list[dict[str, dict]], field: str):
+    for store in stores:
+        value = store.get(sid, {}).get(field)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def _max_message_count(sid: str, stores: list[dict[str, dict]]) -> int:
+    return max((_safe_int(store.get(sid, {}).get("message_count"), 0) for store in stores), default=0)
+
+
+def _lineage_root(sid: str, parent_by_id: dict[str, str | None]) -> str:
+    seen: set[str] = set()
+    current = sid
+    while current and current not in seen:
+        seen.add(current)
+        parent = parent_by_id.get(current)
+        if not parent:
+            return current
+        current = parent
+    return sid
+
+
+def _webui_origin(*records: dict) -> bool:
+    values: list[str] = []
+    for record in records:
+        for key in ("source", "source_tag", "session_source"):
+            value = record.get(key)
+            if value is not None:
+                values.append(str(value).strip().lower())
+    return "webui" in values
+
+
+def _computed_is_cli_session(row: dict) -> bool:
+    sources = {
+        str(row.get(key) or "").strip().lower()
+        for key in ("session_source", "source_tag", "raw_source", "source", "source_label")
+    }
+    if "webui" in sources:
+        return False
+    try:
+        from api.agent_sessions import is_cli_session_row
+
+        return is_cli_session_row(row)
+    except Exception:
+        source = str(row.get("session_source") or row.get("source_tag") or row.get("raw_source") or row.get("source") or "").strip().lower()
+        return source == "cli"
+
+
+def _new_item(session_id: str, kind: str, category: str, recommendation: str, **extra) -> dict:
+    item = {
+        "session_id": session_id,
+        "kind": kind,
+        "category": category,
+        "recommendation": recommendation,
+    }
+    item.update(extra)
+    return item
+
+
+def audit_session_discoverability(
+    session_dir: Path,
+    state_db_path: Path | None = None,
+    *,
+    api_sessions: Iterable[dict] | None = None,
+) -> dict:
+    """Return a read-only cross-store discoverability report.
+
+    The audit is intentionally diagnostic only. It reports cases where
+    messageful sessions have no visible API/sidebar representative, stale source
+    flags can put WebUI sessions into the CLI tab, and index/sidecar/state-db
+    drift can make a session harder to resolve.
+    """
+    session_dir = Path(session_dir)
+    sidecars = _read_sidecars(session_dir)
+    index = _read_index(session_dir)
+    state = _read_state_db(state_db_path)
+    api = _normalize_api_sessions(api_sessions)
+    stores = [sidecars, index, state, api]
+    all_ids = set().union(*(store.keys() for store in stores))
+
+    parent_by_id: dict[str, str | None] = {}
+    for sid in all_ids:
+        parent = _merged_field(sid, stores, "parent_session_id")
+        parent_by_id[sid] = str(parent) if parent else None
+    api_lineage_ids: set[str] = set()
+    api_lineage_representative_by_id: dict[str, str] = {}
+    for sid, row in api.items():
+        explicit_root = row.get("_lineage_root_id")
+        if explicit_root:
+            root_id = str(explicit_root)
+            api_lineage_ids.add(root_id)
+            api_lineage_representative_by_id.setdefault(root_id, sid)
+        current = sid
+        seen: set[str] = set()
+        while current and current not in seen:
+            seen.add(current)
+            api_lineage_ids.add(current)
+            api_lineage_representative_by_id.setdefault(current, sid)
+            current = parent_by_id.get(current) or ""
+
+    items: list[dict] = []
+    for sid in sorted(all_ids):
+        message_count = _max_message_count(sid, stores)
+        present_in = {
+            "sidecar": sid in sidecars,
+            "index": sid in index,
+            "state_db": sid in state,
+            "api": sid in api,
+        }
+        sidecar = sidecars.get(sid, {})
+        index_row = index.get(sid, {})
+        state_row = state.get(sid, {})
+        api_row = api.get(sid, {})
+        webui_origin = _webui_origin(sidecar, index_row, state_row, api_row)
+
+        api_is_cli = api_row.get("is_cli_session") is True
+        api_computed_is_cli = _computed_is_cli_session(api_row) if api_row else False
+        index_is_cli = index_row.get("is_cli_session") is True
+        sidecar_is_cli = sidecar.get("is_cli_session") is True
+        lineage_root = _lineage_root(sid, parent_by_id)
+        api_representative = api_lineage_representative_by_id.get(sid) or api_lineage_representative_by_id.get(lineage_root)
+        api_lineage_extra = {
+            "represented_by_api_lineage": bool(api_representative),
+            "api_representative_session_id": api_representative,
+        }
+        if webui_origin and api_is_cli and api_computed_is_cli:
+            items.append(_new_item(
+                sid,
+                "source_misclassified",
+                "warning",
+                "normalize_api_source_flags",
+                message_count=message_count,
+                state_source=state_row.get("source"),
+                api_is_cli_session=api_row.get("is_cli_session"),
+                api_computed_is_cli_session=api_computed_is_cli,
+                index_is_cli_session=index_row.get("is_cli_session"),
+                sidecar_is_cli_session=sidecar.get("is_cli_session"),
+                present_in=present_in,
+                **api_lineage_extra,
+            ))
+        elif webui_origin and (api_is_cli or index_is_cli or sidecar_is_cli):
+            items.append(_new_item(
+                sid,
+                "persisted_source_flag_stale",
+                "warning",
+                "rewrite_persisted_sidebar_source_flags_or_ignore_route_normalizes",
+                message_count=message_count,
+                state_source=state_row.get("source"),
+                api_is_cli_session=api_row.get("is_cli_session"),
+                api_computed_is_cli_session=api_computed_is_cli,
+                index_is_cli_session=index_row.get("is_cli_session"),
+                sidecar_is_cli_session=sidecar.get("is_cli_session"),
+                present_in=present_in,
+                **api_lineage_extra,
+            ))
+
+        if message_count <= 0 or sid in api:
+            continue
+
+        is_hidden_snapshot = bool(sidecar.get("pre_compression_snapshot") or index_row.get("pre_compression_snapshot"))
+        if sid in api_lineage_ids or lineage_root in api_lineage_ids:
+            continue
+
+        if is_hidden_snapshot:
+            items.append(_new_item(
+                sid,
+                "lineage_missing_visible_representative",
+                "warning",
+                "repair_lineage_or_expose_tip",
+                message_count=message_count,
+                lineage_root=lineage_root,
+                present_in=present_in,
+            ))
+            continue
+
+        if not present_in["sidecar"] and not present_in["index"] and present_in["state_db"]:
+            items.append(_new_item(
+                sid,
+                "state_db_messageful_missing_sidecar",
+                "warning",
+                "materialize_sidecar_or_archive_state_row",
+                message_count=message_count,
+                lineage_root=lineage_root,
+                present_in=present_in,
+            ))
+            continue
+
+        items.append(_new_item(
+            sid,
+            "api_missing_messageful",
+            "warning",
+            "investigate_sidebar_filters_or_api_merge",
+            message_count=message_count,
+            lineage_root=lineage_root,
+            present_in=present_in,
+        ))
+
+    summary = {
+        "sessions_seen": len(all_ids),
+        "messageful": sum(1 for sid in all_ids if _max_message_count(sid, stores) > 0),
+        "visible_api": len(api),
+        "warnings": sum(1 for item in items if item.get("category") == "warning"),
+    }
+    status = "warn" if summary["warnings"] else "ok"
+    return {
+        "status": status,
+        "summary": summary,
+        "stores": {
+            "sidecar": len(sidecars),
+            "index": len(index),
+            "state_db": len(state),
+            "api": len(api),
+        },
+        "items": items,
+    }
+
+
+def _atomic_write_json(path: Path, payload) -> None:
+    tmp = path.with_suffix(path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _backup_file(path: Path, backup_dir: Path, backed_up: dict[Path, str]) -> str | None:
+    if not path.exists():
+        return None
+    resolved = path.resolve()
+    if resolved in backed_up:
+        return backed_up[resolved]
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    target = backup_dir / path.name
+    if target.exists():
+        stem = target.name
+        i = 1
+        while (backup_dir / f"{stem}.{i}").exists():
+            i += 1
+        target = backup_dir / f"{stem}.{i}"
+    shutil.copy2(path, target)
+    backed_up[resolved] = str(target)
+    return str(target)
+
+
+def _plan_discoverability_repairs(report: dict) -> list[dict]:
+    actions: list[dict] = []
+    for item in report.get("items") or []:
+        sid = str(item.get("session_id") or "")
+        if not sid:
+            continue
+        if item.get("kind") == "persisted_source_flag_stale":
+            if item.get("sidecar_is_cli_session") is True:
+                actions.append({"session_id": sid, "action": "clear_sidecar_cli_flag"})
+            if item.get("index_is_cli_session") is True:
+                actions.append({"session_id": sid, "action": "clear_index_cli_flag"})
+        elif item.get("kind") == "state_db_messageful_missing_sidecar":
+            actions.append({"session_id": sid, "action": "materialize_sidecar_from_state_db"})
+    return actions
+
+
+def _clear_sidecar_cli_flag(session_dir: Path, sid: str, backup_dir: Path, backed_up: dict[Path, str]) -> dict:
+    path = session_dir / f"{sid}.json"
+    payload = _read_json(path)
+    if not isinstance(payload, dict):
+        return {"session_id": sid, "action": "clear_sidecar_cli_flag", "applied": False, "error": "sidecar_unreadable"}
+    if not _webui_origin(payload):
+        return {"session_id": sid, "action": "clear_sidecar_cli_flag", "applied": False, "skipped": "not_webui_origin"}
+    if payload.get("is_cli_session") is not True:
+        return {"session_id": sid, "action": "clear_sidecar_cli_flag", "applied": False, "skipped": "already_clear"}
+    backup = _backup_file(path, backup_dir, backed_up)
+    payload["is_cli_session"] = False
+    _atomic_write_json(path, payload)
+    return {"session_id": sid, "action": "clear_sidecar_cli_flag", "applied": True, "backup": backup}
+
+
+def _clear_index_cli_flag(session_dir: Path, sid: str, backup_dir: Path, backed_up: dict[Path, str]) -> dict:
+    path = session_dir / "_index.json"
+    payload = _read_json(path)
+    if not isinstance(payload, list):
+        return {"session_id": sid, "action": "clear_index_cli_flag", "applied": False, "error": "index_unreadable"}
+    changed = False
+    for entry in payload:
+        if not isinstance(entry, dict):
+            continue
+        if str(entry.get("session_id") or "") != sid:
+            continue
+        if not _webui_origin(entry):
+            continue
+        if entry.get("is_cli_session") is True:
+            entry["is_cli_session"] = False
+            changed = True
+    if not changed:
+        return {"session_id": sid, "action": "clear_index_cli_flag", "applied": False, "skipped": "already_clear_or_missing"}
+    backup = _backup_file(path, backup_dir, backed_up)
+    _atomic_write_json(path, payload)
+    return {"session_id": sid, "action": "clear_index_cli_flag", "applied": True, "backup": backup}
+
+
+def _materialize_sidecar_from_state_db(session_dir: Path, state_db_path: Path | None, sid: str, backup_dir: Path, backed_up: dict[Path, str]) -> dict:
+    if state_db_path is None:
+        return {"session_id": sid, "action": "materialize_sidecar_from_state_db", "applied": False, "error": "state_db_required"}
+    target = session_dir / f"{sid}.json"
+    if target.exists():
+        return {"session_id": sid, "action": "materialize_sidecar_from_state_db", "applied": False, "skipped": "sidecar_exists"}
+    try:
+        from api.session_recovery import _read_state_db_missing_sidecar_rows, _state_db_row_to_sidecar
+    except Exception as exc:
+        return {"session_id": sid, "action": "materialize_sidecar_from_state_db", "applied": False, "error": f"recovery_import_failed:{exc}"}
+    rows = {str(row.get("id") or ""): row for row in _read_state_db_missing_sidecar_rows(session_dir, state_db_path)}
+    row = rows.get(sid)
+    if not row:
+        return {"session_id": sid, "action": "materialize_sidecar_from_state_db", "applied": False, "skipped": "state_row_not_repairable"}
+    payload = _state_db_row_to_sidecar(row)
+    _backup_file(state_db_path, backup_dir, backed_up)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_suffix(target.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    try:
+        os.link(str(tmp), str(target))
+    except FileExistsError:
+        return {"session_id": sid, "action": "materialize_sidecar_from_state_db", "applied": False, "skipped": "sidecar_appeared_during_repair"}
+    finally:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+    index_updated = False
+    index_path = session_dir / "_index.json"
+    index_payload = _read_json(index_path)
+    if not isinstance(index_payload, list):
+        index_payload = []
+    if not any(isinstance(entry, dict) and str(entry.get("session_id") or "") == sid for entry in index_payload):
+        _backup_file(index_path, backup_dir, backed_up)
+        index_entry = {key: value for key, value in payload.items() if key not in {"messages", "tool_calls"}}
+        index_payload.append(index_entry)
+        _atomic_write_json(index_path, index_payload)
+        index_updated = True
+    return {
+        "session_id": sid,
+        "action": "materialize_sidecar_from_state_db",
+        "applied": True,
+        "messages": len(payload.get("messages") or []),
+        "index_updated": index_updated,
+        "backup": str((backup_dir / state_db_path.name)) if (backup_dir / state_db_path.name).exists() else None,
+    }
+
+
+def repair_session_discoverability(
+    session_dir: Path,
+    state_db_path: Path | None = None,
+    *,
+    api_sessions: Iterable[dict] | None = None,
+    dry_run: bool = True,
+    backup_dir: Path | None = None,
+) -> dict:
+    """Plan or apply deterministic discoverability repairs.
+
+    Default mode is read-only. Applying mutations requires ``backup_dir`` and is
+    limited to stale persisted WebUI-as-CLI flags plus materializing WebUI
+    messageful sidecars from canonical state.db rows.
+    """
+    before = audit_session_discoverability(session_dir, state_db_path=state_db_path, api_sessions=api_sessions)
+    planned = _plan_discoverability_repairs(before)
+    if dry_run:
+        return {"ok": True, "dry_run": True, "planned": planned, "applied": [], "before": before, "after": before}
+    if backup_dir is None:
+        return {"ok": False, "dry_run": False, "error": "backup_dir_required_for_apply", "planned": planned, "applied": [], "before": before}
+
+    session_dir = Path(session_dir)
+    backup_dir = Path(backup_dir)
+    backed_up: dict[Path, str] = {}
+    applied: list[dict] = []
+    for action in planned:
+        sid = str(action.get("session_id") or "")
+        name = action.get("action")
+        try:
+            if name == "clear_sidecar_cli_flag":
+                applied.append(_clear_sidecar_cli_flag(session_dir, sid, backup_dir, backed_up))
+            elif name == "clear_index_cli_flag":
+                applied.append(_clear_index_cli_flag(session_dir, sid, backup_dir, backed_up))
+            elif name == "materialize_sidecar_from_state_db":
+                applied.append(_materialize_sidecar_from_state_db(session_dir, state_db_path, sid, backup_dir, backed_up))
+        except Exception as exc:
+            applied.append({"session_id": sid, "action": name, "applied": False, "error": str(exc)})
+    after = audit_session_discoverability(session_dir, state_db_path=state_db_path, api_sessions=api_sessions)
+    errors = [item for item in applied if item.get("error")]
+    return {
+        "ok": not errors,
+        "dry_run": False,
+        "planned": planned,
+        "applied": applied,
+        "backups": sorted(set(backed_up.values())),
+        "before": before,
+        "after": after,
+    }
+
+
+def render_discoverability_markdown(report: dict) -> str:
+    lines = [
+        "# WebUI Session Discoverability Audit",
+        "",
+        f"Status: `{report.get('status')}`",
+        "",
+        "## Summary",
+        "",
+    ]
+    for key, value in (report.get("summary") or {}).items():
+        lines.append(f"- `{key}`: {value}")
+    lines.extend(["", "## Stores", ""])
+    for key, value in (report.get("stores") or {}).items():
+        lines.append(f"- `{key}`: {value}")
+    lines.extend(["", "## Findings", ""])
+    items = report.get("items") or []
+    if items:
+        lines.extend(["### By kind", ""])
+        for kind, count in sorted(Counter(str(item.get("kind")) for item in items).items()):
+            lines.append(f"- `{kind}`: {count}")
+        lines.extend(["", "### Details", ""])
+    if not items:
+        lines.append("No discoverability findings.")
+    else:
+        for item in items:
+            lines.append(
+                f"- `{item.get('kind')}` `{item.get('session_id')}` "
+                f"messages={item.get('message_count', 'n/a')} recommendation=`{item.get('recommendation')}`"
+            )
+            present = item.get("present_in")
+            if isinstance(present, dict):
+                lines.append(
+                    "  - present_in: " + ", ".join(f"{k}={v}" for k, v in sorted(present.items()))
+                )
+            if item.get("represented_by_api_lineage"):
+                lines.append(
+                    f"  - represented_by_api_lineage: true via `{item.get('api_representative_session_id')}`"
+                )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description="Read-only Hermes WebUI session discoverability audit")
+    parser.add_argument("--session-dir", type=Path, required=True)
+    parser.add_argument("--state-db", type=Path, default=None)
+    parser.add_argument("--format", choices=("json", "markdown"), default="json")
+    parser.add_argument("--repair-safe", action="store_true", help="Plan/apply deterministic discoverability repairs")
+    parser.add_argument("--apply", action="store_true", help="Apply --repair-safe changes; default is dry-run")
+    parser.add_argument("--backup-dir", type=Path, default=None, help="Required with --repair-safe --apply")
+    parser.add_argument("--out", type=Path, default=None)
+    args = parser.parse_args()
+
+    if args.repair_safe:
+        report = repair_session_discoverability(
+            args.session_dir,
+            state_db_path=args.state_db,
+            dry_run=not args.apply,
+            backup_dir=args.backup_dir,
+        )
+        text = json.dumps(report, sort_keys=True)
+    else:
+        report = audit_session_discoverability(args.session_dir, state_db_path=args.state_db)
+        text = render_discoverability_markdown(report) if args.format == "markdown" else json.dumps(report, sort_keys=True)
+    if args.out:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(text, encoding="utf-8")
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

api/session_events.py

@@ -0,0 +1,107 @@
+"""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 _profile_is_root_alias(profile: str | None) -> bool:
+    name = str(profile or "").strip()
+    if not name:
+        return False
+    if name == "default":
+        return True
+    try:
+        from api.profiles import _is_root_profile
+
+        return bool(_is_root_profile(name))
+    except Exception:
+        return False
+
+
+def _sessions_changed_payload(
+    *,
+    reason: str,
+    version: int,
+    profile: str | None = None,
+) -> dict:
+    payload = {
+        "type": "sessions_changed",
+        "version": version,
+        "reason": reason,
+    }
+    normalized_profile = str(profile or "").strip()
+    # Root/default aliases must stay unscoped: browser tabs cannot infer every
+    # renamed-root alias, and an unscoped refresh preserves the old fail-safe.
+    if normalized_profile and not _profile_is_root_alias(normalized_profile):
+        payload["profile"] = normalized_profile
+    return payload
+
+
+def _payload_profile(payload: dict | None) -> str | None:
+    value = payload.get("profile") if isinstance(payload, dict) else None
+    value = str(value or "").strip()
+    return value or None
+
+
+def _coalesced_sessions_changed_payload(pending: dict | None, incoming: dict) -> dict:
+    """Merge bounded-queue refresh events without dropping profile-relevant work.
+
+    A maxsize=1 queue is safe only while all events are interchangeable. Once
+    events can be profile-scoped, replacing profile A with profile B can make
+    an A tab ignore the queued event and miss the refresh entirely. On any
+    scope mismatch, fall back to an unscoped refresh-all event.
+    """
+    if pending is None:
+        return incoming
+    pending_profile = _payload_profile(pending)
+    incoming_profile = _payload_profile(incoming)
+    if pending_profile == incoming_profile:
+        return incoming
+    merged = dict(incoming)
+    merged.pop("profile", None)
+    return merged
+
+
+def publish_session_list_changed(
+    reason: str = "session_changed",
+    profile: str | None = None,
+) -> None:
+    """Notify connected browsers that the session sidebar may be stale."""
+    global _SESSION_EVENTS_VERSION
+    with _SESSION_EVENTS_LOCK:
+        _SESSION_EVENTS_VERSION += 1
+        payload = _sessions_changed_payload(
+            reason=reason,
+            version=_SESSION_EVENTS_VERSION,
+            profile=profile,
+        )
+        subscribers = list(_SESSION_EVENTS_SUBSCRIBERS)
+    for q in subscribers:
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            pending = None
+            try:
+                pending = q.get_nowait()
+            except queue.Empty:
+                pass
+            try:
+                q.put_nowait(_coalesced_sessions_changed_payload(pending, 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,241 @@
+"""
+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 discard_session(session_id: str) -> bool:
+    """Permanently drop a session's lifecycle entry to bound memory growth.
+
+    The ``_sessions`` dict is process-global and historically only ever grew:
+    ``register_agent`` / ``mark_turn_completed`` insert keys but no runtime path
+    ever removed them, so every unique ``session_id`` the WebUI touched leaked a
+    permanent entry (issue #3506). Over days of use on a large install this is a
+    monotonic, unbounded climb.
+
+    This removes the entry, but only when it is provably safe to do so: no commit
+    is in flight and there is no uncommitted memory work that still needs the
+    retained agent handle. If the entry is busy or dirty it is left untouched so
+    failed batch-extraction memory work stays retryable -- exactly the invariant
+    ``unregister_agent`` and ``_evict_session_agent`` already preserve.
+
+    Returns True when the entry was removed (or was already absent), False when
+    it was retained because work is still pending.
+    """
+    if not session_id:
+        return False
+    with _condition:
+        entry = _sessions.get(session_id)
+        if entry is None:
+            return True
+        if entry["in_flight"]:
+            return False
+        if entry["generation"] > entry["committed_generation"]:
+            return False
+        del _sessions[session_id]
+        _condition.notify_all()
+        return True
+
+
+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_ops.py

@@ -9,11 +9,63 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-from api.config import LOCK
+from api.config import LOCK, _get_session_agent_lock
 from api.models import get_session, SESSIONS
 
 logger = logging.getLogger(__name__)
 
+AUTO_TITLE_LABELS = {'untitled', 'new chat'}
+
+
+def session_has_manual_title(session) -> bool:
+    """Return whether adaptive title refresh should leave this title alone."""
+    return getattr(session, 'manual_title', False) is True
+
+
+def apply_session_title_rename(session, raw_title) -> str:
+    """Apply user-driven rename semantics to a Session object.
+
+    Non-empty custom titles are protected from adaptive refresh. Clearing the
+    title, or resetting it to an automatic label, removes that protection so the
+    normal auto-title path can run again.
+    """
+    title = str(raw_title or '').strip()[:80]
+    if not title:
+        title = 'Untitled'
+    manual_title = title.strip().casefold() not in AUTO_TITLE_LABELS
+    session.title = title
+    session.manual_title = manual_title
+    session.llm_title_generated = False
+    return title
+
+
+def mark_session_title_generated(session) -> None:
+    """Mark a session title as generated by the title model."""
+    session.llm_title_generated = True
+    session.manual_title = False
+
+
+def _truncate_at_last_user(messages):
+    history = messages or []
+    last_user_idx = None
+    for i in range(len(history) - 1, -1, -1):
+        if isinstance(history[i], dict) and history[i].get('role') == 'user':
+            last_user_idx = i
+            break
+    if last_user_idx is None:
+        return None
+    return history[:last_user_idx]
+
+
+def _truncation_watermark_for(messages):
+    history = list(messages or [])
+    if not history:
+        return 0.0
+    try:
+        return float(history[-1].get('timestamp') or 0)
+    except (AttributeError, TypeError, ValueError):
+        return 0.0
+
 
 def retry_last(session_id: str) -> dict[str, Any]:
     """Truncate the session to before the last user message, return its text.
@@ -27,38 +79,48 @@ def retry_last(session_id: str) -> dict[str, Any]:
         KeyError: session not found
         ValueError: no user message in transcript
     """
-    # get_session() and Session.save() both acquire the module-level LOCK
-    # internally (the latter via _write_session_index()), and LOCK is a
-    # non-reentrant threading.Lock — so they MUST be called outside our
-    # own `with LOCK:` block to avoid self-deadlocking.
-    #
-    # The race we close is the read-modify-write of s.messages: two
-    # concurrent /api/session/retry calls could otherwise both compute the
-    # same last_user_idx from the same history and double-truncate. We
-    # serialize just the in-memory mutation; persistence happens outside
-    # the lock and is naturally last-write-wins on a consistent state.
-    #
-    # Stale-object guard: on a cache miss, two concurrent get_session()
-    # calls can each load and cache a *different* Session instance for the
-    # same session_id (the second store_clobbers the first). Re-bind to
-    # the canonical cached instance inside the lock so the mutation lands
-    # on the object the next reader will see, not a stale parallel copy.
-    s = get_session(session_id)  # raises KeyError if missing
-    with LOCK:
-        s = SESSIONS.get(session_id, s)
-        history = s.messages or []
-        last_user_idx = None
-        for i in range(len(history) - 1, -1, -1):
-            if history[i].get('role') == 'user':
-                last_user_idx = i
-                break
-        if last_user_idx is None:
-            raise ValueError('No previous message to retry.')
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        # get_session() and Session.save() both acquire the module-level LOCK
+        # internally (the latter via _write_session_index()), and LOCK is a
+        # non-reentrant threading.Lock — so they MUST be called outside our
+        # own `with LOCK:` block to avoid self-deadlocking.
+        #
+        # The race we close is the read-modify-write of s.messages: two
+        # concurrent /api/session/retry calls could otherwise both compute the
+        # same last_user_idx from the same history and double-truncate. We
+        # serialize just the in-memory mutation; persistence happens inside
+        # the per-session lock so the checkpoint thread cannot race us.
+        #
+        # Stale-object guard: on a cache miss, two concurrent get_session()
+        # calls can each load and cache a *different* Session instance for the
+        # same session_id (the second store clobbers the first). Re-bind to
+        # the canonical cached instance inside the lock so the mutation lands
+        # on the object the next reader will see, not a stale parallel copy.
+        s = get_session(session_id)  # raises KeyError if missing
+        with LOCK:
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('No previous message to retry.')
 
-        last_user_text = _extract_text(history[last_user_idx].get('content', ''))
-        removed_count = len(history) - last_user_idx
-        s.messages = history[:last_user_idx]
-    s.save()
+            last_user_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            s.truncation_watermark = _truncation_watermark_for(s.messages)
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()
     return {'last_user_text': last_user_text, 'removed_count': removed_count}
 
 
@@ -72,23 +134,33 @@ def undo_last(session_id: str) -> dict[str, Any]:
         KeyError: session not found
         ValueError: no user message in transcript
     """
-    s = get_session(session_id)  # acquires LOCK transiently
-    with LOCK:
-        # Stale-object guard — see retry_last for the rationale.
-        s = SESSIONS.get(session_id, s)
-        history = s.messages or []
-        last_user_idx = None
-        for i in range(len(history) - 1, -1, -1):
-            if history[i].get('role') == 'user':
-                last_user_idx = i
-                break
-        if last_user_idx is None:
-            raise ValueError('Nothing to undo.')
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        s = get_session(session_id)  # acquires LOCK transiently
+        with LOCK:
+            # Stale-object guard — see retry_last for the rationale.
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('Nothing to undo.')
 
-        removed_text = _extract_text(history[last_user_idx].get('content', ''))
-        removed_count = len(history) - last_user_idx
-        s.messages = history[:last_user_idx]
-    s.save()  # outside LOCK -- save() re-acquires LOCK via _write_session_index()
+            removed_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            s.truncation_watermark = _truncation_watermark_for(s.messages)
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()  # outside LOCK -- save() re-acquires LOCK via _write_session_index()
     preview = (removed_text[:40] + '...') if len(removed_text) > 40 else removed_text
     return {
         'removed_count': removed_count,
@@ -105,16 +177,30 @@ def session_status(session_id: str) -> dict[str, Any]:
     (active_stream_id is set).
     """
     s = get_session(session_id)
+    inp = int(s.input_tokens or 0)
+    out = int(s.output_tokens or 0)
+    profile = getattr(s, 'profile', None) or 'default'
+    try:
+        from api.profiles import get_hermes_home_for_profile
+        hermes_home = str(get_hermes_home_for_profile(profile))
+    except Exception:
+        hermes_home = ''
     return {
         'session_id': s.session_id,
         'title': s.title,
         'model': s.model,
+        'profile': profile,
+        'hermes_home': hermes_home,
         'workspace': s.workspace,
         'personality': s.personality,
         'message_count': len(s.messages or []),
         'created_at': s.created_at,
         'updated_at': s.updated_at,
         'agent_running': bool(getattr(s, 'active_stream_id', None)),
+        'input_tokens': inp,
+        'output_tokens': out,
+        'total_tokens': inp + out,
+        'estimated_cost': s.estimated_cost,
     }
 
 

api/session_recovery.py

@@ -0,0 +1,657 @@
+"""
+Session recovery from .bak snapshots — last line of defense against
+data-loss bugs like #1558.
+
+``Session.save()`` writes a ``<sid>.json.bak`` snapshot of the previous
+state whenever an incoming save would shrink the messages array. This
+module reads those snapshots back and restores any session whose live
+file has fewer messages than its backup, 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, 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
+   manually if their session was open through a server restart.
+
+3. ``inspect_session_recovery_status(sid)`` — read-only audit returning
+   message counts for the live JSON, the .bak, and a recommendation.
+"""
+from __future__ import annotations
+
+import 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__)
+
+
+def _msg_count(p: Path) -> int:
+    """Return the number of messages in a session JSON file, or -1 on read/parse error.
+
+    Returns -1 for any non-session-shape file:
+    - File can't be read (OSError)
+    - Top-level isn't valid JSON or is invalid (JSONDecodeError, ValueError)
+    - Top-level isn't a dict (AttributeError on .get) — e.g. ``_index.json``
+      which is a top-level list of session metadata, not a session itself.
+      The startup recovery scanner globs ``*.json`` and would otherwise
+      crash on the first non-dict file it encounters.
+    """
+    try:
+        data = json.loads(p.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return -1
+    if not isinstance(data, dict):
+        return -1
+    msgs = data.get('messages')
+    return len(msgs) if isinstance(msgs, list) else -1
+
+
+def inspect_session_recovery_status(session_path: Path) -> dict:
+    """Return a status dict describing whether recovery is recommended.
+
+    {
+      "session_id": "...",
+      "live_messages": int,    # -1 if live file unreadable
+      "bak_messages": int,     # -1 if no .bak or unreadable
+      "recommend": "restore" | "no_action" | "no_backup",
+    }
+    """
+    bak_path = session_path.with_suffix('.json.bak')
+    live_count = _msg_count(session_path)
+    if not bak_path.exists():
+        return {
+            "session_id": session_path.stem,
+            "live_messages": live_count,
+            "bak_messages": -1,
+            "recommend": "no_backup",
+        }
+    bak_count = _msg_count(bak_path)
+    if bak_count > live_count:
+        return {
+            "session_id": session_path.stem,
+            "live_messages": live_count,
+            "bak_messages": bak_count,
+            "recommend": "restore",
+        }
+    return {
+        "session_id": session_path.stem,
+        "live_messages": live_count,
+        "bak_messages": bak_count,
+        "recommend": "no_action",
+    }
+
+
+def recover_session(session_path: Path) -> dict:
+    """Restore session_path from its .bak when the bak has more messages.
+
+    Returns a status dict identical to ``inspect_session_recovery_status``
+    plus a "restored" boolean.
+    """
+    status = inspect_session_recovery_status(session_path)
+    if status["recommend"] != "restore":
+        return {**status, "restored": False}
+    bak_path = session_path.with_suffix('.json.bak')
+    # Stage the recovery via a tmp copy + atomic replace so a crash mid-restore
+    # cannot leave a half-written session.json.
+    tmp_path = session_path.with_suffix('.json.recover.tmp')
+    try:
+        shutil.copyfile(bak_path, tmp_path)
+        tmp_path.replace(session_path)
+    except OSError as exc:
+        logger.warning("recover_session: copy failed for %s: %s", session_path, exc)
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return {**status, "restored": False, "error": str(exc)}
+    logger.warning(
+        "recover_session: restored %s from .bak (live=%d → bak=%d messages). "
+        "See #1558 for the data-loss class this guards against.",
+        session_path.name, status["live_messages"], status["bak_messages"],
+    )
+    return {**status, "restored": True}
+
+
+def _state_db_has_session(session_id: str, state_db_path: Path | None) -> bool:
+    """Return whether state.db still knows this session.
+
+    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 {
+            "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": []}
+    restored = 0
+    details: list[dict] = []
+    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)
+    # Only sessions with a backup can be restored through this startup path.
+    # Older code called recover_session() for every live sidecar, and
+    # inspect_session_recovery_status() read the complete JSON file before even
+    # checking whether <sid>.json.bak existed. Large WebUI installs therefore
+    # parsed the entire session corpus on every boot even when there was
+    # nothing to recover. Keep the public scanned count compatible, but limit
+    # expensive reads to actual recovery candidates.
+    recovery_paths = [path for path in live_paths if path.with_suffix('.json.bak').exists()]
+    scanned = len(live_paths) + len(orphan_paths)
+    for path in [*recovery_paths, *orphan_paths]:
+        try:
+            result = recover_session(path)
+        except Exception as exc:
+            # Defensive: a malformed session file shouldn't break recovery
+            # for the rest. Log and continue.
+            logger.warning(
+                "recover_all_sessions_on_startup: skipped %s due to %s: %s",
+                path.name, type(exc).__name__, exc,
+            )
+            continue
+        if result.get("restored"):
+            restored += 1
+            details.append(result)
+    if restored:
+        logger.warning(
+            "recover_all_sessions_on_startup: restored %d/%d sessions from .bak. "
+            "If you weren't expecting this, check the session list for missing "
+            "messages — see #1558.", restored, scanned,
+        )
+    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/skill_usage.py

@@ -0,0 +1,32 @@
+# ── Skill usage reader (read-only) ──
+# Note: .usage.json is written by hermes-agent (tools/skill_usage.py).
+# WebUI only reads to display usage stats in Insights page.
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_USAGE_FILE = ".usage.json"
+
+
+def read_skill_usage(skills_dir: Path) -> dict:
+    """Read the current .usage.json.
+
+    Returns the raw nested dict ``{skill_name: {use_count: N, view_count: N, ...}}``
+    or an empty dict when the file does not exist or is corrupt.
+    """
+    usage_path = skills_dir / _USAGE_FILE
+    if not usage_path.exists():
+        return {}
+    try:
+        raw = usage_path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if isinstance(data, dict):
+            return data
+        logger.debug("Unexpected .usage.json format, resetting: %s", raw[:200])
+        return {}
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.debug("Failed to read .usage.json: %s", exc)
+        return {}

api/startup.py

@@ -14,7 +14,25 @@ _SENSITIVE_FILES = (
 
 
 def fix_credential_permissions() -> None:
-    """Ensure sensitive files in HERMES_HOME are chmod 600 (owner-only)."""
+    """Ensure sensitive files in HERMES_HOME have safe permissions.
+
+    Respects:
+      - HERMES_SKIP_CHMOD=1  → bypass entirely
+      - HERMES_HOME_MODE     → group bits are allowed if set by the operator,
+                               only world-readable/world-writable files are fixed
+    """
+    if os.environ.get('HERMES_SKIP_CHMOD', '').strip() in ('1', 'true'):
+        return
+
+    # Parse operator-declared mode to know if group bits are intentional
+    declared_mode = None
+    raw_mode = os.environ.get('HERMES_HOME_MODE', '').strip()
+    if raw_mode:
+        try:
+            declared_mode = int(raw_mode, 8)
+        except ValueError:
+            pass
+
     hermes_home = Path(os.environ.get('HERMES_HOME', str(Path.home() / '.hermes')))
     if not hermes_home.is_dir():
         return
@@ -24,9 +42,15 @@ def fix_credential_permissions() -> None:
             continue
         try:
             current = stat.S_IMODE(fpath.stat().st_mode)
-            if current & 0o077:  # group or other bits set
-                fpath.chmod(0o600)
-                print(f'  [security] fixed permissions on {fpath.name} ({oct(current)} -> 0600)', flush=True)
+            # If operator declared a mode, allow group bits but still fix world bits
+            if declared_mode is not None:
+                if current & 0o007:  # other bits set (world-readable/writable)
+                    fpath.chmod(current & ~0o007)
+                    print(f'  [security] removed world bits on {fpath.name} ({oct(current)} -> {oct(current & ~0o007)})', flush=True)
+            else:
+                if current & 0o077:  # group or other bits set
+                    fpath.chmod(0o600)
+                    print(f'  [security] fixed permissions on {fpath.name} ({oct(current)} -> 0600)', flush=True)
         except OSError:
             pass  # best-effort; don't abort startup
 
@@ -41,11 +65,41 @@ def _agent_dir() -> Path | None:
             return p.resolve()
     return None
 
+def _trusted_agent_dir(agent_dir: Path) -> bool:
+    """Return True if agent_dir passes ownership and permission checks.
+
+    Validates that the directory is not world- or group-writable and,
+    on POSIX systems, is owned by the current process user.
+
+    Intentionally does NOT enforce a canonical path (i.e. does not require
+    the dir to be ~/.hermes/hermes-agent), so custom HERMES_WEBUI_AGENT_DIR
+    paths work correctly when HERMES_WEBUI_AUTO_INSTALL=1 is set.
+    """
+    try:
+        st = agent_dir.stat()
+        if stat.S_IMODE(st.st_mode) & 0o022:
+            # World- or group-writable — untrusted
+            return False
+        if hasattr(os, 'getuid') and st.st_uid != os.getuid():
+            # Not owned by current user (POSIX only; Windows fallback skips)
+            return False
+        return True
+    except OSError:
+        return False
+
+
 def auto_install_agent_deps() -> bool:
+    enabled = os.environ.get('HERMES_WEBUI_AUTO_INSTALL', '').strip().lower() in ('1', 'true', 'yes')
+    if not enabled:
+        print('[!!] Auto-install disabled. Set HERMES_WEBUI_AUTO_INSTALL=1 to enable.', flush=True)
+        return False
     agent_dir = _agent_dir()
     if agent_dir is None:
         print('[!!] Auto-install skipped: agent directory not found.', flush=True)
         return False
+    if not _trusted_agent_dir(agent_dir):
+        print('[!!] Auto-install skipped: agent directory failed trust check (check ownership/permissions).', flush=True)
+        return False
     req_file = agent_dir / 'requirements.txt'
     pyproject = agent_dir / 'pyproject.toml'
     if req_file.exists():

api/state_sync.py

@@ -16,26 +16,83 @@ any double-counting risk.
 import logging
 import os
 from pathlib import Path
+from typing import Optional
 
 logger = logging.getLogger(__name__)
 
 
-def _get_state_db():
-    """Get a SessionDB instance for the active profile's state.db.
-    Returns None if hermes_state is not importable or DB is unavailable.
-    Each caller is responsible for calling db.close() when done.
+def _get_state_db(profile: Optional[str] = None):
+    """Get a SessionDB instance for a profile's state.db.
+
+    When ``profile`` is provided the function resolves *that* profile's
+    home directory directly (via ``_resolve_profile_home_for_name``).
+    If resolution fails (unknown profile name, IO error, etc.) the
+    function returns ``None`` rather than silently falling back to
+    ``HERMES_HOME`` — silently routing the write to the wrong DB
+    would defeat the point of the explicit-profile path (#2762).
+
+    When ``profile`` is None it falls back to the TLS-based
+    ``get_active_hermes_home()`` lookup for backward compatibility,
+    with a final ``HERMES_HOME`` fallback only on that path. TLS may be
+    unset in background/worker threads, in which case the lookup falls
+    through to the process-global active profile and can write to the
+    wrong DB. Callers that know the session's profile (e.g.
+    ``sync_session_usage`` after a stream completes on a background
+    thread) should pass it explicitly to avoid that race.
+
+    Returns None if hermes_state is not importable, the explicit
+    profile cannot be resolved, or the DB is unavailable. Each caller
+    is responsible for calling db.close() when done.
     """
     try:
         from hermes_state import SessionDB
     except ImportError:
         return None
 
-    try:
-        from api.profiles import get_active_hermes_home
-        hermes_home = Path(get_active_hermes_home()).expanduser().resolve()
-    except Exception:
-        logger.debug("Failed to resolve hermes home, using default")
-        hermes_home = Path(os.getenv('HERMES_HOME', str(Path.home() / '.hermes')))
+    if profile is not None:
+        # Explicit-profile path — a resolution failure here MUST NOT
+        # silently fall back to HERMES_HOME or the caller's "write to
+        # the named profile" contract is broken (the original #2762
+        # symptom: writes leaking into the wrong profile's state.db).
+        #
+        # Defense-in-depth (per #2827 maintainer review): validate the
+        # name shape BEFORE handing it to ``_resolve_profile_home_for_name``.
+        # The resolver itself rarely raises — for an invalid-but-non-
+        # malicious name (e.g. one that fails ``_PROFILE_ID_RE``) it
+        # quietly returns ``_DEFAULT_HERMES_HOME``, which is the exact
+        # leak we're trying to prevent on the explicit-profile path.
+        # Validating up-front turns that quiet leak into an explicit
+        # "refuse + log + return None" so the contract is "write to
+        # the EXACT named profile, or write nowhere."
+        try:
+            from api.profiles import (
+                _resolve_profile_home_for_name,
+                _PROFILE_ID_RE,
+                _is_root_profile,
+            )
+            if not (_is_root_profile(profile) or _PROFILE_ID_RE.fullmatch(profile)):
+                logger.warning(
+                    "state_sync: refusing invalid profile name %r — skipping "
+                    "write rather than leaking to the default state.db (#2762).",
+                    profile,
+                )
+                return None
+            hermes_home = Path(_resolve_profile_home_for_name(profile)).expanduser().resolve()
+        except Exception:
+            logger.warning(
+                "state_sync: could not resolve profile %r — skipping write rather "
+                "than leaking to the active profile (#2762).", profile,
+            )
+            return None
+    else:
+        # Implicit / TLS-fallback path — preserves pre-#2762 behavior
+        # for any caller that doesn't pass profile= explicitly.
+        try:
+            from api.profiles import get_active_hermes_home
+            hermes_home = Path(get_active_hermes_home()).expanduser().resolve()
+        except Exception:
+            logger.debug("Failed to resolve hermes home, using default")
+            hermes_home = Path(os.getenv('HERMES_HOME', str(Path.home() / '.hermes')))
 
     db_path = hermes_home / 'state.db'
     if not db_path.exists():
@@ -48,11 +105,16 @@ def _get_state_db():
         return None
 
 
-def sync_session_start(session_id: str, model=None) -> None:
+def sync_session_start(session_id: str, model=None, profile: Optional[str] = None) -> None:
     """Register a WebUI session in state.db (idempotent).
     Called when a session's first message is sent.
+
+    ``profile`` lets the caller name the target state.db explicitly,
+    avoiding the TLS-vs-background-thread mismatch in #2762. When
+    omitted, the active profile is resolved from TLS (then process
+    globals) as before.
     """
-    db = _get_state_db()
+    db = _get_state_db(profile=profile)
     if not db:
         return
     try:
@@ -71,13 +133,21 @@ def sync_session_start(session_id: str, model=None) -> None:
 
 
 def sync_session_usage(session_id: str, input_tokens: int=0, output_tokens: int=0,
-                       estimated_cost=None, model=None, title: str=None,
-                       message_count: int=None) -> None:
+                       estimated_cost=None, model=None, title: Optional[str] = None,
+                       message_count: Optional[int] = None, profile: Optional[str] = None) -> None:
     """Update token usage and title for a WebUI session in state.db.
     Called after each turn completes. Uses absolute=True to set totals
     (the WebUI Session already accumulates across turns).
+
+    ``profile`` lets the caller name the target state.db explicitly,
+    which is what fixes #2762: this function is invoked from the
+    agent streaming worker thread, where the request-thread's TLS
+    profile context has not been propagated. Without an explicit
+    profile, the TLS lookup falls back to the process-global active
+    profile and writes the session's usage to the wrong state.db
+    (e.g. ``hiyuki``'s instead of the cookie-switched ``maiko``'s).
     """
-    db = _get_state_db()
+    db = _get_state_db(profile=profile)
     if not db:
         return
     try:

api/system_health.py

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

api/terminal.py

@@ -0,0 +1,460 @@
+"""Embedded workspace terminal support for Hermes Web UI.
+
+The terminal is intentionally independent from the agent execution path.  It
+starts a shell with an explicit cwd/env per process and never mutates
+process-global os.environ, which avoids expanding the session-env race tracked
+in the agent execution layer.
+"""
+
+from __future__ import annotations
+
+import errno
+import atexit
+import codecs
+import os
+import queue
+import shutil
+import signal
+import struct
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_TERMINAL_SUPPORTED = sys.platform != "win32"
+
+if _TERMINAL_SUPPORTED:
+    import fcntl
+    import select
+    import termios
+else:
+    fcntl = None  # type: ignore[assignment]
+    select = None  # type: ignore[assignment]
+    termios = None  # type: ignore[assignment]
+
+
+def _set_nonblocking(fd: int) -> None:
+    flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+    fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+
+def _winsize(rows: int, cols: int) -> bytes:
+    rows = max(8, min(int(rows or 24), 80))
+    cols = max(20, min(int(cols or 80), 240))
+    return struct.pack("HHHH", rows, cols, 0, 0)
+
+
+def _safe_close_fd(fd: int) -> None:
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+
+
+@dataclass
+class TerminalSession:
+    session_id: str
+    workspace: str
+    proc: subprocess.Popen
+    master_fd: int
+    rows: int = 24
+    cols: int = 80
+    output: queue.Queue = field(default_factory=lambda: queue.Queue(maxsize=2000))
+    closed: threading.Event = field(default_factory=threading.Event)
+    reader: threading.Thread | None = None
+
+    def is_alive(self) -> bool:
+        return not self.closed.is_set() and self.proc.poll() is None
+
+    def put_output(self, event: str, payload: dict) -> None:
+        try:
+            self.output.put_nowait((event, payload))
+        except queue.Full:
+            # Keep the terminal responsive by dropping the oldest queued chunk.
+            try:
+                self.output.get_nowait()
+            except queue.Empty:
+                pass
+            try:
+                self.output.put_nowait((event, payload))
+            except queue.Full:
+                pass
+
+
+_TERMINALS: dict[str, TerminalSession] = {}
+_LOCK = threading.RLock()
+_spawn_queue: queue.Queue = queue.Queue()
+_spawn_supervisor_started = False
+_spawn_supervisor_lock = threading.Lock()
+_spawn_supervisor_thread: threading.Thread | None = None
+_terminal_descendant_reaper_lock = threading.Lock()
+_TERMINAL_DESCENDANT_REAPER_LIMIT = 64
+
+
+@dataclass
+class _SpawnRequest:
+    kwargs: dict
+    done: threading.Event = field(default_factory=threading.Event)
+    timed_out: threading.Event = field(default_factory=threading.Event)
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    proc: subprocess.Popen | None = None
+    error: BaseException | None = None
+
+
+def _reap_abandoned_spawn(proc: subprocess.Popen) -> bool:
+    if proc.poll() is not None:
+        return True
+    try:
+        os.killpg(proc.pid, signal.SIGHUP)
+    except (OSError, ProcessLookupError):
+        try:
+            proc.terminate()
+        except (OSError, ProcessLookupError):
+            pass
+    try:
+        proc.wait(timeout=1.0)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except (OSError, ProcessLookupError):
+            try:
+                proc.kill()
+            except (OSError, ProcessLookupError):
+                pass
+        try:
+            proc.wait(timeout=1.0)
+        except (subprocess.TimeoutExpired, ProcessLookupError):
+            pass
+    if proc.poll() is None:
+        print("terminal abandoned spawn cleanup failed", flush=True)
+        return False
+    return True
+
+
+def _reap_terminal_descendants(
+    terminal_pgid: int,
+    limit: int = _TERMINAL_DESCENDANT_REAPER_LIMIT,
+) -> int:
+    """Reap exited descendants that still belong to a terminal-owned process group."""
+    if not _TERMINAL_SUPPORTED:
+        return 0
+    try:
+        terminal_pgid = abs(int(terminal_pgid))
+    except (TypeError, ValueError):
+        return 0
+    if terminal_pgid <= 0:
+        return 0
+    reaped = 0
+    with _terminal_descendant_reaper_lock:
+        for _ in range(max(0, int(limit))):
+            try:
+                pid, _status = os.waitpid(-terminal_pgid, os.WNOHANG)
+            except (ChildProcessError, OSError):
+                break
+            if pid == 0:
+                break
+            reaped += 1
+    return reaped
+
+
+def _spawn_supervisor_loop() -> None:
+    while True:
+        request = None
+        try:
+            request = _spawn_queue.get()
+            try:
+                proc = subprocess.Popen(**request.kwargs)
+                with request.lock:
+                    if request.timed_out.is_set():
+                        _reap_abandoned_spawn(proc)
+                    else:
+                        request.proc = proc
+                    request.done.set()
+            except BaseException as exc:
+                with request.lock:
+                    try:
+                        request.error = exc
+                    except BaseException:
+                        pass
+                    request.done.set()
+        except BaseException as exc:
+            if request is not None:
+                try:
+                    request.error = exc
+                except BaseException:
+                    pass
+                try:
+                    request.done.set()
+                except BaseException:
+                    pass
+            time.sleep(0.01)
+
+
+def _spawn_supervisor_entry() -> None:
+    while True:
+        try:
+            _spawn_supervisor_loop()
+        except BaseException:
+            time.sleep(0.01)
+            pass
+
+
+def _ensure_spawn_supervisor() -> None:
+    global _spawn_supervisor_started, _spawn_supervisor_thread
+    with _spawn_supervisor_lock:
+        if _spawn_supervisor_started and _spawn_supervisor_thread and _spawn_supervisor_thread.is_alive():
+            return
+        thread = threading.Thread(target=_spawn_supervisor_entry, daemon=True)
+        thread.start()
+        _spawn_supervisor_thread = thread
+        _spawn_supervisor_started = True
+
+
+if _TERMINAL_SUPPORTED:
+    _ensure_spawn_supervisor()
+
+
+# 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)
+
+
+def _shell_path() -> str:
+    shell = os.environ.get("SHELL") or ""
+    if shell and Path(shell).exists():
+        return shell
+    return shutil.which("zsh") or shutil.which("bash") or shutil.which("sh") or "/bin/sh"
+
+
+def _shell_argv(shell: str) -> list[str]:
+    name = Path(shell).name
+    if name in {"zsh", "bash", "sh"}:
+        return [shell, "-i"]
+    return [shell]
+
+
+def _reader_loop(term: TerminalSession) -> None:
+    decoder = codecs.getincrementaldecoder("utf-8")("replace")
+    try:
+        while not term.closed.is_set():
+            if term.proc.poll() is not None:
+                break
+            try:
+                ready, _, _ = select.select([term.master_fd], [], [], 0.25)
+            except (OSError, ValueError):
+                break
+            if not ready:
+                continue
+            try:
+                data = os.read(term.master_fd, 8192)
+            except OSError as exc:
+                if exc.errno in (errno.EIO, errno.EBADF):
+                    break
+                raise
+            if not data:
+                break
+            text = _decode_terminal_output(decoder, data)
+            if text:
+                term.put_output("output", {"text": text})
+    except Exception as exc:
+        term.put_output("terminal_error", {"error": str(exc)})
+    finally:
+        term.closed.set()
+        code = term.proc.poll()
+        _reap_terminal_descendants(term.proc.pid)
+        term.put_output("terminal_closed", {"exit_code": code})
+
+
+def _set_size(term: TerminalSession, rows: int, cols: int) -> None:
+    term.rows = max(8, min(int(rows or term.rows or 24), 80))
+    term.cols = max(20, min(int(cols or term.cols or 80), 240))
+    try:
+        fcntl.ioctl(term.master_fd, termios.TIOCSWINSZ, _winsize(term.rows, term.cols))
+    except OSError:
+        pass
+    try:
+        if term.proc.poll() is None:
+            os.killpg(term.proc.pid, signal.SIGWINCH)
+    except (OSError, ProcessLookupError):
+        pass
+
+
+def start_terminal(session_id: str, workspace: Path, rows: int = 24, cols: int = 80, restart: bool = False) -> TerminalSession:
+    """Start or return the embedded terminal for a WebUI session."""
+    if not _TERMINAL_SUPPORTED:
+        raise NotImplementedError("Embedded terminal is not supported on Windows")
+    sid = str(session_id or "").strip()
+    if not sid:
+        raise ValueError("session_id is required")
+    cwd = str(Path(workspace).expanduser().resolve())
+    if not Path(cwd).is_dir():
+        raise ValueError("workspace is not a directory")
+
+    with _LOCK:
+        current = _TERMINALS.get(sid)
+        if current and current.is_alive() and not restart and current.workspace == cwd:
+            _set_size(current, rows, cols)
+            return current
+        if current:
+            close_terminal(sid)
+
+        master_fd, slave_fd = os.openpty()
+        # Build a safe env: allowlist common shell vars, strip API keys and secrets.
+        # The PTY shell is an interactive UI surface — do not leak server credentials.
+        _SAFE_ENV_KEYS = {
+            "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL",
+            "LC_CTYPE", "LC_MESSAGES", "LANGUAGE", "TZ", "TMPDIR", "TEMP",
+            "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME",
+        }
+        env = {k: v for k, v in os.environ.items() if k in _SAFE_ENV_KEYS}
+        env.update(
+            {
+                "TERM": "xterm-256color",
+                "COLORTERM": "truecolor",
+                "COLUMNS": str(cols),
+                "LINES": str(rows),
+                "PWD": cwd,
+                "HERMES_WEBUI_TERMINAL": "1",
+            }
+        )
+        shell = _shell_path()
+        # Keep the shell in its own process group for explicit cleanup via
+        # close_terminal()/close_all_terminals(); do not use PDEATHSIG here.
+        request = _SpawnRequest(
+            {
+                "args": _shell_argv(shell),
+                "cwd": cwd,
+                "env": env,
+                "stdin": slave_fd,
+                "stdout": slave_fd,
+                "stderr": slave_fd,
+                "close_fds": True,
+                # Required so cleanup can signal the whole interactive shell tree.
+                "start_new_session": True,
+            }
+        )
+        _ensure_spawn_supervisor()
+        _spawn_queue.put(request)
+        try:
+            if not request.done.wait(timeout=5.0):
+                timed_out = False
+                with request.lock:
+                    if not request.done.is_set():
+                        request.timed_out.set()
+                        timed_out = True
+                if timed_out:
+                    raise TimeoutError("terminal spawn timeout - supervisor unresponsive")
+            if request.error:
+                raise request.error
+            proc = request.proc
+            if proc is None:
+                raise RuntimeError("terminal spawn failed without process")
+        except BaseException:
+            _safe_close_fd(master_fd)
+            _safe_close_fd(slave_fd)
+            raise
+        os.close(slave_fd)
+        _set_nonblocking(master_fd)
+
+        term = TerminalSession(
+            session_id=sid,
+            workspace=cwd,
+            proc=proc,
+            master_fd=master_fd,
+            rows=rows,
+            cols=cols,
+        )
+        _set_size(term, rows, cols)
+        term.reader = threading.Thread(target=_reader_loop, args=(term,), daemon=True)
+        term.reader.start()
+        _TERMINALS[sid] = term
+        return term
+
+
+def get_terminal(session_id: str) -> TerminalSession | None:
+    if not _TERMINAL_SUPPORTED:
+        return None
+    with _LOCK:
+        term = _TERMINALS.get(str(session_id or ""))
+        if term and term.is_alive():
+            return term
+        return term
+
+
+def write_terminal(session_id: str, data: str) -> None:
+    if not _TERMINAL_SUPPORTED:
+        raise NotImplementedError("Embedded terminal is not supported on Windows")
+    term = get_terminal(session_id)
+    if not term or not term.is_alive():
+        raise KeyError("terminal not running")
+    os.write(term.master_fd, str(data or "").encode("utf-8", errors="replace"))
+
+
+def resize_terminal(session_id: str, rows: int, cols: int) -> None:
+    if not _TERMINAL_SUPPORTED:
+        raise NotImplementedError("Embedded terminal is not supported on Windows")
+    term = get_terminal(session_id)
+    if not term:
+        raise KeyError("terminal not running")
+    _set_size(term, rows, cols)
+
+
+def close_terminal(session_id: str) -> bool:
+    if not _TERMINAL_SUPPORTED:
+        return False
+    sid = str(session_id or "")
+    with _LOCK:
+        term = _TERMINALS.pop(sid, None)
+    if not term:
+        return False
+    term.closed.set()
+    try:
+        if term.proc.poll() is None:
+            try:
+                os.killpg(term.proc.pid, signal.SIGHUP)
+            except ProcessLookupError:
+                pass
+            try:
+                term.proc.wait(timeout=1.5)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(term.proc.pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+                try:
+                    term.proc.wait(timeout=1.0)
+                except (subprocess.TimeoutExpired, ProcessLookupError):
+                    pass
+    finally:
+        try:
+            os.close(term.master_fd)
+        except OSError:
+            pass
+        _reap_terminal_descendants(term.proc.pid)
+    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/todo_state.py

@@ -0,0 +1,320 @@
+"""Derive ``todo_state`` snapshots from tool results and settled session messages.
+
+The ``todo`` tool's in-memory store lives on the per-session AIAgent. The
+WebUI bridge needs to mirror that state to the browser in two situations:
+
+1. **Live**: when the agent calls ``todo`` mid-stream, ``api.streaming``
+   emits a dedicated ``todo_state`` SSE event so the Todos panel updates
+   without waiting for the turn to finish. See :func:`emit_todo_state`.
+
+2. **Cold-load**: when the browser opens a session (no live stream), the
+   session GET handler attaches ``todo_state`` derived from the most
+   recent ``role='tool'`` message whose JSON content carries a ``todos``
+   list. See :func:`attach_todo_state`.
+
+Both paths normalize through :func:`_normalize_snapshot` so the frontend
+has a single deserialization contract:
+
+    {
+        "todos":   [{"id": ..., "content": ..., "status": ...}, ...],
+        "summary": {"total": N, "pending": N, "in_progress": N,
+                    "completed": N, "cancelled": N},
+        "version": 1,
+    }
+
+Live SSE payloads add ``session_id``, ``stream_id``, ``source`` and ``ts``
+on top so the frontend can filter cross-session events and ignore
+out-of-order replays.
+
+**Detection symmetry with the agent.** The cold-load helper deliberately
+uses the same loose detector as ``run_agent.AIAgent._hydrate_todo_store``
+(``role='tool'`` + JSON content with ``todos: list``). If a future change
+tightens or relaxes that detector, mirror it here so the WebUI panel
+never disagrees with the agent's in-memory ``TodoStore``.
+
+**Multimodal tool results.** Some tools return content as a list of
+OpenAI/Anthropic content parts rather than a JSON string. The ``todo``
+tool always returns a JSON string, so list-shaped content cannot be a
+todo write — :func:`derive_todo_state` skips them by design.
+
+This module is **side-effect free** by design — it only parses data and
+calls a caller-supplied ``put`` callable for SSE. Routing/event-shape
+decisions live here so the call sites stay one-liners.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable, Iterable, Optional, Sequence
+
+
+logger = logging.getLogger(__name__)
+
+
+# Bumped when the on-wire payload shape changes in a non-additive way.
+# Additive fields (e.g. timestamps, tags) keep VERSION at 1.
+VERSION = 1
+
+# Single source of truth for the SSE event name and the session GET
+# payload key. Any current or future caller must reuse these so a
+# rename only happens in one place.
+EVENT_NAME = "todo_state"
+PAYLOAD_KEY = "todo_state"
+
+
+def _normalize_snapshot(data: Any) -> Optional[dict]:
+    """Return a normalized snapshot dict, or ``None`` if the payload is invalid.
+
+    Accepts the canonical ``{"todos": [...], "summary": {...}}`` shape
+    produced by ``tools.todo_tool.todo_tool``. Anything else returns
+    ``None`` so callers can fall through to legacy paths or skip
+    emission.
+
+    The detector is intentionally loose so it stays symmetric with the
+    agent's hydration logic — see the module docstring.
+
+    **Empty list is a valid snapshot.** ``todos == []`` returns a normal
+    snapshot (not ``None``), so the latest write wins even when it cleared
+    the list. This is deliberately symmetric with the agent: its
+    ``_hydrate_todo_store`` (run_agent.py) breaks at the most-recent todo
+    message and, because ``if last_todo_response:`` is falsy for ``[]``,
+    leaves its TodoStore empty — i.e. agent shows empty, panel shows empty.
+    Do NOT reintroduce a ``len(todos) > 0`` guard here or in the frontend
+    fallback (``_legacyTodosFromMessages``): that was the pre-Phase-2
+    behavior that kept scanning past an empty write to an older non-empty
+    list, diverging from the agent and showing a stale "cleared" list.
+    """
+    if not isinstance(data, dict):
+        return None
+    todos = data.get("todos")
+    if not isinstance(todos, list):
+        return None
+    summary = data.get("summary")
+    if not isinstance(summary, dict):
+        summary = {}
+    return {
+        "todos": todos,
+        "summary": summary,
+        "version": VERSION,
+    }
+
+
+def parse_todo_tool_result(function_result: Any) -> Optional[dict]:
+    """Parse a fresh ``todo`` tool call result into a snapshot dict.
+
+    The agent's ``todo`` handler returns a JSON string; this helper
+    accepts either that string or an already-parsed dict (defensive —
+    future callers may deserialize earlier in the pipeline).
+
+    Returns ``None`` on any parse/shape failure so the caller can
+    swallow the error without breaking the tool delivery path.
+    """
+    data: Any = function_result
+    if isinstance(function_result, str):
+        try:
+            data = json.loads(function_result)
+        except (ValueError, TypeError):
+            return None
+    return _normalize_snapshot(data)
+
+
+def derive_todo_state(messages: Optional[Iterable[dict]]) -> Optional[dict]:
+    """Derive the latest todo snapshot from settled conversation history.
+
+    Mirrors the agent-side ``_hydrate_todo_store`` logic: walk messages
+    in reverse, return the first ``role='tool'`` message whose JSON
+    content carries a ``todos`` list. Returns ``None`` when no such
+    message is found (fresh session, or a session that never invoked
+    ``todo``).
+
+    Multimodal tool results — ``content`` as a list of content parts
+    rather than a JSON string — are skipped intentionally. The ``todo``
+    tool always returns a string, so list-shaped content cannot be a
+    todo write; non-string ``content`` is therefore correct to ignore.
+
+    The fast-path string check (``'"todos"' in content``) avoids parsing
+    JSON for every tool result — most sessions have many non-todo tool
+    calls but at most a handful of todo writes.
+    """
+    if not messages:
+        return None
+    # ``reversed`` works on ``list`` and ``tuple`` natively; for any
+    # other iterable (e.g. a generator) we materialize once. Routes
+    # always pass a list, so this branch is normally a no-op.
+    if not isinstance(messages, (list, tuple)):
+        messages = list(messages)
+    for idx in range(len(messages) - 1, -1, -1):
+        msg = messages[idx]
+        if not isinstance(msg, dict) or msg.get("role") != "tool":
+            continue
+        content = msg.get("content", "")
+        if not isinstance(content, str) or '"todos"' not in content:
+            continue
+        try:
+            data = json.loads(content)
+        except (ValueError, TypeError):
+            continue
+        snapshot = _normalize_snapshot(data)
+        if snapshot is not None:
+            # Carry a timestamp so the frontend can reconcile cold-load
+            # vs. INFLIGHT snapshots by recency.
+            #
+            # Primary source: this message's own ``timestamp``. But a
+            # todo tool message can lose its timestamp during context
+            # compression/rebuild — the on-disk message ends up with
+            # ``timestamp=None``. If we emit a snapshot with no ``ts``,
+            # the frontend reads coldTs=0 and a STALE-but-timestamped
+            # INFLIGHT snapshot wins the recency comparison, so the panel
+            # renders a historical todo list. This is the latest-by-
+            # POSITION snapshot, so it must never lose recency to an
+            # earlier list. When this message has no usable timestamp,
+            # fall back to the max timestamp seen anywhere at or before
+            # this position — guaranteeing cold ts >= any earlier todo
+            # write's ts.
+            ts_val = _message_ts_float(msg.get("timestamp"))
+            if ts_val <= 0:
+                ts_val = _max_timestamp_through(messages, idx)
+            if ts_val > 0:
+                snapshot["ts"] = ts_val
+            return snapshot
+    return None
+
+
+def _message_ts_float(ts_raw: Any) -> float:
+    """Coerce a message ``timestamp`` field to a positive float, or 0.0."""
+    try:
+        return float(ts_raw) if ts_raw is not None else 0.0
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _max_timestamp_through(messages: "Sequence[Any]", upto_idx: int) -> float:
+    """Largest valid ``timestamp`` among messages[0:upto_idx+1].
+
+    Used as a recency floor when the latest todo message itself lost its
+    timestamp during compression/rebuild. Scanning only up to the todo's
+    position keeps the floor causally correct — it never borrows a
+    timestamp from a message that came after the todo write.
+    """
+    best = 0.0
+    end = min(upto_idx, len(messages) - 1)
+    for i in range(end, -1, -1):
+        m = messages[i]
+        if not isinstance(m, dict):
+            continue
+        ts = _message_ts_float(m.get("timestamp"))
+        if ts > best:
+            best = ts
+    return best
+
+
+def _redact_snapshot(snapshot: dict) -> dict:
+    """Redact credential-shaped text from a todo snapshot before it leaves the process.
+
+    The live SSE path (:func:`emit_todo_state`) does NOT pass through
+    ``redact_session_data`` (api/helpers.py) the way the cold-load session
+    GET response does, so emission must redact the same content that path
+    would — otherwise the live Todos panel (and the run-journal replay that
+    persists every SSE event) becomes a redaction bypass for any credential
+    an agent wrote into a todo item's ``content``. The live event also
+    carries the FULL untruncated todos, a wider exposure surface than the
+    truncated ``preview`` the sibling ``tool``/``tool_complete`` events send.
+
+    ``_redact_value`` is imported lazily to keep the dependency direction
+    one-way (helpers must never import todo_state) and to avoid paying the
+    import cost on the cold-load path, which redacts via ``redact_session_data``.
+    The redaction setting is read once per SSE snapshot and threaded through the
+    recursive helper so nested strings do not reload settings.json individually.
+
+    Returns a new, redacted snapshot. Raises on failure so the caller fails
+    closed (no emission) rather than leaking an unredacted payload.
+    """
+    from typing import cast
+    from api.config import load_settings
+    from api.helpers import _redact_value
+    _enabled = bool(load_settings().get("api_redact_enabled", True))
+    # ``_redact_value`` preserves container shape (dict in → dict out); the
+    # cast narrows its broad recursive union back to dict for the type checker.
+    return cast(dict, _redact_value(snapshot, _enabled=_enabled))
+
+
+def emit_todo_state(
+    put: Callable[[str, dict], Any],
+    *,
+    name: Optional[str],
+    function_result: Any,
+    session_id: Optional[str],
+    stream_id: Optional[str],
+    source: str = "tool",
+) -> bool:
+    """Emit a ``todo_state`` SSE event when ``name == 'todo'``.
+
+    Returns ``True`` if an event was emitted, ``False`` otherwise.
+    Always swallows internal errors — emission must never break tool
+    delivery, which is the caller's primary contract.
+
+    Args:
+        put: streaming queue callback; signature ``put(event, data)``.
+        name: tool name from the callback. Skipped when not ``'todo'``.
+        function_result: raw tool result (JSON string or dict).
+        session_id: tag so the frontend can filter cross-session events.
+        stream_id: tag so SSE replay can dedupe by stream.
+        source: emission origin tag. ``'tool'`` for live tool calls;
+                future callers may use ``'compression-refresh'`` etc.
+
+    The full snapshot is always sent — idempotent re-application is safe
+    under SSE replay through the run journal. The snapshot is redacted
+    before emission (see :func:`_redact_snapshot`); if redaction fails the
+    event is dropped (fail-closed) rather than leaking an unredacted payload.
+    """
+    if name != "todo":
+        return False
+    try:
+        snapshot = parse_todo_tool_result(function_result)
+        if snapshot is None:
+            return False
+        snapshot = _redact_snapshot(snapshot)
+        put(EVENT_NAME, {
+            "session_id": session_id,
+            "stream_id": stream_id,
+            "source": source,
+            "ts": time.time(),
+            **snapshot,
+        })
+        return True
+    except Exception:
+        # Per-call debug logging — a flood would mean the queue is
+        # broken, in which case the rest of the stream is already dead.
+        # Redaction failure also lands here and correctly drops the event.
+        logger.debug("todo_state emit failed (name=%s)", name, exc_info=True)
+        return False
+
+
+def attach_todo_state(
+    payload: dict,
+    messages: Optional[Iterable[dict]],
+) -> bool:
+    """Attach a derived ``todo_state`` snapshot to a session GET response.
+
+    Mutates ``payload`` in place when a snapshot can be derived.
+    Returns ``True`` if attached, ``False`` otherwise. Always swallows
+    errors — a malformed sidecar must never break the session GET
+    response.
+
+    The caller is responsible for any higher-level gating
+    (e.g. ``load_messages``); this helper is a no-op on empty/``None``
+    ``messages`` so callers can hand it whatever message list they have.
+    """
+    if not messages:
+        return False
+    try:
+        snapshot = derive_todo_state(messages)
+        if snapshot is None:
+            return False
+        payload[PAYLOAD_KEY] = snapshot
+        return True
+    except Exception:
+        logger.debug("todo_state attach failed", exc_info=True)
+        return False

api/turn_journal.py

@@ -0,0 +1,281 @@
+"""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}~{os.getpid()}.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())
+    if event_name in _TERMINAL_EVENTS:
+        payload.setdefault("terminal", True)
+
+    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())
+    o_directory = getattr(os, "O_DIRECTORY", None)
+    if o_directory is not None:
+        try:
+            dir_fd = os.open(path.parent, 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, merging all pid-scoped shards and returning valid events plus malformed lines."""
+    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()
+    journal_dir = root / TURN_JOURNAL_DIR_NAME
+    events: list[dict] = []
+    malformed: list[dict] = []
+    # Collect pid-scoped shards ({sid}~{pid}.jsonl) plus legacy ({sid}.jsonl).
+    # The ~ separator cannot appear in session IDs (_SESSION_ID_RE allows only [A-Za-z0-9_.-]),
+    # so the glob is unambiguous even for dotted-numeric session IDs like "sess.123".
+    shards: list[Path] = list(journal_dir.glob(f"{sid}~*.jsonl")) if journal_dir.exists() else []
+    legacy = journal_dir / f"{sid}.jsonl"
+    if legacy.exists():
+        shards.append(legacy)
+    if not shards:
+        return {"session_id": str(session_id), "events": [], "malformed": []}
+    for shard in shards:
+        try:
+            lines = shard.read_text(encoding="utf-8").splitlines()
+        except FileNotFoundError:
+            continue
+        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, "shard": shard.name})
+                continue
+            if isinstance(event, dict):
+                events.append(event)
+            else:
+                malformed.append({"line": line_no, "raw": raw, "shard": shard.name})
+    def _safe_ts(e):
+        try:
+            return float(e.get("created_at") or 0)
+        except (ValueError, TypeError):
+            return 0.0
+    events.sort(key=_safe_ts)
+    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 []
+    session_ids: set[str] = set()
+    for path in journal_dir.glob("*.jsonl"):
+        if not path.is_file():
+            continue
+        stem = path.stem  # e.g. "sid-1~12345" or "sid-1"
+        tilde = stem.find("~")
+        if tilde > 0:
+            session_ids.add(stem[:tilde])
+        else:
+            session_ids.add(stem)
+    return sorted(session_ids)
+
+
+def delete_turn_journal(session_id: str, *, session_dir: Path | None = None) -> int:
+    """Remove every turn-journal shard for ``session_id``.
+
+    Deletes both the pid-scoped shards (``{sid}~{pid}.jsonl``) written by
+    :func:`append_turn_journal_event` and the legacy single-file form
+    (``{sid}.jsonl``) that :func:`read_turn_journal` still merges. Returns the
+    number of files removed. Invalid/empty ids and a missing journal directory
+    are treated as a no-op so callers can invoke this unconditionally on delete.
+    """
+    sid = str(session_id or "").strip()
+    # Reject "."/".." for parity with delete_run_journal — the regex permits
+    # dots, and a traversal id has no legitimate use here.
+    if sid in (".", "..") or not sid or "/" in sid or "\\" in sid or not _SESSION_ID_RE.fullmatch(sid):
+        return 0
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    journal_dir = root / TURN_JOURNAL_DIR_NAME
+    if not journal_dir.exists():
+        return 0
+    removed = 0
+    shards = list(journal_dir.glob(f"{sid}~*.jsonl"))
+    legacy = journal_dir / f"{sid}.jsonl"
+    if legacy.exists():
+        shards.append(legacy)
+    for shard in shards:
+        try:
+            shard.unlink()
+            removed += 1
+        except FileNotFoundError:
+            pass
+        except OSError:
+            # Best-effort cleanup; the caller logs the overall delete outcome.
+            pass
+    return removed
+
+
+def is_terminal_turn_event(event: dict) -> bool:
+    return str((event or {}).get("event") or "") in _TERMINAL_EVENTS

api/upload.py

@@ -1,24 +1,76 @@
 """
 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
+from api.workspace import (
+    safe_resolve_ws,
+    resolve_trusted_workspace,
+    open_anchored_create_fd,
+    make_anchored_dir,
+    rmtree_anchored,
+    unlink_anchored,
+)
+
+
+def _max_extracted_bytes() -> int:
+    """Total-extracted-bytes cap for archive uploads (zip/tar-bomb guard).
+
+    Independently tunable from the upload size cap via
+    HERMES_WEBUI_MAX_EXTRACTED_MB; defaults to 10x the upload cap. Read at call
+    time (not import) so the value reflects the running process's environment
+    and is exercisable by tests against the out-of-process test server.
+    """
+    raw = os.getenv("HERMES_WEBUI_MAX_EXTRACTED_MB", "").strip()
+    if raw:
+        try:
+            mb = float(raw)
+            if mb > 0:
+                return int(mb * 1024 * 1024)
+        except ValueError:
+            pass
+    return 10 * MAX_UPLOAD_BYTES
+
+
+# Back-compat module constant (some call sites / tests reference it). The
+# authoritative value is _max_extracted_bytes(), read at extraction time.
+_MAX_EXTRACTED_BYTES = 10 * MAX_UPLOAD_BYTES
 
 
 def parse_multipart(rfile, content_type, content_length) -> tuple:
     import re as _re, email.parser as _ep
+    # Imported locally (not just module-level) so the function stays
+    # self-contained — some tests exec() this function's source in an isolated
+    # namespace, and a bare module global would NameError there.
+    try:
+        from api.config import MAX_UPLOAD_BYTES as _MAX_UPLOAD_BYTES
+    except Exception:
+        _MAX_UPLOAD_BYTES = 20 * 1024 * 1024
     m = _re.search(r'boundary=([^;\s]+)', content_type)
     if not m:
         raise ValueError('No boundary in Content-Type')
     boundary = m.group(1).strip('"').encode()
-    raw = rfile.read(content_length)
+    # Centralized length guard for ALL upload callers: a missing/garbage or
+    # NEGATIVE Content-Length must never reach rfile.read(<0), which reads the
+    # stream unbounded (read(-1) == read-to-EOF) and bypasses the per-handler
+    # size cap. Reject anything not in [0, MAX_UPLOAD_BYTES].
+    try:
+        length = int(content_length)
+    except (TypeError, ValueError):
+        raise ValueError('Invalid Content-Length') from None
+    if length < 0:
+        raise ValueError('Invalid Content-Length (negative)')
+    if length > _MAX_UPLOAD_BYTES:
+        raise ValueError(f'Upload too large (max {_MAX_UPLOAD_BYTES} bytes)')
+    raw = rfile.read(length)
     fields = {}
     files = {}
     delimiter = b'--' + boundary
@@ -58,6 +110,46 @@ 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')
+    if dest.exists():
+        stem = dest.stem
+        suffix = dest.suffix
+        for idx in range(1, 1000):
+            candidate = (dest_dir / f'{stem}-{idx}{suffix}').resolve()
+            if not candidate.is_relative_to(dest_dir):
+                raise ValueError('Invalid upload destination')
+            if not candidate.exists():
+                return candidate
+        raise ValueError('Too many uploads with the same filename')
+    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:
@@ -76,11 +168,17 @@ 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)
-        return j(handler, {'filename': safe_name, 'path': str(dest), 'size': dest.stat().st_size})
+        mime = mimetypes.guess_type(safe_name)[0] or 'application/octet-stream'
+        return j(handler, {
+            'filename': dest.name,
+            'path': str(dest),
+            'size': dest.stat().st_size,
+            'mime': mime,
+            'is_image': mime.startswith('image/'),
+        })
     except ValueError as e:
         return j(handler, {'error': str(e)}, status=400)
     except Exception:
@@ -88,6 +186,175 @@ def handle_upload(handler):
         return j(handler, {'error': 'Upload failed'}, status=500)
 
 
+def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
+    """Extract a zip or tar archive into the workspace.
+
+    Returns a dict with ``extracted`` (int), ``files`` (list[str]).
+    Raises ValueError on zip-slip or unsupported format.
+    """
+    import zipfile, tarfile, io, os, shutil
+
+    cap = _max_extracted_bytes()
+    name = Path(filename).name
+    stem = Path(filename).stem  # strip .zip / .tar.gz etc.
+
+    if name.lower().endswith(('.zip',)):
+        _mode = 'zip'
+    elif name.lower().endswith(('.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tar.xz', '.txz')):
+        _mode = 'tar'
+    else:
+        raise ValueError(f'Unsupported archive format: {filename}')
+
+    # Determine destination directory — use archive stem as folder name
+    dest_dir = safe_resolve_ws(workspace, stem)
+    # Avoid overwriting existing files by appending a suffix (bounded — astronomically
+    # unlikely to collide, but never spin forever).
+    if dest_dir.exists():
+        import string, random
+        for _ in range(1000):
+            if not dest_dir.exists():
+                break
+            suffix = ''.join(random.choices(string.digits, k=3))
+            dest_dir = safe_resolve_ws(workspace, stem).with_name(stem + '_' + suffix)
+        else:
+            raise ValueError('Could not allocate a unique extraction directory')
+    # #3398: create the extraction root race-safely under the true workspace root.
+    make_anchored_dir(workspace, dest_dir)
+
+    # Member-count cap: a tiny archive with millions of (possibly empty) members
+    # slips under the byte cap but can exhaust inodes / file descriptors. Bound it.
+    _MAX_ARCHIVE_MEMBERS = 10000
+
+    extracted_files = []
+    total_extracted = 0
+
+    try:
+        if _mode == 'zip':
+            with zipfile.ZipFile(io.BytesIO(file_bytes)) as zf:
+                for member in zf.infolist():
+                    # Skip directories
+                    if member.is_dir():
+                        continue
+                    if len(extracted_files) >= _MAX_ARCHIVE_MEMBERS:
+                        raise ValueError(
+                            f'Archive has too many files (> {_MAX_ARCHIVE_MEMBERS}). '
+                            f'Possible archive bomb.'
+                        )
+                    # Zip-slip protection
+                    member_path = (dest_dir / member.filename).resolve()
+                    if not member_path.is_relative_to(dest_dir.resolve()):
+                        raise ValueError(f'Zip-slip blocked: {member.filename}')
+                    # Zip-bomb protection: track actual extracted bytes (not declared file_size)
+                    if total_extracted > cap:
+                        raise ValueError(
+                            f'Extraction too large ({total_extracted // (1024*1024)} MB > '
+                            f'{cap // (1024*1024)} MB limit). '
+                            f'Possible zip bomb.'
+                        )
+                    # #3398: open_anchored_create_fd creates intermediate dirs
+                    # race-safely under the true workspace root (anchored mkdirat),
+                    # so no pathname member_path.parent.mkdir() before it (which
+                    # could be redirected outside by a raced symlink component).
+                    _mfd = open_anchored_create_fd(workspace, member_path)
+                    with zf.open(member) as src, os.fdopen(_mfd, 'wb', closefd=True) as dst:
+                        _chunk_size = 65536
+                        while True:
+                            chunk = src.read(_chunk_size)
+                            if not chunk:
+                                break
+                            total_extracted += len(chunk)
+                            if total_extracted > cap:
+                                raise ValueError(
+                                    f'Extraction too large (> '
+                                    f'{cap // (1024*1024)} MB limit). '
+                                    f'Possible zip bomb.'
+                                )
+                            dst.write(chunk)
+                    extracted_files.append(str(member_path.relative_to(workspace.resolve())))
+
+        elif _mode == 'tar':
+            with tarfile.open(fileobj=io.BytesIO(file_bytes)) as tf:
+                for member in tf.getmembers():
+                    if not member.isfile():
+                        continue
+                    if len(extracted_files) >= _MAX_ARCHIVE_MEMBERS:
+                        raise ValueError(
+                            f'Archive has too many files (> {_MAX_ARCHIVE_MEMBERS}). '
+                            f'Possible archive bomb.'
+                        )
+                    # Tar-slip protection
+                    member_path = (dest_dir / member.name).resolve()
+                    if not member_path.is_relative_to(dest_dir.resolve()):
+                        raise ValueError(f'Tar-slip blocked: {member.name}')
+                    # Tar-bomb protection: track actual extracted bytes (not declared size)
+                    if total_extracted > cap:
+                        raise ValueError(
+                            f'Extraction too large ({total_extracted // (1024*1024)} MB > '
+                            f'{cap // (1024*1024)} MB limit). '
+                            f'Possible zip bomb.'
+                        )
+                    # #3398: anchored member create makes intermediate dirs
+                    # race-safely; no pathname member_path.parent.mkdir() first.
+                    src_obj = tf.extractfile(member)
+                    if src_obj:
+                        # #3398: fd-anchored member create under the TRUE workspace root.
+                        _mfd = open_anchored_create_fd(workspace, member_path)
+                        with src_obj as src, os.fdopen(_mfd, 'wb', closefd=True) as dst:
+                            _chunk_size = 65536
+                            while True:
+                                chunk = src.read(_chunk_size)
+                                if not chunk:
+                                    break
+                                total_extracted += len(chunk)
+                                if total_extracted > cap:
+                                    raise ValueError(
+                                        f'Extraction too large (> '
+                                        f'{cap // (1024*1024)} MB limit). '
+                                        f'Possible zip bomb.'
+                                    )
+                                dst.write(chunk)
+                    extracted_files.append(str(member_path.relative_to(workspace.resolve())))
+    except Exception:
+        # Clean up partially-extracted directory to avoid orphaned folders
+        try:
+            rmtree_anchored(workspace, dest_dir)
+        except Exception:
+            pass
+        raise
+
+    return {'extracted': len(extracted_files), 'files': extracted_files, 'dest': str(dest_dir)}
+
+
+def handle_upload_extract(handler):
+    """Handle archive upload and extraction."""
+    import traceback as _tb
+    try:
+        content_type = handler.headers.get('Content-Type', '')
+        content_length = int(handler.headers.get('Content-Length', 0) or 0)
+        if content_length > MAX_UPLOAD_BYTES:
+            return j(handler, {'error': f'File too large (max {MAX_UPLOAD_BYTES//1024//1024}MB)'}, status=413)
+        fields, files = parse_multipart(handler.rfile, content_type, content_length)
+        session_id = fields.get('session_id', '')
+        if 'file' not in files:
+            return j(handler, {'error': 'No file field in request'}, status=400)
+        filename, file_bytes = files['file']
+        if not filename:
+            return j(handler, {'error': 'No filename in upload'}, status=400)
+        try:
+            s = get_session(session_id)
+        except KeyError:
+            return j(handler, {'error': 'Session not found'}, status=404)
+        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)
+    except Exception:
+        print('[webui] upload extract error: ' + _tb.format_exc(), flush=True)
+        return j(handler, {'error': 'Archive extraction failed'}, status=500)
+
+
 def handle_transcribe(handler):
     import traceback as _tb
     temp_path = None
@@ -129,3 +396,295 @@ def handle_transcribe(handler):
                 Path(temp_path).unlink(missing_ok=True)
             except Exception:
                 pass
+
+
+def _stt_provider_capability_from_module(stt):
+    """Return (available, provider) for a loaded transcription_tools module."""
+    try:
+        load_cfg = getattr(stt, "_load_stt_config", None)
+        stt_config = load_cfg() if callable(load_cfg) else {}
+        cfg_dict = stt_config if isinstance(stt_config, dict) else {}
+        is_enabled = getattr(stt, "is_stt_enabled", None)
+        if callable(is_enabled) and not is_enabled(stt_config):
+            return False, "none"
+
+        # Some tests and future agent releases expose the provider decision as a
+        # single helper. Use it when the lower-level capability flags are not
+        # available. The current agent module exposes the flags below, so the
+        # normal path mirrors _get_provider() without triggering its lazy local
+        # STT install side effect during a passive web page probe.
+        has_internal_flags = any(
+            hasattr(stt, name)
+            for name in ("_HAS_FASTER_WHISPER", "_HAS_OPENAI", "_HAS_MISTRAL")
+        )
+        get_provider = getattr(stt, "_get_provider", None)
+        if callable(get_provider) and not has_internal_flags:
+            provider = str(get_provider(stt_config) or "none")
+            return provider not in ("", "none"), provider or "none"
+
+        def env(name):
+            getter = getattr(stt, "get_env_value", None)
+            try:
+                if callable(getter):
+                    return str(getter(name) or "").strip()
+            except Exception:
+                return ""
+            return os.getenv(name, "").strip()
+
+        def has_local_command():
+            helper = getattr(stt, "_has_local_command", None)
+            try:
+                return bool(helper()) if callable(helper) else False
+            except Exception:
+                return False
+
+        def has_browser_audio_converter():
+            helper = getattr(stt, "_find_ffmpeg_binary", None)
+            try:
+                return bool(helper()) if callable(helper) else False
+            except Exception:
+                return False
+
+        def has_openai_audio():
+            helper = getattr(stt, "_has_openai_audio_backend", None)
+            try:
+                return bool(helper()) if callable(helper) else False
+            except Exception:
+                return False
+
+        def local_command_available():
+            # The browser sends WebM/Ogg blobs; the local-command path converts
+            # non-WAV input through ffmpeg before invoking the command.
+            return has_local_command() and has_browser_audio_converter()
+
+        def resolve_provider(provider):
+            if provider == "local":
+                if bool(getattr(stt, "_HAS_FASTER_WHISPER", False)):
+                    return "local"
+                if local_command_available():
+                    return "local_command"
+                return "none"
+            if provider == "local_command":
+                if local_command_available():
+                    return "local_command"
+                if bool(getattr(stt, "_HAS_FASTER_WHISPER", False)):
+                    return "local"
+                return "none"
+            if provider == "groq":
+                return "groq" if bool(getattr(stt, "_HAS_OPENAI", False)) and bool(env("GROQ_API_KEY")) else "none"
+            if provider == "openai":
+                return "openai" if bool(getattr(stt, "_HAS_OPENAI", False)) and has_openai_audio() else "none"
+            if provider == "mistral":
+                return "mistral" if bool(getattr(stt, "_HAS_MISTRAL", False)) and bool(env("MISTRAL_API_KEY")) else "none"
+            if provider == "xai":
+                try:
+                    from tools.xai_http import resolve_xai_http_credentials
+
+                    return "xai" if resolve_xai_http_credentials().get("api_key") else "none"
+                except Exception:
+                    return "none"
+            if provider == "elevenlabs":
+                return "elevenlabs" if bool(env("ELEVENLABS_API_KEY")) else "none"
+            return "none"
+
+        explicit = "provider" in cfg_dict
+        if explicit:
+            configured = str(cfg_dict.get("provider") or "local")
+            provider = resolve_provider(configured)
+            return provider != "none", provider if provider != "none" else configured
+
+        for candidate in ("local", "local_command", "groq", "openai", "mistral", "xai", "elevenlabs"):
+            provider = resolve_provider(candidate)
+            if provider != "none":
+                return True, provider
+        return False, "none"
+    except Exception:
+        return False, "none"
+
+
+
+def _stt_provider_capability():
+    """Return (available, provider) for a cheap server-side STT capability probe."""
+    try:
+        import tools.transcription_tools as stt
+    except ImportError:
+        return False, "none"
+    return _stt_provider_capability_from_module(stt)
+
+
+def handle_transcribe_capability(handler):
+    available, provider = _stt_provider_capability()
+    return j(handler, {"ok": True, "available": bool(available), "provider": provider})
+
+
+def handle_workspace_upload(handler):
+    """Upload a file into a session's workspace directory.
+
+    Form fields:
+        session_id – target session
+        path       – subdirectory within the workspace (default: '')
+    File:
+        file – the uploaded file(s)
+    """
+    import traceback as _tb
+    try:
+        content_type = handler.headers.get('Content-Type', '')
+        content_length = int(handler.headers.get('Content-Length', 0) or 0)
+        if content_length > MAX_UPLOAD_BYTES:
+            return j(handler, {'error': f'File too large (max {MAX_UPLOAD_BYTES//1024//1024}MB)'}, status=413)
+
+        fields, files = parse_multipart(handler.rfile, content_type, content_length)
+        session_id = fields.get('session_id', '')
+        subpath = fields.get('path', '')
+
+        if not session_id:
+            return j(handler, {'error': 'Missing session_id'}, status=400)
+
+        if not files:
+            return j(handler, {'error': 'No file field in request'}, status=400)
+
+        # Validate session
+        try:
+            session = get_session(session_id)
+        except KeyError:
+            return j(handler, {'error': 'Session not found'}, status=404)
+
+        # Resolve workspace root from session
+        workspace = resolve_trusted_workspace(session.workspace)
+
+        # Resolve target subdirectory within workspace
+        target_dir = safe_resolve_ws(workspace, subpath) if subpath else workspace
+        # safe_resolve_ws intentionally permits in-workspace symlinks pointing
+        # outside the root (read trust model). For an UPLOAD target that's not
+        # acceptable: a planted symlink subpath would let mkdir() + writes create
+        # files OUTSIDE the workspace. Require the resolved target to be inside
+        # the workspace before creating anything. (is_relative_to is True for the
+        # workspace==target equality case, so the normal subpath='' path passes.)
+        if not target_dir.resolve().is_relative_to(workspace.resolve()):
+            return j(handler, {'error': 'Upload target escapes workspace'}, status=403)
+        # #3398: create the upload target dir race-safely under the workspace root
+        # (anchored mkdirat) so a raced symlink subpath can't mkdir outside.
+        try:
+            make_anchored_dir(workspace, target_dir)
+        except (ValueError, OSError):
+            return j(handler, {'error': 'Upload target escapes workspace'}, status=403)
+
+        results = []
+        for _field_name, (filename, file_bytes) in files.items():
+            if not filename:
+                continue
+
+            safe_name = _sanitize_upload_name(filename)
+            dest = safe_resolve_ws(target_dir, safe_name)
+
+            # Path traversal guard (belt-and-suspenders: safe_resolve_ws above is
+            # the authoritative guard and raises ValueError on traversal; this
+            # check catches any edge case where the resolved path escapes).
+            if not dest.resolve().is_relative_to(workspace.resolve()):
+                return j(handler, {'error': f'Path traversal blocked: {safe_name}'}, status=403)
+
+            # Deduplicate: append -1, -2, etc. if file already exists
+            if dest.exists():
+                stem = dest.stem
+                suffix = dest.suffix
+                for idx in range(1, 1000):
+                    candidate = safe_resolve_ws(target_dir, f'{stem}-{idx}{suffix}')
+                    if not candidate.resolve().is_relative_to(workspace.resolve()):
+                        return j(handler, {'error': 'Path traversal blocked'}, status=403)
+                    if not candidate.exists():
+                        dest = candidate
+                        break
+                else:
+                    return j(handler, {'error': 'Too many uploads with the same filename'}, status=400)
+
+            # #3398 TOCTOU hardening: create the destination via an anchored
+            # openat-walk from the true workspace root with O_CREAT|O_EXCL|
+            # O_NOFOLLOW, so a symlink raced into any path component after the
+            # containment checks above cannot redirect the write outside the
+            # workspace. The dedup loop guarantees `dest` does not exist.
+            try:
+                _wfd = open_anchored_create_fd(workspace, dest.resolve())
+            except FileExistsError:
+                return j(handler, {'error': f'Upload destination already exists: {safe_name}'}, status=409)
+            except (ValueError, OSError):
+                return j(handler, {'error': f'Path traversal blocked: {safe_name}'}, status=403)
+            with os.fdopen(_wfd, 'wb', closefd=True) as _wfh:
+                _wfh.write(file_bytes)
+            mime = mimetypes.guess_type(safe_name)[0] or 'application/octet-stream'
+
+            # For archives, optionally extract into the target directory.
+            # Suffix set MUST match extract_archive()'s supported formats, else
+            # accepted-but-unlisted archives (.tar/.tbz2/.txz) silently land as
+            # raw files instead of extracting.
+            is_archive = safe_name.lower().endswith(('.zip', '.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tar.xz', '.txz'))
+            if is_archive:
+                import zipfile, tarfile, traceback as _extract_tb
+                try:
+                    extraction = extract_archive(file_bytes, safe_name, target_dir)
+                    # Remove the archive file after successful extraction
+                    try:
+                        unlink_anchored(workspace, dest.resolve())
+                    except FileNotFoundError:
+                        pass
+                    results.append({
+                        'filename': safe_name,
+                        'path': str(extraction.get('dest', target_dir)),
+                        'size': len(file_bytes),
+                        'is_image': False,
+                        'extracted': True,
+                        'extracted_files': extraction.get('files', []),
+                        'extracted_count': extraction.get('extracted', 0),
+                    })
+                    continue
+                except (zipfile.BadZipFile, tarfile.TarError, ValueError) as e:
+                    # Extraction failed — remove the archive file (no partial
+                    # content left behind) and surface the error to the user.
+                    try:
+                        unlink_anchored(workspace, dest.resolve())
+                    except FileNotFoundError:
+                        pass
+                    print(f'[webui] workspace upload extract error: {e}', flush=True)
+                    results.append({
+                        'filename': safe_name,
+                        'path': str(target_dir),
+                        'size': len(file_bytes),
+                        'mime': mime,
+                        'is_image': False,
+                        'extracted': False,
+                        'extract_error': str(e) or 'Archive extraction failed',
+                    })
+                    continue
+                except Exception:
+                    print('[webui] workspace upload extract error: ' + _extract_tb.format_exc(), flush=True)
+                    try:
+                        unlink_anchored(workspace, dest.resolve())
+                    except FileNotFoundError:
+                        pass
+                    results.append({
+                        'filename': safe_name,
+                        'path': str(target_dir),
+                        'size': len(file_bytes),
+                        'mime': mime,
+                        'is_image': False,
+                        'extracted': False,
+                        'extract_error': 'Archive extraction failed',
+                    })
+                    continue
+
+            results.append({
+                'filename': dest.name,
+                'path': str(dest),
+                'size': dest.stat().st_size,
+                'mime': mime,
+                'is_image': mime.startswith('image/'),
+                'extracted': False,
+            })
+
+        if len(results) == 1:
+            return j(handler, results[0])
+        return j(handler, {'files': results, 'count': len(results)})
+    except ValueError as e:
+        return j(handler, {'error': str(e)}, status=400)
+    except Exception:
+        print('[webui] workspace upload error: ' + _tb.format_exc(), flush=True)
+        return j(handler, {'error': 'Upload failed'}, status=500)

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

@@ -0,0 +1,250 @@
+"""Dormant JSON-backed SessionDB-shaped adapter for WebUI sessions.
+
+This module intentionally does not replace existing WebUI runtime call sites.
+It provides a small compatibility surface over the current JSON sidecars so the
+unified SessionDB contract can be tested without changing persistence behavior.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any
+
+import api.models as models
+
+
+_METADATA_FIELDS = frozenset(
+    {
+        "title",
+        "workspace",
+        "model",
+        "model_provider",
+        "created_at",
+        "updated_at",
+        "pinned",
+        "archived",
+        "project_id",
+        "profile",
+        "input_tokens",
+        "output_tokens",
+        "estimated_cost",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "personality",
+        "active_stream_id",
+        "pending_user_message",
+        "pending_attachments",
+        "pending_started_at",
+        "compression_anchor_visible_idx",
+        "compression_anchor_message_key",
+        "compression_anchor_summary",
+        "pre_compression_snapshot",
+        "context_engine",
+        "compression_anchor_engine",
+        "compression_anchor_mode",
+        "compression_anchor_details",
+        "context_engine_state",
+        "context_length",
+        "threshold_tokens",
+        "last_prompt_tokens",
+        "truncation_watermark",
+        "gateway_routing",
+        "gateway_routing_history",
+        "llm_title_generated",
+        "manual_title",
+        "parent_session_id",
+        "worktree_path",
+        "worktree_branch",
+        "worktree_repo_root",
+        "worktree_created_at",
+        "is_cli_session",
+        "source_tag",
+        "raw_source",
+        "session_source",
+        "source_label",
+        "read_only",
+        "enabled_toolsets",
+        "composer_draft",
+    }
+)
+
+_UNSAFE_FIELDS = frozenset({"session_id", "messages", "tool_calls", "message_count"})
+
+
+class WebUIJsonSessionDB:
+    """Small SessionDB-like facade over existing WebUI session JSON files."""
+
+    def __init__(self, session_dir: Path | str | None = None):
+        self._session_dir = Path(session_dir).expanduser().resolve() if session_dir else None
+
+    @property
+    def session_dir(self) -> Path:
+        return self._session_dir or models.SESSION_DIR
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """Return compact metadata for persisted WebUI JSON sessions.
+
+        Reads are direct JSON loads and never call ``Session.load()``, because
+        that path may self-heal and write repaired transcripts.
+        """
+        rows: list[dict[str, Any]] = []
+        if not self.session_dir.exists():
+            return rows
+        for path in self.session_dir.glob("*.json"):
+            if path.name.startswith("_"):
+                continue
+            data = self._read_path(path)
+            if not isinstance(data, dict):
+                continue
+            sid = str(data.get("session_id") or path.stem)
+            if not models.is_safe_session_id(sid):
+                continue
+            rows.append(self._metadata_row(sid, data))
+        rows.sort(key=lambda row: (bool(row.get("pinned")), self._sort_timestamp(row)), reverse=True)
+        return rows
+
+    def read_session(self, sid: str) -> dict[str, Any] | None:
+        """Return the full JSON session payload for ``sid`` without mutation."""
+        path = self._path_for_sid(sid)
+        if path is None or not path.exists():
+            return None
+        data = self._read_path(path)
+        if not isinstance(data, dict):
+            return None
+        return copy.deepcopy(data)
+
+    def update_metadata(self, sid: str, fields: dict[str, Any]) -> dict[str, Any]:
+        """Persist allowlisted metadata fields while preserving messages.
+
+        This dormant adapter method is for migration experiments and tests only.
+        Runtime wiring must add Session lock/cache/index parity before using it
+        from live WebUI routes.
+        """
+        if not isinstance(fields, dict):
+            raise TypeError("fields must be a dict")
+        unsafe = sorted((set(fields) & _UNSAFE_FIELDS) | (set(fields) - _METADATA_FIELDS))
+        if unsafe:
+            raise ValueError(f"Unsafe session metadata fields: {', '.join(unsafe)}")
+
+        path = self._existing_path_for_sid(sid)
+        data = self._read_writable_session(path)
+        data.update(copy.deepcopy(fields))
+        data["message_count"] = len(data["messages"])
+        self._atomic_write(path, data)
+        return self._metadata_row(str(data.get("session_id") or sid), data)
+
+    def archive(self, sid: str, archived: bool = True) -> dict[str, Any]:
+        """Set the archived metadata flag without touching transcript messages."""
+        return self.update_metadata(sid, {"archived": bool(archived)})
+
+    def write_session(self, session: dict[str, Any]) -> dict[str, Any]:
+        """Write a full session payload for tests and migration experiments."""
+        if not isinstance(session, dict):
+            raise TypeError("session must be a dict")
+        sid = session.get("session_id")
+        path = self._path_for_sid(sid)
+        if path is None:
+            raise ValueError(f"Unsafe session_id {sid!r}")
+        messages = session.get("messages")
+        if not isinstance(messages, list):
+            raise ValueError("session payload must include a messages list")
+        payload = copy.deepcopy(session)
+        payload["message_count"] = len(messages)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._atomic_write(path, payload)
+        return copy.deepcopy(payload)
+
+    def _path_for_sid(self, sid: str) -> Path | None:
+        if not models.is_safe_session_id(sid):
+            return None
+        return self.session_dir / f"{sid}.json"
+
+    def _existing_path_for_sid(self, sid: str) -> Path:
+        path = self._path_for_sid(sid)
+        if path is None:
+            raise ValueError(f"Unsafe session_id {sid!r}")
+        if not path.exists():
+            raise KeyError(sid)
+        return path
+
+    def _read_writable_session(self, path: Path) -> dict[str, Any]:
+        data = self._read_path(path)
+        if not isinstance(data, dict):
+            raise ValueError(f"Malformed session JSON: {path.name}")
+        sid = data.get("session_id")
+        if not models.is_safe_session_id(sid):
+            raise ValueError(f"Unsafe session_id {sid!r}")
+        if not isinstance(data.get("messages"), list):
+            raise ValueError(f"Refusing to write metadata-only session stub: {sid!r}")
+        return data
+
+    @staticmethod
+    def _read_path(path: Path) -> dict[str, Any] | None:
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            return None
+
+    @staticmethod
+    def _metadata_row(sid: str, data: dict[str, Any]) -> dict[str, Any]:
+        messages = data.get("messages")
+        message_count = data.get("message_count")
+        if not isinstance(message_count, int):
+            message_count = len(messages) if isinstance(messages, list) else 0
+        row = {field: copy.deepcopy(data.get(field)) for field in _METADATA_FIELDS if field in data}
+        row["session_id"] = sid
+        row["message_count"] = message_count
+        row["last_message_at"] = data.get("last_message_at") or data.get("updated_at") or data.get("created_at")
+        return row
+
+    @staticmethod
+    def _sort_timestamp(row: dict[str, Any]) -> float:
+        for key in ("last_message_at", "updated_at", "created_at"):
+            value = row.get(key)
+            if value is None or value == "":
+                continue
+            try:
+                return float(value)
+            except (TypeError, ValueError):
+                continue
+        return 0.0
+
+    @staticmethod
+    def _atomic_write(path: Path, data: dict[str, Any]) -> None:
+        payload = json.dumps(data, ensure_ascii=False, indent=2)
+        tmp = path.with_suffix(f".tmp.{os.getpid()}.{threading.current_thread().ident}")
+        try:
+            with open(tmp, "w", encoding="utf-8") as handle:
+                handle.write(payload)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(tmp, path)
+        finally:
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def list_sessions() -> list[dict[str, Any]]:
+    return WebUIJsonSessionDB().list_sessions()
+
+
+def read_session(sid: str) -> dict[str, Any] | None:
+    return WebUIJsonSessionDB().read_session(sid)
+
+
+def update_metadata(sid: str, fields: dict[str, Any]) -> dict[str, Any]:
+    return WebUIJsonSessionDB().update_metadata(sid, fields)
+
+
+def archive(sid: str, archived: bool = True) -> dict[str, Any]:
+    return WebUIJsonSessionDB().archive(sid, archived)
+
+
+def write_session(session: dict[str, Any]) -> dict[str, Any]:
+    return WebUIJsonSessionDB().write_session(session)

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

@@ -28,8 +28,8 @@ def _load_repo_dotenv() -> None:
     ``python3 bootstrap.py`` directly behaves identically to ``./start.sh``.
     Variables are set unconditionally (matching shell source semantics), so a
     value in .env overrides one already present in the shell environment.
-    To keep a CLI-supplied value, unset it from .env or launch via start.sh
-    and override there.
+    ``ctl.sh`` sets HERMES_WEBUI_PRESERVE_ENV=1 when it has already resolved
+    launcher-specific values such as HERMES_HOME or HERMES_WEBUI_STATE_DIR.
 
     Only loads the webui repo .env — not ~/.hermes/.env, which the server
     loads independently at startup for provider credentials.
@@ -41,6 +41,12 @@ def _load_repo_dotenv() -> None:
     if not env_path.exists():
         return
     try:
+        preserve_existing = os.getenv("HERMES_WEBUI_PRESERVE_ENV", "").strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
         for raw_line in env_path.read_text(encoding="utf-8").splitlines():
             line = raw_line.strip()
             if not line or line.startswith("#") or "=" not in line:
@@ -52,6 +58,8 @@ def _load_repo_dotenv() -> None:
                 k = k[7:].strip()
             v = v.strip().strip('"').strip("'")
             if k:
+                if preserve_existing and k in os.environ:
+                    continue
                 os.environ[k] = v
     except Exception as exc:
         import sys as _sys
@@ -84,12 +92,53 @@ def is_wsl() -> bool:
 
 def ensure_supported_platform() -> None:
     if platform.system() == "Windows" and not is_wsl():
-        raise RuntimeError(
-            "Native Windows is not supported for this bootstrap yet. "
-            "Please run it from Linux, macOS, or inside WSL2."
+        info(
+            "Warning: Native Windows bootstrap is experimental. "
+            "Embedded terminal and auto-install are not supported."
         )
 
 
+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 +154,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:
@@ -113,7 +162,7 @@ def discover_launcher_python(agent_dir: Path | None) -> str:
     if env_python:
         return env_python
     if agent_dir:
-        for rel in ("venv/bin/python", "venv/Scripts/python.exe"):
+        for rel in ("venv/bin/python", "venv/Scripts/python.exe", ".venv/bin/python", ".venv/Scripts/python.exe"):
             candidate = agent_dir / rel
             if candidate.exists():
                 return str(candidate)
@@ -124,22 +173,71 @@ def discover_launcher_python(agent_dir: Path | None) -> str:
     return shutil.which("python3") or shutil.which("python") or sys.executable
 
 
-def ensure_python_has_webui_deps(python_exe: str) -> str:
+def _python_can_run_webui_and_agent(python_exe: str, agent_dir: Path | None = None) -> bool:
+    script = "import yaml\nfrom run_agent import AIAgent\n"
+    env = os.environ.copy()
+    if agent_dir:
+        # PREPEND agent_dir to PYTHONPATH so an `agent_dir/run_agent.py` wins
+        # over any stale `run_agent` package in system site-packages (sys.path
+        # order: script-dir → PYTHONPATH entries → site-packages). The
+        # "if PYTHONPATH unset" branch avoids a leading os.pathsep, which
+        # CPython would interpret as "current directory" — a footgun.
+        env["PYTHONPATH"] = (
+            str(agent_dir)
+            if not env.get("PYTHONPATH")
+            else f"{agent_dir}{os.pathsep}{env['PYTHONPATH']}"
+        )
     check = subprocess.run(
-        [python_exe, "-c", "import yaml"],
+        [python_exe, "-c", script],
         capture_output=True,
         text=True,
+        env=env,
     )
-    if check.returncode == 0:
+    return check.returncode == 0
+
+
+def ensure_python_has_webui_deps(python_exe: str, agent_dir: Path | None = None) -> str:
+    """Return a Python executable that can run both WebUI and Hermes Agent.
+
+    The WebUI can be launched directly with its local .venv. That venv has the
+    WebUI dependencies (for example PyYAML), but may not have Hermes Agent on its
+    import path. In that case the server starts healthy, then chat fails later
+    with "AIAgent not available". Prefer the agent venv when it is usable, and
+    validate the final interpreter before starting the server.
+    """
+    if _python_can_run_webui_and_agent(python_exe, agent_dir):
         return python_exe
 
+    agent_candidates: list[Path] = []
+    if agent_dir:
+        for rel in (
+            "venv/bin/python",
+            "venv/Scripts/python.exe",
+            ".venv/bin/python",
+            ".venv/Scripts/python.exe",
+        ):
+            agent_candidates.append(agent_dir / rel)
+        for candidate in agent_candidates:
+            if str(candidate) != python_exe and candidate.exists():
+                if _python_can_run_webui_and_agent(str(candidate), agent_dir):
+                    return str(candidate)
+
     venv_dir = REPO_ROOT / ".venv"
     venv_python = venv_dir / (
         "Scripts/python.exe" if platform.system() == "Windows" else "bin/python"
     )
     if not venv_python.exists():
         info(f"Creating local virtualenv at {venv_dir}")
-        venv.EnvBuilder(with_pip=True).create(venv_dir)
+        # symlinks=True: some Python builds (notably mise/asdf shared-library
+        # installs on macOS) default venv to copy mode. The copied binary still
+        # uses @executable_path/../lib/libpython3.X.dylib for its load command,
+        # so the venv binary aborts with SIGABRT on first import because the
+        # dylib never gets copied into .venv/lib. Symlinking the interpreter
+        # keeps @executable_path resolving back to the original install.
+        # CPython's venv falls back to copy mode automatically when symlink
+        # creation fails (e.g. older Windows without SeCreateSymbolicLinkPrivilege),
+        # so this is safe to set unconditionally.
+        venv.EnvBuilder(with_pip=True, symlinks=True).create(venv_dir)
 
     info("Installing WebUI dependencies into local virtualenv")
     subprocess.run(
@@ -158,7 +256,13 @@ def ensure_python_has_webui_deps(python_exe: str) -> str:
         ],
         check=True,
     )
-    return str(venv_python)
+    if _python_can_run_webui_and_agent(str(venv_python), agent_dir):
+        return str(venv_python)
+    raise RuntimeError(
+        "Python environment cannot import both WebUI dependencies and Hermes Agent. "
+        "Set HERMES_WEBUI_PYTHON to the Hermes Agent venv Python or install the "
+        "WebUI requirements into that environment."
+    )
 
 
 def hermes_command_exists() -> bool:
@@ -166,6 +270,11 @@ def hermes_command_exists() -> bool:
 
 
 def install_hermes_agent() -> None:
+    if platform.system() == "Windows" and not is_wsl():
+        raise RuntimeError(
+            "Auto-install is not supported on native Windows. "
+            "Install hermes-agent manually first."
+        )
     info(f"Hermes Agent not found. Attempting install via {INSTALLER_URL}")
     subprocess.run(
         ["/bin/bash", "-lc", f"curl -fsSL {INSTALLER_URL} | bash"], check=True
@@ -208,9 +317,85 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Fail instead of attempting the official Hermes installer.",
     )
+    parser.add_argument(
+        "--foreground",
+        action="store_true",
+        help=(
+            "Run server.py in this process (via os.execv on POSIX; via a "
+            "Popen child + exit on Windows, where execv can't replace the "
+            "process image) instead of spawning a detached child. Use this "
+            "under launchd / systemd / supervisord so the "
+            "supervisor sees the long-lived server as the original child. "
+            "Implies --no-browser. Skips the post-launch health probe — the "
+            "supervisor's own KeepAlive / Restart=on-failure handles liveness."
+        ),
+    )
     return parser.parse_args()
 
 
+# Env vars whose presence indicates this process was launched by a supervisor
+# that wants to manage the server's lifecycle (KeepAlive, Restart=always, etc.).
+# When any is set, we auto-promote to --foreground so we don't double-fork.
+#
+# - INVOCATION_ID            systemd (set on every service activation)
+# - JOURNAL_STREAM           systemd (set when stdio is wired to the journal)
+# - NOTIFY_SOCKET            systemd Type=notify, s6 sd_notify-style
+# - XPC_SERVICE_NAME         launchd (set to the Label of the running plist)
+# - SUPERVISOR_ENABLED       supervisord
+# - HERMES_WEBUI_FOREGROUND  explicit user opt-in (=1 / true / yes / on)
+#
+# Note on XPC_SERVICE_NAME: macOS launchd sets this in EVERY Terminal-launched
+# shell too — typical values include "0" (truthy in Python!) and
+# "application.com.apple.Terminal.<UUID>". A bare existence check would
+# false-positive on every Mac dev machine running ./start.sh interactively.
+# We narrow to launchd Label-style names (com.<reverse-dns>.<svc>) — those
+# are real services. Verified with `launchctl getenv XPC_SERVICE_NAME` and
+# Apple's documented launchd behavior.
+_SUPERVISOR_ENV_VARS = (
+    "INVOCATION_ID",
+    "JOURNAL_STREAM",
+    "NOTIFY_SOCKET",
+    "XPC_SERVICE_NAME",
+    "SUPERVISOR_ENABLED",
+)
+
+
+def _is_real_supervisor_value(name: str, value: str) -> bool:
+    """Filter out known-noise env-var values that aren't actual supervisors.
+
+    Most env vars in _SUPERVISOR_ENV_VARS are only set by the supervisor we
+    care about, so any non-empty value is meaningful. XPC_SERVICE_NAME is the
+    exception: macOS launchd sets it in every Terminal-spawned shell with
+    values like "0" or "application.com.apple.Terminal.<UUID>". A real
+    launchd-managed service has a reverse-DNS Label like "com.example.foo".
+    """
+    if not value:
+        return False
+    if name == "XPC_SERVICE_NAME":
+        # Reject Apple's noise values; accept Label-style names.
+        if value == "0":
+            return False
+        if value.startswith("application."):
+            return False
+    return True
+
+
+def _detect_supervisor() -> str | None:
+    """Return the name of the detected supervisor env var, or None.
+
+    Pure inspection of os.environ — no side effects. Returned name is the env
+    var that triggered detection, useful for log messages and for tests.
+    """
+    explicit = os.environ.get("HERMES_WEBUI_FOREGROUND", "").strip().lower()
+    if explicit in ("1", "true", "yes", "on"):
+        return "HERMES_WEBUI_FOREGROUND"
+    for name in _SUPERVISOR_ENV_VARS:
+        value = os.environ.get(name, "")
+        if _is_real_supervisor_value(name, value):
+            return name
+    return None
+
+
 def main() -> int:
     args = parse_args()
     ensure_supported_platform()
@@ -224,26 +409,75 @@ def main() -> int:
         install_hermes_agent()
         agent_dir = discover_agent_dir()
 
-    python_exe = ensure_python_has_webui_deps(discover_launcher_python(agent_dir))
+    python_exe = ensure_python_has_webui_deps(discover_launcher_python(agent_dir), agent_dir)
     state_dir = Path(
         os.getenv("HERMES_WEBUI_STATE_DIR", str(Path.home() / ".hermes" / "webui"))
     ).expanduser()
     state_dir.mkdir(parents=True, exist_ok=True)
-    log_path = state_dir / f"bootstrap-{args.port}.log"
 
-    env = os.environ.copy()
-    env["HERMES_WEBUI_HOST"] = args.host
-    env["HERMES_WEBUI_PORT"] = str(args.port)
-    env.setdefault("HERMES_WEBUI_STATE_DIR", str(state_dir))
+    # Mutate os.environ so child (or post-execv) inherits the resolved values.
+    os.environ["HERMES_WEBUI_HOST"] = args.host
+    os.environ["HERMES_WEBUI_PORT"] = str(args.port)
+    os.environ.setdefault("HERMES_WEBUI_STATE_DIR", str(state_dir))
     if agent_dir:
-        env["HERMES_WEBUI_AGENT_DIR"] = str(agent_dir)
+        os.environ["HERMES_WEBUI_AGENT_DIR"] = str(agent_dir)
+
+    server_cwd = str(agent_dir or REPO_ROOT)
+    server_path = str(REPO_ROOT / "server.py")
+
+    # --foreground (or auto-detected supervisor): replace this process with the
+    # server. The supervisor sees the long-lived server as the original child,
+    # so KeepAlive / Restart=always / autorestart=true work correctly. No
+    # health probe — the supervisor's own restart-on-exit handles liveness.
+    foreground_reason = "--foreground" if args.foreground else _detect_supervisor()
+    if foreground_reason:
+        info(
+            f"Starting Hermes Web UI on http://{args.host}:{args.port} "
+            f"(foreground mode: {foreground_reason})"
+        )
+        try:
+            os.chdir(server_cwd)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Could not chdir to {server_cwd!r} before exec: {exc}"
+            ) from exc
+        # Defensive check: if python_exe is missing or non-executable, execv
+        # raises OSError, the wrapper catches and SystemExit(1)s, and the
+        # supervisor restarts — looping forever, exactly the failure mode this
+        # PR is meant to eliminate. Convert to a single visible error.
+        if not os.access(python_exe, os.X_OK):
+            raise RuntimeError(
+                f"Python interpreter at {python_exe!r} is not executable. "
+                f"Set HERMES_WEBUI_PYTHON to a working interpreter or fix "
+                f"the agent venv at {agent_dir}."
+            )
+        # os.execv replaces the current process image. On Windows, execv
+        # spawns a new process instead of replacing (Python calls CreateProcess),
+        # orphaning it from any supervisor. Use Popen + exit there instead.
+        if sys.platform == "win32":
+            # CREATE_NEW_PROCESS_GROUP only exists in the subprocess module on
+            # Windows; resolve it defensively (0 = no extra flags) so this line
+            # can't AttributeError if reached on a non-Windows interpreter
+            # (e.g. a win32-simulating test) — mirrors the getattr() guard used
+            # for SO_EXCLUSIVEADDRUSE.
+            _CREATE_NEW_PROCESS_GROUP = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            subprocess.Popen([python_exe, server_path],
+                             creationflags=_CREATE_NEW_PROCESS_GROUP)
+            sys.exit(0)
+        os.execv(python_exe, [python_exe, server_path])
+        # Unreachable — execv either replaces the process or raises.
+        raise RuntimeError("os.execv returned unexpectedly")
+
+    # Default (legacy) path: spawn the server as a detached child, probe
+    # /health, then return. Suitable for an interactive `bash start.sh` run.
+    log_path = state_dir / f"bootstrap-{args.port}.log"
 
     info(f"Starting Hermes Web UI on http://{args.host}:{args.port}")
     with log_path.open("ab") as log_file:
         proc = subprocess.Popen(
-            [python_exe, str(REPO_ROOT / "server.py")],
-            cwd=str(agent_dir or REPO_ROOT),
-            env=env,
+            [python_exe, server_path],
+            cwd=server_cwd,
+            env=os.environ.copy(),
             stdout=log_file,
             stderr=subprocess.STDOUT,
             start_new_session=True,

ctl.sh

@@ -0,0 +1,503 @@
+#!/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}"
+DEFAULT_LAUNCHD_LABEL="${HERMES_WEBUI_LAUNCHD_LABEL:-com.parantoux.hermes-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() {
+  [[ "${HERMES_WEBUI_NO_DOTENV:-0}" == "1" ]] && return 0
+  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
+}
+
+_is_windows_bash() {
+  [[ "${OS:-}" == "Windows_NT" ]] && return 0
+  case "$(uname -s 2>/dev/null || true)" in
+    MINGW*|MSYS*|CYGWIN*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+_windows_bash_path() {
+  local path="${1//\\//}" drive rest
+  if [[ "${path}" =~ ^([A-Za-z]):(.*)$ ]]; then
+    drive="${BASH_REMATCH[1],,}"
+    rest="${BASH_REMATCH[2]}"
+    printf '/%s%s\n' "${drive}" "${rest}"
+    return
+  fi
+  printf '%s\n' "${path}"
+}
+
+_windows_pid_for_bash_pid() {
+  local pid="$1"
+  ps -p "${pid}" -l 2>/dev/null | awk 'NR == 2 { print $4 }'
+}
+
+_stop_webui_pid() {
+  local pid="$1" signal="${2:-TERM}"
+  if _is_windows_bash && command -v taskkill >/dev/null 2>&1; then
+    local winpid
+    winpid="$(_windows_pid_for_bash_pid "${pid}")"
+    if [[ "${winpid}" =~ ^[0-9]+$ ]]; then
+      taskkill //F //T //PID "${winpid}" >/dev/null 2>&1 || true
+      return
+    fi
+  fi
+  if [[ "${signal}" == "KILL" ]]; then
+    kill -KILL "${pid}" >/dev/null 2>&1 || true
+  else
+    kill "${pid}" >/dev/null 2>&1 || true
+  fi
+}
+
+_proc_args() {
+  local pid="$1" args
+  args="$(ps -p "${pid}" -o args= 2>/dev/null || true)"
+  if [[ -n "${args}" ]]; then
+    printf '%s\n' "${args}"
+    return
+  fi
+  if _is_windows_bash; then
+    local winpid
+    winpid="$(_windows_pid_for_bash_pid "${pid}")"
+    if [[ "${winpid}" =~ ^[0-9]+$ ]] && command -v wmic >/dev/null 2>&1; then
+      args="$(wmic process where "ProcessId=${winpid}" get CommandLine //value 2>/dev/null | sed -n 's/^CommandLine=//p' | tr -d '\r')"
+      if [[ -n "${args}" ]]; then
+        printf '%s\n' "${args}"
+        return
+      fi
+    fi
+    ps -p "${pid}" -f 2>/dev/null | awk 'NR == 2 { for (i = 8; i <= NF; i++) printf "%s%s", (i == 8 ? "" : " "), $i; print "" }'
+  fi
+}
+
+_is_owned_webui_pid() {
+  local pid="$1" args args_slash state_repo="" state_repo_slash="" state_repo_win="" state_repo_win_slash="" state_python="" state_python_slash="" state_python_bash=""
+  [[ -f "${STATE_FILE}" ]] || return 1
+  _load_state_if_present
+  state_repo="${REPO_ROOT:-}"
+  state_python="${PYTHON_EXE:-}"
+  state_repo_slash="${state_repo//\\//}"
+  state_python_slash="${state_python//\\//}"
+  if _is_windows_bash; then
+    state_repo_win="$(cygpath -w "${state_repo}" 2>/dev/null || true)"
+    state_repo_win_slash="${state_repo_win//\\//}"
+  fi
+  if [[ -n "${state_python}" ]] && _is_windows_bash; then
+    state_python_bash="$(_windows_bash_path "${state_python}")"
+  fi
+  [[ "${state_repo}" == "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ]] || return 1
+  args="$(_proc_args "${pid}")"
+  [[ -n "${args}" ]] || return 1
+  args_slash="${args//\\//}"
+  [[ "${args_slash}" == *"${state_repo_slash}/bootstrap.py"* ||
+     "${args_slash}" == *"${state_repo_slash}/server.py"* ||
+     "${args_slash}" == *"${state_repo_slash}/start.sh"* ||
+     ( -n "${state_repo_win_slash}" && "${args_slash}" == *"${state_repo_win_slash}/bootstrap.py"* ) ||
+     ( -n "${state_repo_win_slash}" && "${args_slash}" == *"${state_repo_win_slash}/server.py"* ) ||
+     ( -n "${state_repo_win_slash}" && "${args_slash}" == *"${state_repo_win_slash}/start.sh"* ) ||
+     ( -n "${state_python}" && "${args}" == *"${state_python}"* ) ||
+     ( -n "${state_python_slash}" && "${args_slash}" == *"${state_python_slash}"* ) ||
+     ( -n "${state_python_bash}" && "${args_slash}" == *"${state_python_bash}"* ) ]]
+}
+
+_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
+}
+
+_pid_listens_on_port() {
+  # Best-effort check that PID $1 has a listening socket on TCP port $2.
+  # macOS (where launchd exists) ships lsof; if we can't determine ownership we
+  # return 2 ("unknown") so the caller can fall back conservatively rather than
+  # guess. Never blocks on a hard failure.
+  local pid="$1" port="$2"
+  [[ "${pid}" =~ ^[0-9]+$ && "${port}" =~ ^[0-9]+$ ]] || return 2
+  if command -v lsof >/dev/null 2>&1; then
+    if lsof -nP -p "${pid}" -iTCP:"${port}" -sTCP:LISTEN >/dev/null 2>&1; then
+      return 0   # PID is listening on that port → real conflict
+    fi
+    return 1     # PID is alive but NOT listening on that port → no conflict
+  fi
+  return 2       # can't determine
+}
+
+_launchd_webui_pid() {
+  [[ "${HERMES_WEBUI_CTL_ALLOW_LAUNCHD_CONFLICT:-0}" == "1" ]] && return 1
+  command -v launchctl >/dev/null 2>&1 || return 1
+  local label="${HERMES_WEBUI_LAUNCHD_LABEL:-${DEFAULT_LAUNCHD_LABEL}}"
+  [[ -n "${label}" ]] || return 1
+  local uid launchd_out pid
+  uid="$(id -u)"
+  launchd_out="$(launchctl print "gui/${uid}/${label}" 2>/dev/null)" || return 1
+  pid="$(printf '%s\n' "${launchd_out}" | awk '/^[[:space:]]*pid = / {print $3; exit}')"
+  [[ "${pid}" =~ ^[0-9]+$ ]] || return 1
+  (( pid > 0 )) || return 1
+  _is_alive "${pid}" || return 1
+  # Only treat the launchd job as a conflict for the port we are about to bind.
+  # A second instance on a DIFFERENT port (e.g. HERMES_WEBUI_PORT=8788 for a
+  # test build) does not collide with the launchd-managed default and must be
+  # allowed to start (#3291 over-block fix). When port ownership can't be
+  # determined (no lsof), fall back to the conservative previous behavior of
+  # only guarding the default port so non-default ports are never wrongly blocked.
+  local want_port="${CTL_PORT:-${HERMES_WEBUI_PORT:-8787}}"
+  _pid_listens_on_port "${pid}" "${want_port}"
+  case "$?" in
+    0) printf '%s\n' "${pid}"; return 0 ;;   # launchd job listens on our port → block
+    1) return 1 ;;                            # launchd job on a different port → allow
+    *)                                        # unknown: only guard the default port
+      if [[ "${want_port}" == "8787" ]]; then
+        printf '%s\n' "${pid}"; return 0
+      fi
+      return 1 ;;
+  esac
+}
+
+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
+  local launchd_pid
+  if launchd_pid="$(_launchd_webui_pid 2>/dev/null)"; then
+    echo "[ctl] Refusing to start a second Hermes WebUI while launchd job ${HERMES_WEBUI_LAUNCHD_LABEL:-${DEFAULT_LAUNCHD_LABEL}} is running (PID ${launchd_pid})." >&2
+    echo "[ctl] Use launchctl kickstart -k gui/$(id -u)/${HERMES_WEBUI_LAUNCHD_LABEL:-${DEFAULT_LAUNCHD_LABEL}} or disable the launchd job before using ctl.sh start." >&2
+    return 2
+  fi
+  _clear_stale_pid >/dev/null 2>&1 || true
+
+  local python_exe pid
+  python_exe="$(_find_python)"
+  : >> "${LOG_FILE}"
+  (
+    cd "${REPO_ROOT}"
+    trap '' HUP
+    export HERMES_WEBUI_PRESERVE_ENV=1
+    exec nohup "${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})"
+  _stop_webui_pid "${pid}" TERM
+  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
+  _stop_webui_pid "${pid}" KILL
+  rm -f "${PID_FILE}" "${STATE_FILE}"
+}
+
+_health_line() {
+  local host="$1" port="$2" url result
+  url="http://${host}:${port}/health"
+  if command -v curl >/dev/null 2>&1; then
+    if result="$(curl -fsS --max-time 2 "${url}" 2>/dev/null)"; then
+      if command -v python3 >/dev/null 2>&1; then
+        printf '%s' "${result}" | python3 -c 'import json,sys
+try:
+    data=json.load(sys.stdin)
+    sessions=data.get("sessions", data.get("session_count", "?"))
+    active=data.get("active_streams", "?")
+    status=data.get("status", "ok")
+    print(f"ok ({sessions} sessions, {active} active streams)" if status == "ok" else status)
+except Exception:
+    print("ok")'
+      else
+        echo "ok"
+      fi
+    else
+      echo "unreachable (${url})"
+    fi
+  else
+    echo "unknown (curl not found; ${url})"
+  fi
+}
+
+status_cmd() {
+  ensure_home
+  _load_state_if_present
+  local host="${HOST:-${HERMES_WEBUI_HOST:-127.0.0.1}}"
+  local port="${PORT:-${HERMES_WEBUI_PORT:-8787}}"
+  local log_path="${LOG_FILE}"
+  local pid uptime health
+
+  if pid="$(_current_pid 2>/dev/null)"; then
+    uptime="$(ps -p "${pid}" -o etime= 2>/dev/null | sed 's/^ *//' || true)"
+    health="$(_health_line "${host}" "${port}")"
+    echo "● hermes-webui — running"
+    echo "  PID:     ${pid}"
+    echo "  Uptime:  ${uptime:-unknown}"
+    echo "  Bound:   ${host}:${port}"
+    echo "  Log:     ${log_path}"
+    echo "  Health:  ${health}"
+  else
+    [[ -f "${PID_FILE}" ]] && _clear_stale_pid >/dev/null 2>&1 || true
+    echo "● hermes-webui — stopped"
+    echo "  PID:     -"
+    echo "  Bound:   ${host}:${port}"
+    echo "  Log:     ${log_path}"
+    echo "  Health:  not checked"
+  fi
+}
+
+logs_cmd() {
+  ensure_home
+  local lines=100 follow=1
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --lines)
+        shift
+        lines="${1:-}"
+        [[ "${lines}" =~ ^[0-9]+$ ]] || { echo "[ctl] --lines requires a number" >&2; return 2; }
+        ;;
+      --lines=*)
+        lines="${1#--lines=}"
+        [[ "${lines}" =~ ^[0-9]+$ ]] || { echo "[ctl] --lines requires a number" >&2; return 2; }
+        ;;
+      --follow|-f)
+        follow=1
+        ;;
+      --no-follow)
+        follow=0
+        ;;
+      *)
+        echo "[ctl] Unknown logs option: $1" >&2
+        return 2
+        ;;
+    esac
+    shift
+  done
+  touch "${LOG_FILE}"
+  if (( follow )); then
+    tail -n "${lines}" -f "${LOG_FILE}"
+  else
+    tail -n "${lines}" "${LOG_FILE}"
+  fi
+}
+
+cmd="${1:-}"
+if [[ $# -gt 0 ]]; then
+  shift
+fi
+
+case "${cmd}" in
+  start) start_cmd "$@" ;;
+  stop) stop_cmd ;;
+  restart) stop_cmd; start_cmd "$@" ;;
+  status) status_cmd ;;
+  logs) logs_cmd "$@" ;;
+  -h|--help|help|"") usage ;;
+  *) echo "[ctl] Unknown command: ${cmd}" >&2; usage >&2; exit 2 ;;
+esac

docker-compose.three-container.yml

@@ -1,18 +1,37 @@
 # Three-container Docker Compose: Hermes Agent + Dashboard + WebUI
 #
+# QUICK START:
+#   docker compose -f docker-compose.three-container.yml up -d
+#   Open http://localhost:8787 (chat) and http://localhost:9119 (dashboard)
+#
 # This extends the two-container setup with the Hermes Dashboard for
 # monitoring agent activity, sessions, and resource usage.
 #
-# Usage:
-#   docker compose -f docker-compose.three-container.yml up -d
-#
 # Services:
-#   hermes-agent   — gateway API on port 8642 (CLI, Telegram, cron, tools)
+#   hermes-agent     — gateway API on port 8642 (CLI, Telegram, cron, tools)
 #   hermes-dashboard — monitoring dashboard on port 9119
-#   hermes-webui   — browser chat interface on port 8787
+#   hermes-webui     — browser chat interface on port 8787
 #
 # All three share the same hermes-home volume so config, sessions,
 # skills, and memory are consistent across all surfaces.
+#
+# WHEN NOT TO USE THIS:
+#   - You hit "Permission denied" trying to share an existing ~/.hermes directory
+#     → use docker-compose.yml (single-container) instead, OR
+#     → keep this file but switch to NAMED VOLUMES (the default) instead of bind mounts
+#   - You're on Podman 3.4 or older without keep-id namespace support
+#     → see https://github.com/sunnysktsang/hermes-suite for an all-in-one image
+#
+# KNOWN LIMITATION (#681): tools triggered from the WebUI run in the WebUI
+# container, not the agent container. See docker-compose.two-container.yml
+# for context.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box. If you prefer bind mounts (e.g. to an existing
+#   directory), see docker-compose.two-container.yml for a bind-mount example.
+#   When using bind mounts, ALL THREE containers must mount the same host path
+#   AND run as the same UID/GID (set via the UID/GID env vars below).
 
 services:
   hermes-agent:
@@ -23,13 +42,24 @@ services:
       - "127.0.0.1:8642:8642"
     volumes:
       # Persist config, state, sessions, skills, memory across restarts
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
       # Expose agent source so the WebUI can install dependencies from it
       - hermes-agent-src:/opt/hermes
     environment:
-      - HERMES_HOME=/root/.hermes
-      - HERMES_UID=${HERMES_UID:-10000}
-      - HERMES_GID=${HERMES_GID:-10000}
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      # Bind-mount permission handling for the agent — narrow set of overrides.
+      # NOTE: The agent's HERMES_HOME_MODE applies to the HERMES_HOME *directory*
+      # mode (default 0700) — NOT to credential files like the WebUI's variant.
+      # If you set this, you MUST keep the owner-execute bit so the agent can
+      # traverse its own home directory. 0640 BREAKS the agent (no x bit → no
+      # traversal). Use 0750 for group-traversable or 0701 for x-only.
+      # The agent's container detection (/.dockerenv) already auto-skips
+      # credential chmod inside Docker, so HERMES_SKIP_CHMOD is redundant here.
+      # - HERMES_HOME_MODE=0750
     restart: unless-stopped
     deploy:
       resources:
@@ -46,11 +76,13 @@ services:
     ports:
       - "127.0.0.1:9119:9119"
     volumes:
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
     environment:
-      - HERMES_HOME=/root/.hermes
-      - HERMES_UID=${HERMES_UID:-10000}
-      - HERMES_GID=${HERMES_GID:-10000}
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
       # Dashboard connects to the gateway for health/session data
       - GATEWAY_HEALTH_URL=http://hermes-agent:8642
     depends_on:
@@ -77,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
@@ -102,6 +136,13 @@ services:
       # to match the agent container's UID, or use a named Docker volume (preferred).
       # Optional: set a password for remote access
       # - HERMES_WEBUI_PASSWORD=your-secret-password
+      # Bind-mount permission handling for the WebUI (fixes #1389, #1399).
+      # NOTE: WebUI's HERMES_HOME_MODE is a credential-file threshold (allow
+      # group bits on .env/.signing_key/etc.), DIFFERENT from the agent's
+      # which applies to the HERMES_HOME directory itself. 0640 is correct
+      # for the WebUI; do NOT copy this value to the agent service block.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
     restart: unless-stopped
     networks:
       - hermes-net
@@ -111,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

@@ -1,15 +1,49 @@
 # Two-container Docker Compose: Hermes Agent + Hermes WebUI
 #
-# This runs the agent and web UI in separate containers connected via
-# shared volumes. The WebUI installs the agent's Python dependencies
-# at startup from the shared agent source volume.
-#
-# Usage:
+# QUICK START:
 #   docker compose -f docker-compose.two-container.yml up -d
+#   Open http://localhost:8787
 #
-# The agent container runs the gateway (CLI, Telegram, cron, etc.).
-# The WebUI container serves the browser interface on port 8787.
-# Both share ~/.hermes for config, sessions, and state.
+# This runs the agent and web UI in separate containers connected via shared
+# Docker volumes. The WebUI installs the agent's Python dependencies from the
+# shared agent source volume at startup.
+#
+# WHEN TO USE THIS:
+#   - You want isolation between the agent gateway and the WebUI
+#   - You're already running hermes-agent in its own container
+#   - You don't need the dashboard (use docker-compose.three-container.yml for that)
+#
+# WHEN NOT TO USE THIS:
+#   - You hit "Permission denied" trying to share an existing ~/.hermes directory
+#     → use docker-compose.yml (single-container) instead, OR
+#     → keep this file but switch to NAMED VOLUMES (the default) instead of bind mounts
+#   - You're on Podman 3.4 or older without keep-id namespace support
+#     → see https://github.com/sunnysktsang/hermes-suite for an all-in-one image
+#
+# KNOWN LIMITATION (#681): tools triggered from the WebUI run in the WebUI
+# container, not the agent container. If you need git/node/etc. on the
+# WebUI's filesystem, install them in the WebUI image — or use a single-
+# container setup where everything lives in one place.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box on every Docker installation. If you prefer bind mounts
+#   to share an existing host directory:
+#
+#     volumes:
+#       hermes-home:
+#         driver: local
+#         driver_opts:
+#           type: none
+#           o: bind
+#           device: /home/youruser/.hermes
+#
+#   When using bind mounts, BOTH containers must mount the same host path,
+#   AND your host directory must be readable by UID 1000 (the default). Run:
+#     id -u && id -g
+#   to find your host UID/GID, then put them in a .env file:
+#     echo "UID=$(id -u)" >> .env
+#     echo "GID=$(id -g)" >> .env
 
 services:
   hermes-agent:
@@ -23,11 +57,25 @@ services:
       - "127.0.0.1:8642:8642"
     volumes:
       # Persist config, state, sessions, skills, memory across restarts
-      - hermes-home:/root/.hermes
+      - hermes-home:/home/hermes/.hermes
       # Expose agent source so the WebUI can install dependencies from it
       - hermes-agent-src:/opt/hermes
     environment:
-      - HERMES_HOME=/root/.hermes
+      - HERMES_HOME=/home/hermes/.hermes
+      # Align UID/GID across containers sharing the hermes-home volume.
+      # Defaults to 1000 to match WANTED_UID/WANTED_GID in the webui service.
+      # The agent image's entrypoint already supports usermod remapping.
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      # Bind-mount permission handling for the agent — narrow set of overrides.
+      # NOTE: The agent's HERMES_HOME_MODE applies to the HERMES_HOME *directory*
+      # mode (default 0700) — NOT to credential files like the WebUI's variant.
+      # If you set this, you MUST keep the owner-execute bit so the agent can
+      # traverse its own home directory. 0640 BREAKS the agent (no x bit → no
+      # traversal). Use 0750 for group-traversable or 0701 for x-only.
+      # The agent's container detection (/.dockerenv) already auto-skips
+      # credential chmod inside Docker, so HERMES_SKIP_CHMOD is redundant here.
+      # - HERMES_HOME_MODE=0750
     restart: unless-stopped
     networks:
       - hermes-net
@@ -43,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
@@ -64,7 +114,14 @@ services:
       - WANTED_UID=${UID:-1000}
       - WANTED_GID=${GID:-1000}
       # Optional: set a password for remote access
-      # - HERMES_WEBUI_PASSWORD=***
+      # - HERMES_WEBUI_PASSWORD=your-secret-password
+      # Bind-mount permission handling for the WebUI (fixes #1389, #1399).
+      # NOTE: WebUI's HERMES_HOME_MODE is a credential-file threshold (allow
+      # group bits on .env/.signing_key/etc.), DIFFERENT from the agent's
+      # which applies to the HERMES_HOME directory itself. 0640 is correct
+      # for the WebUI; do NOT copy this value to the agent service block.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
     restart: unless-stopped
     networks:
       - hermes-net
@@ -74,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-compose.yml

@@ -1,4 +1,15 @@
-version: "3.8"
+# Hermes WebUI — single-container Docker Compose
+#
+# QUICK START (most users):
+#   1. (Optional) Copy .env.docker.example to .env and edit values
+#   2. docker compose up -d
+#   3. Open http://localhost:8787
+#
+# This is the simplest setup: one WebUI container that runs the agent in-process.
+# The WebUI auto-detects host UID/GID from the mounted .hermes volume.
+#
+# For multi-container setups (separate agent + webui or agent+webui+dashboard),
+# see docker-compose.two-container.yml or docker-compose.three-container.yml.
 
 services:
   hermes-webui:
@@ -33,5 +44,14 @@ services:
 #      - HERMES_WEBUI_DEFAULT_WORKSPACE=/workspace
       # Optional: set a password for remote access
       # - HERMES_WEBUI_PASSWORD=your-secret-password
+      #
+      # Bind-mount permission handling (fixes #1389, #1399):
+      #   When you mount an EXISTING ~/.hermes directory (the common case),
+      #   the WebUI's startup credential-permission fixer can clash with
+      #   your host file modes (e.g. 0640 group-readable .env files).
+      #   Set HERMES_SKIP_CHMOD=1 to bypass the fixer entirely, OR set
+      #   HERMES_HOME_MODE=0640 to allow group bits while still stripping
+      #   world-readable. Both are documented in api/startup.py.
+      # - HERMES_SKIP_CHMOD=1
+      # - HERMES_HOME_MODE=0640
     restart: unless-stopped
-

docker_init.bash

@@ -19,13 +19,14 @@ ok_exit() {
 # Ignore list: variables to ignore when loading environment variables from user to user
 export ENV_IGNORELIST="HOME PWD USER SHLVL TERM OLDPWD SHELL _ SUDO_COMMAND HOSTNAME LOGNAME MAIL SUDO_GID SUDO_UID SUDO_USER CHECK_NV_CUDNN_VERSION VIRTUAL_ENV VIRTUAL_ENV_PROMPT ENV_IGNORELIST ENV_OBFUSCATE_PART"
 # Obfuscate part: part of the key to obfuscate when loading environment variables from user to user, ex: HF_TOKEN, ...
-export ENV_OBFUSCATE_PART="TOKEN API KEY"
+export ENV_OBFUSCATE_PART="TOKEN API KEY PASSWORD SECRET CREDENTIAL COOKIE SESSION"
 
 # Check for ENV_IGNORELIST and ENV_OBFUSCATE_PART
 if [ -z "${ENV_IGNORELIST+x}" ]; then error_exit "ENV_IGNORELIST not set"; fi
 if [ -z "${ENV_OBFUSCATE_PART+x}" ]; then error_exit "ENV_OBFUSCATE_PART not set"; fi
 
-whoami=`whoami`
+# 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,120 @@ 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 -name ".git" -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"
+
+  # Preserve Docker --group-add supplemental groups (for example render/video
+  # for /dev/dri GPU access) when dropping privileges. `su` rebuilds the target
+  # user's groups from /etc/group, so host-passed numeric groups must be made
+  # visible to hermeswebui before re-entering as the runtime user.
+  for gid in $(id -G); do
+    if [ "$gid" = "0" ] || [ "$gid" = "$WANTED_GID" ]; then
+      continue
+    fi
+    group_name="$(getent group "$gid" | cut -d: -f1 || true)"
+    if [ -z "$group_name" ]; then
+      group_name="hostgpu${gid}"
+      groupadd -g "$gid" "$group_name" 2>/dev/null || true
+      group_name="$(getent group "$gid" | cut -d: -f1 || true)"
+    fi
+    if [ -z "$group_name" ]; then
+      echo "!! WARNING: Could not create supplemental group for GID $gid; GPU device access may be unavailable"
+      continue
+    fi
+    if [ -n "$group_name" ]; then
+      usermod -a -G "$group_name" hermeswebui 2>/dev/null || echo "!! WARNING: Could not add hermeswebui to supplemental group $group_name ($gid)"
+    fi
+  done
+
   # 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 +303,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 +325,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 +336,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 +362,9 @@ else
 fi
 export UV_PROJECT_ENVIRONMENT=venv
 
-export UV_CACHE_DIR=/uv_cache
-sudo mkdir -p ${UV_CACHE_DIR} || error_exit "Failed to create /uv_cache directory"
-sudo chown hermeswebui:hermeswebui ${UV_CACHE_DIR} || error_exit "Failed to set owner of ${UV_CACHE_DIR} to hermeswebui user"
+export UV_CACHE_DIR=${UV_CACHE_DIR:-/uv_cache}
+mkdir -p "${UV_CACHE_DIR}" || error_exit "Failed to create ${UV_CACHE_DIR} directory"
+test -w "${UV_CACHE_DIR}" || error_exit "${UV_CACHE_DIR} is not writable by hermeswebui"
 
 cd /app
 if [ -f /app/venv/bin/python3 ]; then
@@ -285,6 +381,19 @@ echo "";echo "== Activating hermes webui's virtual environment"
 source /app/venv/bin/activate || error_exit "Failed to activate hermeswebui virtual environment"
 test -x /app/venv/bin/python3
 
+ensure_hindsight_client_docker_dependency() {
+  # Keep this outside the .deps_installed fast-restart guard so existing
+  # two-container Docker venvs self-heal after this dependency was added.
+  _hindsight_client_requirement="hindsight-client>=0.4.22"
+  echo ""; echo "== Checking Hindsight memory provider dependency"
+  if uv pip show hindsight-client >/dev/null 2>&1; then
+    echo "-- hindsight-client already installed"
+  else
+    echo "-- Installing ${_hindsight_client_requirement} for Hindsight memory provider support"
+    uv pip install "${_hindsight_client_requirement}" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hindsight-client"
+  fi
+}
+
 if [ -f /app/venv/.deps_installed ]; then
   echo ""; echo "== Dependencies already installed — skipping (fast restart)"
 else
@@ -294,20 +403,79 @@ else
   test -x /app/venv/bin/pip
 
   echo ""; echo "== Adding hermes-agent's pyproject.toml base dependencies to the virtual environment"
-  if [ -d "/home/hermeswebui/.hermes/hermes-agent" ] && [ -f "/home/hermeswebui/.hermes/hermes-agent/pyproject.toml" ]; then
-    uv pip install "/home/hermeswebui/.hermes/hermes-agent[honcho]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
+  _agent_paths=(
+    "/home/hermeswebui/.hermes/hermes-agent"
+    "/opt/hermes"
+  )
+  _agent_src=""
+  for _p in "${_agent_paths[@]}"; do
+    if [ -d "$_p" ] && [ -f "$_p/pyproject.toml" ]; then
+      _agent_src="$_p"
+      break
+    fi
+  done
+  if [ -n "$_agent_src" ]; then
+    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 at /home/hermeswebui/.hermes/hermes-agent"
+    echo "!! WARNING: hermes-agent source not found."
+    echo "!!   Looked in: ${_agent_paths[0]}"
+    echo "!!              ${_agent_paths[1]}"
     echo "!! The WebUI will start with reduced functionality (no model auto-detection,"
     echo "!! no personality routing, no CLI session imports)."
-    echo "!! To fix: mount the agent source volume into the container. See:"
+    echo "!! To fix: mount the agent source volume into the container:"
+    echo "!!   -v /path/to/hermes-agent:/home/hermeswebui/.hermes/hermes-agent"
+    echo "!! Or see the two-container compose example:"
     echo "!!   https://github.com/nesquena/hermes-webui/blob/master/docker-compose.two-container.yml"
     echo ""
   fi
   touch /app/venv/.deps_installed
 fi
 
+ensure_hindsight_client_docker_dependency
+
 echo ""; echo "== Running hermes-webui"
 cd /app; python server.py || error_exit "hermes-webui failed or exited with an error"
 

docs/CONTRACTS.md

@@ -0,0 +1,225 @@
+# 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/live-to-final-assistant-replies.md`](rfcs/live-to-final-assistant-replies.md):
+  proposed product model for long-running assistant replies, live process text,
+  tool activity, recovery, terminal outcomes, and final-answer boundaries. Start
+  here for UI/UX changes to running-session assistant reply rendering.
+- [`docs/architecture/stable-assistant-turn-anchor-phase0.md`](architecture/stable-assistant-turn-anchor-phase0.md):
+  current Phase 0 inventory for the Stable Assistant Turn Anchors work under
+  #3926. Use this before wiring anchor helpers into live SSE, replay,
+  settlement, `INFLIGHT`, or `renderMessages()` paths.
+- [`docs/rfcs/canonical-session-resolution.md`](rfcs/canonical-session-resolution.md):
+  proposed contract for resolving URL routes, query parameters, localStorage,
+  sidebar rows, and compression-lineage IDs to one canonical visible session
+  target. Start here for session routing, boot restore, stale parent, or
+  compression-tip selection changes.
+- [`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/architecture/agent-api-contract.md`](architecture/agent-api-contract.md):
+  current audit of WebUI dependencies on the hermes-agent source checkout and
+  the replacement API/client surfaces needed before source mounts can be removed.
+  Start here for issue #2491 and Docker/source-boundary migration slices.
+- [`docs/rfcs/turn-journal.md`](rfcs/turn-journal.md): proposed crash-safe
+  write-ahead journal for browser-originated chat turns.
+- [`docs/rfcs/webui-pending-intent-controls.md`](rfcs/webui-pending-intent-controls.md):
+  proposed control-surface companion to the long-running-session reply model for
+  Queue, Steer, Stop-and-send, Interrupt, and leftover-steer inputs submitted
+  while an agent run is active. Start here for busy-composer behavior, pending
+  queued messages, interrupt replacement, steer visibility, or leftover-steer
+  recovery changes.
+- [`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.
+
+## Contract changes
+
+Changing contract documents, RFC guidance, or contract tests changes review
+expectations for future contributors. A PR that intentionally changes an
+existing contract should include a `Contract Change` section in its PR body with:
+
+- the previous contract,
+- the new contract,
+- the affected docs and tests,
+- the compatibility or migration reason.
+
+Contract tests and corresponding docs must move together. Tests that encode
+product semantics must not silently redefine the contract by asserting the
+opposite behavior without updating the public docs and naming the change in the
+PR body.
+
+The static tests for this guidance are advisory coverage. They pin contributor
+wording so the rule stays visible. This advisory coverage is not an automated
+policy gate; static coverage is not an automated policy gate and does not enforce
+PR-body content on GitHub. A future release-time or CI check could
+surface contract-affecting diffs whose PR body lacks `Contract Routing`, but this
+document only defines the review expectation.
+
+Release batches should list included contract-affecting PRs explicitly so
+reviewers can distinguish ordinary green-CI fixes from changes that update the
+project's product or runtime guardrails.
+
+## 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.
+- Contract-affecting PRs include `Contract Routing`; intentional contract
+  changes also include `Contract Change`.
+- 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/EXTENSIONS.md

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

docs/ISSUES.md

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

docs/UIUX-GUIDE.md

@@ -0,0 +1,205 @@
+# 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.
+
+Visible interim assistant progress is part of the live conversation timeline,
+not raw debug detail. Compact Activity may collapse tool arguments, long tool
+results, and low-level reasoning detail, but it must not make concise
+user-visible progress text available only inside a collapsed disclosure.
+
+Automatic compression is a live-only context barrier, not a special branded
+tool card. Render it as a centered, non-interactive divider with quiet horizontal
+rules: `Compressing context` while the compression barrier is active and
+`Context auto-compressed` when the agent has continued or the compression
+completion event arrives. Do not give it a caret, click target, leading status
+dot, or standalone running badge. In settled final history, remove live-only
+automatic compression rows unless they explain a visible recovery or error
+state.
+
+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/advanced-chat-setup.md

@@ -0,0 +1,83 @@
+# Advanced chat setup
+
+Two optional features for self-hosted Hermes WebUI deployments. **Most users need neither** — the defaults (in-process chat, no prefill) work out of the box.
+
+## Session recall prefill
+
+WebUI can attach ephemeral prefill messages to new browser-originated
+agent turns. This is useful when a deployment already has a local recall or
+router script for Joplin, Obsidian, Notion, llm-wiki, or another third-party
+notes source and wants browser chat to know where durable context lives.
+
+Prefer a compact router-style prefill (for example, "Joplin has the durable
+project context; use the available notes/search tools before answering
+detail-dependent questions") instead of dumping the full note corpus into every
+new browser session. The prefill should point the agent toward retrieval; the
+notes/search tools should provide the specific facts on demand.
+
+Static JSON remains supported through `prefill_messages_file` or
+`HERMES_PREFILL_MESSAGES_FILE`. For dynamic recall, opt in explicitly with a
+WebUI-specific script hook:
+
+```yaml
+webui_prefill_messages_script:
+  - python3
+  - /path/to/notes_recall.py
+webui_prefill_messages_script_timeout: 5
+```
+
+or:
+
+```bash
+HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT="python3 /path/to/notes_recall.py" \
+HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT=5 \
+./ctl.sh restart
+```
+
+The script may print either an OpenAI-style JSON message list, a JSON object with
+a `messages` list, or plain text; plain text is wrapped as one `user` prefill
+message so dynamic recall text becomes ordinary context instead of an extra
+system instruction. If the hook must provide system-level guidance, emit JSON
+messages with an explicit `role: "system"` entry instead. Script output is capped
+at 256 KiB before parsing. Parsed prefill context is then bounded by
+`webui_prefill_context_max_chars` or `HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS`
+(default: 12,000 characters; set to `0` to disable). When a dynamic script
+exceeds the budget and a compact static prefill file is configured, WebUI falls
+back to that file. If no compact fallback is available, WebUI injects a short
+retrieval instruction instead of sending the oversized note/body payload with
+every new browser turn. The browser only receives a compact status event
+(`source`, `label`, message count, compaction metadata, and redacted errors),
+never the prefill message bodies.
+
+## Gateway-backed browser chat
+
+By default, browser chat runs through WebUI's in-process legacy runtime. Advanced
+self-hosted deployments can opt into routing new browser turns through a running
+Hermes Gateway API server while preserving the existing WebUI `/api/chat/start`
+and `/api/chat/stream` browser contract:
+
+```bash
+HERMES_WEBUI_CHAT_BACKEND=gateway \
+HERMES_WEBUI_GATEWAY_BASE_URL=http://127.0.0.1:8642 \
+HERMES_WEBUI_GATEWAY_API_KEY=... \
+./ctl.sh restart
+```
+
+`HERMES_WEBUI_CHAT_BACKEND` is intentionally strict: only `gateway`,
+`api_server`, or `api-server` enable the bridge. Generic truthy values such as
+`1` or `true` are ignored so existing deployments do not change execution
+ownership accidentally. If `HERMES_WEBUI_GATEWAY_API_KEY` is omitted, WebUI falls
+back to `API_SERVER_KEY` when present. When Gateway returns HTTP 401, WebUI
+reports a `gateway_auth_error` that points at this WebUI↔Gateway key mismatch
+rather than showing the Gateway's generic provider-style "Invalid API key" body.
+`/api/health/agent` also includes a redacted `gateway_chat` block so operators can
+see whether gateway mode, base URL, and API-key presence are configured without
+exposing the key value. That `gateway_chat` field is an operator diagnostic
+payload only; it is not currently rendered as a user-facing health banner in the
+browser UI.
+
+The bridge is best used by operators who already run Hermes Gateway/API Server
+locally and want browser-originated chat to use the same runtime/tool path as
+messaging surfaces. Attachments, cancellation, approvals, and clarify prompts
+still follow WebUI's current compatibility path and may not match every messaging
+surface until the runtime-adapter migration is complete.

docs/architecture/agent-api-contract.md

@@ -0,0 +1,111 @@
+# WebUI to hermes-agent source dependency contract
+
+This document records the current WebUI dependency on the hermes-agent source
+tree for issue #2491. It is an audit and replacement contract only; it does not
+change runtime behavior or Docker wiring.
+
+Run the deterministic audit with:
+
+```powershell
+python scripts/audit_agent_source_dependencies.py
+python scripts/audit_agent_source_dependencies.py --format markdown
+```
+
+The JSON output is repo-relative and grouped by stable dependency class IDs so
+follow-up PRs can remove one class at a time without relying on exact line
+fixtures.
+
+## Current boundary
+
+The multi-container setup still shares the agent source tree with the WebUI:
+
+- `docker-compose.two-container.yml` mounts `hermes-agent-src` at `/opt/hermes`
+  in the agent service and read-only at
+  `/home/hermeswebui/.hermes/hermes-agent` in the WebUI service.
+- `docker-compose.three-container.yml` uses the same source volume pattern.
+- `docker_init.bash` documents that the WebUI-side mount is read-only and uses
+  a staged copy when installing from the source checkout.
+- `docs/docker.md` explicitly documents that this is not a filesystem trust
+  boundary: the WebUI cannot write the mount, but it still installs and imports
+  code from it.
+
+The durable target is that multi-container WebUI should not need a direct
+`hermes-agent-src` mount. The WebUI should communicate with hermes-agent through
+HTTP endpoints and a small versioned client/shared-schema package where pure
+helpers are genuinely shared code.
+
+## Dependency classes
+
+| Audit class | Current surface | Replacement classification |
+| --- | --- | --- |
+| `docker_agent_source_volume` | Compose files and Docker docs expose `hermes-agent-src` and `/opt/hermes` to make the agent checkout visible to WebUI. | Remove the WebUI source mount only after startup install and runtime imports have migrated. This needs Docker/compose follow-up work, not a runtime behavior change in this audit PR. |
+| `startup_dependency_install` | `api/startup.py` discovers `HERMES_WEBUI_AGENT_DIR` or `$HERMES_HOME/hermes-agent`; `server.py` calls `auto_install_agent_deps()` after import verification fails; `docker_init.bash` installs from the staged agent source. | Replace source-tree pip installs with a packaged hermes-agent WebUI client plus an agent health/version capability contract. Keep `HERMES_WEBUI_AGENT_DIR` during migration as an override/debug path, but it should stop being required in normal multi-container startup. |
+| `runtime_auxiliary_model_metadata` | `api/streaming.py`, `api/routes.py`, `api/config.py`, and `api/providers.py` import `agent.auxiliary_client`, `agent.model_metadata`, `agent.models_dev`, `hermes_cli.models`, and `agent.account_usage`. | Existing provider/model WebUI endpoints can keep serving UI data where they already wrap agent helpers. Missing surfaces need hermes-agent endpoints or a client package for auxiliary task config, text auxiliary calls, context length, token estimate, provider catalog, and account usage. |
+| `runtime_session_state` | `api/streaming.py`, `api/goals.py`, and `api/state_sync.py` import `hermes_state.SessionDB` directly. | Move cross-container state reads and writes behind hermes-agent session/state endpoints. WebUI-only presentation state can remain local, but agent session storage should not be opened from the WebUI container. |
+| `runtime_gateway_provider` | `api/streaming.py` and `api/routes.py` import `hermes_cli.runtime_provider`; adapter helpers such as `agent.anthropic_adapter` are also imported for gateway normalization. | Provider resolution, runtime routing, and gateway invocation should be hermes-agent API calls. WebUI can keep request validation and display formatting, but it should not import runtime provider internals from the agent checkout. |
+| `webui_local_or_client_package` | WebUI imports `hermes_cli.auth`, `hermes_cli.config`, `hermes_cli.plugins`, `hermes_cli.profiles`, `hermes_cli.goals`, `agent.skill_utils`, `agent.credential_pool`, and `hermes_constants`. | Pure schemas, constants, and parsing helpers can move into a small versioned client/shared package. Privileged data such as credential pools, auth status, profile mutation, plugin discovery, and goal persistence need hermes-agent endpoints. UI-only formatting can remain in WebUI. |
+
+## Replacement contract
+
+### Existing endpoint candidates
+
+The WebUI already exposes provider, model, profile, route, and streaming
+handlers that callers use today. Those handlers can remain as WebUI HTTP routes
+when they only format UI responses, but their implementations should stop
+loading agent modules directly. Good candidates for reusing the current WebUI
+route shape while changing its backend dependency are:
+
+- Provider/model catalog routes currently backed by `hermes_cli.models`.
+- Auxiliary title/compression paths currently backed by `agent.auxiliary_client`.
+- Context-window and token-estimate paths currently backed by
+  `agent.model_metadata`.
+- Runtime-provider choices currently backed by `hermes_cli.runtime_provider`.
+
+### New hermes-agent endpoints needed
+
+These surfaces require an agent-owned endpoint because they read agent state,
+perform provider/runtime decisions, or expose privileged data:
+
+- SessionDB/session state read and write operations now using
+  `hermes_state.SessionDB`.
+- Runtime provider resolution and gateway normalization now using
+  `hermes_cli.runtime_provider` and `agent.anthropic_adapter`.
+- Auxiliary task execution and configuration now using `agent.auxiliary_client`.
+- Credential/auth/account usage access now using `agent.credential_pool`,
+  `hermes_cli.auth`, and `agent.account_usage`.
+- Profile, plugin, goal, and skill operations that mutate or discover
+  agent-owned resources.
+
+### Client/shared package candidates
+
+These items can be kept out of the live agent API if they are pure, versioned,
+and safe to import without the agent source tree:
+
+- Shared constants currently imported from `hermes_constants`.
+- Provider/model schema names and non-privileged catalog shape definitions.
+- Pure skill/profile parsing helpers that do not touch agent-owned state.
+- Typed response/request models for the new hermes-agent endpoints.
+
+### WebUI-local items
+
+The WebUI can keep code that is only presentation, validation, or routing glue:
+
+- User-facing diagnostics that display whether `HERMES_WEBUI_AGENT_DIR` is set.
+- Route-level request validation and response formatting.
+- WebUI-only caches and client-facing state that do not open agent SessionDB.
+- Docker documentation describing the transition while both paths are supported.
+
+## Audit expectations
+
+`tests/test_agent_source_dependency_audit.py` pins the contract shape:
+
+- Docker/compose source sharing is reported.
+- Startup dependency installation and `HERMES_WEBUI_AGENT_DIR` are reported.
+- Runtime auxiliary/model metadata imports are reported.
+- Runtime SessionDB/state imports are reported.
+- Runtime provider/gateway imports are reported.
+- The catch-all class for local/client-package candidates remains populated.
+
+The tests intentionally check stable class IDs and representative anchors, not
+exact full fixtures. Follow-up migration PRs should update this document and the
+audit expectations when a dependency class is intentionally reduced or removed.

docs/architecture/stable-assistant-turn-anchor-phase0.md

@@ -0,0 +1,191 @@
+# Stable Assistant Turn Anchors Phase 0 Inventory
+
+This inventory implements the first non-visual slice of
+[`stable-assistant-turn-anchors.md`](../rfcs/stable-assistant-turn-anchors.md).
+It documents the current per-turn state layers and the event-shape contract that
+future anchor phases must consume. It does not claim that anchors are wired into
+streaming or rendering yet.
+
+## RFC Phase Progress
+
+- The #3962 Phase 0 scaffold shipped through #3977 / v0.51.359: inventory the
+  current state layers, encode the owner seed, and pin the source classification
+  contract.
+- PR #3980 / v0.51.366 delivered the first RFC Phase 2 foundation: normalize
+  current live, replay, and settled source events into anchor-shaped events while
+  staying unwired from rendering.
+- This slice advances RFC Phase 1 and Phase 2 together: it adds a local registry
+  owner plus a shadow source-feed harness that can combine live, replay,
+  settled, and in-flight observations into one anchor snapshot.
+- It also covers the RFC Phase 2.5 contract-hardening boundary: the semantic
+  anchor seed excludes renderer presentation state, terminal states are exposed
+  as constants with alias normalization, and replay + settlement ordering is
+  pinned by tests before visible wiring begins.
+- Slice 4 starts RFC Phase 3 by routing settled assistant final prose through the
+  anchor owner before `renderMessages()` renders the final assistant body.
+- Slice 5 starts RFC Phase 5 by projecting anchor-owned activity events into a
+  renderer-neutral activity scene that Compact Worklog and Transparent Stream
+  can later consume from the same ordered rows.
+- The next independently reviewable boundary is wiring one current renderer to
+  the activity scene. `S.messages`, `INFLIGHT`, stream-local state, and DOM nodes
+  remain projection/cache layers outside the settled final-prose path and the
+  inert activity-scene projection.
+
+## State Layers
+
+| Layer | Current surface | Phase 0 anchor policy |
+| --- | --- | --- |
+| RuntimeAdapter / run-journal Event Envelope | `event_id`, `run_id`, `seq`, `Last-Event-ID` / `after_seq` | Preferred identity and replay dedupe source. |
+| Run journal replay events | `read_run_events()`, `_replay_run_journal`, `runtime_journal_snapshot` | Durable replay hydration source before browser caches. |
+| Server settled transcript | `/api/session` messages and metadata | Settlement updates final answer and terminal state on an existing turn. |
+| `S.messages` | Browser transcript projection consumed by `renderMessages()` | Projection/cache, not a second semantic owner. |
+| `INFLIGHT` | Browser recovery cache and persisted localStorage state | Recovery fallback only; does not outrank journal or settled transcript. |
+| Stream closure state | `attachLiveStream()` local assistant text, reasoning text, parser target, tool state | Hot-path write buffer; future phases normalize this into anchor events. |
+| Live DOM | `#liveAssistantTurn`, Worklog rows, tool cards, Thinking cards | Renderer output only; DOM survival is not semantic truth. |
+
+The same inventory is encoded in `static/assistant_turn_anchors.js` as
+`HermesAssistantTurnAnchors.stateLayers` so tests can pin the current authority
+order.
+
+## Slice 2 Normalizer Helper
+
+`HermesAssistantTurnAnchors.normalizeAssistantTurnAnchorSourceEvent()` converts a
+single current source event into a normalized anchor event envelope without
+registering it, rendering it, or mutating browser state. It accepts live SSE-like
+events (`type`, `data`, `lastEventId`), replay/journal-like events (`event`,
+`payload`, `event_id`, `seq`), and settled/session payload events such as
+`settled_message`.
+
+`HermesAssistantTurnAnchors.normalizeAssistantTurnAnchorSourceEvents()` applies
+the same helper to a list and dedupes repeated live + replay observations by the
+same event-envelope key. This is still inert: `send()`, `attachLiveStream()`,
+`renderMessages()`, settlement restore, `S.messages`, `INFLIGHT`, and the DOM do
+not consume the helper yet.
+
+## Slice 3 Registry / Owner Skeleton
+
+`HermesAssistantTurnAnchors.createAssistantTurnAnchorRegistry()` creates a local
+owner object for one assistant turn. The registry contains the anchor seed, a
+dedupe index, and application stats. It is not a global store and is not wired
+into current runtime, session, or renderer code.
+
+`HermesAssistantTurnAnchors.applyAssistantTurnAnchorSourceEvent()` and
+`applyAssistantTurnAnchorSourceEvents()` normalize incoming source events, apply
+the same event-envelope dedupe rule, and route events into one owner:
+
+- `activity_events` for visible assistant activity such as prose, reasoning,
+  tools, control boundaries, and terminal status
+- `artifacts` for workspace/file references
+- `side_effects` for persisted state side effects
+- `metadata_events` for settlement/session metadata such as `settled_message`
+- `transport_events` for transport-only signals such as `stream_end`
+
+The registry may fill missing `run_id` / `stream_id` identity from the first
+matching normalized event, update lifecycle on terminal status, and copy the
+settled assistant message into `content.final_answer` as a derived render
+snapshot while keeping `content.final_message_ref` as the settled transcript
+reference. It rejects mismatched session or turn identity and skips duplicate
+live + replay observations by the same dedupe key.
+
+This slice deliberately keeps the ownership boundary inert: `send()`,
+`attachLiveStream()`, replay hydration, `renderMessages()`, `S.messages`,
+`INFLIGHT`, and DOM continuity still do not consume the registry. Later slices
+can replace local renderer-owned state with this owner instead of adding another
+parallel source of truth.
+
+`HermesAssistantTurnAnchors.createAssistantTurnAnchorShadowSnapshot()` is the
+shadow wiring harness for this slice. It accepts grouped `live_events`,
+`replay_events` / `run_journal_events`, `settled_events`, and `inflight_events`,
+feeds them through one local registry, and returns the resulting snapshot plus
+per-source apply results. This gives later slices an invariant target without
+making the current UI consume the owner yet.
+
+Renderer-only UI state such as Compact Worklog expansion, Transparent Stream
+expansion, copy-button visibility, and scroll-follow preference is intentionally
+not stored in the anchor seed. Those choices belong in renderer state or a
+separate per-session UI preference store so replay and settlement do not carry
+historic display preferences as semantic facts.
+
+`HermesAssistantTurnAnchors.terminalStates` exposes the RFC terminal-state enum:
+`completed`, `cancelled`, `interrupted`, `no_response`,
+`tool_limit_reached`, `compression_exhausted`, `connection_lost`, `degraded`,
+and `error`. `normalizeAssistantTurnAnchorTerminalState()` maps current source
+aliases such as `done`, `cancel`, `apperror`, `interrupted-by-user`,
+`max_iterations`, and `lost_worker_bookkeeping` into that enum.
+
+During the later `INFLIGHT` migration, the registry is the semantic owner for
+event identity, lifecycle, final answer reference, and activity events.
+`INFLIGHT.lastRunJournalSeq`, `activityBurstAnchors`, `currentLiveSegmentSeq`,
+`streamId`, and cached live text/tool state remain recovery or renderer caches
+until the matching field is explicitly moved. The fallback order is journal
+replay first, settled transcript second, `INFLIGHT` only for gaps.
+
+## Slice 4 Settled Final Projection
+
+`HermesAssistantTurnAnchors.projectAssistantTurnAnchorSettledMessageFinalAnswer()`
+projects one settled assistant transcript message through a local anchor
+registry. The settled transcript message reference remains the semantic
+authority (`content.final_message_ref`); `content.final_answer` is a derived
+render snapshot for the existing markdown pipeline.
+
+`renderMessages()` uses that projection only for settled assistant messages
+(`!isUser && !m._live`) and only after preserving the current content-array
+flattening behavior. It then continues through the existing inline-thinking and
+markdown rendering pipeline. If the anchor helper is unavailable or cannot
+produce a final answer, `renderMessages()` falls back to the existing message
+content path.
+
+This is intentionally narrower than render-scene ownership: live stream tokens,
+replay hydration, worklog rows, transparent-stream rows, tool cards, `INFLIGHT`,
+and DOM continuity are still not consumed by the anchor registry in this slice.
+
+## Slice 5 Activity Scene Projection
+
+`HermesAssistantTurnAnchors.projectAssistantTurnAnchorActivityScene()` projects
+an anchor or registry into `activity_scene_v1`: identity, lifecycle,
+`final_answer`, `final_message_ref`, terminal state, and an ordered
+`activity_rows` list.
+
+The rows are renderer-neutral. Compact Worklog receives display hints such as
+`main_prose`, `collapsed_thinking`, `tool_row`, and `terminal_status_row`.
+Transparent Stream receives the same row IDs, order, kinds, roles, text, tool
+IDs, and sanitized payloads with a chronological display hint. This pins the
+shared input shape before either renderer is rewired.
+
+This slice is still inert. No current UI module consumes the activity scene.
+`renderMessages()` and the live streaming hot path are unchanged by this slice.
+
+## Source Event Classification
+
+Phase 0 classifies current sources before changing render behavior:
+
+- activity: `token`, `interim_assistant`, `reasoning`, `tool`,
+  `tool_complete`, `tool_update`, `compressing`, `compressed`, `approval`,
+  `clarify`, `pending_steer_leftover`, `goal_continue`, `done`, `cancel`,
+  `error`, `apperror`
+- artifact: `artifact_reference`
+- side effect: `state_saved`
+- metadata: `usage`, `title`, `settled_message`, `runtime_journal_snapshot`,
+  `inflight_snapshot`
+- transport: `stream_end`
+
+Future phases may add sources, but every source must choose one of these classes
+or explicitly mark itself `excluded`.
+
+## Dedupe Invariant
+
+Anchor event dedupe is intentionally independent of visible text and timestamps.
+The Phase 0 helper uses this order:
+
+1. `event_id`
+2. `run_id + seq`
+3. `session_id + source_event_type + local_id + seq` as a browser fallback only
+   when a concrete local `seq` is present
+
+This mirrors the RuntimeAdapter Event Envelope and keeps the browser aligned
+with run-journal replay while the anchor registry is still unwired.
+
+The registry tests also pin the reconnect/settlement race shape: if one run is
+observed live, replayed, and settled in either order, duplicate event envelopes
+are skipped and the resulting anchor has the same activity list, terminal state,
+final message reference, final-answer snapshot, and usage metadata.

docs/architecture/unified-session-db.md

@@ -0,0 +1,98 @@
+# Unified SessionDB Adapter Spike
+
+WebUI currently persists conversations as JSON files under the WebUI session
+directory, while the CLI uses its own session database. The first safe slice of
+unification is a dormant adapter that presents a small SessionDB-shaped API over
+the existing WebUI JSON files without changing runtime call sites or file
+format.
+
+## Adapter Contract
+
+`api.webui_session_db.WebUIJsonSessionDB` exposes:
+
+- `list_sessions()` returns compact metadata rows for persisted WebUI JSON
+  sessions.
+- `read_session(sid)` returns a full session JSON payload or `None`.
+- `update_metadata(sid, fields)` writes only allowlisted metadata fields and
+  rejects unsafe keys such as `session_id`, `messages`, `tool_calls`, and
+  `message_count`.
+- `archive(sid, archived=True)` is a convenience metadata update for the
+  archived flag.
+- `write_session(session)` exists for tests and migration experiments that need
+  to materialize a complete JSON payload.
+
+Read operations must not call `Session.load()` or `all_sessions()`, because
+those paths can repair indexes or transcripts. Metadata writes must load the
+complete JSON payload, verify that a real `messages` list is present, update only
+safe fields, recompute `message_count`, and atomically replace the file. The
+adapter must never write a metadata-only stub that could drop transcript
+messages.
+
+## Why JSON-Backed And Dormant
+
+The selected first slice is infrastructure only. Keeping the adapter backed by
+the current JSON sidecars validates the API shape while preserving all current
+WebUI behavior, backups, and import paths. The feature flag defaults to:
+
+```yaml
+experimental:
+  unified_session_db: false
+```
+
+No UI exposes this flag, and no runtime session route switches to the adapter in
+this slice.
+
+## Runtime Wiring Preconditions
+
+Before any route uses this adapter for live metadata changes, a follow-up PR must
+prove parity with the existing `Session.save()` path:
+
+- take the same per-session mutation locks used by streaming and session routes,
+  so metadata writes cannot replace a newer transcript with a stale copy;
+- refresh or invalidate the in-memory `Session` cache and `_index.json`, so
+  sidebar rows and later `Session.save()` calls cannot overwrite adapter changes;
+- match `Session.compact()` sidebar semantics for pending first turns,
+  `has_pending_user_message`, `pending_started_at`, and real non-tool
+  `last_message_at` ordering.
+
+Until those invariants are implemented, `update_metadata()` and `archive()` are
+test/migration helpers, not runtime persistence replacements.
+
+## Planned Migration Sequence
+
+1. Land the dormant JSON adapter and contract tests.
+2. Add parity tests that compare adapter reads with existing WebUI sidebar and
+   session payloads.
+3. Introduce an opt-in dual-read or shadow-read mode for development builds.
+4. Add a migration path that can write unified SessionDB records without
+   deleting or rewriting JSON sidecars.
+5. Switch selected call sites behind the flag only after parity and rollback
+   behavior are proven.
+6. Make the unified store authoritative in a later release after import,
+   archive, pin, profile, project, and recovery semantics match WebUI JSON.
+
+## Authoritative Fields And Open Questions
+
+The JSON sidecar remains authoritative for `messages`, `tool_calls`, metadata
+display fields, profile/project ownership, archive and pin state, token/cost
+totals, pending stream recovery fields, worktree metadata, and composer draft
+state during this spike.
+
+Open questions for later slices:
+
+- Whether `updated_at` should reflect metadata-only changes such as archive and
+  pin operations or only transcript changes.
+- How to resolve conflicts when CLI and WebUI update titles, archive state, or
+  project/profile ownership concurrently.
+- Whether imported CLI sessions remain read-only projections or become editable
+  unified records.
+- How unified records should preserve WebUI recovery safeguards such as backup
+  creation before transcript shrinkage.
+- Which store owns sidebar ordering once JSON and SessionDB records coexist.
+
+## Out Of Scope
+
+This spike does not switch runtime WebUI call sites, migrate existing session
+files, expose a UI setting, alter CLI storage, change session import behavior, or
+remove any JSON sidecars. It is a contract and safety test bed for future
+migration work.

docs/docker.md

@@ -0,0 +1,524 @@
+# Hermes WebUI — Docker setup guide
+
+This is the comprehensive Docker reference. For a 5-minute quickstart, see the [README Docker section](../README.md#docker).
+
+## TL;DR — pick one
+
+| Setup | When to use | File |
+|---|---|---|
+| **Single-container** (recommended) | You just want chat working. WebUI runs the agent in-process. | `docker-compose.yml` |
+| **Two-container** | You want isolation between gateway (CLI/Telegram/cron) and chat UI. | `docker-compose.two-container.yml` |
+| **Three-container** | Two-container PLUS the dashboard for monitoring. | `docker-compose.three-container.yml` |
+| **All-in-one image** (community fork — third-party, not maintained by us) | Podman 3.4 / multi-arch / supervisord-style preference. | [sunnysktsang/hermes-suite](https://github.com/sunnysktsang/hermes-suite) — see [#1399](https://github.com/nesquena/hermes-webui/issues/1399) for the original discussion |
+
+> **Note (v0.14+):** If you use `docker-compose.three-container.yml`, both
+> `hermes-agent` and `hermes-dashboard` initialise from the same image and write
+> to the same `hermes-home` volume simultaneously. This can cause overlapping lock
+> files and stale `gateway_state.json` entries. The unified pattern described in
+> [Three-service unified setup (v0.14+)](#three-service-unified-setup-v014) below
+> avoids this by running a single `hermes-agent` process that serves both the
+> gateway and the dashboard.
+
+If something stops working, **start with the single-container setup** — it's the simplest path and fixes most permission/UID/path-mismatch issues by construction.
+
+## Production image security model
+
+The production Docker image is hardened for the normal single-tenant container threat model:
+Hermes WebUI assumes one operator controls the container, mounted Hermes home, and workspace.
+The image does **not** install `sudo`, does not add runtime users to a sudo group, and does not
+grant `NOPASSWD` escalation. If an agent/tool process gains a shell as `hermeswebui`, it should
+not be able to become root with a passwordless sudo command.
+
+The entrypoint still starts as `root` for a narrow init phase because Docker bind mounts often need
+UID/GID alignment and ownership preparation before the app can read `~/.hermes`, `/workspace`,
+`/app`, and `/uv_cache`. After that setup, `docker_init.bash` re-execs itself as the unprivileged
+`hermeswebui` user and starts the server there. Init scratch files under `/tmp/hermeswebui_init`
+are owner-only (`0700` directory, `0600` files), not world-writable.
+
+For multi-tenant or hostile-container environments, rebuild with your own runtime user, mount policy,
+and supervisor assumptions. Development images that need package-manager convenience should add
+those tools in a dev-only Dockerfile instead of reintroducing passwordless sudo to production.
+
+## 5-minute quickstart (single container)
+
+```bash
+git clone https://github.com/nesquena/hermes-webui
+cd hermes-webui
+cp .env.docker.example .env
+# Edit .env if needed (most users can skip this on Linux)
+docker compose up -d
+open http://localhost:8787
+```
+
+That's it 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. See [Scheduled jobs and the gateway daemon](#scheduled-jobs-and-the-gateway-daemon) below for the full background and verification steps.
+
+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.
+
+> **Linux note**: run Compose as the user who owns the Hermes home. The command
+> `sudo docker compose up -d` can make Compose expand `${HOME}` as `/root`, so
+> the default `${HOME}/.hermes` bind mount becomes `/root/.hermes` instead of
+> your user's real Hermes directory. Prefer adding your user to the `docker group`
+> and running `docker compose up -d`; if you must preserve the caller environment
+> for a one-off root run, use `sudo -E docker compose up -d` and verify the
+> rendered mount with `docker compose config` first.
+
+## Optional GPU runtime image
+
+The default Hermes WebUI Docker image stays CPU-only. GPU user-space packages
+are installed only when you build a custom image with the opt-in build arg:
+
+```bash
+docker build --build-arg INSTALL_GPU_LIBS=1 -t hermes-webui:gpu .
+```
+
+That build path installs VA-API basics (`libva2`, `vainfo`), AMD Mesa VA-API
+drivers (`mesa-va-drivers`), and the Intel non-free media driver when that
+package is available from the configured Debian repositories. NVIDIA host
+runtime tooling is not installed into the app image; use the NVIDIA Container
+Toolkit on the host and pass GPUs through at runtime.
+
+GPU passthrough still depends on host drivers, Docker runtime support, and
+device mappings. The commands below are configuration guidance for a suitable
+Linux Docker host; they are not a claim that native GPU passthrough was verified
+in this workspace.
+
+### Intel and AMD VA-API
+
+Expose the host render devices and add the runtime user to the common video and
+render groups:
+
+```bash
+docker run --rm \
+  --device /dev/dri:/dev/dri \
+  --group-add video \
+  --group-add render \
+  hermes-webui:gpu vainfo
+```
+
+For Compose, add the same mapping to a custom service definition:
+
+```yaml
+services:
+  hermes-webui:
+    image: hermes-webui:gpu
+    devices:
+      - /dev/dri:/dev/dri
+    group_add:
+      - video
+      - render
+```
+
+`vainfo` should list the VA-API driver and supported profiles when the host
+driver stack and container permissions are correct. The container entrypoint
+preserves Docker-provided supplemental groups before it drops privileges to the
+`hermeswebui` runtime user, so the WebUI process keeps access to `/dev/dri`.
+
+### NVIDIA
+
+Install and configure the NVIDIA Container Toolkit on the host first, then use
+Docker's GPU runtime flag:
+
+```bash
+docker run --rm --gpus all hermes-webui:gpu nvidia-smi
+```
+
+For Compose, use a custom service with GPU access enabled:
+
+```yaml
+services:
+  hermes-webui:
+    image: hermes-webui:gpu
+    gpus: all
+```
+
+If `nvidia-smi` is unavailable or reports no devices, fix the host NVIDIA driver
+and container toolkit setup before debugging Hermes WebUI. The container image
+only supplies the WebUI plus optional user-space media libraries; it cannot
+provide host kernel drivers or the NVIDIA runtime.
+
+## Scheduled jobs and the gateway daemon
+
+**Symptom**: Cron jobs created in the Tasks panel never fire. System Settings or Tasks shows:
+
+- Orange "Gateway not configured", or
+- Red "Gateway metadata stale" when runtime metadata is stale, or
+- Red "Gateway endpoint not reachable" when WebUI has a gateway URL configured but cannot reach its health endpoint.
+
+**Cause**: Scheduled cron ticks are not driven by the WebUI itself. The gateway daemon ticks the scheduler every 60 seconds; without one running, scheduled jobs sit idle. "Run now" / "Trigger" buttons still work because the WebUI handles those in-process.
+
+In older gateway builds, or when the daemon runs in a separate container, `gateway_state.json` can become stale and WebUI may lose confidence even if the daemon is up. This is especially visible if only base URLs are configured (e.g. `HERMES_WEBUI_GATEWAY_BASE_URL`) and local daemon state files are not being refreshed.
+
+**Fix**: Run a gateway container alongside the WebUI. The two-container compose file is the recommended path:
+
+```bash
+cp .env.docker.example .env
+docker compose -f docker-compose.two-container.yml up -d
+```
+
+The three-container layout adds the dashboard but is otherwise the same shape. If you must stay single-container, you can run `hermes gateway` inside the container as a long-lived background process, but the compose split is sturdier.
+
+**Verify**: Once the gateway is up, the System Settings pill should turn green and the Tasks banner disappear. From the host:
+
+```bash
+export GATEWAY_BASE_URL="${HERMES_API_URL:-${HERMES_WEBUI_GATEWAY_BASE_URL:-http://hermes:8642}}"
+docker compose -f docker-compose.two-container.yml exec hermes-agent hermes gateway status
+curl -sS "${GATEWAY_BASE_URL%/}/health/detailed" | jq '.gateway_state, .state'
+```
+
+If the service name differs in your compose file, `docker compose -f docker-compose.two-container.yml ps` lists the running services.
+For container-to-container diagnostics, set one of `HERMES_API_URL` or `HERMES_WEBUI_GATEWAY_BASE_URL` in the WebUI environment when using gateway chat mode (`HERMES_WEBUI_CHAT_BACKEND=gateway`), then restart WebUI.
+
+Refs #2785.
+
+## Three-service unified setup (v0.14+)
+
+Since v0.14, `hermes-agent` can serve the gateway API and the built-in dashboard
+from the same process by setting `HERMES_DASHBOARD_HOST` and
+`HERMES_DASHBOARD_PORT`. Running agent and dashboard in one container means a
+single writer to `hermes-home`, eliminating the concurrent-init write conflicts
+that occur when `hermes-agent` and `hermes-dashboard` both start from the same
+image against the same volume.
+
+The three-service pattern uses two containers:
+
+| Service | Image | Ports |
+|---|---|---|
+| `hermes-agent` | `nousresearch/hermes-agent:latest` | 8642 (gateway), 9119 (dashboard) |
+| `hermes-webui` | `ghcr.io/nesquena/hermes-webui:latest` | 8787 (chat UI) |
+
+Example compose snippet (save as `docker-compose.three-service.yml` or inline into your own file):
+
+```yaml
+services:
+  hermes-agent:
+    image: nousresearch/hermes-agent:latest
+    container_name: hermes-agent
+    command: gateway run
+    ports:
+      - "127.0.0.1:8642:8642"
+      - "127.0.0.1:9119:9119"
+    volumes:
+      - hermes-home:/home/hermes/.hermes
+      - hermes-agent-src:/opt/hermes
+    environment:
+      - HERMES_HOME=/home/hermes/.hermes
+      - HERMES_UID=${UID:-1000}
+      - HERMES_GID=${GID:-1000}
+      - HERMES_DASHBOARD_HOST=0.0.0.0
+      - HERMES_DASHBOARD_PORT=9119
+    restart: unless-stopped
+    networks:
+      - hermes-net
+
+  hermes-webui:
+    image: ghcr.io/nesquena/hermes-webui:latest
+    container_name: hermes-webui
+    depends_on:
+      - hermes-agent
+    ports:
+      - "127.0.0.1:8787:8787"
+    volumes:
+      - hermes-home:/home/hermeswebui/.hermes
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro
+      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
+    environment:
+      - HERMES_WEBUI_HOST=0.0.0.0
+      - HERMES_WEBUI_PORT=8787
+      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
+      - WANTED_UID=${UID:-1000}
+      - WANTED_GID=${GID:-1000}
+    restart: unless-stopped
+    networks:
+      - hermes-net
+
+networks:
+  hermes-net:
+    driver: bridge
+
+volumes:
+  hermes-home:
+  hermes-agent-src:
+```
+
+Open http://localhost:8787 for chat and http://localhost:9119 for the dashboard.
+Check `hermes gateway run --help` for the exact flag names for your agent release —
+the env-var equivalents shown above (`HERMES_DASHBOARD_HOST`, `HERMES_DASHBOARD_PORT`)
+are available in recent releases alongside the CLI flags.
+
+If you need the separate dashboard container (e.g. resource limits per service),
+`docker-compose.three-container.yml` still works. Add a `depends_on` from
+`hermes-dashboard` to `hermes-agent` with a `condition: service_healthy` healthcheck
+so the dashboard waits for the gateway to finish initialising agent-home before it
+starts its own init pass.
+
+## What goes wrong (and how to fix it)
+
+### Compatibility policy and version pinning
+
+WebUI shows the version it is currently running, but that display does not in itself guarantee tested compatibility with your agent release.
+
+Until the compatibility boundary work in [#1925](https://github.com/nesquena/hermes-webui/issues/1925) and [#2491](https://github.com/nesquena/hermes-webui/issues/2491) land, the WebUI and Hermes Agent deployment should be treated as a release pair: the WebUI release is tested against its matching agent release and should be upgraded/pinned together.
+
+If you use `latest`, use it consistently on both sides and avoid mixing a fixed tag with `latest`:
+- fixed WebUI tag + `hermes-agent:latest`
+- `hermes-webui:latest` + fixed `hermes-agent` tag
+
+In multi-container setups, if you must run a pinned pair, prefer the matching tag in `docker-compose.two-container.yml`/`docker-compose.three-container.yml` and perform the agent-volume refresh workflow in [Upgrading the agent container](#upgrading-the-agent-container) whenever you upgrade the agent image.
+
+If you see behavior issues after a mixed-version upgrade, capture both WebUI and hermes-agent versions and the compose layout in the issue.
+
+### 1. "Permission denied" at startup
+
+**Symptom**: Container starts but immediately crashes, logs show:
+```
+PermissionError: [Errno 13] Permission denied: '/home/hermeswebui/.hermes/...'
+```
+
+**Cause**: The container's user (UID 1000 by default) can't read your bind-mounted directory because your host files are owned by a different UID.
+
+**Fix**: Set `UID` and `GID` in `.env` to match your host:
+```bash
+echo "UID=$(id -u)" >> .env
+echo "GID=$(id -g)" >> .env
+docker compose down && docker compose up -d
+```
+
+On macOS, host UIDs start at 501. On Linux, the first interactive user is usually UID 1000.
+
+> **macOS Docker Desktop**: if UID mapping still misbehaves after the env fix, try toggling **Settings → General → File sharing implementation** between VirtioFS and gRPC-FUSE. Different implementations preserve UIDs across the host/container boundary differently.
+
+### 2. ".env file mode 0640 → permission denied" (#1389)
+
+**Symptom**: You set `HERMES_HOME_MODE=0640` (or some other group-readable mode) on your host `.env` file, container starts, then errors out:
+```
+[security] fixed permissions on .env (0o640 -> 0600)
+failed to load .env: open .env: permission denied
+```
+
+**Cause**: WebUI's `fix_credential_permissions()` startup hook enforces 0600 by default. This is the right thing for a clean install but conflicts with operator-set modes.
+
+**Fix**: Set one of these env vars in your `.env`:
+- `HERMES_SKIP_CHMOD=1` — bypass the fixer entirely
+- `HERMES_HOME_MODE=0640` — allow group bits, only strip world-readable
+
+Both are documented in `api/startup.py::fix_credential_permissions()`.
+
+> ⚠️ **Multi-container warning**: `HERMES_HOME_MODE` has DIFFERENT semantics in the agent image vs. the WebUI:
+> - **WebUI**: credential FILE mode threshold (`0640` allows group bits on `.env`)
+> - **Agent**: `HERMES_HOME` *directory* mode (default `0700`)
+>
+> `0640` on a directory has no owner-execute bit, so the agent can't traverse its own home → bricked. For multi-container setups, use `HERMES_HOME_MODE=0750` (group-traversable) or `0701` (x-only). The compose files have per-service comments that match each side's semantics.
+
+### 3. "Workspace appears empty even though my files are there"
+
+**Symptom**: WebUI loads but `/workspace` shows no files.
+
+**Cause**: Same as #1 — UID mismatch on the bind mount.
+
+**Fix**: Same as #1 — match host UID/GID via `.env`.
+
+### 4. "Two-container setup: WebUI can't find agent source" (#858)
+
+**Symptom**: WebUI logs at startup:
+```
+!! WARNING: hermes-agent source not found.
+!!   Looked in: /home/hermeswebui/.hermes/hermes-agent
+!!              /opt/hermes
+```
+
+**Cause**: The agent's source (`/opt/hermes` inside the agent container) needs to be exposed to the WebUI container via a shared volume. The two-container compose file does this via `hermes-agent-src` named volume, but if you're using bind mounts incorrectly the path won't resolve.
+
+**Fix**: Use the named volumes that ship with `docker-compose.two-container.yml` — don't replace them with bind mounts unless you know what you're doing. The agent container writes its source to `/opt/hermes`, and the WebUI mounts that volume at `/home/hermeswebui/.hermes/hermes-agent`.
+
+If you must use a bind mount: pick a host path, then mount it to `/opt/hermes` in the agent container AND `/home/hermeswebui/.hermes/hermes-agent` in the WebUI container.
+
+### 5. "Tools (git, node, etc.) missing in two-container setup" (#681)
+
+**Symptom**: You ask the agent to run `git status` in chat and it errors with `command not found`.
+
+**Cause**: This is **architectural, not a bug**. In the two-container setup, agent processes started by the WebUI run **inside the WebUI container**, not the agent container. The WebUI image doesn't include git/node by design (it's a UI image, not a tool host).
+
+**Workarounds**:
+- **Single-container setup** (`docker-compose.yml`) — everything in one container, no boundary
+- **Custom WebUI image** — extend the `Dockerfile` to install the tools you need
+- **Combined image** ([sunnysktsang/hermes-suite](https://github.com/sunnysktsang/hermes-suite)) — community fork that ships agent+webui+dashboard in one container
+
+### 6. "config.yaml not loaded"
+
+**Symptom**: You have a `config.yaml` in your host `~/.hermes/`, but the WebUI shows "no model configured" or doesn't pick up your custom providers.
+
+**Cause**: Either the file isn't readable (UID/GID issue, see #1) or it's not in the expected path inside the container.
+
+**Fix**:
+- Verify: `docker exec hermes-webui ls -la /home/hermeswebui/.hermes/config.yaml`
+- If it doesn't exist: your host bind mount is pointing at the wrong directory.
+- If it exists but is unreadable: see #1 for the UID/GID fix.
+
+### 7. "On Podman: can't share .hermes between containers"
+
+**Symptom**: Two-container setup works on Docker but fails on Podman with permission errors no matter what UID/GID you set.
+
+**Cause**: Podman 3.4 (Ubuntu 22.04 default) has limited support for `userns_mode: keep-id` across multiple containers — files written by one container appear with a different UID in the other.
+
+**Fix**: Either upgrade to Podman 4+ (which fixes this), or use the [single-container setup](#5-minute-quickstart-single-container), or use the [community all-in-one image](https://github.com/sunnysktsang/hermes-suite).
+
+### 8. "API base URL set to localhost fails from Docker" (#3012)
+
+**Symptom**: A provider, local model server, webhook, or custom API works on the host at `http://localhost:<port>`, but fails when the same URL is configured in Hermes WebUI running in Docker.
+
+**Cause**: Inside a container, `localhost` means *that container*, not your laptop/host. The WebUI process cannot reach host services through `127.0.0.1` unless the service is running inside the same container.
+
+**Fix**: Point Docker-hosted WebUI at the host gateway name instead:
+
+- Docker Desktop on macOS/Windows: `http://host.docker.internal:<port>`
+- Podman: `http://host.containers.internal:<port>`
+- Linux Docker Engine: either publish the host service on the Docker bridge address, or add a host-gateway alias to your compose service:
+
+```yaml
+services:
+  hermes-webui:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+Then configure the URL as `http://host.docker.internal:<port>`. Also ensure the host service binds to an address reachable from containers (not only a loopback interface the Docker bridge cannot reach) and that your host firewall allows the connection.
+
+## Multi-container architecture
+
+The two- and three-container setups use **named Docker volumes** (not bind mounts) by default for a reason: named volumes solve the UID/GID problem by construction. Docker creates the volume's root directory with the correct ownership, all containers reading/writing to it see the same files, no host-side permission setup required.
+
+```
+                 ┌─────────────────────────────────┐
+                 │      hermes-home (volume)       │
+                 │  (config, sessions, state, ...)  │
+                 └─────────────────────────────────┘
+                          ↑              ↑
+                          │ rw           │ rw
+                          │              │
+      ┌──────────────┐    │              │    ┌──────────────┐
+      │ hermes-agent │────┘              └────│ hermes-webui │
+      │  (port 8642) │                        │  (port 8787) │
+      └──────────────┘                        └──────────────┘
+              │                                       ↑
+              │ rw                                    │ ro
+              ↓                                       │
+      ┌─────────────────────────┐                     │
+      │ hermes-agent-src (vol)  │─────────────────────┘
+      │ (agent's Python source) │
+      └─────────────────────────┘
+```
+
+The WebUI container doesn't ship with the agent's Python deps — at startup it runs `uv pip install /home/hermeswebui/.hermes/hermes-agent` to install them from the shared volume. 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)
+
+If you really need to bind-mount an existing host `~/.hermes` (e.g. you're keeping config in dotfiles, sharing with a non-Docker `hermes` install, etc.):
+
+```yaml
+volumes:
+  hermes-home:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: /home/youruser/.hermes
+  hermes-agent-src:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: /opt/hermes-agent-source
+```
+
+**Critical requirements**:
+
+1. The host directory MUST be readable by your container UID. Run `id -u` on the host and ensure `~/.hermes` is owned by that UID (or readable via group bits).
+2. ALL containers sharing the volume must run as the SAME UID/GID. Set `UID=$(id -u)` and `GID=$(id -g)` in `.env`.
+3. If you run Compose with sudo, do not rely on `${HOME}` defaults: `sudo` often changes `$HOME` to `/root`, so `${HERMES_HOME:-${HOME}/.hermes}` becomes `/root/.hermes`. Prefer running Docker as your user; otherwise pass absolute paths with `sudo -E`, for example `HERMES_HOME=/home/youruser/.hermes HERMES_WORKSPACE=/home/youruser/workspace sudo -E docker compose up -d`, and confirm the rendered bind mount with `docker compose config`.
+4. If your host `.env` is mode 0640, set `HERMES_SKIP_CHMOD=1` or `HERMES_HOME_MODE=0640` so the startup hook doesn't try to enforce 0600.
+
+## Reference
+
+- [`docker-compose.yml`](../docker-compose.yml) — single container (recommended)
+- [`docker-compose.two-container.yml`](../docker-compose.two-container.yml) — agent + webui
+- [`docker-compose.three-container.yml`](../docker-compose.three-container.yml) — agent + dashboard + webui
+- [`.env.docker.example`](../.env.docker.example) — environment variable template
+- [`Dockerfile`](../Dockerfile) — single-container build
+- [`docker_init.bash`](../docker_init.bash) — container entrypoint script
+
+## Related issues
+
+- #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)
+- #3012 — host `localhost` API URLs fail from Docker containers (use `host.docker.internal` / `host.containers.internal`)
+- #3006 — `sudo docker compose` can mount `/root/.hermes` instead of the user's Hermes home
+- #3243 — optional GPU runtime image/docs for containerized acceleration workloads
+- #858 — two-container `/opt/hermes` path confusion
+- #681 — tools running in WebUI container, not agent container (architectural)
+- #668 — auto-detect UID/GID from mounted volume
+- #569 — UID/GID detection priority order
+
+If you hit a new failure mode not covered here, please [open an issue](https://github.com/nesquena/hermes-webui/issues/new) with:
+
+1. Which compose file you used
+2. The error from `docker logs hermes-webui`
+3. `docker exec hermes-webui id` output
+4. `docker exec hermes-webui ls -la /home/hermeswebui/.hermes` output

docs/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,211 @@
+# 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, AIML API | 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.
+
+AIML API uses the existing custom OpenAI-compatible setup path, not a
+first-class built-in Hermes provider id. Configure it under the
+custom-provider flow with Base URL `https://api.aimlapi.com/v1`, then use
+either the normal custom-provider API key field or a config entry that points
+at `AIMLAPI_API_KEY` if you want the custom provider to read its key from the
+environment. Create or manage keys at `https://aimlapi.com/app/keys`. Model
+discovery comes from the live `/v1/models` response for that endpoint, not from
+a static WebUI-maintained model list.
+
+Advanced provider flows such as Nous Portal and GitHub Copilot are still
+terminal-first. OpenAI Codex and Anthropic Claude Code OAuth can be started in
+the onboarding flow when your Hermes config selects the corresponding provider.
+If the wizard points you back to `hermes model`, use that CLI flow first, then
+refresh WebUI.
+
+## Base URL rules for local model servers
+
+For self-hosted providers, the Base URL should point to the OpenAI-compatible
+API root. Common examples:
+
+| Server | Typical Base URL |
+|---|---|
+| LM Studio on the same non-Docker host | `http://127.0.0.1:1234/v1` |
+| Ollama on the same non-Docker host | `http://127.0.0.1:11434/v1` |
+| LM Studio from Docker Desktop | `http://host.docker.internal:1234/v1` |
+| Ollama from Docker Desktop | `http://host.docker.internal:11434/v1` |
+| Local server from Linux Docker Engine | `http://api.local:<port>/v1` with `api.local:host-gateway` in Compose `extra_hosts` |
+| Local server on another LAN machine | `http://<lan-ip>:<port>/v1` |
+
+Inside Docker, `localhost` means the WebUI container itself, not your Mac,
+Windows host, Linux host, or another machine on your LAN. If LM Studio or Ollama
+is running outside the container, use `host.docker.internal` on Docker Desktop,
+use the server's LAN IP address, or add a Linux Docker host alias:
+
+```yaml
+services:
+  hermes-webui:
+    extra_hosts:
+      - "api.local:host-gateway"
+```
+
+Then use `http://api.local:<port>/v1` as the Base URL. The alias avoids writing
+`localhost` in WebUI config where it would resolve to the container loopback
+instead of the host service.
+
+The wizard probes `<base-url>/models` before saving. A successful probe fills
+the model dropdown. A failed probe blocks the setup step and shows an inline
+error such as DNS failure, connection refused, timeout, HTTP error, or
+unexpected response shape.
+
+## Workspace step
+
+The workspace is the filesystem location Hermes should use for new sessions.
+It can be a source checkout, a project directory, or a general workspace folder.
+
+In Docker, the default browsable path is `/workspace`, which maps to the host
+directory mounted by the compose file. If the workspace appears empty, check the
+Docker UID/GID and mount guidance in [Docker setup guide](docker.md).
+
+## Password step
+
+Password protection is optional for localhost-only installs. Enable it if you
+expose WebUI outside `127.0.0.1`, behind a reverse proxy, or on a LAN.
+
+The password is stored through the normal WebUI settings path and hashed
+server-side. You can change it later from Settings.
+
+## What gets written
+
+The wizard uses the same files and APIs as the normal app:
+
+- Active Hermes `config.yaml`: provider, default model, and Base URL when
+  relevant.
+- Active Hermes `.env`: provider API keys when you entered one.
+- WebUI `settings.json`: onboarding completion, workspace, password state, and
+  other WebUI preferences.
+
+State normally lives outside the repository. By default:
+
+- Hermes Agent state: Windows `%LOCALAPPDATA%\hermes`; POSIX `~/.hermes`
+- WebUI state: `$HERMES_HOME/webui` (Windows default `%LOCALAPPDATA%\hermes\webui`, POSIX default `~/.hermes/webui`)
+
+Override these with `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` when you need an
+isolated test install.
+
+## When to file an issue
+
+File an issue when the diagnostics point to WebUI rather than local
+configuration. Include:
+
+1. Install path: local bootstrap, Docker single-container, Docker
+   two-container, Docker three-container, WSL2, or community native Windows.
+2. Output from `/health`, or the startup banner if the server never starts.
+3. The provider selected in onboarding and the Base URL shape, with secrets
+   redacted.
+4. For Docker provider problems, the result of probing from inside the
+   container, for example:
+
+```bash
+docker exec hermes-webui sh -c 'curl -sS -w "\nHTTP %{http_code}\n" http://host.docker.internal:1234/v1/models | head -50'
+```
+
+5. Any inline wizard error text and relevant logs.
+
+Never paste API keys, OAuth tokens, or full `.env` contents into an issue.