fix: record fallback routing metadata

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

.env.example

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

.github/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

@@ -19,7 +19,7 @@ archive/
 !.env.docker.example
 .claude/
 CLAUDE.md
-AGENTS.md
+AGENTS.local.md
 .cursorrules
 .windsurfrules
 .aider*
@@ -36,17 +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/docker.md
-!docs/supervisor.md
-!docs/troubleshooting.md
+!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.245` (April 30, 2026).
-> Automated coverage: 3309 tests via `pytest tests/ --collect-only -q`. CI runs on Python 3.11, 3.12, and 3.13 against every PR.
+> Current shipped build: `v0.51.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 as of v0.50.245: workspace panel closed/open state is preloaded via a `documentElement` dataset marker before `style.css` paints to avoid first-load flash; transcript disclosure cards animate via transitionable `max-height`/`opacity` states; thinking cards share rounded bordered card chrome with tool cards (gold palette); incremental streaming-markdown via vendored `streaming-markdown@0.2.15` (no CDN); HTTP byte-range streaming for large media; SSE-driven session sidebar with `pending_user_message` + `active_stream_id` lifecycle tracking; configurable model badges (`primary` / `fallback N`) computed in `_build_configured_model_badges()` and provider-aware in the dropdown picker.
+> Notable architecture state: 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`.)
 
 ---
 
@@ -43,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
@@ -99,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
 
 ---
 
@@ -118,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.
@@ -156,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.
 
@@ -319,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
@@ -362,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
@@ -679,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)
 
@@ -778,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.
 
@@ -794,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)
 
@@ -888,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
@@ -898,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']))"
@@ -919,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
 
@@ -1194,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)
 
@@ -1320,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
 
@@ -1455,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)
 
@@ -1466,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
 

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

@@ -150,6 +150,14 @@ A tool card is a debug event row, not a chat message. Show icon, name, short tar
 
 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.

Dockerfile

@@ -21,14 +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
@@ -41,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
 
@@ -75,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).
@@ -95,5 +104,8 @@ EXPOSE 8787
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
   CMD curl -f http://localhost:8787/health || exit 1
 
+# docker_init.bash performs root-only bind-mount setup, then drops to hermeswebui
+# before starting the WebUI server. The production image does not ship sudo.
+USER root
 CMD ["/hermeswebui_init.bash"]
 

README.md

@@ -45,6 +45,20 @@ This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** wh
 
 ---
 
+## Contents
+
+- [Why Hermes](#why-hermes) — what it is and how it compares
+- [Quick start](#quick-start) — clone + `bootstrap.py` / `start.sh` / `ctl.sh`
+- [Features](#features) — chat, sessions, workspace, voice, profiles, security, themes, panels, mobile
+- [Configuration & access](#configuration--access) — auto-discovery, overrides, remote/Tailscale/phone, manual launch
+- [Docker](#docker) — single- and multi-container deploys
+- [Running tests](#running-tests)
+- [Architecture](#architecture) — backend/frontend layout, state dir
+- [Docs](#docs) — the full documentation index
+- [Contributors](#contributors)
+
+---
+
 ## Why Hermes
 
 Most AI tools reset every session. They don't know who you are, what you worked on, or what
@@ -68,7 +82,7 @@ What makes it different from other agentic tools:
   the results back into its own memory
 - **Self-hosted** — your conversations, your memory, your hardware
 
-**vs. the field** *(landscape is actively shifting — see [HERMES.md](HERMES.md) for the full breakdown)*:
+**vs. the field** *(landscape is actively shifting — see [docs/why-hermes.md](docs/why-hermes.md) for the full breakdown)*:
 
 | | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
 |---|---|---|---|---|---|
@@ -89,7 +103,7 @@ with memory, cron, and messaging. The key differences: Hermes writes and saves i
 automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
 Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
 has had security incidents involving malicious skills); and Hermes runs natively in the Python
-ecosystem. See [HERMES.md](HERMES.md) for the full side-by-side.
+ecosystem. See [docs/why-hermes.md](docs/why-hermes.md) for the full side-by-side.
 
 ---
 
@@ -121,6 +135,20 @@ For self-hosted VM or homelab installs, `ctl.sh` wraps the common daemon lifecyc
 
 `ctl.sh start` runs the bootstrap in foreground/no-browser mode behind the daemon wrapper, writes logs to `~/.hermes/webui.log`, and respects `.env` plus inline overrides such as `HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start`.
 
+> **Stopping the server.** Each launch method has its own stop path because only `ctl.sh start` writes a PID file (`~/.hermes/webui.pid`):
+>
+> | Launch method | How to stop |
+> |---|---|
+> | `python3 bootstrap.py` or `./start.sh` | **Ctrl-C** in the terminal (both run in the foreground) |
+> | `./ctl.sh start` | `./ctl.sh stop` (sends SIGTERM, waits, then SIGKILL) |
+> | Detached `bootstrap.py` (no `--foreground`) | Find the PID via `lsof -i :8787` (or `ss -tlnp`) and `kill` it |
+>
+> `./ctl.sh stop` cannot stop a server launched by `bootstrap.py` or `start.sh` directly — it only manages processes it started itself.
+
+### Advanced: dynamic recall prefill & Gateway-backed chat
+
+Two optional, self-hosted-deployment features — attaching dynamic **session-recall prefill** to browser turns (Joplin/Obsidian/Notion/llm-wiki routers), and routing browser chat through a running **Hermes Gateway** — are documented in [`docs/advanced-chat-setup.md`](docs/advanced-chat-setup.md). Most users need neither.
+
 The bootstrap will:
 
 1. Detect Hermes Agent and, if missing, attempt the official installer (`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`).
@@ -132,7 +160,218 @@ The bootstrap will:
 > Native Windows is not supported for this bootstrap yet. Use Linux, macOS, or WSL2.
 > For Windows / WSL auto-start at login, see [`docs/wsl-autostart.md`](docs/wsl-autostart.md).
 
+A community-maintained native Windows setup is documented at [@markwang2658/hermes-windows-native-guide](https://github.com/markwang2658/hermes-windows-native-guide) (companion setup repo: [@markwang2658/hermes-windows-native](https://github.com/markwang2658/hermes-windows-native)). Notes from the community report in [#1952](https://github.com/nesquena/hermes-webui/issues/1952):
+
+- **Memory:** community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
+- **What works:** chat, workspace browser, session management, all themes.
+- **Known limitations:** some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.
+- **Native Windows setup:** install Python 3.11+, then from the hermes-agent root in PowerShell: `python -m venv venv` → `pip install -r requirements.txt` → `pwsh .\start.ps1` (it auto-discovers `venv\Scripts\python.exe`).
+- **WSL2 relationship:** not a prerequisite — a WSL2-built venv (`venv/bin/python`, ELF) isn't invokable by native Windows Python, so use the native setup above. WSL2 stays useful as a parallel install if you want the full `bootstrap.py` + Linux runtime.
+
 If provider setup is still incomplete after install, the onboarding wizard will point you to finish it with `hermes model` instead of trying to replicate the full CLI setup in-browser.
+For a step-by-step walkthrough of the wizard, provider choices, local model server Base URLs, and safe re-runs, see [`docs/onboarding.md`](docs/onboarding.md).
+If an AI assistant is helping with install, reinstall, bootstrap, provider setup, or first-run support, have it read [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) before running commands or inspecting logs.
+
+---
+
+## Features
+
+### Chat and agent
+- Streaming responses via SSE (tokens appear as they are generated)
+- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI); dynamic model dropdown populated from configured keys
+- Send a message while one is processing -- it queues automatically
+- Edit any past user message inline and regenerate from that point
+- Retry the last assistant response with one click
+- Cancel a running task directly from the composer footer (Stop button next to Send)
+- Tool call cards inline -- each shows the tool name, args, and result snippet; expand/collapse all toggle for multi-tool turns
+- Subagent delegation cards -- child agent activity shown with distinct icon and indented border
+- Mermaid diagram rendering inline (flowcharts, sequence diagrams, gantt charts)
+- Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
+- Approval card for dangerous shell commands (allow once / session / always / deny)
+- SSE auto-reconnect on network blips (SSH tunnel resilience)
+- File attachments persist across page reloads and are stored outside the active workspace by default (`~/.hermes/webui/attachments/<session_id>/`, or `HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/` when configured)
+- Message timestamps (HH:MM next to each message, full date on hover)
+- Code block copy button with "Copied!" feedback
+- Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
+- Safe HTML rendering in AI responses (bold, italic, code converted to markdown)
+- rAF-throttled token streaming for smoother rendering during long responses
+- Context usage indicator in composer footer -- token count, cost, and fill bar (model-aware)
+
+### Sessions
+- Create, rename, duplicate, delete, search by title and message content
+- Session actions via `⋯` dropdown per session — pin, move to project, archive, duplicate, delete
+- Pin/star sessions to the top of the sidebar (gold indicator)
+- Archive sessions (hide without deleting, toggle to show)
+- Session projects -- named groups with colors for organizing sessions
+- Session tags -- add #tag to titles for colored chips and click-to-filter
+- Grouped by Today / Yesterday / Earlier in the sidebar (collapsible date groups)
+- Download as Markdown transcript, full JSON export, or import from JSON
+- Sessions persist across page reloads and SSH tunnel reconnects
+- Browser tab title reflects the active session name
+- CLI session bridge -- CLI sessions from hermes-agent's SQLite store appear in the sidebar with a gold "cli" badge; click to import with full history and reply normally
+- Token/cost display -- input tokens, output tokens, estimated cost shown per conversation (toggle in Settings or `/usage` command)
+
+### Workspace file browser
+- Directory tree with expand/collapse (single-click toggles, double-click navigates)
+- Breadcrumb navigation with clickable path segments
+- Preview text, code, Markdown (rendered), and images inline
+- Chat links using `workspace://path/to/file` open files in the right-side preview pane
+- Edit, create, delete, and rename files; create folders
+- Binary file download (auto-detected from server)
+- File preview auto-closes on directory navigation (with unsaved-edit guard)
+- Git detection -- branch name and dirty file count badge in workspace header
+- Right panel is drag-resizable
+- Syntax highlighted code preview (Prism.js)
+
+### Voice input
+- Microphone button in the composer (Web Speech API)
+- Tap to record, tap again or send to stop
+- Live interim transcription appears in the textarea
+- Auto-stops after ~2s of silence
+- Appends to existing textarea content (doesn't replace)
+- Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)
+
+### Profiles
+- Profile chip in the **composer footer** -- dropdown showing all profiles with gateway status and model info
+- Gateway status dots (green = running), model info, skill count per profile
+- Profiles management panel -- create, switch, and delete profiles from the sidebar
+- Clone config from active profile on create
+- Optional custom endpoint fields on create -- Base URL and API key written into the profile's `config.yaml` at creation time, so Ollama, LMStudio, and other local endpoints can be configured without editing files manually
+- Seamless switching -- no server restart; reloads config, skills, memory, cron, models
+- Per-session profile tracking (records which profile was active at creation)
+
+### Authentication and security
+- Optional password auth -- off by default, zero friction for localhost
+- Enable via `HERMES_WEBUI_PASSWORD` env var or Settings panel
+- Optional passkeys/WebAuthn -- register from Settings -> System after signing in with a password; the login page only shows passkey sign-in after at least one passkey exists
+- After registering at least one passkey, Settings -> System can remove the password and keep passkey-only sign-in enabled. Password auth remains the bootstrap/recovery path until you choose to go passwordless; passkeys are same-origin and stored locally in the WebUI state directory
+- Signed HMAC HTTP-only cookie with 24h TTL
+- Minimal dark-themed login page at `/login`
+- Security headers on all responses (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
+- 20MB POST body size limit
+- CDN resources pinned with SRI integrity hashes
+
+### Themes
+- Appearance is split into two axes: Theme (`system`, `dark`, `light`) and Skin
+  (`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, `charizard`,
+  `sienna`, `catppuccin`, `nous`, `geist-contrast` / Geist Contrast)
+- Switch via Settings -> Appearance (instant live preview) or `/theme <theme-or-skin>`
+- Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
+- Skins use `data-skin` plus CSS variables; dark mode resolves through the
+  `.dark` class, not a `data-theme` custom-theme axis — see [THEMES.md](THEMES.md)
+
+### Settings and configuration
+- **Hermes Control Center** (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
+- Send key: Enter (default) or Ctrl/Cmd+Enter
+- Show/hide CLI sessions toggle (enabled by default)
+- Token usage display toggle (off by default, also via `/usage` command)
+- Control Center always opens on the Conversation tab; resets on close
+- Unsaved changes guard -- discard/save prompt when closing with unpersisted changes
+- Cron completion alerts -- toast notifications and unread badge on Tasks tab
+- Background agent error alerts -- banner when a non-active session encounters an error
+
+### Slash commands
+- Type `/` in the composer for autocomplete dropdown
+- Built-in: `/help`, `/clear`, `/compress [focus topic]`, `/compact` (alias), `/model <name>`, `/workspace <name>`, `/new`, `/usage`, `/theme`
+- Arrow keys navigate, Tab/Enter select, Escape closes
+- Unrecognized commands pass through to the agent
+
+### Panels
+- **Chat** -- session list, search, pin, archive, projects, new conversation
+- **Tasks** -- view, create, edit, run, pause/resume, delete cron jobs; run history; completion alerts
+- **Skills** -- list all skills by category, search, preview, create/edit/delete; linked files viewer
+- **Memory** -- view and edit MEMORY.md and USER.md inline
+- **Profiles** -- create, switch, delete agent profiles; clone config
+- **Todos** -- live task list from the current session
+- **Spaces** -- add, rename, remove workspaces; quick-switch from topbar
+
+### Mobile responsive
+- Hamburger sidebar -- slide-in overlay on mobile (<640px)
+- Sidebar top tabs stay available on mobile; no fixed bottom nav stealing chat height
+- Files slide-over panel from right edge
+- Touch targets minimum 44px on all interactive elements
+- Full-height chat/composer on phones without bottom-nav spacing
+- Desktop layout completely unchanged
+
+---
+
+## Configuration & access
+
+`start.sh` auto-detects almost everything; the subsections below cover the knobs for when it can't, and how to reach the UI remotely.
+
+### What start.sh discovers automatically
+
+| Thing | How it finds it |
+|---|---|
+| Hermes agent dir | `HERMES_WEBUI_AGENT_DIR` env, then `$HERMES_HOME/hermes-agent` (Windows default `%LOCALAPPDATA%\hermes\hermes-agent`, POSIX default `~/.hermes/hermes-agent`), then sibling `../hermes-agent` |
+| Python executable | Agent venv first, then `.venv` in this repo, then system `python3` |
+| State directory | `HERMES_WEBUI_STATE_DIR` env, then `$HERMES_HOME/webui` (Windows default `%LOCALAPPDATA%\hermes\webui`, POSIX default `~/.hermes/webui`) |
+| Default workspace | `HERMES_WEBUI_DEFAULT_WORKSPACE` env, then `~/workspace`, then state dir |
+| Port | `HERMES_WEBUI_PORT` env or first argument, default `8787` |
+
+If discovery finds everything, nothing else is required.
+
+---
+
+### Overrides (only needed if auto-detection misses)
+
+```bash
+export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
+export HERMES_WEBUI_PYTHON=/path/to/python
+export HERMES_WEBUI_PORT=9000
+export HERMES_WEBUI_AUTO_INSTALL=1  # enable auto-install of agent deps (disabled by default)
+./start.sh
+```
+
+Or inline:
+
+```bash
+HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000
+```
+
+Full list of environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `HERMES_WEBUI_AGENT_DIR` | auto-discovered | Path to the hermes-agent checkout |
+| `HERMES_WEBUI_PYTHON` | auto-discovered | Python executable |
+| `HERMES_WEBUI_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for all IPv4, `::` for all IPv6, `::1` for IPv6 loopback) |
+| `HERMES_WEBUI_PORT` | `8787` | Port |
+| `HERMES_WEBUI_STATE_DIR` | `$HERMES_HOME/webui` (Windows default `%LOCALAPPDATA%\hermes\webui`, POSIX default `~/.hermes/webui`) | Where sessions and state are stored |
+| `HERMES_WEBUI_DEFAULT_WORKSPACE` | `~/workspace` | Default workspace |
+| `HERMES_WEBUI_DEFAULT_MODEL` | *(provider default)* | Optional model override; leave unset to use the active Hermes provider default |
+| `HERMES_WEBUI_PASSWORD` | *(unset)* | Set to enable password authentication |
+| `HERMES_WEBUI_CSP_CONNECT_EXTRA` | *(unset)* | Optional space-separated `http(s)://` or `ws(s)://` origins to append to the report-only CSP `connect-src` directive for reverse-proxy or tunnel deployments |
+| `HERMES_WEBUI_EXTENSION_DIR` | *(unset)* | Optional local directory served at `/extensions/`; must point to an existing directory before extension injection is enabled |
+| `HERMES_WEBUI_EXTENSION_SCRIPT_URLS` | *(unset)* | Optional comma-separated same-origin script URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
+| `HERMES_WEBUI_EXTENSION_STYLESHEET_URLS` | *(unset)* | Optional comma-separated same-origin stylesheet URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
+| `HERMES_HOME` | Windows: `%LOCALAPPDATA%\hermes`; POSIX: `~/.hermes` | Base directory for Hermes state (affects all paths) |
+| `HERMES_CONFIG_PATH` | `$HERMES_HOME/config.yaml` | Path to Hermes config file |
+| `HERMES_WEBUI_AGENT_CACHE_MAX` | `25` | Max live agent instances kept warm in the in-memory LRU. Each pins a full conversation transcript, so this is the dominant lever on resident memory — lower it on installs with many long sessions to cap RAM (at the cost of more cold reloads) |
+| `HERMES_WEBUI_SESSIONS_MAX` | `100` | Max compact `Session` objects held in the in-memory LRU. Lighter than the agent cache; lower it on installs with hundreds of sessions |
+
+---
+
+### Remote access (SSH tunnel, Tailscale, phone)
+
+The server binds to `127.0.0.1` by default. To reach it from another machine use an SSH tunnel (`ssh -N -L 8787:127.0.0.1:8787 user@host`, which `start.sh` prints for you over SSH), or join your server and phone to a [Tailscale](https://tailscale.com) network and browse to `http://<server-tailscale-ip>:8787` with `HERMES_WEBUI_HOST=0.0.0.0` + `HERMES_WEBUI_PASSWORD` set. Full walkthrough (incl. a community ARM64-Android field report): [`docs/remote-access.md`](docs/remote-access.md).
+
+### Manual launch (without start.sh)
+
+If you prefer to launch the server directly:
+
+```bash
+cd /path/to/hermes-agent          # or wherever sys.path can find Hermes modules
+HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py
+```
+
+Note: use the agent venv Python (or any Python environment that has the Hermes agent dependencies installed). System Python will be missing `openai`, `httpx`, and other required packages.
+
+Health check:
+
+```bash
+curl http://127.0.0.1:8787/health
+```
 
 ---
 
@@ -155,6 +394,8 @@ docker compose up -d
 # Open http://localhost:8787
 ```
 
+Run Compose as the user who owns your Hermes home. `sudo docker compose up -d` can make `${HOME}` expand to the root user's home, so Docker mounts the wrong `.hermes` directory instead of your real `~/.hermes` and the WebUI starts with `config.yaml (not found, using defaults)`. Prefer adding your user to the Docker group and running `docker compose up -d`; if you must use sudo, set absolute paths first, for example `HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d`, then verify with `docker compose config`.
+
 The container auto-detects your UID/GID from the mounted `~/.hermes` volume so files written by the agent stay readable by you on the host.
 
 To enable password protection (required if you expose the port outside `127.0.0.1`):
@@ -205,6 +446,8 @@ docker compose -f docker-compose.three-container.yml up -d
 Both compose files use **named Docker volumes** by default, which solves the UID/GID problem by construction. If you need bind mounts to share an existing host directory, see [`docs/docker.md`](docs/docker.md) for the full migration recipe.
 
 > **Known limitation (#681)**: in the two-container setup, tools triggered from the WebUI run in the **WebUI container**, not the agent container. If you need git/node/etc. on the WebUI's filesystem, either use the single-container setup, extend the WebUI Dockerfile, or use the community [all-in-one image](https://github.com/sunnysktsang/hermes-suite).
+>
+> **Source boundary note (#2453)**: the multi-container setup mounts `hermes-agent-src` read-only into the WebUI by default. This prevents WebUI-side source rewrites but is still an implementation-coupling bridge, not a stable Agent API boundary. See [`docs/rfcs/agent-source-boundary.md`](docs/rfcs/agent-source-boundary.md) for the current source/API decoupling inventory.
 
 ### Common failure modes
 
@@ -216,6 +459,8 @@ Both compose files use **named Docker volumes** by default, which solves the UID
 | `git: command not found` in chat | Two-container architectural limit (#681) | Use single-container or extend Dockerfile |
 | WebUI can't find agent source | `hermes-agent-src` volume misconfigured | Use the named volumes from compose files as-is |
 | Podman shared `.hermes` fails | Podman 3.4 `keep-id` limitation | Use Podman 4+ or single-container |
+| Host API at `localhost` fails from WebUI | Container `localhost` means the container, not your host (#3012) | Use `http://host.docker.internal:<port>` on Docker Desktop, or `http://host.containers.internal:<port>` on Podman |
+| WebUI can't see `~/.hermes` after `sudo docker compose` | `${HOME}` expanded to the root user's home (#3006) | Run Compose as your user, or pass absolute `HERMES_HOME`/`HERMES_WORKSPACE` with `sudo -E` |
 
 For the deep dive on each of these, see [`docs/docker.md`](docs/docker.md).
 
@@ -225,131 +470,6 @@ For the deep dive on each of these, see [`docs/docker.md`](docs/docker.md).
 
 ---
 
-## What start.sh discovers automatically
-
-| Thing | How it finds it |
-|---|---|
-| Hermes agent dir | `HERMES_WEBUI_AGENT_DIR` env, then `~/.hermes/hermes-agent`, then sibling `../hermes-agent` |
-| Python executable | Agent venv first, then `.venv` in this repo, then system `python3` |
-| State directory | `HERMES_WEBUI_STATE_DIR` env, then `~/.hermes/webui-mvp` |
-| Default workspace | `HERMES_WEBUI_DEFAULT_WORKSPACE` env, then `~/workspace`, then state dir |
-| Port | `HERMES_WEBUI_PORT` env or first argument, default `8787` |
-
-If discovery finds everything, nothing else is required.
-
----
-
-## Overrides (only needed if auto-detection misses)
-
-```bash
-export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
-export HERMES_WEBUI_PYTHON=/path/to/python
-export HERMES_WEBUI_PORT=9000
-export HERMES_WEBUI_AUTO_INSTALL=1  # enable auto-install of agent deps (disabled by default)
-./start.sh
-```
-
-Or inline:
-
-```bash
-HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000
-```
-
-Full list of environment variables:
-
-| Variable | Default | Description |
-|---|---|---|
-| `HERMES_WEBUI_AGENT_DIR` | auto-discovered | Path to the hermes-agent checkout |
-| `HERMES_WEBUI_PYTHON` | auto-discovered | Python executable |
-| `HERMES_WEBUI_HOST` | `127.0.0.1` | Bind address |
-| `HERMES_WEBUI_PORT` | `8787` | Port |
-| `HERMES_WEBUI_STATE_DIR` | `~/.hermes/webui-mvp` | Where sessions and state are stored |
-| `HERMES_WEBUI_DEFAULT_WORKSPACE` | `~/workspace` | Default workspace |
-| `HERMES_WEBUI_DEFAULT_MODEL` | `openai/gpt-5.4-mini` | Default model |
-| `HERMES_WEBUI_PASSWORD` | *(unset)* | Set to enable password authentication |
-| `HERMES_WEBUI_EXTENSION_DIR` | *(unset)* | Optional local directory served at `/extensions/`; must point to an existing directory before extension injection is enabled |
-| `HERMES_WEBUI_EXTENSION_SCRIPT_URLS` | *(unset)* | Optional comma-separated same-origin script URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
-| `HERMES_WEBUI_EXTENSION_STYLESHEET_URLS` | *(unset)* | Optional comma-separated same-origin stylesheet URLs to inject; see [WebUI Extensions](docs/EXTENSIONS.md) |
-| `HERMES_HOME` | `~/.hermes` | Base directory for Hermes state (affects all paths) |
-| `HERMES_CONFIG_PATH` | `~/.hermes/config.yaml` | Path to Hermes config file |
-
----
-
-## Accessing from a remote machine
-
-The server binds to `127.0.0.1` by default (loopback only). If you are running
-Hermes on a VPS or remote server, use an SSH tunnel from your local machine:
-
-```bash
-ssh -N -L <local-port>:127.0.0.1:<remote-port> <user>@<server-host>
-```
-
-Example:
-
-```bash
-ssh -N -L 8787:127.0.0.1:8787 user@your.server.com
-```
-
-Then open `http://localhost:8787` in your local browser.
-
-`start.sh` will print this command for you automatically when it detects you
-are running over SSH.
-
----
-
-## Accessing on your phone with Tailscale
-
-[Tailscale](https://tailscale.com) is a zero-config mesh VPN built on
-WireGuard. Install it on your server and your phone, and they join the same
-private network -- no port forwarding, no SSH tunnels, no public exposure.
-
-The Hermes Web UI is fully responsive with a mobile-optimized layout
-(hamburger sidebar, sidebar top tabs in the drawer, touch-friendly controls),
-so it works well as a daily-driver agent interface from your phone.
-
-**Setup:**
-
-1. Install [Tailscale](https://tailscale.com/download) on your server and
-   your iPhone/Android.
-2. Start the WebUI listening on all interfaces with password auth enabled:
-
-```bash
-HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secret ./start.sh
-```
-
-3. Open `http://<server-tailscale-ip>:8787` in your phone's browser
-   (find your server's Tailscale IP in the Tailscale app or with
-   `tailscale ip -4` on the server).
-
-That's it. Traffic is encrypted end-to-end by WireGuard, and password auth
-protects the UI at the application level. You can add it to your home screen
-for an app-like experience.
-
-> **Tip:** If using Docker, set `HERMES_WEBUI_HOST=0.0.0.0` in your
-> `docker-compose.yml` environment (already the default) and set
-> `HERMES_WEBUI_PASSWORD`.
-
----
-
-## Manual launch (without start.sh)
-
-If you prefer to launch the server directly:
-
-```bash
-cd /path/to/hermes-agent          # or wherever sys.path can find Hermes modules
-HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py
-```
-
-Note: use the agent venv Python (or any Python environment that has the Hermes agent dependencies installed). System Python will be missing `openai`, `httpx`, and other required packages.
-
-Health check:
-
-```bash
-curl http://127.0.0.1:8787/health
-```
-
----
-
 ## Running tests
 
 Tests discover the repo and the Hermes agent dynamically -- no hardcoded paths.
@@ -365,309 +485,246 @@ Or using the agent venv explicitly:
 /path/to/hermes-agent/venv/bin/python -m pytest tests/ -v
 ```
 
-Tests run against an isolated server on port 8788 with a separate state directory.
-Production data and real cron jobs are never touched. Current count: **3309 tests**
-across 100+ test files.
-
----
-
-## Features
-
-### Chat and agent
-- Streaming responses via SSE (tokens appear as they are generated)
-- Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Z.AI); dynamic model dropdown populated from configured keys
-- Send a message while one is processing -- it queues automatically
-- Edit any past user message inline and regenerate from that point
-- Retry the last assistant response with one click
-- Cancel a running task directly from the composer footer (Stop button next to Send)
-- Tool call cards inline -- each shows the tool name, args, and result snippet; expand/collapse all toggle for multi-tool turns
-- Subagent delegation cards -- child agent activity shown with distinct icon and indented border
-- Mermaid diagram rendering inline (flowcharts, sequence diagrams, gantt charts)
-- Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
-- Approval card for dangerous shell commands (allow once / session / always / deny)
-- SSE auto-reconnect on network blips (SSH tunnel resilience)
-- File attachments persist across page reloads
-- Message timestamps (HH:MM next to each message, full date on hover)
-- Code block copy button with "Copied!" feedback
-- Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
-- Safe HTML rendering in AI responses (bold, italic, code converted to markdown)
-- rAF-throttled token streaming for smoother rendering during long responses
-- Context usage indicator in composer footer -- token count, cost, and fill bar (model-aware)
-
-### Sessions
-- Create, rename, duplicate, delete, search by title and message content
-- Session actions via `⋯` dropdown per session — pin, move to project, archive, duplicate, delete
-- Pin/star sessions to the top of the sidebar (gold indicator)
-- Archive sessions (hide without deleting, toggle to show)
-- Session projects -- named groups with colors for organizing sessions
-- Session tags -- add #tag to titles for colored chips and click-to-filter
-- Grouped by Today / Yesterday / Earlier in the sidebar (collapsible date groups)
-- Download as Markdown transcript, full JSON export, or import from JSON
-- Sessions persist across page reloads and SSH tunnel reconnects
-- Browser tab title reflects the active session name
-- CLI session bridge -- CLI sessions from hermes-agent's SQLite store appear in the sidebar with a gold "cli" badge; click to import with full history and reply normally
-- Token/cost display -- input tokens, output tokens, estimated cost shown per conversation (toggle in Settings or `/usage` command)
-
-### Workspace file browser
-- Directory tree with expand/collapse (single-click toggles, double-click navigates)
-- Breadcrumb navigation with clickable path segments
-- Preview text, code, Markdown (rendered), and images inline
-- Edit, create, delete, and rename files; create folders
-- Binary file download (auto-detected from server)
-- File preview auto-closes on directory navigation (with unsaved-edit guard)
-- Git detection -- branch name and dirty file count badge in workspace header
-- Right panel is drag-resizable
-- Syntax highlighted code preview (Prism.js)
-
-### Voice input
-- Microphone button in the composer (Web Speech API)
-- Tap to record, tap again or send to stop
-- Live interim transcription appears in the textarea
-- Auto-stops after ~2s of silence
-- Appends to existing textarea content (doesn't replace)
-- Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)
-
-### Profiles
-- Profile chip in the **composer footer** -- dropdown showing all profiles with gateway status and model info
-- Gateway status dots (green = running), model info, skill count per profile
-- Profiles management panel -- create, switch, and delete profiles from the sidebar
-- Clone config from active profile on create
-- Optional custom endpoint fields on create -- Base URL and API key written into the profile's `config.yaml` at creation time, so Ollama, LMStudio, and other local endpoints can be configured without editing files manually
-- Seamless switching -- no server restart; reloads config, skills, memory, cron, models
-- Per-session profile tracking (records which profile was active at creation)
-
-### Authentication and security
-- Optional password auth -- off by default, zero friction for localhost
-- Enable via `HERMES_WEBUI_PASSWORD` env var or Settings panel
-- Signed HMAC HTTP-only cookie with 24h TTL
-- Minimal dark-themed login page at `/login`
-- Security headers on all responses (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
-- 20MB POST body size limit
-- CDN resources pinned with SRI integrity hashes
-
-### Themes
-- 7 built-in themes: Dark (default), Light, Slate, Solarized Dark, Monokai, Nord, OLED
-- Switch via Settings panel dropdown (instant live preview) or `/theme` command
-- Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
-- Custom themes: define a `:root[data-theme="name"]` CSS block and it works — see [THEMES.md](THEMES.md)
-
-### Settings and configuration
-- **Hermes Control Center** (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
-- Send key: Enter (default) or Ctrl/Cmd+Enter
-- Show/hide CLI sessions toggle (enabled by default)
-- Token usage display toggle (off by default, also via `/usage` command)
-- Control Center always opens on the Conversation tab; resets on close
-- Unsaved changes guard -- discard/save prompt when closing with unpersisted changes
-- Cron completion alerts -- toast notifications and unread badge on Tasks tab
-- Background agent error alerts -- banner when a non-active session encounters an error
-
-### Slash commands
-- Type `/` in the composer for autocomplete dropdown
-- Built-in: `/help`, `/clear`, `/compress [focus topic]`, `/compact` (alias), `/model <name>`, `/workspace <name>`, `/new`, `/usage`, `/theme`
-- Arrow keys navigate, Tab/Enter select, Escape closes
-- Unrecognized commands pass through to the agent
-
-### Panels
-- **Chat** -- session list, search, pin, archive, projects, new conversation
-- **Tasks** -- view, create, edit, run, pause/resume, delete cron jobs; run history; completion alerts
-- **Skills** -- list all skills by category, search, preview, create/edit/delete; linked files viewer
-- **Memory** -- view and edit MEMORY.md and USER.md inline
-- **Profiles** -- create, switch, delete agent profiles; clone config
-- **Todos** -- live task list from the current session
-- **Spaces** -- add, rename, remove workspaces; quick-switch from topbar
-
-### Mobile responsive
-- Hamburger sidebar -- slide-in overlay on mobile (<640px)
-- Sidebar top tabs stay available on mobile; no fixed bottom nav stealing chat height
-- Files slide-over panel from right edge
-- Touch targets minimum 44px on all interactive elements
-- Full-height chat/composer on phones without bottom-nav spacing
-- Desktop layout completely unchanged
+Tests run against an isolated server with a separate state directory.
+Production data and real cron jobs are never touched. Current snapshot:
+**~7,150 tests collected** across **~700 test files**, run in CI on Python 3.11,
+3.12, and 3.13 (3 parallel shards each).
 
 ---
 
 ## Architecture
 
+No build step, no framework, no bundler — a Python standard-library HTTP server
+and vanilla JS. The backend lives in `api/`, the frontend in `static/`.
+
+**Backend (`api/`)**
+
 ```
-server.py               HTTP routing shell + auth middleware (~154 lines)
+server.py         HTTP routing shell + auth middleware
 api/
-  auth.py               Optional password authentication, signed cookies (~201 lines)
-  config.py             Discovery, globals, model detection, reloadable config (~1110 lines)
-  helpers.py            HTTP helpers, security headers (~175 lines)
-  models.py             Session model + CRUD + CLI bridge (~377 lines)
-  onboarding.py         First-run onboarding wizard, OAuth provider support (~507 lines)
-  profiles.py           Profile state management, hermes_cli wrapper (~411 lines)
-  routes.py             All GET + POST route handlers (~2250 lines)
-  state_sync.py         /insights sync — message_count to state.db (~113 lines)
-  streaming.py          SSE engine, run_agent, cancel support (~660 lines)
-  updates.py            Self-update check and release notes (~257 lines)
-  upload.py             Multipart parser, file upload handler (~82 lines)
-  workspace.py          File ops, workspace helpers, git detection (~288 lines)
-static/
-  index.html            HTML template (~600 lines)
-  style.css             All CSS incl. mobile responsive, themes (~1050 lines)
-  ui.js                 DOM helpers, renderMd, tool cards, context indicator (~1740 lines)
-  workspace.js          File preview, file ops, git badge (~286 lines)
-  sessions.js           Session CRUD, collapsible groups, search, reload recovery (~800 lines)
-  messages.js           send(), SSE handlers, live streaming, session recovery (~655 lines)
-  panels.js             Cron, skills, memory, profiles, settings (~1438 lines)
-  commands.js           Slash command autocomplete (~267 lines)
-  boot.js               Mobile nav, voice input, boot IIFE (~524 lines)
-tests/
-  conftest.py           Isolated test server (port 8788)
-  61 test files          961 test functions
-Dockerfile              python:3.12-slim container image
-docker-compose.yml      Compose with named volume and optional auth
-.github/workflows/      CI: multi-arch Docker build + GitHub Release on tag
+  auth.py         Optional password authentication, signed cookies, passkeys
+  config.py       Discovery, globals, model detection, reloadable config
+  helpers.py      HTTP helpers, security headers
+  models.py       Session model + CRUD + CLI/state.db bridge
+  onboarding.py   First-run onboarding wizard, OAuth provider support
+  profiles.py     Profile state management, hermes_cli wrapper
+  routes.py       All GET + POST route handlers (if/elif dispatch, no decorators)
+  state_sync.py   /insights sync — message_count to state.db
+  streaming.py    SSE engine, run_agent, cancellation, compression
+  updates.py      Self-update check and release notes
+  upload.py       Multipart parser, file upload handler
+  workspace.py    File ops, workspace helpers, git detection
 ```
 
-State lives outside the repo at `~/.hermes/webui-mvp/` by default
+**Frontend (`static/`)**
+
+```
+index.html        HTML template
+style.css         All CSS incl. mobile responsive, themes + skins
+ui.js             DOM helpers, renderMd, tool cards, context indicator
+workspace.js      File preview, file ops, git badge, central api() fetch wrapper
+sessions.js       Session CRUD, collapsible groups, search, reload recovery
+messages.js       send(), SSE handlers, live streaming, session recovery
+panels.js         Cron, skills, memory, profiles, settings (Control Center)
+commands.js       Slash command autocomplete
+boot.js           Mobile nav, voice input, theme/skin boot, bfcache handler
+```
+
+**Tests + packaging**
+
+```
+tests/            Pytest suite (~7,150 tests; isolated server/state fixtures)
+pyproject.toml    Tooling config (ruff lint gate) — not a packaged distribution
+Dockerfile        python:3.12-slim container image
+docker-compose.yml  Compose with named volume and optional auth
+.github/workflows/  CI: ruff + sharded pytest, browser smoke, Docker smoke,
+                    multi-arch Docker build + GitHub Release on tag
+```
+
+State lives outside the repo at `~/.hermes/webui/` by default
 (sessions, workspaces, settings, projects, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`.
+Full design notes and the endpoint catalog are in [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+---
+
+## Compatibility
+
+The version shown in the WebUI runtime status is the **WebUI version only** (build/image/tag currently running). It is not a full compatibility map.
+
+The WebUI is still coupled to Hermes Agent internals for runtime execution, provider/model access, and state/schema usage until the stable agent boundary work in [#1925](https://github.com/nesquena/hermes-webui/issues/1925) and [#2491](https://github.com/nesquena/hermes-webui/issues/2491) land. In practice, the WebUI imports Agent modules directly (`api/config.py`, `api/providers.py`, `api/streaming.py`) and reads Agent state layout directly, so version skew can cause import or behavior drift.
+
+**Compatibility policy**
+- WebUI release branches are tested against the matching Hermes Agent release available at that WebUI release time.
+- **Upgrade both together**: upgrade or pin WebUI and hermes-agent together (same release train/version/date), especially before enabling production traffic.
+- Running pinned older/newer combinations is **untested and unsupported** until the stable API boundary work in [#1925](https://github.com/nesquena/hermes-webui/issues/1925) / [#2491](https://github.com/nesquena/hermes-webui/issues/2491) is in place.
+- Record the full `hermes-agent` + `hermes-webui` versions in issue reports when upgrade mismatches are suspected.
+
+**Docker users**: pin both image tags (or corresponding pinned source revisions) rather than using `latest` on one side and a fixed tag on the other. When upgrading the multi-container setup, follow the agent-image upgrade procedure in [`docs/docker.md`](docs/docker.md) (which requires dropping the `hermes-agent-src` volume before recreating). The current source-boundary status is tracked in [`docs/rfcs/agent-source-boundary.md`](docs/rfcs/agent-source-boundary.md).
 
 ---
 
 ## Docs
 
-- `HERMES.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
-- `ROADMAP.md` -- feature roadmap and sprint history
-- `ARCHITECTURE.md` -- system design, all API endpoints, implementation notes
-- `TESTING.md` -- manual browser test plan and automated coverage reference
-- `CHANGELOG.md` -- release notes per sprint
-- `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets
-- `THEMES.md` -- theme system documentation, custom theme guide
-- `docs/troubleshooting.md` -- diagnostic flows for common failures (e.g. "AIAgent not available")
+**Start here**
+- [`docs/why-hermes.md`](docs/why-hermes.md) — why Hermes, the mental model, and a detailed comparison to Claude Code / Codex / OpenCode / Cursor
+- [`docs/onboarding.md`](docs/onboarding.md) — first-run wizard, provider setup, local model server Base URLs, and safe re-runs
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — diagnostic flows for common failures (e.g. "AIAgent not available")
 
-## Contributors
+**Using & customizing**
+- [`THEMES.md`](THEMES.md) — theme + skin system, custom theme guide
+- [`docs/workspace-git.md`](docs/workspace-git.md) — the workspace Git controls
+- [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) — administrator-controlled WebUI extension injection
 
-Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly or incorporated via batch release — shapes the project, and we're grateful to everyone who has taken the time to contribute.
+**Deploying & operating**
+- [`docs/remote-access.md`](docs/remote-access.md) — SSH tunnel, Tailscale, and phone access (incl. a community ARM64-Android field report)
+- [`docs/advanced-chat-setup.md`](docs/advanced-chat-setup.md) — optional dynamic recall-prefill and Gateway-backed browser chat for self-hosted deployments
+- [`docs/docker.md`](docs/docker.md) — Docker compose setup, common failures, and bind-mount migration
+- [`docs/supervisor.md`](docs/supervisor.md) — launchd, systemd, supervisord, runit, and s6 process-supervisor setup
+- [`docs/wsl-autostart.md`](docs/wsl-autostart.md) — WSL2 auto-start at Windows login
+- [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) — safety rules and pass/fail checks for assistant-led install/reinstall support
 
-**66 contributors have shipped code that landed in a release tag** as of v0.50.245. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights:
+**Contributing & design**
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution style, PR expectations, and local verification
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — system design, all API endpoints, implementation notes
+- [`TESTING.md`](TESTING.md) — manual browser test plan and automated coverage reference
+- [`DESIGN.md`](DESIGN.md) — design tokens and the calm-console direction
+- [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md) — UI/UX principles sourced from the design docs and visual inventories
+- [`docs/CONTRACTS.md`](docs/CONTRACTS.md) — project contract/RFC/design index for contributors and agents
+- [`docs/rfcs/README.md`](docs/rfcs/README.md) — RFC index for larger architecture and durability proposals
 
-### Top contributors (by merged-PR count)
-
-| # | Contributor | PRs | First → latest release |
-|---|---|---:|---|
-| 1 | [@franksong2702](https://github.com/franksong2702) | 22 | `v0.50.49` → `v0.50.245` |
-| 2 | [@bergeouss](https://github.com/bergeouss) | 18 | `v0.50.49` → `v0.50.240` |
-| 3 | [@aronprins](https://github.com/aronprins) | 8 | `v0.47.0` → `v0.50.77` |
-| 4 | [@iRonin](https://github.com/iRonin) | 6 | `v0.41.0` |
-| 5 | [@24601](https://github.com/24601) | 6 | `v0.50.201` |
-| 6 | [@KingBoyAndGirl](https://github.com/KingBoyAndGirl) | 4 | `v0.50.232` → `v0.50.237` |
-| 7 | [@renheqiang](https://github.com/renheqiang) | 4 | `v0.50.93` |
-| 8 | [@ccqqlo](https://github.com/ccqqlo) | 3 | `v0.50.83` → `v0.50.207` |
-| 9 | [@deboste](https://github.com/deboste) | 3 | `v0.16.1` |
-| 10 | [@frap129](https://github.com/frap129) | 3 | `v0.50.157` → `v0.50.166` |
-
-See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full ranked list of all 66 contributors, including everyone with one or two merged PRs and the special-thanks roll for design and architectural contributions.
-
-### Notable contributions
-
-**[@aronprins](https://github.com/aronprins)** — v0.50.0 UI overhaul (PR #242)
-The biggest single contribution to the project: a complete UI redesign that moved model/profile/workspace controls into the composer footer, replaced the gear-icon settings panel with the Hermes Control Center (tabbed modal), removed the activity bar in favor of inline composer status, redesigned the session list with a `⋯` action dropdown, and added the workspace panel state machine. 26 commits, thoroughly designed and iterated through multiple review rounds.
-
-**[@iRonin](https://github.com/iRonin)** — Security hardening sprint (PRs #196–#204)
-Six consecutive security and reliability PRs: session memory leak fix (expired token pruning), Content-Security-Policy + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file browser API. This is the kind of focused, high-quality security work that makes a self-hosted tool trustworthy.
-
-**[@DavidSchuchert](https://github.com/DavidSchuchert)** — German translation (PR #190)
-Complete German locale (`de`) covering all UI strings, settings labels, commands, and system messages — and in doing so, stress-tested the i18n system and exposed several elements that weren't yet translatable, which got fixed as part of the same PR.
-
-**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming, session recovery, workspace fallback (PRs #366, #367)
-Three interlocking improvements: workspace fallback resolution so the server recovers gracefully when the configured workspace is deleted or unavailable; live reasoning cards that upgrade the generic thinking spinner to a real-time reasoning display as the model thinks; and durable session state recovery via `localStorage` so in-flight tool cards, partial assistant output, and the live SSE stream all survive a full page reload or session switch.
-
-### Feature contributions
-
-**[@gabogabucho](https://github.com/gabogabucho)** — Spanish locale + onboarding wizard (PRs #275, #285)
-Full Spanish (`es`) locale covering all 175 UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch — the feature most responsible for new users actually getting started.
-
-**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + gateway sync + Docker hardening (18 PRs, `v0.50.49` → `v0.50.240`)
-Real-time gateway session sync (Telegram/Discord/Slack into the WebUI sidebar via SSE), the provider management UI for adding/editing custom providers from Settings, the two-container Docker setup docs, OAuth provider status detection, profile isolation hardening (per-profile `.env` secrets), and the bulk of what users see when they touch Settings → Providers.
-
-**[@ccqqlo](https://github.com/ccqqlo)** — Terminal approval UX + custom model discovery + mobile close button (PRs #224, #225, #238, #333)
-A run of focused quality-of-life improvements: terminal tool approval prompts that stay visible long enough to actually be read, restored custom model API key discovery, and the redundant mobile close button fix that had been confusing users on narrow screens.
-
-**[@kevin-ho](https://github.com/kevin-ho)** — OLED theme (PR #168)
-Added the 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk. Small diff, big impact for anyone on an OLED display.
-
-**[@Bobby9228](https://github.com/Bobby9228)** — Mobile Profiles button + Android Chrome fixes (PRs #253, #263, #265)
-Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones, plus a set of Android Chrome-specific fixes for the profile dropdown.
-
-**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (22 PRs, `v0.50.49` → `v0.50.245`)
-The session title guard, breadcrumb workspace navigation, mobile workspace panel sliver fix (#1300), composer footer container queries, streaming session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, and a long tail of polish across the session sidebar, mobile responsive layout, and workspace state machine.
-
-**[@betamod](https://github.com/betamod)** — Security hardening (PR #171)
-A comprehensive security audit PR covering CSRF protection, SSRF guards, XSS escaping improvements, and the env race condition between concurrent agent sessions — foundational security work that shipped in v0.39.0.
-
-**[@TaraTheStar](https://github.com/TaraTheStar)** — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
-Made the assistant display name configurable throughout the UI, added thinking/reasoning block display in chat, and refactored the login page to use template variables instead of inline string replacement.
-
-**[@thadreber-web](https://github.com/thadreber-web)** — CLI session bridge (PR #56)
-The original CLI session bridge: reads CLI sessions from the agent's SQLite state store and surfaces them in the WebUI sidebar. This was the first bridge between the CLI and WebUI session worlds.
-
-**[@deboste](https://github.com/deboste)** — Reverse proxy auth + mobile responsive layout + model routing (PRs #3, #4, #5)
-Three of the very first community PRs: fixed EventSource/fetch to use the URL origin for reverse proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.
-
-### Bug fix and security contributions
-
-**[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — Profile .env secret isolation (PR #351)
-Fixed API key leakage between profiles on switch — switching from a profile with `OPENAI_API_KEY` to one without it left the key in the process environment for the duration of the session, effectively leaking credentials. A subtle and important security fix.
-
-**[@lawrencel1ng](https://github.com/lawrencel1ng)** — Bandit security fixes B310/B324/B110 + QuietHTTPServer (PR #354)
-Systematic bandit security scan fixes: URL scheme validation before `urlopen`, MD5 `usedforsecurity=False`, and 40+ bare `except: pass` blocks replaced with proper logging — plus `QuietHTTPServer` to stop client-disconnect log spam from SSE streams.
-
-**[@lx3133584](https://github.com/lx3133584)** — CSRF fix for reverse proxy on non-standard ports (PR #360)
-Fixed CSRF rejection for deployments behind Nginx Proxy Manager or similar on non-standard ports — a real-world blocker for anyone hosting on a port other than 80/443.
-
-**[@DelightRun](https://github.com/DelightRun)** — session_search fix for WebUI sessions (PR #356)
-The `session_search` tool silently returned "Session database not available" in every WebUI session. Tracked down the missing `SessionDB` injection in the streaming path and fixed it.
-
-**[@shaoxianbilly](https://github.com/shaoxianbilly)** — Unicode filename downloads (PR #378)
-Fixed `UnicodeEncodeError` crashes when downloading workspace files with Chinese, Japanese, or other non-ASCII names. Implemented proper `Content-Disposition` header with RFC 5987 `filename*=UTF-8''...` encoding.
-
-**[@huangzt](https://github.com/huangzt)** — Cancel interrupts agent (PR #244)
-Made the Cancel button actually interrupt the running agent and clean up UI state, rather than just hiding the button while the agent kept running.
-
-**[@tgaalman](https://github.com/tgaalman)** — Thinking card fix (PR #169)
-Fixed top-level reasoning fields being missed in the thinking card display — an edge case in how Claude's extended thinking blocks surface in the API response.
-
-**[@smurmann](https://github.com/smurmann)** — Custom provider routing fix (PR #189)
-Fixed model routing for slash-prefixed custom provider models, which were being misrouted in the model selector. A precise fix for a real edge case in multi-provider setups.
-
-**[@jeffscottward](https://github.com/jeffscottward)** — Claude Haiku model ID fix (PR #145)
-Caught and corrected the Claude Haiku model ID (`3-5` → `4-5`) immediately after the Anthropic release — the kind of quick community catch that keeps the model dropdown accurate.
-
-**[@kcclaw001](https://github.com/kcclaw001)** — Credential redaction in API responses (PR #243)
-Added credential redaction to all API response paths so API keys, tokens, and other secrets in session data or error messages are masked before reaching the browser.
-
-**[@mbac](https://github.com/mbac)** — Phantom "Custom" provider group fix (PR #191)
-Removed the phantom "Custom" optgroup that appeared in the model dropdown even when no custom provider was configured — a small but consistently confusing UI noise issue.
-
-**[@andrewy-wizard](https://github.com/andrewy-wizard)** — Chinese localization (PR #177)
-Added Simplified Chinese (`zh`) locale to the WebUI. One of the first non-English locales and the most-used non-English locale in the codebase.
-
-**[@mmartial](https://github.com/mmartial)** — Docker UID/GID matching (PR #237)
-Added Docker support for running as an arbitrary UID/GID matching the host user, eliminating permission issues with bind-mounted volumes — essential for Docker deployments where the host user isn't UID 1000.
-
-**[@vCillusion](https://github.com/vCillusion)** — pip package resolution fix (PR #76)
-Fixed agent dependency resolution to prefer packages from the venv's site-packages over the agent directory itself, preventing shadowing bugs when developing locally.
-
-**[@carlytwozero](https://github.com/carlytwozero)** — API key pass-through for non-Anthropic providers (PR #78)
-Fixed `api_key` not being passed to `AIAgent` for non-Anthropic `/anthropic` providers — a quiet regression that silently broke any non-default provider.
-
-**[@mangodxd](https://github.com/mangodxd)** — Type hints cleanup (PR #115)
-Added missing type hints across 10 files and corrected 9 inaccurate existing ones — the kind of maintenance work that makes the codebase easier to reason about.
-
-**[@Argonaut790](https://github.com/Argonaut790)** — HTML entity decode + Traditional Chinese locale (PR #239)
-Fixed double-escaping of HTML entities in `renderMd()` — LLM output containing `&lt;code&gt;` was being escaped a second time, rendering as literal text instead of the intended markdown. The same PR also completed the Simplified Chinese translation (40+ missing keys) and added a full Traditional Chinese (`zh-Hant`) locale.
-
-**[@indigokarasu](https://github.com/indigokarasu)** — Visual redesign proposal: icon rail + design token system + 7 themes (PR #213)
-A CSS-only redesign of the full UI — proper design tokens (`--bg-primary`, `--text-info`, spacing scale), an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but directly shaped the design language and theme architecture that shipped in v0.50.0.
-
-**[@zenc-cp](https://github.com/zenc-cp)** — Anti-hallucination guard for ReAct loop (PR #133)
-Added a streaming token buffer and post-run message scrub to `streaming.py` to detect and strip fake tool execution JSON that weaker models write inline instead of calling tools properly. A three-layer approach: ephemeral anti-hallucination prompt, live token filtering, and session history cleanup. The pattern influenced later streaming.py improvements.
+**Release history & plan**
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes per version
+- [`ROADMAP.md`](ROADMAP.md) — feature roadmap and sprint history
+- [`SPRINTS.md`](SPRINTS.md) — forward sprint plan with CLI + Claude parity targets
+- [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — the full community credit roll
 
 ---
 
-Want to contribute? See [ARCHITECTURE.md](ARCHITECTURE.md) for the codebase layout and [TESTING.md](TESTING.md) for how to run the test suite. The best contributions are focused, well-tested, and solve a real problem — exactly what every person on this list did.
+## Contributors
+
+Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute.
+
+Over **190 contributors** have shipped code that landed in a release tag. The full,
+continuously-updated credit roll — including everyone with one or two PRs and the
+special-thanks roll for design and architectural work — lives in
+[`CONTRIBUTORS.md`](CONTRIBUTORS.md). A snapshot of the most prolific contributors:
+
+### Top contributors (by PR count, including absorbed/batch-released work)
+
+| # | Contributor | PRs | First → latest release |
+|---|---|---:|---|
+| 1 | [@franksong2702](https://github.com/franksong2702) | 148 | `v0.49.3` → `v0.51.153` |
+| 2 | [@Michaelyklam](https://github.com/Michaelyklam) | 117 | `v0.50.240` → `v0.51.139` |
+| 3 | [@bergeouss](https://github.com/bergeouss) | 70 | `v0.48.0` → `v0.51.46` |
+| 4 | [@ai-ag2026](https://github.com/ai-ag2026) | 67 | `v0.50.279` → `v0.51.190` |
+| 5 | [@dso2ng](https://github.com/dso2ng) | 25 | `v0.50.227` → `v0.51.153` |
+| 6 | [@AJV20](https://github.com/AJV20) | 24 | `v0.51.93` → `v0.51.188` |
+| 7 | [@starship-s](https://github.com/starship-s) | 19 | `v0.50.123` → `v0.51.153` |
+| 8 | [@jasonjcwu](https://github.com/jasonjcwu) | 16 | `v0.50.227` → `v0.51.132` |
+| 9 | [@dobby-d-elf](https://github.com/dobby-d-elf) | 15 | `v0.51.38` → `v0.51.161` |
+| 10 | [@Jordan-SkyLF](https://github.com/Jordan-SkyLF) | 12 | `v0.50.18` → `v0.51.66` |
+
+See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full ranked list of all 194 contributors, including everyone with one or two PRs and the special-thanks roll for design and architectural contributions.
+
+### Notable contributions
+
+**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (148 PRs, `v0.49.3` → `v0.51.153`)
+Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual `/compress` async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine.
+
+**[@Michaelyklam](https://github.com/Michaelyklam)** — Most prolific contributor of recent releases (117 PRs, `v0.50.240` → `v0.51.139`)
+Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), `/goal` command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894).
+
+**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + Docker hardening (70 PRs, `v0.48.0` → `v0.51.46`)
+Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile `.env` secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644).
+
+**[@ai-ag2026](https://github.com/ai-ag2026)** — Session recovery + audit infrastructure (67 PRs, `v0.50.279` → `v0.51.190`)
+Autonomous-AI contributor (Hermes Agent-driven) focused on durability: `state.db`-backed sidecar reconciliation (#2041), orphan `.json.bak` recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in `/health` (#2039), crash-safe turn-journal RFC at `docs/rfcs/turn-journal.md` (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), `Content-Security-Policy-Report-Only` header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014).
+
+**[@dso2ng](https://github.com/dso2ng)** — Session lineage + diagnostics (25 PRs, `v0.50.227` → `v0.51.153`)
+`/api/session/lineage-report/<sid>` endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), `session_source="fork"` continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading.
+
+**[@jasonjcwu](https://github.com/jasonjcwu)** — Composer + transcript polish (16 PRs, `v0.50.227` → `v0.51.132`)
+Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes.
+
+**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming + UX polish (12 PRs, `v0.50.18` → `v0.51.66`)
+Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210).
+
+**[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242, plus 9 follow-ups)
+The biggest single contribution to the project: a complete UI redesign that moved model/profile/workspace controls into the composer footer, replaced the gear-icon settings panel with the Hermes Control Center (tabbed modal), removed the activity bar in favor of inline composer status, redesigned the session list with a `⋯` action dropdown, and added the workspace panel state machine. Plus chat transcript redesign (#587), sidebar declutter (#584), three-column layout refactor (#899), light/dark theme + accent skins (#627), and shared `confirm()`/`prompt()` dialog replacement (PR #251 extracted from #242).
+
+**[@iRonin](https://github.com/iRonin)** — Security hardening sprint (PRs #196–#204)
+Six consecutive, focused security PRs: session memory leak fix (expired token pruning), CSP + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file-browser API. The kind of focused, high-quality security work that makes a self-hosted tool trustworthy.
+
+**[@lucasrc](https://github.com/lucasrc)** — Auth-hardening trilogy (PRs #2191, #2192, #2193)
+Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces.
+
+**[@LumenYoung](https://github.com/LumenYoung)** — Streaming hot-path correctness (8 PRs, `v0.51.47` → `v0.51.99`)
+The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase.
+
+**[@dobby-d-elf](https://github.com/dobby-d-elf)** — Frontend reliability + motion polish (15 PRs, `v0.51.38` → `v0.51.161`)
+Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212).
+
+**[@JKJameson](https://github.com/JKJameson)** — Composer + session polish (10 PRs)
+Persistent composer draft per session (#1956), and a long tail of polish across the composer and session sidebar.
+
+**[@gabogabucho](https://github.com/gabogabucho)** — Spanish locale + onboarding wizard
+Full Spanish (`es`) locale covering all UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch.
+
+**[@deboste](https://github.com/deboste)** — Reverse-proxy auth + mobile responsive layout (PRs #3, #4, #5)
+Three of the very first community PRs: fixed EventSource/fetch to use URL origin for reverse-proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.
+
+**[@indigokarasu](https://github.com/indigokarasu)** — Visual redesign proposal (PR #213)
+A CSS-only redesign of the full UI — proper design tokens, an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but shaped the design language and theme architecture that shipped in v0.50.0.
+
+**[@zenc-cp](https://github.com/zenc-cp)** — Anti-hallucination guard for the ReAct loop (PR #133)
+A three-layer approach (ephemeral anti-hallucination prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.
+
+**[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — Profile + session security (PRs #351, #2048)
+Profile `.env` secret isolation fix (PR #351) preventing API key leakage between profiles, and session-import workspace validation (PR #2048) blocking a crafted-JSON file-read against `/`.
+
+**[@Sanjays2402](https://github.com/Sanjays2402)** — Endless-scroll + Start-jump race fix (PR #1949)
+A generation-token + mutex pair fixing the v0.51.30 race between endless-scroll prefetch and Start-jump's `_ensureAllMessagesLoaded`. The naive same-flag-check approach (proposed in #1942 and #1962) was a no-op for the post-await race — Sanjays2402's fix was the correct shape.
+
+**[@fxd-jason](https://github.com/fxd-jason)** — Real-time approval + clarify via SSE (PRs #1350, #1355)
+Replaced 1.5s HTTP polling with SSE long-connections for both approval and clarify, cutting latency from up to 1.5s to near-instant. Got all the correctness details right (atomic subscribe + snapshot, notify-inside-lock, head-of-queue payload, trailing event re-emission).
+
+**[@happy5318](https://github.com/happy5318)** — Custom provider model dedup (PR #1947)
+Fixed the same model from different named custom providers being silently deduplicated in the picker, with Opus catching a race in the original tests that needed augmentation.
+
+**[@NocGeek](https://github.com/NocGeek)** — Streaming scroll + manual cron output persistence (7 PRs)
+Streaming scroll viewport stability when tool/queue cards insert (#1360), manual cron-run output and metadata persistence (#1372, split from held #1352).
+
+**[@DavidSchuchert](https://github.com/DavidSchuchert)** — German translation (PR #190)
+Complete German locale (`de`) covering all UI strings, settings labels, commands, and system messages — and stress-tested the i18n system, exposing several elements that weren't yet translatable and getting them fixed as part of the same PR.
+
+**[@Bobby9228](https://github.com/Bobby9228)** — Mobile Profiles button (PR #265)
+Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones.
+
+**[@kevin-ho](https://github.com/kevin-ho)** — OLED theme (PR #168)
+The 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk.
+
+**[@andrewy-wizard](https://github.com/andrewy-wizard)** — Chinese localization (PR #177)
+Initial Simplified Chinese (`zh`) locale. One of the first non-English locales.
+
+**[@DelightRun](https://github.com/DelightRun)** — `session_search` fix for WebUI sessions (PR #356)
+Tracked down the missing `SessionDB` injection in the streaming path that was silently breaking the tool for every WebUI session.
+
+**[@lawrencel1ng](https://github.com/lawrencel1ng)** — Bandit security fixes (PR #354)
+Systematic bandit-scan fixes: URL scheme validation before `urlopen`, MD5 `usedforsecurity=False`, and 40+ bare `except: pass` blocks replaced with proper logging.
+
+**[@shaoxianbilly](https://github.com/shaoxianbilly)** — Unicode filename downloads (PR #378)
+Proper `Content-Disposition` with RFC 5987 `filename*=UTF-8''...` encoding so non-ASCII filenames download without crashing.
+
+**[@lx3133584](https://github.com/lx3133584)** — CSRF fix for reverse proxy (PR #360)
+A real-world blocker for anyone hosting behind Nginx Proxy Manager or similar on a port other than 80/443.
+
+**[@betamod](https://github.com/betamod)** — Security audit (PR #171)
+A comprehensive CSRF / SSRF / XSS / env-race-condition audit that shipped in v0.39.0.
+
+**[@TaraTheStar](https://github.com/TaraTheStar)** — Bot name + thinking blocks + login refactor (PRs #132, #176, #181)
+Configurable assistant display name, thinking/reasoning block display, and a login page refactor.
+
+---
 
 ## Repo
 

ROADMAP.md

@@ -2,7 +2,7 @@
 
 > Web companion to the Hermes Agent CLI. Same workflows, browser-native.
 >
-> Last updated: v0.51.13 (May 6, 2026) — 4642 tests collected — single-PR composer UX (#1758)
+> 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)
 
@@ -18,7 +18,7 @@
 | **Sessions + projects + search** | ✅ CRUD, content search, projects, tags, archive, fork, import |
 | **Mobile + Docker + auth** | ✅ Hamburger nav, slide-overs, password auth, GHCR images |
 | **Auxiliary surfaces** | ✅ Workspace tree + edit, cron CRUD, skills CRUD, memory write, MCP server UI |
-| **Visual polish** | ✅ 8 themes (incl. light/system/OLED/Sienna), Mermaid, KaTeX, syntax highlighting |
+| **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.
@@ -29,15 +29,17 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 
 | Layer | Files | Status |
 |---|---|---|
-| Python server | `server.py` (~165 lines) + `api/` modules (~20k lines) | Thin shell + auth middleware + business logic |
-| HTML template | `static/index.html` (~600 lines) | Served from disk |
-| CSS | `static/style.css` (~3k lines) | Themes, mobile responsive, KaTeX, table styles |
-| JavaScript | `static/{ui,sessions,messages,workspace,panels,boot,commands,icons,i18n,login,onboarding}.js` (~26k lines) | 11 modules served as static files |
+| 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/release.yml` | Auto-release + GHCR publish on tag push |
+| 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
@@ -168,7 +170,7 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
 
 ### Slash commands
 - [x] Command registry + autocomplete dropdown
-- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/btw`, `/reasoning`, `/skills`, `/toolsets`
+- [x] Built-ins: `/help`, `/clear`, `/model`, `/workspace`, `/new`, `/usage`, `/theme`, `/compact`, `/queue`, `/interrupt`, `/steer`, `/goal`, `/btw`, `/reasoning`, `/skills`, `/toolsets`
 - [x] Transparent pass-through for unrecognized commands
 
 ### Security

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: 3648 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 9 languages, and ~700 issue/PR-pinned regression tests.
+> Automated coverage: ~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:
@@ -533,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}
@@ -557,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)
@@ -577,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)
@@ -1835,8 +1925,8 @@ Bridged CLI sessions:
 
 ---
 
-*Last updated: v0.51.13, May 6, 2026*
-*Total automated tests collected: 4642*
+*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

@@ -1,28 +1,255 @@
-"""Hermes agent/gateway heartbeat payload helpers (#716).
+"""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.
 
@@ -63,6 +290,168 @@ def _runtime_detail_subset(runtime_status: dict[str, Any] | None) -> dict[str, A
     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.
 
@@ -73,6 +462,16 @@ def build_agent_health_payload() -> dict[str, Any]:
         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:
@@ -86,17 +485,16 @@ def build_agent_health_payload() -> dict[str, Any]:
             },
         }
 
+    gateway_pid_path = _gateway_root_pid_path()
+
     runtime_status = None
     try:
-        runtime_status = gateway_status.read_runtime_status()
+        runtime_status = _read_gateway_runtime_status(gateway_status, gateway_pid_path)
     except Exception:
         runtime_status = None
 
     try:
-        running_pid = gateway_status.get_running_pid(cleanup_stale=False)
-    except TypeError:
-        # Older agent versions may not expose cleanup_stale. Keep compatibility.
-        running_pid = gateway_status.get_running_pid()
+        running_pid = _gateway_running_pid(gateway_status, gateway_pid_path)
     except Exception:
         running_pid = None
 
@@ -111,6 +509,45 @@ def build_agent_health_payload() -> dict[str, Any]:
             },
         }
 
+    # 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,

api/agent_sessions.py

@@ -9,6 +9,9 @@ logger = logging.getLogger(__name__)
 
 MESSAGING_SOURCES = {
     'discord',
+    'email',
+    'wecom',
+    'wecom_callback',
     'slack',
     'telegram',
     'weixin',
@@ -22,6 +25,9 @@ SOURCE_LABELS = {
     'cli': 'CLI',
     'cron': 'Cron',
     'discord': 'Discord',
+    'email': 'Email',
+    'wecom': 'WeCom',
+    'wecom_callback': 'WeCom Callback',
     'slack': 'Slack',
     'telegram': 'Telegram',
     'tool': 'Tool',
@@ -114,6 +120,26 @@ def _as_positive_int(value) -> int:
         return 0
 
 
+def _as_score(*values) -> float:
+    """First numerically-coercible value as a float, else 0.0.
+
+    Used to score lineage tips by recency. ``last_message_at`` comes from
+    ``MAX(timestamp)`` and is normally a numeric epoch, but older/non-standard
+    state.db schemas can store an ISO-8601 *text* timestamp. Rather than letting
+    a non-numeric value raise ValueError (which previously escaped the DB
+    try-block and dropped all lineage metadata), fall through to the next
+    candidate (e.g. ``started_at``).
+    """
+    for value in values:
+        if value in (None, ""):
+            continue
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            continue
+    return 0.0
+
+
 def _count_user_turns(row: dict) -> int:
     user_turns = row.get("actual_user_message_count")
     if user_turns is None:
@@ -140,14 +166,16 @@ def is_cli_session_row(row: dict) -> bool:
     if not isinstance(row, dict):
         return False
     source = _safe_lower(row.get("session_source"))
-    if source == "messaging":
-        return False
-    if source == "cli":
-        return True
     source_tag = _safe_lower(row.get("source_tag"))
     raw_source = _safe_lower(row.get("raw_source"))
     source_name = _safe_lower(row.get("source"))
     source_label = _safe_lower(row.get("source_label"))
+    if "webui" in {source, source_tag, raw_source, source_name, source_label}:
+        return False
+    if source == "messaging":
+        return False
+    if source == "cli":
+        return True
     if source_tag == "cli" or raw_source == "cli" or source_name == "cli" or source_label == "cli":
         return True
 
@@ -199,6 +227,8 @@ def _is_continuation_session(parent: dict | None, child: dict | None) -> bool:
     """
     if not parent or not child:
         return False
+    if str(child.get('session_source') or '').strip().lower() == 'fork':
+        return False
     parent_source = str(parent.get('source') or '').strip().lower()
     child_source = str(child.get('source') or '').strip().lower()
     if parent_source and child_source and parent_source != child_source:
@@ -269,23 +299,50 @@ def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
         children.sort(key=lambda row: row.get('started_at') or 0, reverse=True)
 
     def compression_tip(row: dict) -> tuple[dict | None, int]:
-        current = row
-        seen = {row['id']}
+        """Return the freshest importable continuation descendant for ``row``.
+
+        Compression parents can have multiple continuation-looking children when
+        a stale segment is resumed after a newer compressed branch already
+        exists. Picking the newest *direct* child can hide the branch whose
+        deeper descendant has the actual latest activity. Walk all reachable
+        continuation descendants and select by real message activity instead.
+        """
         latest_importable = row if (row.get('actual_message_count') or 0) > 0 else None
-        segment_count = 1
-        for _ in range(len(rows_by_id) + 1):
-            candidates = [
-                child for child in children_by_parent.get(current['id'], [])
-                if child['id'] not in seen and _is_continuation_session(current, child)
-            ]
-            if not candidates:
-                return latest_importable, segment_count
-            current = candidates[0]
-            seen.add(current['id'])
+        segment_count = 0
+        best_depth = 1
+        best_score = (
+            _as_score(latest_importable.get('last_activity'), latest_importable.get('started_at'))
+            if latest_importable
+            else 0
+        )
+        stack: list[tuple[dict, int]] = [(row, 1)]
+        seen: set[str] = set()
+
+        while stack:
+            current, depth = stack.pop()
+            current_id = current.get('id')
+            if not current_id or current_id in seen:
+                continue
+            seen.add(current_id)
             segment_count += 1
-            if (current.get('actual_message_count') or 0) > 0:
+
+            current_score = _as_score(current.get('last_activity'), current.get('started_at'))
+            if (
+                (current.get('actual_message_count') or 0) > 0
+                and (current_score > best_score or (current_score == best_score and depth >= best_depth))
+            ):
                 latest_importable = current
-        return latest_importable, segment_count
+                best_depth = depth
+                best_score = current_score
+            for child in children_by_parent.get(current_id, []):
+                child_id = child.get('id')
+                if not child_id or child_id in seen:
+                    continue
+                if not _is_continuation_session(current, child):
+                    continue
+                stack.append((child, depth + 1))
+
+        return latest_importable, max(segment_count, 1)
 
     projected = []
     for row in rows:
@@ -328,7 +385,7 @@ def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
         projected.append(merged)
 
     projected.sort(
-        key=lambda row: row.get('last_activity') or row.get('started_at') or 0,
+        key=lambda row: _as_score(row.get('last_activity'), row.get('started_at')),
         reverse=True,
     )
     return projected
@@ -336,7 +393,7 @@ def _project_agent_session_rows(rows: list[dict]) -> list[dict]:
 
 def read_importable_agent_session_rows(
     db_path: Path,
-    limit: int = 200,
+    limit: int | None = 200,
     log=None,
     exclude_sources: tuple[str, ...] | None = ("cron", "webui"),
 ) -> list[dict]:
@@ -379,6 +436,7 @@ def read_importable_agent_session_rows(
             return []
 
         parent_expr = _optional_col('parent_session_id', session_cols)
+        session_source_expr = _optional_col('session_source', session_cols)
         ended_expr = _optional_col('ended_at', session_cols)
         end_reason_expr = _optional_col('end_reason', session_cols)
         user_id_expr = _optional_col('user_id', session_cols)
@@ -389,14 +447,76 @@ def read_importable_agent_session_rows(
         origin_chat_id_expr = _optional_col('origin_chat_id', session_cols)
         origin_user_id_expr = _optional_col('origin_user_id', session_cols)
         platform_expr = _optional_col('platform', session_cols)
-        user_message_count_expr = (
-            "COUNT(CASE WHEN LOWER(m.role) = 'user' THEN 1 END)"
-            if 'role' in message_cols
-            else "COUNT(m.id)"
-        )
+        # Older/minimal state.db schemas can have NO ``messages`` table at all,
+        # or a ``messages`` table without a ``session_id`` / ``timestamp`` column.
+        # The projection SQL below joins ``messages`` and aggregates
+        # ``MAX(m.timestamp)`` unconditionally, so on those schemas the query
+        # raised ``sqlite3.OperationalError`` — which the caller
+        # (``get_cli_sessions``) swallows into an empty list, silently hiding
+        # ALL imported/CLI/agent sessions from the sidebar. Detect the columns
+        # and degrade gracefully (mirrors ``read_session_lineage_metadata``):
+        # only join/aggregate ``messages`` when it's actually usable, otherwise
+        # fall back to the per-session ``s.message_count`` / ``s.started_at``. (#3762)
+        messages_has_session_id = 'session_id' in message_cols
+        messages_has_timestamp = 'timestamp' in message_cols
+        use_messages_join = messages_has_session_id
+        count_col = 'id' if 'id' in message_cols else 'session_id'
+
+        # Defensive index prime (#3887). The candidate-ordering query below sorts
+        # sessions by a correlated ``MAX(mx.timestamp)`` subquery over ``messages``.
+        # That is fast only when the agent's standard
+        # ``idx_messages_session ON messages(session_id, timestamp)`` index exists.
+        # A normally-migrated hermes-agent state.db has it, but a db that lost its
+        # migrations (older hermes-agent, or a hand-rebuilt/reimported db) does
+        # not — and the subquery then degrades to a full ``messages`` scan per
+        # candidate session, stalling ``/api/sessions`` for seconds on every
+        # refresh (the 5s-TTL cache never settles). Priming the index is a no-op
+        # (~free) when it already exists, and self-heals an affected db in
+        # milliseconds. Best-effort: degrade silently on a read-only db or any
+        # error so the listing never fails because of the prime.
+        if messages_has_session_id and messages_has_timestamp:
+            try:
+                cur.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_messages_session "
+                    "ON messages(session_id, timestamp)"
+                )
+                conn.commit()
+            except sqlite3.Error:
+                pass  # read-only db / locked / older schema — degrade gracefully
+
+        if use_messages_join:
+            actual_count_expr = f"COUNT(m.{count_col})"
+            if 'role' in message_cols:
+                user_message_count_expr = "COUNT(CASE WHEN LOWER(m.role) = 'user' THEN 1 END)"
+            else:
+                user_message_count_expr = f"COUNT(m.{count_col})"
+            last_activity_expr = "MAX(m.timestamp)" if messages_has_timestamp else "NULL"
+            join_clause = "LEFT JOIN messages m ON m.session_id = s.id"
+            group_by_clause = "GROUP BY s.id"
+        else:
+            # No usable messages table: use the denormalized per-session counts
+            # and ``started_at`` so the rows still surface in the sidebar.
+            actual_count_expr = "s.message_count"
+            user_message_count_expr = "s.message_count"
+            last_activity_expr = "NULL"
+            join_clause = ""
+            group_by_clause = ""
+
+        if use_messages_join and messages_has_timestamp:
+            order_by_clause = "ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC"
+            candidate_order_clause = (
+                "ORDER BY COALESCE(\n"
+                "                        (SELECT MAX(mx.timestamp) FROM messages mx WHERE mx.session_id = s.id),\n"
+                "                        s.started_at\n"
+                "                    ) DESC,\n"
+                "                    s.started_at DESC"
+            )
+        else:
+            order_by_clause = "ORDER BY s.started_at DESC"
+            candidate_order_clause = "ORDER BY s.started_at DESC"
 
         where_clauses = ["s.source IS NOT NULL"]
-        params: list[str] = []
+        params: list[object] = []
         if exclude_sources:
             excluded = tuple(str(source) for source in exclude_sources if source)
             if excluded:
@@ -404,10 +524,10 @@ def read_importable_agent_session_rows(
                 where_clauses.append(f"s.source NOT IN ({placeholders})")
                 params.extend(excluded)
 
-        cur.execute(
-            f"""
+        select_sql = f"""
             SELECT s.id, s.title, s.model, s.message_count,
                    s.started_at, s.source,
+                   {session_source_expr},
                    {user_id_expr},
                    {chat_id_expr},
                    {chat_type_expr},
@@ -419,17 +539,53 @@ def read_importable_agent_session_rows(
                    {parent_expr},
                    {ended_expr},
                    {end_reason_expr},
-                   COUNT(m.id) AS actual_message_count,
+                   {actual_count_expr} AS actual_message_count,
                    {user_message_count_expr} AS actual_user_message_count,
-                   MAX(m.timestamp) AS last_activity
-            FROM sessions s
-            LEFT JOIN messages m ON m.session_id = s.id
-            WHERE {' AND '.join(where_clauses)}
-            GROUP BY s.id
-            ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC
-            """,
-            params,
-        )
+                   {last_activity_expr} AS last_activity
+        """
+        if limit is not None:
+            result_limit = max(0, int(limit))
+            if result_limit == 0:
+                return []
+            # The sidebar only needs a small visible window. Bound the expensive
+            # messages join to a recent-activity candidate set instead of
+            # aggregating every historical Hermes state.db session before
+            # slicing in Python. The candidate ordering must include the latest
+            # message timestamp, not only ``started_at``: long-lived CLI sessions
+            # can be resumed days later and should still surface at the top.
+            # Oversampling preserves room for hidden compression segments or
+            # other rows filtered after projection.
+            candidate_limit = max(result_limit * 8, result_limit)
+            cur.execute(
+                f"""
+                WITH candidates AS (
+                    SELECT s.id
+                    FROM sessions s
+                    WHERE {' AND '.join(where_clauses)}
+                    {candidate_order_clause}
+                    LIMIT ?
+                )
+                {select_sql}
+                FROM sessions s
+                JOIN candidates c ON c.id = s.id
+                {join_clause}
+                {group_by_clause}
+                {order_by_clause}
+                """,
+                [*params, candidate_limit],
+            )
+        else:
+            cur.execute(
+                f"""
+                {select_sql}
+                FROM sessions s
+                {join_clause}
+                WHERE {' AND '.join(where_clauses)}
+                {group_by_clause}
+                {order_by_clause}
+                """,
+                params,
+            )
         projected = _project_agent_session_rows([dict(row) for row in cur.fetchall()])
         projected = [_with_normalized_source(row) for row in projected]
         projected = [row for row in projected if is_cli_session_row_visible(row)]
@@ -439,6 +595,175 @@ def read_importable_agent_session_rows(
 
 
 
+def _lineage_report_row(row: dict, role: str) -> dict:
+    updated_at = row.get('ended_at') if row.get('ended_at') is not None else row.get('started_at')
+    return {
+        'session_id': row.get('id'),
+        'role': role,
+        'title': row.get('title'),
+        'source': row.get('source'),
+        'started_at': row.get('started_at'),
+        'updated_at': updated_at,
+        'end_reason': row.get('end_reason'),
+        'active': row.get('ended_at') is None,
+        'archived': False,
+    }
+
+
+def _empty_lineage_report(session_id: str, *, found: bool = False) -> dict:
+    return {
+        'mutation': False,
+        'found': found,
+        'session_id': session_id,
+        'lineage_key': session_id,
+        'tip_session_id': session_id,
+        'total_segments': 0,
+        'materialized_segments': 0,
+        'segments': [],
+        'children': [],
+        'manual_review': False,
+    }
+
+
+def read_session_lineage_report(db_path: Path, session_id: str | None, max_hops: int = 20) -> dict:
+    """Return a bounded, read-only lifecycle report for a session lineage.
+
+    This helper intentionally reports only facts that can be derived from
+    ``state.db.sessions`` without mutating WebUI JSON, archiving rows, or
+    deleting historical segments. It mirrors the sidebar continuation rules so
+    a future UI/PR can explain which rows are hidden compression/cli-close
+    segments and which child-session branches remain distinct.
+    """
+    sid = str(session_id or '').strip()
+    if not sid:
+        return _empty_lineage_report('')
+    db_path = Path(db_path)
+    if not db_path.exists():
+        return _empty_lineage_report(sid)
+
+    try:
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            conn.row_factory = sqlite3.Row
+            cur = conn.cursor()
+            cur.execute("PRAGMA table_info(sessions)")
+            session_cols = {row[1] for row in cur.fetchall()}
+            required = {'id', 'parent_session_id', 'end_reason'}
+            if not required.issubset(session_cols):
+                return _empty_lineage_report(sid)
+
+            source_expr = _optional_col('source', session_cols)
+            session_source_expr = _optional_col('session_source', session_cols)
+            title_expr = _optional_col('title', session_cols)
+            started_expr = _optional_col('started_at', session_cols, '0')
+            ended_expr = _optional_col('ended_at', session_cols)
+            end_reason_expr = _optional_col('end_reason', session_cols)
+            parent_expr = _optional_col('parent_session_id', session_cols)
+
+            def fetch_one(row_id: str | None) -> dict | None:
+                if not row_id:
+                    return None
+                cur.execute(
+                    f"""
+                    SELECT s.id,
+                           {source_expr},
+                           {session_source_expr},
+                           {title_expr},
+                           {started_expr},
+                           {parent_expr},
+                           {ended_expr},
+                           {end_reason_expr}
+                    FROM sessions s
+                    WHERE s.id = ?
+                    """,
+                    (row_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+            target = fetch_one(sid)
+            if not target:
+                return _empty_lineage_report(sid)
+
+            segments = [target]
+            current = target
+            seen = {sid}
+            manual_review = False
+            for _hop in range(max(0, int(max_hops))):
+                parent_id = current.get('parent_session_id')
+                parent = fetch_one(parent_id)
+                if not parent or parent_id in seen:
+                    manual_review = bool(parent_id and parent_id in seen)
+                    break
+                if not _is_continuation_session(parent, current):
+                    break
+                segments.append(parent)
+                seen.add(parent_id)
+                current = parent
+            else:
+                manual_review = True
+
+            segment_ids = {row['id'] for row in segments}
+            child_rows: list[dict] = []
+            parent_ids = [row['id'] for row in segments]
+            children_by_parent: dict[str, list[dict]] = {pid: [] for pid in parent_ids}
+            if parent_ids:
+                placeholders = ','.join('?' * len(parent_ids))
+                cur.execute(
+                    f"""
+                    SELECT s.id,
+                           {source_expr},
+                           {session_source_expr},
+                           {title_expr},
+                           {started_expr},
+                           {parent_expr},
+                           {ended_expr},
+                           {end_reason_expr}
+                    FROM sessions s
+                    WHERE s.parent_session_id IN ({placeholders})
+                    """,
+                    parent_ids,
+                )
+                for child_row in cur.fetchall():
+                    child = dict(child_row)
+                    parent_id = child.get('parent_session_id')
+                    if parent_id in children_by_parent:
+                        children_by_parent[parent_id].append(child)
+            for parent in segments:
+                parent_children = children_by_parent.get(parent['id'], [])
+                parent_children.sort(key=lambda row: row.get('started_at') or 0, reverse=True)
+                for child in parent_children:
+                    if child['id'] in segment_ids:
+                        continue
+                    if _is_continuation_session(parent, child):
+                        # A continuation outside the selected path means the
+                        # lineage is branched or the caller selected an older
+                        # segment. Report manual review rather than proposing
+                        # destructive cleanup candidates.
+                        manual_review = True
+                        continue
+                    child_rows.append(child)
+    except Exception:
+        return _empty_lineage_report(sid)
+
+    root_id = segments[-1]['id'] if segments else sid
+    tip_id = segments[0]['id'] if segments else sid
+    return {
+        'mutation': False,
+        'found': True,
+        'session_id': sid,
+        'lineage_key': root_id,
+        'tip_session_id': tip_id,
+        'total_segments': len(segments),
+        'materialized_segments': len(segments),
+        'segments': [
+            _lineage_report_row(row, 'tip' if idx == 0 else 'hidden_segment')
+            for idx, row in enumerate(segments)
+        ],
+        'children': [_lineage_report_row(row, 'child_session') for row in child_rows],
+        'manual_review': manual_review,
+    }
+
+
 def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[str]) -> dict[str, dict]:
     """Return compression-lineage metadata for known WebUI sidebar sessions.
 
@@ -463,6 +788,9 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
             session_cols = {row[1] for row in cur.fetchall()}
             if 'parent_session_id' not in session_cols or 'end_reason' not in session_cols:
                 return {}
+            session_source_expr = _optional_col('session_source', session_cols)
+            source_expr = _optional_col('source', session_cols)
+            message_count_expr = _optional_col('message_count', session_cols, '0')
             # Scoped fetch via PRIMARY KEY + idx_sessions_parent rather than a
             # full table scan. The sessions table grows unbounded over time
             # (1000+ rows is normal, 10000+ for power users), and this function
@@ -471,7 +799,9 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
             #
             # Fetch the wanted ids first, then chase parent_session_id chains
             # in batches until no new ids appear. Each batch hits PRIMARY KEY
-            # so it's effectively O(N) lookups.
+            # so it's effectively O(N) lookups. Then walk continuation children
+            # from the materialized ancestors so branchy compression lineages can
+            # mark the real freshest tip, not just the newest direct sibling.
             #
             # IN-clause is chunked to 500 to stay under SQLITE_MAX_VARIABLE_NUMBER
             # on older sqlite (Python 3.9 ships sqlite 3.31 which defaults to 999;
@@ -496,9 +826,9 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
                     placeholders = ','.join('?' * len(chunk))
                     cur.execute(
                         f"""
-                        SELECT id, source, title, started_at, parent_session_id, ended_at, end_reason
-                        FROM sessions
-                        WHERE id IN ({placeholders})
+                        SELECT s.id, {source_expr}, {session_source_expr}, s.title, s.started_at, s.parent_session_id, s.ended_at, s.end_reason, {message_count_expr}
+                        FROM sessions s
+                        WHERE s.id IN ({placeholders})
                         """,
                         chunk,
                     )
@@ -509,15 +839,156 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
                     parent_id = rows.get(sid, {}).get('parent_session_id')
                     if parent_id and parent_id not in rows and parent_id not in to_fetch:
                         to_fetch.add(parent_id)
+
+            # Fetch descendants from the discovered ancestors using the parent
+            # index. This keeps the sidebar read scoped while still giving the
+            # collapse metadata enough information to choose the active branch.
+            to_expand = set(rows)
+            expanded: set[str] = set()
+            for _hop in range(20):
+                frontier = [sid for sid in to_expand if sid not in expanded]
+                if not frontier:
+                    break
+                to_expand = set()
+                for i in range(0, len(frontier), IN_CHUNK):
+                    chunk = frontier[i:i + IN_CHUNK]
+                    placeholders = ','.join('?' * len(chunk))
+                    cur.execute(
+                        f"""
+                        SELECT s.id, {source_expr}, {session_source_expr}, s.title, s.started_at, s.parent_session_id, s.ended_at, s.end_reason, {message_count_expr}
+                        FROM sessions s
+                        WHERE s.parent_session_id IN ({placeholders})
+                        """,
+                        chunk,
+                    )
+                    for row in cur.fetchall():
+                        child = dict(row)
+                        rows[child['id']] = child
+                        parent_id = child.get('parent_session_id')
+                        parent = rows.get(str(parent_id)) if parent_id else None
+                        if parent and child['id'] not in expanded and _is_continuation_session(parent, child):
+                            to_expand.add(child['id'])
+                expanded.update(frontier)
+
+            message_stats: dict[str, dict] = {}
+            cur.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'messages'")
+            has_messages_table = cur.fetchone() is not None
+            # Older/minimal state.db schemas can have a `messages` table WITHOUT a
+            # `timestamp` column (or with a non-numeric one). Detect the columns
+            # rather than gating on table existence alone: require `session_id`,
+            # and only select MAX(timestamp) when that column is actually present
+            # so the query can't raise and collapse the whole lineage metadata.
+            messages_has_session_id = False
+            messages_has_timestamp = False
+            if has_messages_table:
+                cur.execute("PRAGMA table_info(messages)")
+                _message_cols = {row[1] for row in cur.fetchall()}
+                messages_has_session_id = 'session_id' in _message_cols
+                messages_has_timestamp = 'timestamp' in _message_cols
+            use_messages_query = has_messages_table and messages_has_session_id
+            row_ids = list(rows)
+            if use_messages_query:
+                last_at_expr = "MAX(timestamp) AS last_message_at" if messages_has_timestamp else "NULL AS last_message_at"
+                for i in range(0, len(row_ids), IN_CHUNK):
+                    chunk = row_ids[i:i + IN_CHUNK]
+                    placeholders = ','.join('?' * len(chunk))
+                    cur.execute(
+                        f"""
+                        SELECT session_id, COUNT(*) AS actual_message_count, {last_at_expr}
+                        FROM messages
+                        WHERE session_id IN ({placeholders})
+                        GROUP BY session_id
+                        """,
+                        chunk,
+                    )
+                    for row in cur.fetchall():
+                        message_stats[row['session_id']] = dict(row)
+            for sid, row in rows.items():
+                stats = message_stats.get(sid) or {}
+                if use_messages_query:
+                    row['actual_message_count'] = int(stats.get('actual_message_count') or 0)
+                else:
+                    row['actual_message_count'] = int(row.get('message_count') or 0)
+                row['last_message_at'] = stats.get('last_message_at')
     except Exception:
         return {}
 
+    children_by_parent: dict[str, list[dict]] = {}
+    for row in rows.values():
+        parent_id = row.get('parent_session_id')
+        if parent_id:
+            children_by_parent.setdefault(parent_id, []).append(row)
+
+    def continuation_root_and_depth(sid: str) -> tuple[str, int]:
+        root_id = sid
+        current_id = sid
+        depth = 1
+        seen = {sid}
+        while True:
+            current = rows.get(current_id)
+            raw_parent_id = current.get('parent_session_id') if current else None
+            parent_id = str(raw_parent_id) if raw_parent_id else ''
+            if not parent_id:
+                break
+            parent = rows.get(parent_id)
+            if not parent or parent_id in seen:
+                break
+            if not _is_continuation_session(parent, current):
+                break
+            root_id = parent_id
+            current_id = parent_id
+            seen.add(parent_id)
+            depth += 1
+        return root_id, depth
+
+    def freshest_continuation_tip(root_id: str) -> tuple[str, int]:
+        best_id = root_id
+        best_depth = 1
+        segment_count = 0
+        best_score = _as_score(rows.get(root_id, {}).get('last_message_at'), rows.get(root_id, {}).get('started_at'))
+        stack: list[tuple[str, int]] = [(root_id, 1)]
+        seen: set[str] = set()
+        while stack:
+            current_id, depth = stack.pop()
+            if current_id in seen:
+                continue
+            seen.add(current_id)
+            current = rows.get(current_id)
+            if not current:
+                continue
+            segment_count += 1
+            actual_count = int(current.get('actual_message_count') or 0)
+            score = _as_score(current.get('last_message_at'), current.get('started_at'))
+            if actual_count > 0 and (score > best_score or (score == best_score and depth >= best_depth)):
+                best_id = current_id
+                best_depth = depth
+                best_score = score
+            for child in children_by_parent.get(current_id, []):
+                if _is_continuation_session(current, child):
+                    stack.append((child['id'], depth + 1))
+
+        return best_id, max(segment_count, best_depth)
+
+    lineage_tip_cache: dict[str, tuple[str, int]] = {}
     metadata: dict[str, dict] = {}
     for sid in wanted:
         row = rows.get(sid)
         if not row:
             continue
 
+        state_title = str(row.get('title') or '').strip()
+        if state_title:
+            metadata.setdefault(sid, {})['_state_db_title'] = state_title
+        state_source = str(row.get('source') or '').strip().lower()
+        if state_source:
+            entry = metadata.setdefault(sid, {})
+            entry['_state_db_source'] = state_source
+            source_meta = normalize_agent_session_source(state_source)
+            entry['_state_db_source_tag'] = state_source
+            entry['_state_db_raw_source'] = source_meta.get('raw_source')
+            entry['_state_db_session_source'] = source_meta.get('session_source')
+            entry['_state_db_source_label'] = source_meta.get('source_label')
+
         parent_id = row.get('parent_session_id')
         parent_row = rows.get(parent_id) if parent_id else None
         if parent_id and parent_row:
@@ -527,31 +998,24 @@ def read_session_lineage_metadata(db_path: Path, session_ids: list[str] | set[st
                 entry['relationship_type'] = 'child_session'
                 entry['parent_title'] = parent_row.get('title')
                 entry['parent_source'] = parent_row.get('source')
+                parent_source = str(parent_row.get('source') or '').strip().lower()
+                child_source = str(row.get('source') or '').strip().lower()
+                if parent_source and child_source and parent_source != child_source:
+                    entry['_cross_surface_child_session'] = True
                 parent_root = _continuation_root_id(rows, parent_id)
                 if parent_root:
                     entry['_parent_lineage_root_id'] = parent_root
                 continue
 
-        root_id = sid
-        current_id = sid
-        segment_count = 1
-        seen = {sid}
-        while True:
-            current = rows.get(current_id)
-            parent_id = current.get('parent_session_id') if current else None
-            parent = rows.get(parent_id) if parent_id else None
-            if not parent or parent_id in seen:
-                break
-            if not _is_continuation_session(parent, current):
-                break
-            root_id = parent_id
-            current_id = parent_id
-            seen.add(parent_id)
-            segment_count += 1
+        root_id, segment_count = continuation_root_and_depth(sid)
 
         if root_id != sid:
             entry = metadata.setdefault(sid, {})
             entry['_lineage_root_id'] = root_id
-            entry['_compression_segment_count'] = segment_count
+            if root_id not in lineage_tip_cache:
+                lineage_tip_cache[root_id] = freshest_continuation_tip(root_id)
+            tip_id, tip_depth = lineage_tip_cache[root_id]
+            entry['_lineage_tip_id'] = tip_id
+            entry['_compression_segment_count'] = max(segment_count, tip_depth)
 
     return metadata

api/auth.py

@@ -1,7 +1,7 @@
 """
-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
@@ -9,23 +9,81 @@ 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 * 30  # 30 days
+CSRF_HEADER_NAME = 'X-Hermes-CSRF-Token'
+
+
+# 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'
 
@@ -75,125 +133,418 @@ def _save_sessions(sessions: dict[str, float]) -> None:
 
 # 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
-    _save_sessions(_sessions)
-    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()
-    expired = [t for t, exp in _sessions.items() if now > exp]
-    if expired:
-        for token in expired:
-            _sessions.pop(token, None)
-        _save_sessions(_sessions)
+    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]
-        if token in _sessions:
-            _sessions.pop(token, None)
-            _save_sessions(_sessions)
+        with _SESSIONS_LOCK:
+            if token in _sessions:
+                _sessions.pop(token, None)
+                _save_sessions(_sessions)
 
 
 def parse_cookie(handler) -> str | None:
@@ -206,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
 
 
@@ -224,10 +575,12 @@ def check_auth(handler, parsed) -> bool:
         return True
     # Not authorized
     if parsed.path.startswith('/api/'):
+        body = b'{"error":"Authentication required"}'
         handler.send_response(401)
         handler.send_header('Content-Type', 'application/json')
+        handler.send_header('Content-Length', str(len(body)))
         handler.end_headers()
-        handler.wfile.write(b'{"error":"Authentication required"}')
+        handler.wfile.write(body)
     else:
         handler.send_response(302)
         # Pass the original path as ?next= so login.js redirects back after auth.
@@ -257,29 +610,77 @@ def check_auth(handler, parsed) -> bool:
         # `?`, `&`, `=`) 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/clarify.py

@@ -9,8 +9,11 @@ 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()
@@ -25,12 +28,13 @@ _clarify_sse_subscribers: dict[str, list[queue.Queue]] = {}
 class _ClarifyEntry:
     """One pending clarify request inside a session."""
 
-    __slots__ = ("event", "data", "result")
+    __slots__ = ("event", "data", "result", "clarify_id")
 
     def __init__(self, data: dict):
         self.event = threading.Event()
         self.data = data
         self.result: Optional[str] = None
+        self.clarify_id: str = data.get("clarify_id", "") or uuid.uuid4().hex[:12]
 
 
 def register_gateway_notify(session_key: str, cb) -> None:
@@ -50,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()
 
@@ -58,6 +64,8 @@ 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)
@@ -120,6 +128,11 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                 == list(data.get("choices_offered") or [])
             ):
                 entry = last
+                # Dedup re-uses the existing entry with its original clarify_id.
+                # If a future caller pre-populates clarify_id in data, it is
+                # silently discarded here — the original entry's id wins.
+                # Today no caller sets clarify_id (it's generated by __init__),
+                # so this is a non-issue.
                 cb = _gateway_notify_cbs.get(session_key)
                 # Keep _pending aligned to the oldest unresolved entry.
                 _pending[session_key] = gw_queue[0].data
@@ -128,14 +141,20 @@ def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
                         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)
+        # 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)
@@ -159,6 +178,15 @@ 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:
@@ -173,9 +201,38 @@ def resolve_clarify(session_key: str, response: str, resolve_all: bool = False)
         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

@@ -12,7 +12,7 @@ import json
 import logging
 import os
 import urllib.request
-from urllib.parse import urlparse
+from urllib.parse import urlparse, urlunparse
 
 logger = logging.getLogger(__name__)
 
@@ -61,6 +61,44 @@ def normalize_dashboard_url(raw_url: str | None) -> tuple[str, int, str, str] |
     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
@@ -132,8 +170,7 @@ def get_dashboard_config(config_data: dict | None = None) -> dict:
         enabled = "auto"
     raw_url = str(dashboard_cfg.get("url") or "").strip()
     if raw_url:
-        # Normalize before echoing so the UI never displays unsafe/stale values.
-        _host, _port, _scheme, raw_url = normalize_dashboard_url(raw_url)
+        raw_url = normalize_dashboard_browser_url(raw_url)
     return {"enabled": enabled, "url": raw_url}
 
 
@@ -143,9 +180,7 @@ def save_dashboard_config(payload: dict) -> dict:
     if enabled not in _DASHBOARD_ENABLED_VALUES:
         raise ValueError("invalid dashboard enabled mode")
     raw_url = str((payload or {}).get("url", "") or "").strip()
-    normalized_url = ""
-    if raw_url:
-        _host, _port, _scheme, normalized_url = normalize_dashboard_url(raw_url)
+    normalized_url = normalize_dashboard_browser_url(raw_url) if raw_url else ""
 
     from api import config as webui_config
 
@@ -186,9 +221,13 @@ def get_dashboard_status(config_data: dict | None = None) -> dict:
 
     raw_url = dashboard_cfg.get("url") or dashboard_cfg.get("target") or ""
     try:
-        override = normalize_dashboard_url(raw_url)
+        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:
@@ -197,8 +236,10 @@ def get_dashboard_status(config_data: dict | None = None) -> dict:
         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": base}
+        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}
@@ -207,5 +248,8 @@ def get_dashboard_status(config_data: dict | None = None) -> dict:
         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/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

@@ -13,8 +13,10 @@ import json
 import logging
 import os
 import queue
+import sqlite3
 import threading
 import time
+from contextlib import closing
 from pathlib import Path
 
 from api.config import HOME
@@ -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:
@@ -98,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."""
@@ -183,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,20 +52,81 @@ 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' https://*.cloudflareaccess.com; "
-        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://static.cloudflareinsights.com; "
-        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; "
-        "img-src 'self' data: https: blob:; font-src 'self' data: https://cdn.jsdelivr.net https://fonts.gstatic.com; connect-src 'self'; "
-        "manifest-src 'self' https://*.cloudflareaccess.com; "
-        "base-uri 'self'; form-action 'self'"
-    )
+    handler.send_header(_CSP_HEADER_NAME, _build_csp_enforced_policy(extra_connect_src))
     handler.send_header(
         'Permissions-Policy',
         'camera=(), microphone=(self), geolocation=(), clipboard-write=(self)'
@@ -64,6 +142,25 @@ def _accepts_gzip(handler) -> bool:
     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.
 
@@ -88,8 +185,7 @@ def j(handler, payload, status: int=200, extra_headers: dict=None) -> None:
     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:
@@ -100,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
@@ -111,7 +206,8 @@ MAX_BODY_BYTES = 20 * 1024 * 1024  # 20MB limit for non-upload POST bodies
 
 def _build_redact_fn():
     """Return a redactor backed by hermes-agent plus local fallback patterns."""
-    # Minimal fallback covering the most common credential prefixes.
+    # Fallback mirrors the agent's known credential prefixes so WebUI API
+    # responses remain a hard redaction boundary even without hermes-agent.
     # Keep this active even when hermes-agent is importable so API responses do
     # not regress if the agent redactor misses a token shape.
     _CRED_RE = _re.compile(
@@ -123,10 +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)
@@ -178,6 +298,103 @@ def _build_redact_fn():
 _redact_fn_cached = _build_redact_fn()
 
 
+_SENSITIVE_CASE_MARKERS = (
+    "sk-",
+    "ghp_",
+    "github_pat_",
+    "gho_",
+    "ghu_",
+    "ghs_",
+    "ghr_",
+    "AKIA",
+    "xoxb-",
+    "xoxa-",
+    "xoxp-",
+    "xoxr-",
+    "xoxs-",
+    "AIza",
+    "pplx-",
+    "fal_",
+    "fc-",
+    "bb_live_",
+    "gAAAA",
+    "sk_live_",
+    "sk_test_",
+    "rk_live_",
+    "SG.",
+    "hf_",
+    "r8_",
+    "npm_",
+    "pypi-",
+    "dop_v1_",
+    "doo_v1_",
+    "am_",
+    "sk_",
+    "tvly-",
+    "exa_",
+    "gsk_",
+    "syt_",
+    "retaindb_",
+    "hsk-",
+    "mem0_",
+    "brv_",
+    "eyJ",
+    "-----BEGIN",
+)
+_SENSITIVE_LOWER_MARKERS = (
+    "authorization: bearer ",
+    "private key",
+    "postgres://",
+    "postgresql://",
+    "mysql://",
+    "mongodb://",
+    "redis://",
+    "amqp://",
+    "://",  # stage-348 Opus SHOULD-FIX: catch http(s)/ws(s)/ftp URL userinfo + sensitive query params (#2171 follow-up)
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "api_key",
+    "apikey",
+    "client_secret",
+    "auth_token",
+    "raw_secret",
+    "secret_input",
+    "key_material",
+    "x-amz-signature",
+    "token=",
+    "secret=",
+    "password=",
+    "authorization=",
+    "key=",
+    '"token"',
+    '"secret"',
+    '"password"',
+    '"bearer"',
+)
+_SENSITIVE_TELEGRAM_MARKER_RE = _re.compile(r"(?:bot)?\d{8,}:[-A-Za-z0-9_]{30,}")
+_SENSITIVE_DISCORD_MARKER_RE = _re.compile(r"<@!?\d{17,20}>")
+_SENSITIVE_PHONE_MARKER_RE = _re.compile(r"(?<![A-Za-z0-9])\+[1-9]\d{6,14}(?![A-Za-z0-9])")
+
+
+def _might_contain_sensitive_text(text: str) -> bool:
+    """Cheap prefilter before the full agent+fallback redaction pass."""
+    if not isinstance(text, str) or not text:
+        return False
+    if any(marker in text for marker in _SENSITIVE_CASE_MARKERS):
+        return True
+    lower = text.lower()
+    if any(marker in lower for marker in _SENSITIVE_LOWER_MARKERS):
+        return True
+    if ":" in text and _SENSITIVE_TELEGRAM_MARKER_RE.search(text):
+        return True
+    if "<@" in text and _SENSITIVE_DISCORD_MARKER_RE.search(text):
+        return True
+    if "+" in text and _SENSITIVE_PHONE_MARKER_RE.search(text):
+        return True
+    return False
+
+
 def _redact_text(text: str, *, _enabled: bool | None = None) -> str:
     """Redact sensitive text from API responses. Respects api_redact_enabled setting.
 
@@ -193,6 +410,8 @@ def _redact_text(text: str, *, _enabled: bool | None = None) -> str:
         _enabled = bool(load_settings().get("api_redact_enabled", True))
     if not _enabled:
         return text
+    if not _might_contain_sensitive_text(text):
+        return text
     return _redact_fn_cached(text)
 
 
@@ -212,9 +431,10 @@ def _redact_value(v, *, _enabled: bool | None = None):
 
 
 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
@@ -232,13 +452,38 @@ def redact_session_data(session_dict: dict) -> dict:
         result['messages'] = _redact_value(result['messages'], _enabled=_enabled)
     if 'tool_calls' in result:
         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:
@@ -250,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
@@ -263,18 +545,33 @@ 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.
 
     Always persist the selected profile in the cookie, including 'default'.
     Clearing the cookie causes the backend to fall back to process-global
@@ -287,8 +584,29 @@ def build_profile_cookie(name: str) -> str:
     """
     import http.cookies as _hc
     cookie = _hc.SimpleCookie()
-    cookie[PROFILE_COOKIE_NAME] = name
-    cookie[PROFILE_COOKIE_NAME]['path'] = '/'
-    cookie[PROFILE_COOKIE_NAME]['httponly'] = True
-    cookie[PROFILE_COOKIE_NAME]['samesite'] = 'Lax'
-    return cookie[PROFILE_COOKIE_NAME].OutputString()
+    cookie_name = get_profile_cookie_name()
+    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/kanban_bridge.py

@@ -1,9 +1,14 @@
-"""Read-only Hermes Kanban bridge for the WebUI.
+"""Hermes Kanban bridge for the WebUI.
 
-This module exposes a small WebUI-native API under ``/api/kanban/*`` while
-keeping Hermes Agent's ``hermes_cli.kanban_db`` as the only source of truth.
-The first integration is deliberately read-only; write/move semantics can be
-added in later focused PRs.
+This module exposes a full CRUD API under ``/api/kanban/*`` while keeping
+Hermes Agent's ``hermes_cli.kanban_db`` as the only source of truth.
+
+Supported operations:
+- Task CRUD (create, read, patch, bulk update, archive)
+- Multi-board management (list, create, archive, switch)
+- Task dependency links (create, delete)
+- SSE live event stream for real-time updates
+- Comments and worker dispatch integration
 """
 
 from __future__ import annotations
@@ -20,6 +25,7 @@ _TASK_PREFIX = "/api/kanban/tasks/"
 
 
 def _kb():
+    """Lazily import hermes_cli.kanban_db to avoid circular imports at module load."""
     from hermes_cli import kanban_db as kb
 
     return kb
@@ -73,12 +79,29 @@ def _normalise_board_or_raise(raw):
 
 
 def _conn(board=None):
+    """Initialize the kanban DB for the given board slug and return a context manager
+    that yields a sqlite connection and CLOSES it on exit.
+
+    Must be ``kb.connect_closing`` — a raw ``kb.connect()`` connection used as
+    ``with _conn(...) as conn:`` only gets sqlite3's transaction-scope context
+    manager, which never closes the file descriptor. In this long-lived server
+    that leaks one FD per request and pins stale WAL snapshots (FDs to deleted
+    ``-wal``/``-shm`` files), which starves SQLite checkpoints on the shared
+    kanban DB and aggravates probe⇄checkpoint contention for every process.
+    """
     kb = _kb()
     kb.init_db(board=board)
+    closing = getattr(kb, "connect_closing", None)
+    if closing is not None:
+        return closing(board=board)
+    # Older kanban_db builds (and lightweight test doubles) without
+    # connect_closing: fall back to the raw connection; sqlite3's own
+    # context manager at least scopes the transaction.
     return kb.connect(board=board)
 
 
 def _obj_dict(value):
+    """Coerce a dataclass or arbitrary object to a plain dict; returns None unchanged."""
     if value is None:
         return None
     if is_dataclass(value):
@@ -89,6 +112,7 @@ def _obj_dict(value):
 
 
 def _task_dict(task):
+    """Convert a task to a JSON-serialisable dict, annotating it with computed age_seconds and progress fields."""
     data = _obj_dict(task)
     if not data:
         return data
@@ -103,6 +127,7 @@ def _task_dict(task):
 
 
 def _latest_event_id(conn) -> int:
+    """Return the highest event id in task_events, falling back to 0 when the table is empty."""
     try:
         row = conn.execute("SELECT COALESCE(MAX(id), 0) AS latest FROM task_events").fetchone()
         return int(row["latest"] or 0)
@@ -111,6 +136,7 @@ def _latest_event_id(conn) -> int:
 
 
 def _bool_query(parsed, name: str, default: bool = False) -> bool:
+    """Extract a boolean query param, treating 1/true/yes/on (case-insensitive) as True."""
     raw = (parse_qs(parsed.query or "").get(name) or [None])[0]
     if raw is None:
         return default
@@ -118,11 +144,13 @@ def _bool_query(parsed, name: str, default: bool = False) -> bool:
 
 
 def _str_query(parsed, name: str):
+    """Extract a string query param, returning None when the param is absent or blank."""
     raw = (parse_qs(parsed.query or "").get(name) or [None])[0]
     return str(raw).strip() or None if raw is not None else None
 
 
 def _int_query(parsed, name: str, default=None, *, minimum=None, maximum=None):
+    """Extract an integer query param, clamped to [minimum, maximum] when those bounds are provided."""
     raw = _str_query(parsed, name)
     if raw is None:
         return default
@@ -138,6 +166,7 @@ def _int_query(parsed, name: str, default=None, *, minimum=None, maximum=None):
 
 
 def _task_link_counts(conn, tasks):
+    """Return a dict mapping each task id to its {parents, children} dependency link counts."""
     counts = {task.id: {"parents": 0, "children": 0} for task in tasks}
     try:
         rows = conn.execute("SELECT parent_id, child_id FROM task_links").fetchall()
@@ -150,6 +179,7 @@ def _task_link_counts(conn, tasks):
 
 
 def _comment_counts(conn):
+    """Return a dict mapping each task id to its total comment count across the board."""
     try:
         rows = conn.execute(
             "SELECT task_id, COUNT(*) AS n FROM task_comments GROUP BY task_id"
@@ -160,6 +190,7 @@ def _comment_counts(conn):
 
 
 def _board_payload(parsed):
+    """Build the full board JSON payload: kanban columns with tasks, filter state, and latest_event_id."""
     board = _resolve_board(parsed)
     kb = _kb()
     tenant = _str_query(parsed, "tenant")
@@ -225,6 +256,7 @@ def _board_payload(parsed):
 
 
 def _validate_status(status: str) -> str:
+    """Validate a status string against BOARD_COLUMNS, raising ValueError for unrecognised values."""
     value = str(status or "").strip().lower()
     allowed = set(BOARD_COLUMNS) | {"archived"}
     if value not in allowed:
@@ -299,6 +331,7 @@ def _set_status_direct(conn, task_id: str, new_status: str) -> bool:
 
 
 def _create_task_payload(body: dict, *, board=None):
+    """Create a new task from a parsed request body and return the task dict in a read_only envelope."""
     title = str(body.get("title") or "").strip()
     if not title:
         raise ValueError("title is required")
@@ -331,6 +364,7 @@ def _create_task_payload(body: dict, *, board=None):
 
 
 def _patch_task(conn, task_id: str, body: dict):
+    """Apply a partial update to a task, routing status transitions through structured verbs (complete, block, archive)."""
     kb = _kb()
     task = kb.get_task(conn, task_id)
     if not task:
@@ -420,6 +454,7 @@ def _patch_task(conn, task_id: str, body: dict):
 
 
 def _patch_task_payload(task_id: str, body: dict, *, board=None):
+    """Validate task_id, open a connection, and delegate field-level updates to _patch_task."""
     task_id = str(task_id or "").strip()
     if not task_id:
         raise ValueError("task_id is required")
@@ -430,6 +465,7 @@ def _patch_task_payload(task_id: str, body: dict, *, board=None):
 
 
 def _comment_payload(task_id: str, body: dict, *, board=None):
+    """Add a comment to a task and return the new comment_id in a read_only envelope."""
     task_id = str(task_id or "").strip()
     comment_body = str(body.get("body") or "").strip()
     if not task_id:
@@ -445,6 +481,7 @@ def _comment_payload(task_id: str, body: dict, *, board=None):
 
 
 def _link_tasks_payload(body: dict, *, unlink: bool = False, board=None):
+    """Create or delete a parent-child dependency link between two tasks."""
     parent_id = str(body.get("parent_id") or "").strip()
     child_id = str(body.get("child_id") or "").strip()
     if not parent_id or not child_id:
@@ -462,6 +499,7 @@ def _link_tasks_payload(body: dict, *, unlink: bool = False, board=None):
         return {"ok": True, "parent_id": parent_id, "child_id": child_id, "read_only": False}
 
 def _links_for(conn, task_id: str) -> dict:
+    """Return {parents: [...], children: [...]} dependency id lists for a task."""
     kb = _kb()
     return {
         "parents": kb.parent_ids(conn, task_id),
@@ -470,6 +508,7 @@ def _links_for(conn, task_id: str) -> dict:
 
 
 def _task_detail_payload(task_id: str, *, board=None):
+    """Return the full task detail: task dict, comments, events, dependency links, and run history."""
     kb = _kb()
     with _conn(board=board) as conn:
         task = kb.get_task(conn, task_id)
@@ -486,6 +525,7 @@ def _task_detail_payload(task_id: str, *, board=None):
 
 
 def _events_payload(parsed):
+    """Return paginated task events from the board's event log, starting after the ?since= cursor."""
     board = _resolve_board(parsed)
     since = _int_query(parsed, "since", 0, minimum=0)
     limit = _int_query(parsed, "limit", 200, minimum=1, maximum=200)
@@ -518,6 +558,7 @@ def _events_payload(parsed):
 
 
 def _config_payload(*, board=None):
+    """Return kanban configuration: column names, known assignees, and lane/display settings from hermes_cli.config."""
     kb = _kb()
     try:
         with _conn(board=board) as conn:
@@ -546,6 +587,7 @@ def _config_payload(*, board=None):
 
 
 def _stats_payload(*, board=None):
+    """Return per-status and per-assignee task counts for the board."""
     kb = _kb()
     with _conn(board=board) as conn:
         if hasattr(kb, "board_stats"):
@@ -564,6 +606,7 @@ def _stats_payload(*, board=None):
 
 
 def _assignees_payload(*, board=None):
+    """Return the list of known assignees derived from task history."""
     kb = _kb()
     with _conn(board=board) as conn:
         try:
@@ -577,6 +620,7 @@ def _assignees_payload(*, board=None):
 
 
 def _task_log_payload(parsed, task_id: str):
+    """Return the raw worker log content and on-disk metadata for a task's dispatcher run."""
     board = _resolve_board(parsed)
     kb = _kb()
     tail = _int_query(parsed, "tail", None, minimum=1, maximum=2_000_000)
@@ -602,6 +646,7 @@ def _task_log_payload(parsed, task_id: str):
 
 
 def _bulk_tasks_payload(body: dict, *, board=None):
+    """Apply a common mutation (archive/status/assignee/priority) to multiple task ids in a single transaction."""
     ids = [str(i).strip() for i in (body.get("ids") or []) if str(i).strip()]
     if not ids:
         raise ValueError("ids is required")
@@ -639,6 +684,7 @@ def _bulk_tasks_payload(body: dict, *, board=None):
 
 
 def _dispatch_payload(parsed):
+    """Trigger a single-pass kanban dispatcher run and return the dispatch result."""
     board = _resolve_board(parsed)
     kb = _kb()
     dry_run = _bool_query(parsed, "dry_run", False)
@@ -656,6 +702,7 @@ def _dispatch_payload(parsed):
 
 
 def _task_action_payload(task_id: str, body: dict, action: str, *, board=None):
+    """Execute a named action (block or unblock) on a task and return the updated task dict."""
     kb = _kb()
     task_id = str(task_id or "").strip()
     if not task_id:
@@ -702,10 +749,12 @@ def _board_meta_dict(meta):
 def _board_counts_for_slug(slug):
     """Per-status task counts for a board, used to populate the board
     switcher with a live "12 tasks" badge. Mirrors the agent dashboard's
-    ``_board_counts`` helper. Best-effort — empty dict if the board's
-    sqlite is missing (which can happen on a freshly-created board before
-    the first task is added)."""
+    ``_board_counts`` helper. Returns an empty dict for boards whose
+    sqlite file has not been materialized yet (freshly-created boards
+    with no tasks)."""
     kb = _kb()
+    if not kb.board_exists(slug):
+        return {}
     try:
         conn = kb.connect(board=slug)
     except Exception:
@@ -738,6 +787,18 @@ def _list_boards_payload(parsed):
         current = kb.get_current_board()
     except Exception:
         current = "default"
+    visible_slugs = {(_board_meta_dict(meta).get("slug")) for meta in boards}
+    default_slug = getattr(kb, "DEFAULT_BOARD", "default")
+    if current not in visible_slugs:
+        # The on-disk active-board pointer can outlive an archived/deleted board
+        # when another CLI/WebUI process removes it. Surface a valid current
+        # board instead of letting the frontend pin every subsequent request to
+        # a ghost slug and fail with an opaque 404.
+        try:
+            kb.clear_current_board()
+        except Exception:
+            pass
+        current = default_slug
     out = []
     for raw_meta in boards:
         meta = _board_meta_dict(raw_meta)
@@ -1003,7 +1064,7 @@ def _handle_events_sse_stream(handler, parsed):
     handler.send_header("Content-Type", "text/event-stream; charset=utf-8")
     handler.send_header("Cache-Control", "no-cache")
     handler.send_header("X-Accel-Buffering", "no")
-    handler.send_header("Connection", "keep-alive")
+    handler.send_header("Connection", "close")
     handler.end_headers()
 
     # Send an initial frame so the client knows the connection is open
@@ -1053,7 +1114,20 @@ def _handle_events_sse_stream(handler, parsed):
         return True
 
 
-def handle_kanban_get(handler, parsed) -> bool:
+def handle_kanban_get(handler, parsed) -> bool | None:
+    """Dispatch a Kanban GET. Three-valued return:
+
+    - ``False`` — no Kanban path matched; caller should emit a 404
+      (``_kanban_unknown_endpoint``) for genuinely stale-bundle requests.
+    - ``None`` — a path matched and the inner handler already sent a
+      response via ``bad(...)`` / ``j(...)`` (which both return ``None``).
+      The caller MUST NOT emit another response.
+    - ``True`` — a path matched and the inner handler succeeded.
+
+    Treat any falsy-but-not-False return (``0``, ``''``, etc.) as a bug and
+    audit the new return path; the caller uses ``is False`` identity check
+    to distinguish unmatched paths from already-responded paths (#1843).
+    """
     path = parsed.path
     try:
         # Multi-board management endpoints — these do NOT take a board arg
@@ -1103,7 +1177,9 @@ def handle_kanban_get(handler, parsed) -> bool:
         return bad(handler, str(exc), status=409)
 
 
-def handle_kanban_post(handler, parsed, body) -> bool:
+def handle_kanban_post(handler, parsed, body) -> bool | None:
+    """Dispatch a Kanban POST. See ``handle_kanban_get`` for the
+    three-valued ``True | None | False`` contract (#1843)."""
     path = parsed.path
     try:
         # Multi-board management endpoints — `_create_board_payload` and
@@ -1154,7 +1230,9 @@ def handle_kanban_post(handler, parsed, body) -> bool:
     return False
 
 
-def handle_kanban_patch(handler, parsed, body) -> bool:
+def handle_kanban_patch(handler, parsed, body) -> bool | None:
+    """Dispatch a Kanban PATCH. See ``handle_kanban_get`` for the
+    three-valued ``True | None | False`` contract (#1843)."""
     path = parsed.path
     try:
         # /boards/<slug> routes operate on the on-disk board collection
@@ -1190,7 +1268,9 @@ def handle_kanban_patch(handler, parsed, body) -> bool:
     return False
 
 
-def handle_kanban_delete(handler, parsed, body) -> bool:
+def handle_kanban_delete(handler, parsed, body) -> bool | None:
+    """Dispatch a Kanban DELETE. See ``handle_kanban_get`` for the
+    three-valued ``True | None | False`` contract (#1843)."""
     path = parsed.path
     try:
         # Same routing reorder as PATCH: /boards/<slug> path-routed first,

api/oauth.py

@@ -56,9 +56,34 @@ ANTHROPIC_PUBLIC_LINK_ERROR = "Claude Code credential linking failed. Check serv
 
 _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"
@@ -66,6 +91,7 @@ def _normalize_onboarding_oauth_provider(provider: str) -> str:
 
 
 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
 
@@ -132,6 +158,7 @@ def _write_auth_json(data: dict[str, Any], auth_path: Path | None = None) -> Pat
 
 
 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")
 
 
@@ -206,6 +233,7 @@ def _persist_codex_credentials(hermes_home: Path, token_data: dict[str, Any]) ->
 
 # 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)
 
 
@@ -234,18 +262,22 @@ def _read_claude_code_credentials() -> dict[str, Any] | None:
 
 
 def _clear_anthropic_env_values(hermes_home: Path) -> None:
-    """Clear Anthropic API/setup-token env values in the active profile only."""
+    """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",
-            {"ANTHROPIC_TOKEN": None, "ANTHROPIC_API_KEY": None},
+            {key: None for key in _ANTHROPIC_ENV_KEYS},
         )
     except Exception as exc:
         logger.warning("Failed to clear Anthropic env values: %s", exc)
-    os.environ.pop("ANTHROPIC_TOKEN", None)
-    os.environ.pop("ANTHROPIC_API_KEY", None)
+    _clear_process_anthropic_env_values()
 
 
 def _link_anthropic_credentials(hermes_home: Path) -> None:
@@ -310,6 +342,7 @@ def _link_anthropic_credentials(hermes_home: Path) -> None:
 
 
 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",
@@ -329,6 +362,7 @@ def _anthropic_public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[
 
 
 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",
@@ -341,6 +375,7 @@ def _anthropic_public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict
 
 
 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,
     )
@@ -434,6 +469,7 @@ def _remove_anthropic_link_marker(hermes_home: Path) -> None:
 # ── 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"
@@ -451,10 +487,12 @@ def _json_request(url: str, payload: dict[str, Any], *, form: bool = False) -> d
 
 
 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,
@@ -467,6 +505,7 @@ def _poll_codex_authorization(device_auth_id: str, user_code: str) -> dict[str,
 
 
 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,
         {
@@ -481,6 +520,7 @@ def _exchange_codex_authorization(authorization_code: str, code_verifier: str) -
 
 
 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",
@@ -494,6 +534,7 @@ def _codex_public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str,
 
 
 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",
@@ -506,6 +547,7 @@ def _codex_public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str
 
 
 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)
@@ -513,6 +555,7 @@ def _public_start_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]:
 
 
 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)
@@ -520,6 +563,7 @@ def _public_status_payload(flow_id: str, flow: dict[str, Any]) -> dict[str, Any]
 
 
 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",
@@ -532,6 +576,7 @@ def _drop_sensitive_flow_fields(flow: dict[str, Any]) -> 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:
@@ -545,11 +590,13 @@ def _cleanup_oauth_flows(now: float | None = None) -> 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:
@@ -562,6 +609,7 @@ def _set_flow_status(flow_id: str, status: str, **fields: Any) -> None:
 
 
 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 {})
@@ -698,6 +746,7 @@ def start_onboarding_oauth_flow(body: dict[str, Any] | None) -> dict[str, Any]:
 
 
 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:
@@ -714,6 +763,7 @@ def poll_onboarding_oauth_flow(flow_id: str) -> dict[str, Any]:
 
 
 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")
@@ -735,8 +785,10 @@ def cancel_onboarding_oauth_flow(body: dict[str, Any] | None) -> dict[str, Any]:
 # 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

@@ -139,6 +139,15 @@ _SUPPORTED_PROVIDER_SETUPS = {
         "models": list(_PROVIDER_MODELS.get("deepseek", [])),
         "category": "specialized",
     },
+    "xiaomi": {
+        "label": "Xiaomi MiMo",
+        "env_var": "XIAOMI_API_KEY",
+        "default_model": "mimo-v2.5-pro",
+        "default_base_url": "https://api.xiaomimimo.com/v1",
+        "requires_base_url": False,
+        "models": list(_PROVIDER_MODELS.get("xiaomi", [])),
+        "category": "specialized",
+    },
     "zai": {
         "label": "Z.AI / GLM (智谱)",
         "env_var": "GLM_API_KEY",
@@ -303,6 +312,44 @@ class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
 
 
 _PROBE_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+_DNS_ONLY_TEST_TLDS = frozenset({"invalid", "test", "example"})
+
+
+def _hostname_uses_reserved_dns_tld(hostname: str | None) -> bool:
+    host = str(hostname or "").strip().rstrip(".").lower()
+    if not host or "." not in host:
+        return False
+    return host.rsplit(".", 1)[-1] in _DNS_ONLY_TEST_TLDS
+
+
+def _exception_chain_text(exc) -> str:
+    parts: list[str] = []
+    seen: set[int] = set()
+    cur = exc
+    while cur is not None and id(cur) not in seen:
+        seen.add(id(cur))
+        parts.append(str(cur))
+        cur = getattr(cur, "__cause__", None) or getattr(cur, "__context__", None)
+    return " ".join(parts).lower()
+
+
+def _probe_failure_is_dns(exc, hostname: str | None) -> bool:
+    if isinstance(exc, socket.gaierror):
+        return True
+    text = _exception_chain_text(exc)
+    if any(
+        marker in text
+        for marker in (
+            "getaddrinfo",
+            "gaierror",
+            "name or service not known",
+            "temporary failure in name resolution",
+            "nodename nor servname provided",
+            "no address associated with hostname",
+        )
+    ):
+        return True
+    return _hostname_uses_reserved_dns_tld(hostname)
 
 
 def probe_provider_endpoint(
@@ -407,7 +454,7 @@ def probe_provider_endpoint(
         reason = exc.reason
         if isinstance(reason, socket.timeout) or "timed out" in str(reason).lower():
             return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
-        if isinstance(reason, socket.gaierror):
+        if _probe_failure_is_dns(reason, parsed.hostname):
             return {
                 "ok": False,
                 "error": "dns",
@@ -424,6 +471,12 @@ def probe_provider_endpoint(
     except (TimeoutError, socket.timeout):
         return {"ok": False, "error": "timeout", "detail": f"connection timed out after {timeout:g}s"}
     except Exception as exc:  # pragma: no cover — defensive net
+        if _probe_failure_is_dns(exc, parsed.hostname):
+            return {
+                "ok": False,
+                "error": "dns",
+                "detail": f"could not resolve host '{parsed.hostname}'",
+            }
         logger.debug("probe_provider_endpoint unexpected error", exc_info=True)
         return {"ok": False, "error": "unreachable", "detail": str(exc)[:200]}
 

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/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

@@ -14,6 +14,36 @@ 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 []
@@ -27,6 +57,16 @@ def _truncate_at_last_user(messages):
     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.
 
@@ -75,6 +115,7 @@ def retry_last(session_id: str) -> dict[str, Any]:
             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:
@@ -114,6 +155,7 @@ def undo_last(session_id: str) -> dict[str, Any]:
             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:

api/session_recovery.py

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

api/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/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/terminal.py

@@ -9,20 +9,31 @@ in the agent execution layer.
 from __future__ import annotations
 
 import errno
+import atexit
 import codecs
-import fcntl
 import os
 import queue
-import select
 import shutil
 import signal
 import struct
 import subprocess
-import termios
+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)
@@ -35,6 +46,13 @@ def _winsize(rows: int, cols: int) -> bytes:
     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
@@ -67,6 +85,148 @@ class TerminalSession:
 
 _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:
@@ -116,6 +276,7 @@ def _reader_loop(term: TerminalSession) -> None:
     finally:
         term.closed.set()
         code = term.proc.poll()
+        _reap_terminal_descendants(term.proc.pid)
         term.put_output("terminal_closed", {"exit_code": code})
 
 
@@ -135,6 +296,8 @@ def _set_size(term: TerminalSession, rows: int, cols: int) -> None:
 
 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")
@@ -170,16 +333,41 @@ def start_terminal(session_id: str, workspace: Path, rows: int = 24, cols: int =
             }
         )
         shell = _shell_path()
-        proc = subprocess.Popen(
-            _shell_argv(shell),
-            cwd=cwd,
-            env=env,
-            stdin=slave_fd,
-            stdout=slave_fd,
-            stderr=slave_fd,
-            close_fds=True,
-            start_new_session=True,
+        # 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)
 
@@ -199,6 +387,8 @@ def start_terminal(session_id: str, workspace: Path, rows: int = 24, cols: int =
 
 
 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():
@@ -207,6 +397,8 @@ def get_terminal(session_id: str) -> TerminalSession | None:
 
 
 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")
@@ -214,6 +406,8 @@ def write_terminal(session_id: str, data: str) -> None:
 
 
 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")
@@ -221,6 +415,8 @@ def resize_terminal(session_id: str, rows: int, cols: int) -> None:
 
 
 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)
@@ -240,9 +436,25 @@ def close_terminal(session_id: str) -> bool:
                     os.killpg(term.proc.pid, signal.SIGKILL)
                 except ProcessLookupError:
                     pass
+                try:
+                    term.proc.wait(timeout=1.0)
+                except (subprocess.TimeoutExpired, ProcessLookupError):
+                    pass
     finally:
         try:
             os.close(term.master_fd)
         except OSError:
             pass
+        _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

@@ -2,24 +2,75 @@
 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
@@ -59,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:
@@ -77,13 +168,12 @@ def handle_upload(handler):
             s = get_session(session_id)
         except KeyError:
             return j(handler, {'error': 'Session not found'}, status=404)
-        workspace = Path(s.workspace)
         safe_name = _sanitize_upload_name(filename)
-        dest = safe_resolve_ws(workspace, safe_name)
+        dest = _upload_destination(session_id, safe_name)
         dest.write_bytes(file_bytes)
         mime = mimetypes.guess_type(safe_name)[0] or 'application/octet-stream'
         return j(handler, {
-            'filename': safe_name,
+            'filename': dest.name,
             'path': str(dest),
             'size': dest.stat().st_size,
             'mime': mime,
@@ -96,11 +186,6 @@ def handle_upload(handler):
         return j(handler, {'error': 'Upload failed'}, status=500)
 
 
-# Maximum total extracted bytes — guards against zip/tar bombs.
-# Set to 10x the upload limit; a legitimate archive rarely exceeds 3-4x.
-_MAX_EXTRACTED_BYTES = 10 * 20 * 1024 * 1024  # 200 MB
-
-
 def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
     """Extract a zip or tar archive into the workspace.
 
@@ -109,6 +194,7 @@ def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
     """
     import zipfile, tarfile, io, os, shutil
 
+    cap = _max_extracted_bytes()
     name = Path(filename).name
     stem = Path(filename).stem  # strip .zip / .tar.gz etc.
 
@@ -121,13 +207,23 @@ def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
 
     # Determine destination directory — use archive stem as folder name
     dest_dir = safe_resolve_ws(workspace, stem)
-    # Avoid overwriting existing files by appending a suffix
+    # Avoid overwriting existing files by appending a suffix (bounded — astronomically
+    # unlikely to collide, but never spin forever).
     if dest_dir.exists():
         import string, random
-        while dest_dir.exists():
+        for _ in range(1000):
+            if not dest_dir.exists():
+                break
             suffix = ''.join(random.choices(string.digits, k=3))
-            dest_dir = dest_dir.with_name(stem + '_' + suffix)
-    dest_dir.mkdir(parents=True, exist_ok=True)
+            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
@@ -139,29 +235,38 @@ def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
                     # 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 > _MAX_EXTRACTED_BYTES:
+                    if total_extracted > cap:
                         raise ValueError(
                             f'Extraction too large ({total_extracted // (1024*1024)} MB > '
-                            f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                            f'{cap // (1024*1024)} MB limit). '
                             f'Possible zip bomb.'
                         )
-                    member_path.parent.mkdir(parents=True, exist_ok=True)
-                    with zf.open(member) as src, open(member_path, 'wb') as dst:
+                    # #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 > _MAX_EXTRACTED_BYTES:
+                            if total_extracted > cap:
                                 raise ValueError(
                                     f'Extraction too large (> '
-                                    f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                                    f'{cap // (1024*1024)} MB limit). '
                                     f'Possible zip bomb.'
                                 )
                             dst.write(chunk)
@@ -172,31 +277,39 @@ def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
                 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 > _MAX_EXTRACTED_BYTES:
+                    if total_extracted > cap:
                         raise ValueError(
                             f'Extraction too large ({total_extracted // (1024*1024)} MB > '
-                            f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                            f'{cap // (1024*1024)} MB limit). '
                             f'Possible zip bomb.'
                         )
-                    member_path.parent.mkdir(parents=True, exist_ok=True)
+                    # #3398: anchored member create makes intermediate dirs
+                    # race-safely; no pathname member_path.parent.mkdir() first.
                     src_obj = tf.extractfile(member)
                     if src_obj:
-                        with src_obj as src, open(member_path, 'wb') as dst:
+                        # #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 > _MAX_EXTRACTED_BYTES:
+                                if total_extracted > cap:
                                     raise ValueError(
                                         f'Extraction too large (> '
-                                        f'{_MAX_EXTRACTED_BYTES // (1024*1024)} MB limit). '
+                                        f'{cap // (1024*1024)} MB limit). '
                                         f'Possible zip bomb.'
                                     )
                                 dst.write(chunk)
@@ -204,7 +317,7 @@ def extract_archive(file_bytes: bytes, filename: str, workspace: Path):
     except Exception:
         # Clean up partially-extracted directory to avoid orphaned folders
         try:
-            shutil.rmtree(dest_dir, ignore_errors=True)
+            rmtree_anchored(workspace, dest_dir)
         except Exception:
             pass
         raise
@@ -231,8 +344,9 @@ def handle_upload_extract(handler):
             s = get_session(session_id)
         except KeyError:
             return j(handler, {'error': 'Session not found'}, status=404)
-        workspace = Path(s.workspace)
-        result = extract_archive(file_bytes, filename, workspace)
+        session_dir = _session_attachment_dir(session_id)
+        session_dir.mkdir(parents=True, exist_ok=True)
+        result = extract_archive(file_bytes, filename, session_dir)
         return j(handler, {'ok': True, **result})
     except ValueError as e:
         return j(handler, {'error': str(e)}, status=400)
@@ -282,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/workspace.py

@@ -7,9 +7,12 @@ profile has its own workspace configuration.  State files live at
 ``{profile_home}/webui_state/last_workspace.txt``.  The global STATE_DIR
 paths are used as fallback when no profile module is available.
 """
+import hashlib
 import json
 import logging
 import os
+import shutil
+import stat
 import subprocess
 import concurrent.futures
 from pathlib import Path
@@ -55,6 +58,48 @@ def _last_workspace_file() -> Path:
     return _profile_state_dir() / 'last_workspace.txt'
 
 
+def _is_remote_terminal_backend(terminal_cfg: dict | None) -> bool:
+    """Return True when the active terminal backend runs outside this WebUI host."""
+    if not isinstance(terminal_cfg, dict):
+        return False
+    backend = str(terminal_cfg.get('backend') or '').strip().lower()
+    return backend not in ('', 'local')
+
+
+def _remote_terminal_cwd() -> str | None:
+    """Return target-side terminal cwd for remote profiles, without local stat()."""
+    try:
+        from api.config import get_config
+
+        terminal_cfg = get_config().get('terminal', {})
+        if not _is_remote_terminal_backend(terminal_cfg):
+            return None
+        cwd = str(terminal_cfg.get('cwd') or '').strip()
+        if not cwd or cwd == '.':
+            return None
+        return cwd
+    except Exception:
+        logger.debug("Failed to read remote terminal cwd", exc_info=True)
+        return None
+
+
+def _remote_terminal_workspace_candidate(path: str | Path) -> Path | None:
+    """Return a non-stat'ed target-side Path when it is under terminal.cwd."""
+    cwd = _remote_terminal_cwd()
+    if not cwd:
+        return None
+    raw = _strip_surrounding_quotes(str(path)).strip()
+    if not raw:
+        return None
+    candidate = Path(raw).expanduser().resolve()
+    base = Path(cwd).expanduser().resolve()
+    if _is_blocked_workspace_path(candidate, raw) or _is_blocked_workspace_path(base, cwd):
+        return None
+    if candidate == base or _is_within(candidate, base):
+        return candidate
+    return None
+
+
 def _profile_default_workspace() -> str:
     """Read the profile's default workspace from its config.yaml.
 
@@ -63,36 +108,48 @@ def _profile_default_workspace() -> str:
       2. 'default_workspace' — alternate explicit key
       3. 'terminal.cwd'      — hermes-agent terminal working dir (most common)
 
-    Falls back to the boot-time DEFAULT_WORKSPACE constant.
+    For remote/SSH terminal profiles, ``terminal.cwd`` lives on the target
+    machine, not on the WebUI server. In that case return it without a
+    server-local existence check so WebUI can send the correct workspace hint
+    to the agent/tool backend.
+
+    Falls back to the live DEFAULT_WORKSPACE from api.config.
     """
     try:
         from api.config import get_config
         cfg = get_config()
+        terminal_cfg = cfg.get('terminal', {})
+        remote_terminal = _is_remote_terminal_backend(terminal_cfg)
         # Explicit webui workspace keys first
         for key in ('workspace', 'default_workspace'):
             ws = cfg.get(key)
             if ws:
                 p = Path(str(ws)).expanduser().resolve()
-                if p.is_dir():
+                if remote_terminal or p.is_dir():
                     return str(p)
         # Fall through to terminal.cwd — the agent's configured working directory
-        terminal_cfg = cfg.get('terminal', {})
         if isinstance(terminal_cfg, dict):
             cwd = terminal_cfg.get('cwd', '')
             if cwd and str(cwd) not in ('.', ''):
                 p = Path(str(cwd)).expanduser().resolve()
-                if p.is_dir():
+                if remote_terminal or p.is_dir():
                     return str(p)
     except (ImportError, Exception):
         logger.debug("Failed to load profile default workspace config")
-    return str(_BOOT_DEFAULT_WORKSPACE)
+    try:
+        from api.config import DEFAULT_WORKSPACE as _LIVE_DEFAULT_WORKSPACE
+
+        return str(Path(_LIVE_DEFAULT_WORKSPACE).expanduser().resolve())
+    except Exception:
+        return str(Path(_BOOT_DEFAULT_WORKSPACE).expanduser().resolve())
 
 
 # ── Public API ──────────────────────────────────────────────────────────────
 
 def _clean_workspace_list(workspaces: list) -> list:
     """Sanitize a workspace list:
-    - Remove entries whose paths no longer exist on disk.
+    - Preserve saved paths even when they are currently missing or inaccessible;
+      picker state must not be destroyed by a transient stat/permission failure.
     - Remove entries whose paths live inside another profile's directory
       (e.g. ~/.hermes/profiles/X/... should not appear on a different profile).
     - Rename any entry whose name is literally 'default' to 'Home' (avoids
@@ -104,10 +161,9 @@ def _clean_workspace_list(workspaces: list) -> list:
     for w in workspaces:
         path = w.get('path', '')
         name = w.get('name', '')
-        p = Path(path).resolve() if path else Path('/')
-        # Skip paths that no longer exist
-        if not p.is_dir():
+        if not path:
             continue
+        p = _safe_resolve(Path(path).expanduser())
         # Skip paths inside a DIFFERENT profile's directory (cross-profile leak).
         # Allow paths inside the CURRENT profile's own directory (e.g. test workspaces
         # created under ~/.hermes/profiles/webui/webui-mvp-test/).
@@ -130,6 +186,32 @@ def _clean_workspace_list(workspaces: list) -> list:
     return result
 
 
+def _workspace_access_error(candidate: Path, *, missing_label: str = "Path does not exist") -> str | None:
+    """Return a user-facing validation error for an unusable workspace path.
+
+    ``Path.exists()`` can collapse permission/stat failures into a generic falsey
+    result on some Python/OS combinations, which produced misleading "does not
+    exist" messages for macOS/TCC-denied directories.  Probe with ``stat()`` so
+    missing paths, non-directories, and permission-denied paths can be reported
+    separately.
+    """
+    try:
+        st = candidate.stat()
+    except FileNotFoundError:
+        return f"{missing_label}: {candidate}"
+    except PermissionError as exc:
+        return (
+            f"Cannot access path: {candidate}. The server process could not inspect "
+            f"this directory ({exc}). On macOS, grant Full Disk Access or Files and "
+            f"Folders permission to the Hermes/WebUI app or server process, then try again."
+        )
+    except OSError as exc:
+        return f"Cannot access path: {candidate}. The server process could not inspect this path ({exc})."
+    if not stat.S_ISDIR(st.st_mode):
+        return f"Path is not a directory: {candidate}"
+    return None
+
+
 def _migrate_global_workspaces() -> list:
     """Read the legacy global workspaces.json, clean it, and return the result.
 
@@ -192,19 +274,35 @@ def save_workspaces(workspaces: list) -> None:
 
 
 def get_last_workspace() -> str:
+    remote_cwd = _remote_terminal_cwd()
+
+    def valid_last_workspace(raw: str) -> str | None:
+        if not raw:
+            return None
+        if remote_cwd:
+            # For remote/SSH profiles, last_workspace is target-side state. Do
+            # not accept stale server-local paths merely because they exist on
+            # the WebUI host; require the value to stay under terminal.cwd.
+            if _remote_terminal_workspace_candidate(raw) is not None:
+                return raw
+            return None
+        if Path(raw).is_dir():
+            return raw
+        return None
+
     lw_file = _last_workspace_file()
     if lw_file.exists():
         try:
-            p = lw_file.read_text(encoding='utf-8').strip()
-            if p and Path(p).is_dir():
+            p = valid_last_workspace(lw_file.read_text(encoding='utf-8').strip())
+            if p:
                 return p
         except Exception:
             logger.debug("Failed to read last workspace from %s", lw_file)
     # Fallback: try global file
     if _GLOBAL_LW_FILE.exists():
         try:
-            p = _GLOBAL_LW_FILE.read_text(encoding='utf-8').strip()
-            if p and Path(p).is_dir():
+            p = valid_last_workspace(_GLOBAL_LW_FILE.read_text(encoding='utf-8').strip())
+            if p:
                 return p
         except Exception:
             logger.debug("Failed to read global last workspace")
@@ -433,12 +531,35 @@ def list_workspace_suggestions(prefix: str = "", limit: int = 12) -> list[str]:
     else:
         target = Path.home() / raw
 
-    normalized = str(target)
+    try:
+        match_target = target.expanduser().resolve()
+    except Exception:
+        match_target = target
+
+    normalized = str(match_target)
     normalized_lower = normalized.lower()
+    preserve_tilde = raw.startswith("~")
+    home_root: Path | None = None
+    if preserve_tilde:
+        try:
+            home_root = Path.home().expanduser().resolve()
+        except Exception:
+            home_root = None
     suggestions: list[str] = []
 
+    def format_suggestion(path: Path) -> str:
+        if preserve_tilde and home_root is not None:
+            try:
+                rel = path.resolve().relative_to(home_root)
+                if str(rel) == ".":
+                    return "~"
+                return "~/" + rel.as_posix()
+            except (OSError, ValueError):
+                pass
+        return str(path)
+
     def add(path: Path) -> None:
-        value = str(path)
+        value = format_suggestion(path)
         if value not in suggestions:
             suggestions.append(value)
 
@@ -517,10 +638,18 @@ def resolve_trusted_workspace(path: str | Path | None = None) -> Path:
 
     candidate = Path(path).expanduser().resolve()
 
-    if not candidate.exists():
-        raise ValueError(f"Path does not exist: {candidate}")
-    if not candidate.is_dir():
-        raise ValueError(f"Path is not a directory: {candidate}")
+    access_error = _workspace_access_error(candidate)
+    remote_candidate = _remote_terminal_workspace_candidate(path)
+    if access_error:
+        # For remote terminal profiles, workspace paths belong to the target
+        # machine. Allow paths under terminal.cwd so session switching can
+        # update the workspace hint even though this WebUI host cannot stat
+        # the target-side path.
+        if remote_candidate is None:
+            raise ValueError(access_error)
+
+    if remote_candidate is not None:
+        return remote_candidate
 
     # (A) Trusted if under the user's home directory — cross-platform via Path.home()
     # Must be checked before system roots to allow symlinks like /var/home.
@@ -602,10 +731,17 @@ def validate_workspace_to_add(path: str) -> Path:
     path = _strip_surrounding_quotes(path)
     candidate = Path(path).expanduser().resolve()
 
-    if not candidate.exists():
-        raise ValueError(f"Path does not exist: {candidate}")
-    if not candidate.is_dir():
-        raise ValueError(f"Path is not a directory: {candidate}")
+    access_error = _workspace_access_error(candidate)
+    remote_candidate = _remote_terminal_workspace_candidate(path)
+    if access_error:
+        # Remote terminal profiles validate workspace existence on the target
+        # machine, not on the WebUI server. Permit target-side paths under
+        # terminal.cwd.
+        if remote_candidate is None:
+            raise ValueError(access_error)
+
+    if remote_candidate is not None:
+        return remote_candidate
 
     # Home directory is always trusted regardless of where it lives on disk
     # (e.g. /var/home/... on systemd-homed Fedora/RHEL).
@@ -622,74 +758,348 @@ def validate_workspace_to_add(path: str) -> Path:
 def safe_resolve_ws(root: Path, requested: str) -> Path:
     """Resolve a relative path inside a workspace root, raising ValueError on traversal.
 
-    Symlinks whose *unresolved* path is within the workspace root are allowed —
-    the user placed them there intentionally.  Only raw ``..`` traversal outside
-    the root is blocked.
+    Both raw ``..`` traversal and symlink escapes are blocked.  Workspace file
+    APIs can be reached by browser UI actions and agent/tool calls, so a symlink
+    inside the workspace must not expand the trusted workspace boundary to an
+    arbitrary host path.
     """
-    import os
-    unresolved = root / requested
-    resolved = unresolved.resolve()
-    # Fast path: resolved path is inside root (covers most cases)
+    root_resolved = root.resolve()
+    resolved = (root / requested).resolve()
     try:
-        resolved.relative_to(root.resolve())
-        return resolved
-    except ValueError:
-        pass
-    # Symlink path: normalize '..' (without following symlinks) and check
-    # os.path.normpath collapses '..' but does NOT follow symlinks.
-    norm = Path(os.path.normpath(str(unresolved)))
-    try:
-        norm.relative_to(root)
+        resolved.relative_to(root_resolved)
     except ValueError:
         raise ValueError(f"Path traversal blocked: {requested}")
-    # Symlink points outside workspace root — additionally block system directories.
-    # Even if the user placed the symlink intentionally, prevent reads from
-    # /etc, /proc, /sys, /dev and other blocked roots (LLM agents can call
-    # read_file_content via tool calls, not just human users).
-    if _is_blocked_system_path(resolved):
-        raise ValueError(f"Path traversal blocked (system dir): {requested}")
     return resolved
 
 
+# ── Race-safe (TOCTOU) anchored open ─────────────────────────────────────────
+# safe_resolve_ws() validates a path, but if callers then re-open by pathname a
+# symlink swapped in AFTER the check could still escape the workspace. To close
+# that window we open the (already symlink-resolved) target component-by-component
+# from the workspace root using openat (dir_fd) + O_NOFOLLOW: every component must
+# be a real, non-symlink entry, so a component swapped to a symlink mid-flight is
+# refused. Legit in-workspace symlinks still work because safe_resolve_ws() has
+# already collapsed them to their real in-workspace target, and we walk that real
+# (symlink-free) path. Portable: uses os.supports_dir_fd where available (Linux,
+# macOS); on platforms without dir_fd support (Windows — where creating symlinks
+# also requires admin) we fall back to a plain pathname open, matching the prior
+# behaviour with no regression.
+
+_DIR_FD_OK = os.open in getattr(os, "supports_dir_fd", set())
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+
+
+def open_anchored_fd(workspace: Path, target: Path, *, want_dir: bool) -> int:
+    """Open ``target`` race-safely and return an owned file descriptor.
+
+    ``target`` must be the symlink-resolved path returned by safe_resolve_ws()
+    (i.e. already verified to live under the workspace). Raises FileNotFoundError
+    if a component is missing / wrong-type, or ValueError if a component was
+    swapped to a symlink (escape attempt). Caller owns and must close the fd.
+    """
+    root_resolved = workspace.resolve()
+    # Relative, symlink-free component list (resolve() already collapsed any links).
+    try:
+        rel_parts = target.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {target}") from None
+
+    if not _DIR_FD_OK:
+        # Windows / no openat: fall back to a plain pathname open. No new race
+        # protection, but no regression vs the prior path-based behaviour, and
+        # symlink creation needs admin on Windows anyway.
+        flags = os.O_RDONLY | (_O_DIRECTORY if want_dir else 0) | _O_NOFOLLOW
+        try:
+            return os.open(str(target), flags)
+        except OSError:
+            raise FileNotFoundError(f"Not found: {target}") from None
+
+    # Open the (trusted) workspace root. root_resolved is canonical (resolve()
+    # collapsed any symlinks to REACH it, e.g. macOS /tmp -> /private/tmp), so its
+    # final component is legitimately a real directory — O_NOFOLLOW here only fires
+    # if the root itself was raced into a symlink after resolve() (escape attempt).
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for i, part in enumerate(rel_parts):
+            is_last = i == len(rel_parts) - 1
+            want_directory = (not is_last) or want_dir
+            flags = os.O_RDONLY | _O_NOFOLLOW | (_O_DIRECTORY if want_directory else 0)
+            try:
+                nfd = os.open(part, flags, dir_fd=fd)
+            except OSError:
+                # ELOOP (component is a symlink — swapped in) or missing/wrong type.
+                raise FileNotFoundError(f"Not found: {target}") from None
+            os.close(fd)
+            fd = nfd
+        return fd
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        raise
+
+
+def open_anchored_create_fd(root: Path, dest: Path) -> int:
+    """Create ``dest`` for exclusive writing race-safely, anchored under ``root``.
+
+    Walks from ``root`` via openat + O_NOFOLLOW (creating missing intermediate
+    directories with mkdir(dir_fd=...)), then creates the leaf with
+    O_CREAT|O_EXCL|O_NOFOLLOW so a symlink raced into any component cannot
+    redirect the write outside ``root``. ``dest`` must be the resolved path and
+    must not already exist (callers dedup first). Raises ValueError if ``dest``
+    is not under ``root``, FileExistsError if it exists, FileNotFoundError if a
+    component was swapped to a symlink. Caller owns and must close the returned
+    write fd. On platforms without dir_fd support (Windows) falls back to a plain
+    exclusive create — no new race protection but no regression.
+    """
+    root_resolved = root.resolve()
+    try:
+        rel_parts = dest.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {dest}") from None
+    if not rel_parts:
+        raise ValueError(f"Invalid destination: {dest}")
+
+    if not _DIR_FD_OK:
+        # Windows / no openat: create parent dirs then exclusively create the leaf.
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        return os.open(str(dest), os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW, 0o644)
+
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for part in rel_parts[:-1]:
+            try:
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except FileNotFoundError:
+                os.mkdir(part, 0o755, dir_fd=fd)
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except OSError:
+                # ELOOP — component swapped to a symlink (escape attempt).
+                raise FileNotFoundError(f"Not found: {dest}") from None
+            os.close(fd)
+            fd = nfd
+        return os.open(
+            rel_parts[-1],
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW,
+            0o644,
+            dir_fd=fd,
+        )
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+def make_anchored_dir(root: Path, dest: Path) -> None:
+    """Create directory ``dest`` (and any missing parents) race-safely under ``root``.
+
+    Walks from ``root`` via openat + O_NOFOLLOW, creating each missing component
+    with mkdir(dir_fd=...), so a symlink raced into any component cannot make the
+    server create directories outside ``root``. Idempotent (existing dirs are
+    fine). Raises ValueError if ``dest`` is not under ``root``, FileNotFoundError
+    if a component was swapped to a symlink. On platforms without dir_fd support
+    (Windows) falls back to a plain Path.mkdir — no regression.
+    """
+    root_resolved = root.resolve()
+    dest_resolved = dest.resolve()
+    if dest_resolved == root_resolved:
+        return
+    try:
+        rel_parts = dest_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {dest}") from None
+
+    if not _DIR_FD_OK:
+        dest.mkdir(parents=True, exist_ok=True)
+        return
+
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for part in rel_parts:
+            try:
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except FileNotFoundError:
+                os.mkdir(part, 0o755, dir_fd=fd)
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except OSError:
+                # ELOOP — component swapped to a symlink (escape attempt).
+                raise FileNotFoundError(f"Not found: {dest}") from None
+            os.close(fd)
+            fd = nfd
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+def open_anchored_write_fd(root: Path, target: Path) -> int:
+    """Open existing ``target`` for truncating writes anchored under ``root``."""
+    root_resolved = root.resolve()
+    target_resolved = target.resolve()
+    try:
+        rel_parts = target_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {target}") from None
+    if not rel_parts:
+        raise ValueError(f"Invalid target: {target}")
+
+    flags = os.O_WRONLY | os.O_TRUNC | _O_NOFOLLOW
+    if not _DIR_FD_OK:
+        return os.open(str(target_resolved), flags)
+
+    parent_fd = open_anchored_fd(root_resolved, target_resolved.parent, want_dir=True)
+    try:
+        return os.open(rel_parts[-1], flags, dir_fd=parent_fd)
+    finally:
+        os.close(parent_fd)
+
+
+def unlink_anchored(root: Path, target: Path) -> None:
+    """Unlink an existing file anchored under ``root``."""
+    root_resolved = root.resolve()
+    target_resolved = target.resolve()
+    try:
+        rel_parts = target_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {target}") from None
+    if not rel_parts:
+        raise ValueError(f"Invalid target: {target}")
+
+    if not _DIR_FD_OK:
+        target_resolved.unlink()
+        return
+
+    parent_fd = open_anchored_fd(root_resolved, target_resolved.parent, want_dir=True)
+    try:
+        os.unlink(rel_parts[-1], dir_fd=parent_fd)
+    finally:
+        os.close(parent_fd)
+
+
+def rmtree_anchored(root: Path, target: Path) -> None:
+    """Remove a directory tree anchored under ``root`` without following symlink swaps."""
+    root_resolved = root.resolve()
+    target_resolved = target.resolve()
+    try:
+        rel_parts = target_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {target}") from None
+    if not rel_parts:
+        raise ValueError(f"Invalid target: {target}")
+
+    if not _DIR_FD_OK:
+        shutil.rmtree(target_resolved)
+        return
+
+    parent_fd = open_anchored_fd(root_resolved, target_resolved.parent, want_dir=True)
+    try:
+        shutil.rmtree(rel_parts[-1], dir_fd=parent_fd)
+    finally:
+        os.close(parent_fd)
+
+
+def rename_anchored(root: Path, source: Path, dest: Path) -> None:
+    """Rename ``source`` to ``dest`` using anchored parent directory fds."""
+    root_resolved = root.resolve()
+    source_resolved = source.resolve()
+    dest_parent_resolved = dest.parent.resolve()
+    try:
+        source_parts = source_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {source}") from None
+    try:
+        dest_parent_resolved.relative_to(root_resolved)
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {dest}") from None
+    if not source_parts:
+        raise ValueError(f"Invalid source: {source}")
+    dest_leaf = dest.name
+    if not dest_leaf:
+        raise ValueError(f"Invalid destination: {dest}")
+
+    if not _DIR_FD_OK:
+        source_resolved.rename(dest)
+        return
+
+    src_parent_fd = open_anchored_fd(root_resolved, source_resolved.parent, want_dir=True)
+    try:
+        dst_parent_fd = open_anchored_fd(root_resolved, dest_parent_resolved, want_dir=True)
+        try:
+            try:
+                os.stat(dest_leaf, dir_fd=dst_parent_fd, follow_symlinks=False)
+                raise FileExistsError(dest_leaf)
+            except FileNotFoundError:
+                pass
+            os.rename(
+                source_parts[-1],
+                dest_leaf,
+                src_dir_fd=src_parent_fd,
+                dst_dir_fd=dst_parent_fd,
+            )
+        finally:
+            os.close(dst_parent_fd)
+    finally:
+        os.close(src_parent_fd)
+
+
 def list_dir(workspace: Path, rel: str='.'):
     target = safe_resolve_ws(workspace, rel)
     if not target.is_dir():
         raise FileNotFoundError(f"Not a directory: {rel}")
     ws_resolved = workspace.resolve()
+    target_resolved = target.resolve()
     entries = []
-    for item in sorted(target.iterdir(), key=lambda p: (not p.is_symlink(), p.is_file(), p.name.lower())):
-        if item.is_symlink():
-            # Resolve the symlink target and check if it stays within workspace
+
+    def _process(name, is_symlink, raw_link, lstat_result, reachable):
+        """Append one directory entry. ``raw_link`` is the os.readlink() result
+        for symlinks (else None); ``lstat_result`` is an os.stat_result obtained
+        with follow_symlinks=False (else None); ``reachable`` is False when a
+        follow_symlinks=True stat raised (broken target or symlink loop)."""
+        if is_symlink:
+            if raw_link is None:
+                return
+            # A symlink whose follow-stat raised (ELOOP / broken target) can never
+            # be opened — filter it. This catches mutual/self loops portably across
+            # Python versions where Path.resolve() loop handling differs (3.11
+            # raises RuntimeError, 3.13 can return a path), so do not rely on
+            # resolve() raising for cycle detection.
+            if not reachable:
+                return
             try:
-                link_target = item.resolve()
-            except OSError:
-                continue
-            # Cycle detection: skip if symlink points back to current dir,
-            # workspace root, or any ancestor of current dir.
-            # This must run REGARDLESS of whether target is inside workspace.
-            if (link_target == target.resolve() or link_target == target
-                    or link_target == ws_resolved):
-                continue
+                link_target = (target_resolved / raw_link).resolve()
+            except (OSError, RuntimeError):
+                return
+            # Cycle detection: skip if symlink points back to current dir or root.
+            if link_target == target_resolved or link_target == ws_resolved:
+                return
             try:
-                target.resolve().relative_to(link_target)
-                # target is under link_target — link_target is an ancestor → cycle
-                continue
+                target_resolved.relative_to(link_target)
+                return  # target is under link_target — ancestor → cycle
             except ValueError:
                 pass
-            # Block symlinks that resolve to system directories.
+            # Hide symlinks that resolve outside the workspace (can never be opened).
+            try:
+                link_target.relative_to(ws_resolved)
+            except ValueError:
+                return
             if _is_blocked_system_path(link_target):
-                continue
+                return
             is_dir = link_target.is_dir()
-            # Keep the display path relative to workspace (don't follow the link)
-            display_path = str(Path(item.name))
+            display_path = name
             if rel and rel != '.':
                 display_path = rel + '/' + display_path
+            mtime_ns = lstat_result.st_mtime_ns if lstat_result is not None else None
             entry = {
-                'name': item.name,
+                'name': name,
                 'path': display_path,
                 'type': 'symlink',
                 'target': str(link_target),
                 'is_dir': is_dir,
+                'mtime_ns': mtime_ns,
             }
             if not is_dir:
                 try:
@@ -698,31 +1108,163 @@ def list_dir(workspace: Path, rel: str='.'):
                     entry['size'] = None
             entries.append(entry)
         else:
-            # Use rel-based path so entries under symlink targets (outside
-            # the workspace root) still get a valid workspace-relative path.
-            entry_path = item.name
+            entry_path = name
             if rel and rel != '.':
-                entry_path = rel + '/' + item.name
+                entry_path = rel + '/' + name
+            if lstat_result is not None:
+                is_file = stat.S_ISREG(lstat_result.st_mode)
+                size = lstat_result.st_size if is_file else None
+                mtime_ns = lstat_result.st_mtime_ns
+                is_dir_entry = stat.S_ISDIR(lstat_result.st_mode)
+            else:
+                size = None
+                mtime_ns = None
+                is_dir_entry = False
             entries.append({
-                'name': item.name,
+                'name': name,
                 'path': entry_path,
-                'type': 'dir' if item.is_dir() else 'file',
-                'size': item.stat().st_size if item.is_file() else None,
+                'type': 'dir' if is_dir_entry else 'file',
+                'size': size,
+                'mtime_ns': mtime_ns,
             })
-        if len(entries) >= 200:
-            break
+
+    if _DIR_FD_OK:
+        # #3398 TOCTOU hardening (Linux/macOS): open the directory via an anchored
+        # openat-walk (O_NOFOLLOW on every component) and enumerate via the verified
+        # fd (os.scandir(fd) + fd-relative fstatat/readlinkat), so a path component
+        # swapped to an escaping symlink after safe_resolve_ws() cannot redirect the
+        # listing.
+        def _sort_key_de(de):
+            try:
+                is_link = de.is_symlink()
+            except OSError:
+                is_link = False
+            is_file = False
+            if not is_link:
+                try:
+                    is_file = de.is_file()
+                except OSError:
+                    pass
+            return (not is_link, is_file, de.name.lower())
+
+        dir_fd = open_anchored_fd(workspace, target, want_dir=True)
+        try:
+            st = os.fstat(dir_fd)
+            if not stat.S_ISDIR(st.st_mode):
+                raise FileNotFoundError(f"Not a directory: {rel}")
+            with os.scandir(dir_fd) as scan:
+                scandir_entries = sorted(scan, key=_sort_key_de)
+            for de in scandir_entries:
+                name = de.name
+                is_symlink = de.is_symlink()
+                raw_link = None
+                if is_symlink:
+                    try:
+                        raw_link = os.readlink(name, dir_fd=dir_fd)
+                    except OSError:
+                        raw_link = None
+                try:
+                    lst = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+                except OSError:
+                    lst = None
+                # reachable: follow-stat succeeds (filters ELOOP/broken symlinks).
+                reachable = True
+                if is_symlink:
+                    try:
+                        os.stat(name, dir_fd=dir_fd, follow_symlinks=True)
+                    except OSError:
+                        reachable = False
+                _process(name, is_symlink, raw_link, lst, reachable)
+                if len(entries) >= 200:
+                    break
+        finally:
+            try:
+                os.close(dir_fd)
+            except OSError:
+                pass
+    else:
+        # Portability fallback (Windows / no dir_fd): path-based enumeration after
+        # safe_resolve_ws(). No anchored-fd race protection on these platforms, but
+        # no regression vs the prior behaviour (creating symlinks on Windows needs
+        # admin anyway), and safe_resolve_ws() still blocks the static escape.
+        def _sort_key_p(p: Path):
+            is_link = p.is_symlink()
+            is_file = False
+            if not is_link:
+                try:
+                    is_file = p.is_file()
+                except OSError:
+                    pass
+            return (not is_link, is_file, p.name.lower())
+
+        for item in sorted(target.iterdir(), key=_sort_key_p):
+            name = item.name
+            is_symlink = item.is_symlink()
+            raw_link = None
+            if is_symlink:
+                try:
+                    raw_link = os.readlink(str(item))
+                except OSError:
+                    raw_link = None
+            try:
+                lst = item.lstat()
+            except OSError:
+                lst = None
+            # reachable: follow-stat succeeds (filters ELOOP/broken symlinks).
+            reachable = True
+            if is_symlink:
+                try:
+                    os.stat(str(item), follow_symlinks=True)
+                except OSError:
+                    reachable = False
+            _process(name, is_symlink, raw_link, lst, reachable)
+            if len(entries) >= 200:
+                break
     return entries
 
 
+def dir_signature(workspace: Path, rel: str = '.', entries: list[dict] | None = None) -> str:
+    """Return a cheap, stable signature for a listed workspace directory.
+
+    The signature is based only on bounded directory-entry metadata already used
+    by the workspace tree: names, displayed paths, entry type, file sizes,
+    mtimes, and symlink targets. It intentionally does not read file contents.
+    """
+    if entries is None:
+        entries = list_dir(workspace, rel)
+    payload = []
+    for entry in entries:
+        payload.append({
+            'name': entry.get('name'),
+            'path': entry.get('path'),
+            'type': entry.get('type'),
+            'is_dir': entry.get('is_dir'),
+            'size': entry.get('size'),
+            'mtime_ns': entry.get('mtime_ns'),
+            'target': entry.get('target'),
+        })
+    raw = json.dumps(payload, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
+    return hashlib.sha256(raw.encode('utf-8')).hexdigest()
+
+
 def read_file_content(workspace: Path, rel: str) -> dict:
     target = safe_resolve_ws(workspace, rel)
     if not target.is_file():
         raise FileNotFoundError(f"Not a file: {rel}")
-    size = target.stat().st_size
-    if size > MAX_FILE_BYTES:
-        raise ValueError(f"File too large ({size} bytes, max {MAX_FILE_BYTES})")
-    content = target.read_text(encoding='utf-8', errors='replace')
-    return {'path': rel, 'content': content, 'size': size, 'lines': content.count('\n') + 1}
+    # #3398 TOCTOU hardening: open the resolved file via an anchored openat-walk
+    # (O_NOFOLLOW on every component) so a path swapped to an escaping symlink
+    # after safe_resolve_ws() cannot be followed, then read from the fd (not the
+    # pathname) so the bytes returned are guaranteed to be the verified file.
+    fd = open_anchored_fd(workspace, target, want_dir=False)
+    with os.fdopen(fd, 'rb', closefd=True) as fh:
+        st = os.fstat(fh.fileno())
+        if not stat.S_ISREG(st.st_mode):
+            raise FileNotFoundError(f"Not a file: {rel}")
+        if st.st_size > MAX_FILE_BYTES:
+            raise ValueError(f"File too large ({st.st_size} bytes, max {MAX_FILE_BYTES})")
+        raw = fh.read(MAX_FILE_BYTES + 1)
+    content = raw.decode('utf-8', errors='replace')
+    return {'path': rel, 'content': content, 'size': len(raw), 'lines': content.count('\n') + 1}
 
 
 # ── Git detection ──────────────────────────────────────────────────────────

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:
@@ -179,7 +228,16 @@ def ensure_python_has_webui_deps(python_exe: str, agent_dir: Path | None = None)
     )
     if not venv_python.exists():
         info(f"Creating local virtualenv at {venv_dir}")
-        venv.EnvBuilder(with_pip=True).create(venv_dir)
+        # symlinks=True: some Python builds (notably mise/asdf shared-library
+        # installs on macOS) default venv to copy mode. The copied binary still
+        # uses @executable_path/../lib/libpython3.X.dylib for its load command,
+        # so the venv binary aborts with SIGABRT on first import because the
+        # dylib never gets copied into .venv/lib. Symlinking the interpreter
+        # keeps @executable_path resolving back to the original install.
+        # CPython's venv falls back to copy mode automatically when symlink
+        # creation fails (e.g. older Windows without SeCreateSymbolicLinkPrivilege),
+        # so this is safe to set unconditionally.
+        venv.EnvBuilder(with_pip=True, symlinks=True).create(venv_dir)
 
     info("Installing WebUI dependencies into local virtualenv")
     subprocess.run(
@@ -212,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
@@ -258,8 +321,10 @@ def parse_args() -> argparse.Namespace:
         "--foreground",
         action="store_true",
         help=(
-            "Run server.py in this process (via os.execv) instead of spawning a "
-            "child. Use this under launchd / systemd / supervisord so the "
+            "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."
@@ -386,8 +451,19 @@ def main() -> int:
                 f"Set HERMES_WEBUI_PYTHON to a working interpreter or fix "
                 f"the agent venv at {agent_dir}."
             )
-        # os.execv replaces the current process image. Anything after this line
-        # only runs if execv itself fails (it raises OSError on failure).
+        # os.execv 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")

ctl.sh

@@ -7,6 +7,7 @@ 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'
@@ -27,6 +28,7 @@ ensure_home() {
 }
 
 _load_repo_dotenv_preserving_env() {
+  [[ "${HERMES_WEBUI_NO_DOTENV:-0}" == "1" ]] && return 0
   local env_file="${REPO_ROOT}/.env"
   [[ -f "${env_file}" ]] || return 0
 
@@ -39,7 +41,7 @@ _load_repo_dotenv_preserving_env() {
     key="${key#export }"
     key="${key//[[:space:]]/}"
     [[ "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
-    if [[ -v ${key} ]]; then
+    if [[ -n "${!key+x}" ]]; then
       value="${!key}"
       preserved+=("${key}=${value}")
     fi
@@ -51,9 +53,11 @@ _load_repo_dotenv_preserving_env() {
   set +a
 
   local assignment
-  for assignment in "${preserved[@]}"; do
-    export "${assignment}"
-  done
+  if [[ ${#preserved[@]} -gt 0 ]]; then
+    for assignment in "${preserved[@]}"; do
+      export "${assignment}"
+    done
+  fi
 }
 
 _find_python() {
@@ -127,11 +131,12 @@ _build_bootstrap_args() {
 }
 
 _write_state() {
-  local pid="$1" host="$2" port="$3"
+  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}"
@@ -160,20 +165,96 @@ _is_alive() {
   kill -0 "${pid}" >/dev/null 2>&1
 }
 
-_proc_args() {
+_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}" -o args= 2>/dev/null || true
+  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 state_repo=""
+  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}" == *"${state_repo}/bootstrap.py"* || "${args}" == *"${state_repo}/server.py"* || "${args}" == *"${state_repo}/start.sh"* ]]
+  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() {
@@ -193,6 +274,53 @@ _clear_stale_pid() {
   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
@@ -208,6 +336,12 @@ start_cmd() {
     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
@@ -215,12 +349,14 @@ start_cmd() {
   : >> "${LOG_FILE}"
   (
     cd "${REPO_ROOT}"
-    exec "${python_exe}" "${REPO_ROOT}/bootstrap.py" --no-browser --foreground --host "${CTL_HOST}" "${CTL_PORT}" "${CTL_BOOTSTRAP_ARGS[@]}"
+    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}"
+  _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
@@ -247,7 +383,7 @@ stop_cmd() {
   fi
 
   echo "[ctl] Stopping Hermes WebUI (PID ${pid})"
-  kill "${pid}" >/dev/null 2>&1 || true
+  _stop_webui_pid "${pid}" TERM
   local i
   for i in {1..50}; do
     if ! _is_alive "${pid}"; then
@@ -259,7 +395,7 @@ stop_cmd() {
   done
 
   echo "[ctl] Process did not exit after SIGTERM; sending SIGKILL" >&2
-  kill -KILL "${pid}" >/dev/null 2>&1 || true
+  _stop_webui_pid "${pid}" KILL
   rm -f "${PID_FILE}" "${STATE_FILE}"
 }
 

docker-compose.three-container.yml

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

docker-compose.two-container.yml

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

docker_init.bash

@@ -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,22 +181,39 @@ 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"
   # Guard for read-only root filesystem (podman with read_only=true, issue #1470).
-  # The script runs as hermeswebuitoo (non-root), but groupmod/usermod use sudo.
-  # So we must check writability via sudo — a non-root user cannot write /etc/group
-  # even on a normal writable rootfs, which caused a false positive (issue #1658).
   _readonly_root=false
-  if ! sudo sh -c 'test -w /etc/group && test -w /etc/passwd' 2>/dev/null; then
+  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 (even via sudo)"
+    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 "")
@@ -206,20 +224,77 @@ if [ "A${whoami}" == "Ahermeswebuitoo" ]; then
       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
-    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"
+    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
-  sudo chown -R ${WANTED_UID}:${WANTED_GID} /home/hermeswebui || error_exit "Failed to set owner of /home/hermeswebui"
-  save_env /tmp/hermeswebuitoo_env.txt  
+
+  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
 
@@ -228,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"
 
@@ -247,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
@@ -258,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 "==================="
@@ -285,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
@@ -338,7 +415,49 @@ else
     fi
   done
   if [ -n "$_agent_src" ]; then
-    uv pip install "$_agent_src[all]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
+    if [ -w "$_agent_src" ]; then
+      echo ""
+      echo "!! WARNING: hermes-agent source mount is writable from the WebUI container."
+      echo "!!   Path: $_agent_src"
+      echo "!! The multi-container compose defaults use a read-only mount for defence-in-depth."
+      echo "!! If this is not an intentional local development checkout, switch the WebUI"
+      echo "!! agent source volume/bind mount to read-only. See docs/rfcs/agent-source-boundary.md."
+      echo ""
+    fi
+    # The agent source can be mounted read-only (see docker-compose.two-container.yml
+    # / docker-compose.three-container.yml — the WebUI only reads this volume to
+    # install the agent's Python dependencies and never writes to it). setuptools'
+    # `egg_info` build step, however, touches `hermes_agent.egg-info/` inside the
+    # source tree even under PEP 517 build isolation, which `EROFS`-fails on a
+    # `:ro` mount and (under `set -e`) kills startup of every multi-container
+    # deploy. Stage the source into a writable tmpfs copy so the build can write
+    # its metadata side-by-side without touching the underlying mount.
+    #
+    # The copy excludes any pre-baked `*.egg-info` / `build` / `dist` artifacts
+    # to avoid the timestamp-update path setuptools takes when one is present,
+    # and `--reflink=auto` makes the copy near-free on overlay2/btrfs where
+    # supported. We rebuild on every container start (the agent source can
+    # change across volume re-init); cost is one rsync of ~10MB of Python source.
+    _stage_src="/tmp/hermes-agent-build"
+    rm -rf "$_stage_src"
+    mkdir -p "$_stage_src"
+    if command -v rsync >/dev/null 2>&1; then
+      rsync -a \
+        --exclude='*.egg-info' --exclude='build' --exclude='dist' \
+        --exclude='__pycache__' --exclude='.git' \
+        "$_agent_src"/ "$_stage_src"/ \
+        || error_exit "Failed to stage hermes-agent source to writable build dir"
+    else
+      # Fallback when rsync isn't in the image — straight cp -a, then drop
+      # the build artifacts that would trip setuptools.
+      cp -a "$_agent_src"/. "$_stage_src"/ \
+        || error_exit "Failed to copy hermes-agent source to writable build dir"
+      rm -rf "$_stage_src"/*.egg-info "$_stage_src"/build "$_stage_src"/dist 2>/dev/null || true
+      find "$_stage_src" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+    fi
+    uv pip install "$_stage_src[all]" --trusted-host pypi.org --trusted-host files.pythonhosted.org \
+      || error_exit "Failed to install hermes-agent's requirements"
+    rm -rf "$_stage_src"
   else
     echo ""
     echo "!! WARNING: hermes-agent source not found."

docs/CONTRACTS.md

@@ -0,0 +1,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/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

@@ -11,8 +11,34 @@ This is the comprehensive Docker reference. For a 5-minute quickstart, see the [
 | **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
@@ -24,10 +50,235 @@ docker compose up -d
 open http://localhost:8787
 ```
 
-That's it. Your existing `~/.hermes` directory is mounted, your `~/workspace` is browsable, and the WebUI auto-detects your UID/GID from the mounted volume.
+That's it for a real personal Docker install. Your existing `~/.hermes`
+directory is mounted, your `~/workspace` is browsable, and the WebUI
+auto-detects your UID/GID from the mounted volume.
+
+The single-container setup runs the WebUI only. It can create cron jobs and run
+them manually from the Tasks panel. In Docker, scheduled jobs require the Hermes gateway daemon
+to tick while you are away. If System Settings shows `Gateway not configured`,
+use `docker-compose.two-container.yml`,
+`docker-compose.three-container.yml`, or run `hermes gateway` separately before
+relying on offline scheduled runs. 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:
@@ -123,6 +374,27 @@ If you must use a bind mount: pick a host path, then mount it to `/opt/hermes` i
 
 **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.
@@ -148,7 +420,52 @@ The two- and three-container setups use **named Docker volumes** (not bind mount
       └─────────────────────────┘
 ```
 
-The WebUI container doesn't ship with the agent's Python deps — at startup it runs `uv pip install /home/hermeswebui/.hermes/hermes-agent` to install them from the shared volume.
+The WebUI container doesn't ship with the agent's Python deps — at startup it runs `uv pip install /home/hermeswebui/.hermes/hermes-agent` to install them from the shared volume. The WebUI mount is read-only; the agent container is the only writer.
+
+## Upgrading the agent container
+
+The `hermes-agent-src` named volume is initialised from the agent image's `/opt/hermes` on first `up`. Docker reuses the volume verbatim on every subsequent `up` — **even after `docker pull` of a newer agent image**. The cached volume content masks the new image's source tree, so a fresh `docker pull` of `nousresearch/hermes-agent:latest` does not by itself give you the new agent code, dependencies, or entrypoint.
+
+This is the root cause of [#1416](https://github.com/nesquena/hermes-webui/issues/1416): the symptom looked like a missing entrypoint, but the entrypoint was actually present in the new image and hidden behind the stale named volume.
+
+To upgrade the agent image cleanly, drop the source volume before recreating:
+
+```bash
+# Two-container setup
+docker compose -f docker-compose.two-container.yml down
+docker volume rm <project>_hermes-agent-src
+docker compose -f docker-compose.two-container.yml pull
+docker compose -f docker-compose.two-container.yml up -d
+
+# Three-container setup
+docker compose -f docker-compose.three-container.yml down
+docker volume rm <project>_hermes-agent-src
+docker compose -f docker-compose.three-container.yml pull
+docker compose -f docker-compose.three-container.yml up -d
+```
+
+Replace `<project>` with your Compose project name (the parent directory by default; check with `docker volume ls`). The `hermes-home` volume (config, sessions, state) is left untouched — only `hermes-agent-src` (the agent's installed Python source) is recreated.
+
+> The single-container setup (`docker-compose.yml`) does not use `hermes-agent-src` and is not affected by this upgrade pattern — pulling a newer WebUI image and `docker compose up -d --force-recreate` is sufficient.
+
+## What the multi-container setup isolates (and what it doesn't)
+
+The two- and three-container setups give you **process, network, and resource isolation** between the gateway and the chat UI:
+
+- Each service has its own PID namespace and lifecycle — the agent process can crash without taking down the chat UI and vice versa.
+- The gateway API (port 8642) is bound by the agent service only; the WebUI cannot bind it. Other containers reach the gateway via the `hermes-net` Docker network.
+- Resource limits (`deploy.resources.limits` in `docker-compose.three-container.yml`) apply per service, so you can cap the agent independently of the dashboard.
+- Restart policies, log streams, and container health checks are scoped per service.
+
+What multi-container does **not** isolate:
+
+- **Filesystem boundary.** Both services share `hermes-home` (config, sessions, state), and the WebUI mounts the agent's installed source from `hermes-agent-src`. The WebUI mount is read-only (since v0.51.84), but the agent service still has write access, and both services share the home volume.
+- **UID/GID boundary.** Both services default to `${UID:-1000}` so files written by one are readable by the other. If you align them to different UIDs you'll get permission errors on the shared volume.
+- **Trust boundary on the agent source.** The WebUI installs Python dependencies from the shared `hermes-agent-src` volume at startup. The read-only mount means a compromised WebUI cannot rewrite the agent source, but it does run code from that volume.
+
+If you need **filesystem isolation** between the chat UI and the agent (e.g. you don't trust the WebUI to read agent state), the multi-container setup is not enough — run the agent on a separate host and connect the WebUI to it via the gateway HTTP API. If you don't need any boundary, the single-container setup is simpler.
+
+The direct source mount is a compatibility bridge, not the long-term API contract. The current source/API boundary inventory and decoupling task list live in [`docs/rfcs/agent-source-boundary.md`](rfcs/agent-source-boundary.md) for [#2453](https://github.com/nesquena/hermes-webui/issues/2453). If you customize the compose files with bind mounts, keep the WebUI-side agent source mount read-only unless you are intentionally doing local development; `docker_init.bash` warns at startup when that path is writable.
 
 ## Bind-mount migration (advanced)
 
@@ -174,7 +491,8 @@ volumes:
 
 1. The host directory MUST be readable by your container UID. Run `id -u` on the host and ensure `~/.hermes` is owned by that UID (or readable via group bits).
 2. ALL containers sharing the volume must run as the SAME UID/GID. Set `UID=$(id -u)` and `GID=$(id -g)` in `.env`.
-3. If your host `.env` is mode 0640, set `HERMES_SKIP_CHMOD=1` or `HERMES_HOME_MODE=0640` so the startup hook doesn't try to enforce 0600.
+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
 
@@ -187,8 +505,12 @@ volumes:
 
 ## Related issues
 
+- #1416 — agent-image upgrade requires removing `hermes-agent-src` named volume (see [Upgrading the agent container](#upgrading-the-agent-container))
 - #1389 — `HERMES_HOME_MODE` override (fixed in v0.50.254 — agent honors `HERMES_SKIP_CHMOD` and `HERMES_HOME_MODE`)
 - #1399 — UID alignment in compose files (fixed in v0.50.260 via PR #1428 + this guide)
+- #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

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.

docs/pr-media/1772/cli-tool-metadata-api-evidence.json

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

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

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