fix(ipad): incremental batched session-list rendering to preserve momentum scroll

.env.docker.example

@@ -47,6 +47,37 @@ GID=1000
 # the agent.
 # HERMES_WEBUI_PASSWORD=change-me-to-something-strong
 
+# ──────────────────────────────────────────────────────────────────────────
+# Additional security / networking / limit knobs — advanced
+# ──────────────────────────────────────────────────────────────────────────
+# The WebUI process reads more HERMES_WEBUI_* variables than the compose
+# files forward by default. To use any of these in Docker, uncomment it here
+# AND add a matching passthrough line under `environment:` in your compose
+# file (e.g. `- HERMES_WEBUI_SESSION_TTL=${HERMES_WEBUI_SESSION_TTL:-}`).
+# Full descriptions live in .env.example.
+#
+# Auth cookie lifetime in seconds (default 2592000 = 30 days):
+# HERMES_WEBUI_SESSION_TTL=2592000
+#
+# Force the Secure cookie flag when serving HTTPS via a reverse proxy:
+# HERMES_WEBUI_SECURE=1
+#
+# Allowed public origins (scheme required) when behind a reverse proxy:
+# HERMES_WEBUI_ALLOWED_ORIGINS=https://myapp.example.com
+#
+# Trust reverse-proxy forwarded headers (only enable behind a proxy YOU run):
+# HERMES_WEBUI_TRUST_FORWARDED_HOST=1
+# HERMES_WEBUI_TRUST_FORWARDED_FOR=1
+# HERMES_WEBUI_TRUST_FORWARDED_PROTO=1
+#
+# Enable the passkey/WebAuthn login surface (default off):
+# HERMES_WEBUI_PASSKEY=1
+#
+# Archive extraction cap (MB) and "download folder as ZIP" caps:
+# HERMES_WEBUI_MAX_EXTRACTED_MB=2048
+# HERMES_WEBUI_FOLDER_ZIP_MAX_MB=1024
+# HERMES_WEBUI_FOLDER_ZIP_MAX_FILES=50000
+
 # ──────────────────────────────────────────────────────────────────────────
 # Permission handling for bind-mounted .hermes — advanced
 # ──────────────────────────────────────────────────────────────────────────

.env.example

@@ -32,3 +32,120 @@
 
 # Display name for the assistant in the UI (default: Hermes)
 # HERMES_WEBUI_BOT_NAME=Hermes
+
+# ── Security & remote access ─────────────────────────────────────────────────
+
+# Password for the login page. REQUIRED if you bind to anything other than
+# 127.0.0.1 — without it, anyone who can reach the port can run commands.
+# HERMES_WEBUI_PASSWORD=change-me-to-something-strong
+
+# Enable the passkey/WebAuthn login surface (default: off).
+# Alternative: set `webui_passkey_enabled: true` in the profile's config.yaml.
+# HERMES_WEBUI_PASSKEY=1
+
+# Auth cookie lifetime in seconds (default: 2592000 = 30 days).
+# Clamped to [60, 31536000]. Also settable as session_ttl_seconds in settings.json.
+# HERMES_WEBUI_SESSION_TTL=2592000
+
+# Force the Secure flag on auth cookies: 1/true or 0/false.
+# Unset = auto-detect (direct TLS socket, or a trusted X-Forwarded-Proto).
+# HERMES_WEBUI_SECURE=1
+
+# Override the auth cookie name (default: derived internally).
+# HERMES_WEBUI_COOKIE_NAME=hermes_webui_session
+
+# Extra allowed origins for CSRF/origin checks when serving behind a reverse
+# proxy or on a public hostname. Comma-separated; each entry MUST include the
+# scheme. Entries without a scheme are ignored with a warning.
+# HERMES_WEBUI_ALLOWED_ORIGINS=https://myapp.example.com:8000
+
+# Serve HTTPS directly (both must be set; otherwise plain HTTP).
+# HERMES_WEBUI_TLS_CERT=/path/to/fullchain.pem
+# HERMES_WEBUI_TLS_KEY=/path/to/privkey.pem
+
+# Extra sources appended to the Content-Security-Policy (space-separated).
+# HERMES_WEBUI_CSP_CONNECT_EXTRA=https://api.example.com wss://api.example.com
+# HERMES_WEBUI_CSP_FRAME_EXTRA=https://embed.example.com
+
+# ── Reverse-proxy header trust (opt-in; only enable behind a proxy YOU run) ───
+# By default these forwarded headers are NOT trusted, because any direct client
+# could forge them. Enable (1/true/yes/on) only when a reverse proxy you control
+# sets them. TRUST_FORWARDED_HOST: honor X-Forwarded-Host/X-Real-Host in origin
+# checks. TRUST_FORWARDED_FOR: honor X-Forwarded-For for the client IP.
+# TRUST_FORWARDED_PROTO: honor X-Forwarded-Proto for HTTPS detection.
+# HERMES_WEBUI_TRUST_FORWARDED_HOST=1
+# HERMES_WEBUI_TRUST_FORWARDED_FOR=1
+# HERMES_WEBUI_TRUST_FORWARDED_PROTO=1
+
+# ── Trusted-header auth / reverse-proxy SSO (opt-in; OFF by default) ──────────
+# Delegate authentication to a reverse proxy you run (Authelia, oauth2-proxy,
+# corporate SSO, …) that authenticates the user and forwards their identity in a
+# header. When HERMES_WEBUI_TRUSTED_AUTH_HEADER is set, the WebUI treats a request
+# as that identity — but ONLY when the request's un-spoofable raw socket peer is
+# an allowlisted proxy (HERMES_WEBUI_TRUSTED_PROXY_CIDRS below). With no header
+# set, this path is disabled and normal password/passkey auth applies.
+#
+# ⚠️ SECURITY: HERMES_WEBUI_TRUSTED_PROXY_CIDRS MUST list the EXACT IP(s) of your
+# proxy — e.g. 10.0.0.5/32 or 127.0.0.1/32. NEVER use 0.0.0.0/0 or a broad range:
+# any client whose peer IP falls in the range could forge the identity header and
+# log in as anyone. If the allowlist is empty/malformed, the header is ignored
+# (fails closed). Loopback is trusted by default. Set the CIDR to your proxy only.
+# HERMES_WEBUI_TRUSTED_AUTH_HEADER=Remote-User
+# HERMES_WEBUI_TRUSTED_PROXY_CIDRS=10.0.0.5/32
+# Optional: map a forwarded groups header to WebUI profiles (JSON object), and a
+# logout URL to redirect to after clearing the local session (SSO single-logout).
+# HERMES_WEBUI_TRUSTED_GROUPS_HEADER=Remote-Groups
+# HERMES_WEBUI_GROUP_PROFILE_MAP={"admins":"default","team-a":"projecta"}
+# HERMES_WEBUI_TRUSTED_AUTH_LOGOUT_URL=https://sso.example.com/logout
+
+# ── Uploads & limits ─────────────────────────────────────────────────────────
+
+# Where chat attachments are stored (default: <state dir>/attachments).
+# Attachments are transient agent context, kept out of the workspace by default.
+# HERMES_WEBUI_ATTACHMENT_DIR=~/.hermes/webui/attachments
+
+# Cap on total bytes an uploaded archive may expand to (zip-bomb guard).
+# Default derives from the upload size limit; override in MB.
+# HERMES_WEBUI_MAX_EXTRACTED_MB=2048
+
+# Caps for the "download folder as ZIP" feature in the workspace browser.
+# HERMES_WEBUI_FOLDER_ZIP_MAX_MB=1024
+# HERMES_WEBUI_FOLDER_ZIP_MAX_FILES=50000
+
+# Requests slower than this many seconds get a stack-dump diagnostic in the log
+# (default: 5.0; set 0 to log every request's timing).
+# HERMES_WEBUI_SLOW_REQUEST_SECONDS=5.0
+
+# ── Onboarding ───────────────────────────────────────────────────────────────
+
+# Skip the first-run onboarding wizard entirely.
+# HERMES_WEBUI_SKIP_ONBOARDING=1
+
+# ── Advanced integrations ────────────────────────────────────────────────────
+
+# Script whose stdout prefills new-session context (legacy generic hook; the
+# WebUI dynamic-recall hook in config.yaml takes precedence when configured).
+# HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT=/path/to/script
+# HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT=5
+# HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS=12000
+
+# Extra sources for the notes drawer (see docs for the expected format).
+# HERMES_WEBUI_EXTERNAL_NOTES_SOURCES=
+
+# Directory scanned for WebUI plugins (default: ~/.hermes/plugins).
+# HERMES_WEBUI_PLUGINS_DIR=~/.hermes/plugins
+
+# API key used when polling the Hermes gateway health endpoint.
+# HERMES_WEBUI_GATEWAY_API_KEY=
+
+# Override the Claude Code projects directory scanned by the CLI session
+# bridge (default: auto-discovered ~/.claude/projects).
+# HERMES_WEBUI_CLAUDE_PROJECTS_DIR=~/.claude/projects
+
+# Override the Codex CLI home scanned by the CLI session bridge and model
+# catalog merge (default: ~/.codex).
+# CODEX_HOME=~/.codex
+
+# Path to the LLM wiki root shown in the wiki panel (default: resolved from
+# HERMES_HOME's wiki env file).
+# WIKI_PATH=/path/to/wiki

.github/workflows/browser-smoke.yml

@@ -8,6 +8,12 @@ name: Browser smoke
 #
 # No secrets, no credentials: the server boots agent-free and the smoke script
 # strips every *_API_KEY from the environment before launch.
+#
+# Docs-only fast path: `browser-smoke` is a REQUIRED status check in the master
+# ruleset, and a skipped required check reports as pending forever (auto-merge
+# would hang). So on a docs/CHANGELOG/README-only change we keep the job running
+# and reporting green but short-circuit the expensive browser install + smoke.
+# Detection FAILS SAFE: any uncertainty or any non-doc path -> full smoke runs.
 
 on:
   pull_request:
@@ -16,13 +22,85 @@ on:
     branches: [master]
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.detect.outputs.docs_only }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect docs-only change set
+        id: detect
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          # Fail-safe: ALWAYS exits 0 and ALWAYS emits docs_only (default 'false' =
+          # run full smoke), so a detection hiccup can never wedge the required
+          # browser-smoke context into perpetual pending.
+          docs_only="false"
+          emit() { echo "docs_only=$docs_only" >> "$GITHUB_OUTPUT"; }
+          trap emit EXIT
+          set -uo pipefail
+          # STRICT ALLOWLIST — docs iff doc extension (*.md/.markdown/.rst) or an
+          # extensionless doc basename. NOT docs: *.txt (requirements.txt!), anything
+          # under docs/ that isn't a doc extension, and code files merely NAMED
+          # README/CHANGELOG. See tests.yml for the full rationale.
+          is_docs() {
+            f="$1"; low="$(printf '%s' "$f" | tr '[:upper:]' '[:lower:]')"; base="${f##*/}"
+            case "$low" in
+              *.md|*.markdown|*.rst) return 0 ;;
+            esac
+            case "$base" in
+              LICENSE|README|CHANGELOG|NOTICE|AUTHORS|CONTRIBUTING) return 0 ;;
+            esac
+            return 1
+          }
+          if [ -n "${BASE_SHA:-}" ] && [ -n "${HEAD_SHA:-}" ]; then
+            git fetch --no-tags --depth=1 origin "$BASE_SHA" 2>/dev/null || git fetch --no-tags origin master || true
+            RANGE="$BASE_SHA...$HEAD_SHA"
+          else
+            RANGE="${{ github.event.before }}...${{ github.sha }}"
+          fi
+          # --no-renames so a rename reveals BOTH sides (a renamed-away code file is visible).
+          if ! FILES="$(git diff --name-only --no-renames "$RANGE" 2>/dev/null)"; then
+            echo "Could not diff $RANGE — running full smoke (fail-safe)."; exit 0
+          fi
+          if [ -z "$FILES" ]; then
+            echo "Empty diff — running full smoke (fail-safe)."; exit 0
+          fi
+          echo "Changed files:"; echo "$FILES"
+          result="true"
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            if ! is_docs "$f"; then
+              echo "Non-docs path -> full smoke required: $f"
+              result="false"
+              break
+            fi
+          done <<< "$FILES"
+          docs_only="$result"
+          echo "docs_only=$docs_only"
+
   browser-smoke:
+    needs: changes
+    # Belt-and-suspenders (see tests.yml): run even if `changes` errored/was skipped
+    # so this required context can never wedge; step guards degrade to full smoke.
+    if: ${{ always() }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
+      - name: Docs-only short-circuit
+        if: needs.changes.outputs.docs_only == 'true'
+        run: echo "Docs-only change set — skipping browser smoke (no page-executable change)."
+
       - uses: actions/checkout@v4
+        if: needs.changes.outputs.docs_only != 'true'
 
       - name: Set up Python
+        if: needs.changes.outputs.docs_only != 'true'
         uses: actions/setup-python@v5
         with:
           python-version: '3.12'
@@ -32,11 +110,13 @@ jobs:
             **/pyproject.toml
 
       - name: Install dependencies
+        if: needs.changes.outputs.docs_only != 'true'
         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
+        if: needs.changes.outputs.docs_only != 'true'
         run: python tests/browser_smoke.py

.github/workflows/conversation-lifecycle.yml

@@ -0,0 +1,69 @@
+name: Conversation lifecycle (informational)
+
+# Scoped to the code this browser gate actually exercises — the chat
+# render/streaming surface — so it doesn't spin up playwright+chromium on
+# docs-only or unrelated changes. If none of these paths change, the run is
+# skipped entirely (GitHub treats a path-filtered no-match as "not triggered").
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - 'static/**'
+      - 'api/**.py'
+      - 'server.py'
+      - 'tests/browser_conversation_lifecycle.py'
+      - 'requirements*.txt'
+      - 'pyproject.toml'
+      - '.github/workflows/conversation-lifecycle.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'static/**'
+      - 'api/**.py'
+      - 'server.py'
+      - 'tests/browser_conversation_lifecycle.py'
+      - 'requirements*.txt'
+      - 'pyproject.toml'
+      - '.github/workflows/conversation-lifecycle.yml'
+
+jobs:
+  live-to-final:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        scenario: [normal, terminal-error]
+    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
+            .github/workflows/conversation-lifecycle.yml
+
+      - name: Install browser gate dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt playwright
+          python -m playwright install --with-deps chromium
+
+      - name: Run conversation lifecycle gate
+        env:
+          LIFECYCLE_ARTIFACT_DIR: lifecycle-artifacts
+          LIFECYCLE_SCENARIO: ${{ matrix.scenario }}
+        run: python tests/browser_conversation_lifecycle.py
+
+      - name: Upload failure artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: conversation-lifecycle-failure-${{ matrix.scenario }}
+          path: lifecycle-artifacts
+          if-no-files-found: ignore