@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/docs/rfcs/turn-journal.md

@@ -0,0 +1,195 @@
+# RFC: WebUI Turn Journal for Crash-Safe Chat Submissions
+
+- **Status:** Proposed
+- **Author:** @ai-ag2026
+- **Created:** 2026-05-11
+
+## Problem
+
+A WebUI chat turn crosses several durability boundaries:
+
+1. browser submits a user message,
+2. WebUI creates or updates session runtime metadata,
+3. the agent worker starts streaming,
+4. assistant output is appended,
+5. the JSON sidecar and derived index are saved.
+
+If the server crashes between submission and the final sidecar save, recovery has to infer what happened from `pending_user_message`, `active_stream_id`, `.json.bak`, `_index.json`, and `state.db`. Those safeguards are useful, but they are still reconstructing intent after the fact.
+
+The missing primitive is a small write-ahead journal for turns: record the submitted user turn durably before the worker starts, then advance the journal as the turn progresses.
+
+## Goals
+
+- Preserve the exact user-submitted turn, including attachments metadata, before any provider or worker work starts.
+- Make crash recovery deterministic: a submitted-but-unfinished turn can be reported or reconstructed without guessing.
+- Keep the journal append/update format simple enough for startup recovery, CLI audit, and future API repair endpoints.
+- Avoid turning recovery into a background daemon. This is storage hygiene, not a long-running service.
+
+## Non-goals
+
+- Replacing `state.db.sessions` or WebUI JSON sidecars.
+- Journaling every token or every SSE event.
+- Replaying tool calls or provider streams.
+- Automatically inventing assistant messages after ambiguous crashes.
+
+## Proposed storage
+
+Use one JSONL file per session under the existing WebUI state area:
+
+```text
+<SESSION_DIR>/_turn_journal/<session_id>.jsonl
+```
+
+Each line is an immutable event. Recovery can scan by `turn_id` and choose the latest status.
+
+### Event shape
+
+```json
+{
+  "version": 1,
+  "event": "submitted",
+  "turn_id": "20260511T001122Z-abcdef",
+  "session_id": "abc123",
+  "stream_id": "stream-xyz",
+  "created_at": 1778458282.123,
+  "role": "user",
+  "content": "...",
+  "attachments": [],
+  "workspace": "/workspace",
+  "model": "openai/gpt-5",
+  "model_provider": "openai"
+}
+```
+
+Later events for the same `turn_id`:
+
+```json
+{"version":1,"event":"worker_started","turn_id":"...","created_at":1778458283.0}
+{"version":1,"event":"assistant_started","turn_id":"...","created_at":1778458284.0}
+{"version":1,"event":"completed","turn_id":"...","created_at":1778458299.0,"assistant_message_index":12}
+{"version":1,"event":"interrupted","turn_id":"...","created_at":1778458301.0,"reason":"server_startup_recovery"}
+```
+
+## Turn state machine
+
+```text
+submitted -> worker_started -> assistant_started -> completed
+submitted -> interrupted
+worker_started -> interrupted
+assistant_started -> interrupted
+```
+
+`completed` is terminal. `interrupted` is terminal unless a later explicit repair creates a new turn. Recovery should not silently resume a provider call.
+
+## Write rules
+
+1. On `/api/chat/start` or equivalent turn-submission path:
+   - generate `turn_id`,
+   - append `submitted`,
+   - fsync the journal file,
+   - only then start the worker.
+2. When worker thread enters `_run_agent_streaming`, append `worker_started`.
+3. When assistant output is first persisted or clearly begins, append `assistant_started`.
+4. After the sidecar save that includes the assistant answer succeeds, append `completed`.
+5. On cancellation or known worker exception, append `interrupted` with a reason.
+
+## Synchronous durability design rationale
+
+The `submitted` event uses synchronous `fsync` on every write today. This is a deliberate tradeoff between latency and crash-safety guarantees:
+
+### Why synchronous for submitted events
+
+The `submitted` event is the durability anchor for the entire recovery story. If the server crashes before the worker starts, the journal must reflect that the user message was received. Async writes risk losing that guarantee: a crash shortly after a non-fsync'd write could leave the journal silent while `pending_user_message` still exists, creating ambiguity during recovery. The current design avoids that ambiguity at the cost of one extra disk round-trip per turn submission.
+
+### Latency expectations by storage type
+
+Reported fsync latency varies significantly across storage backends. Approximate qualitative ranges to keep in mind:
+
+- **SSD (NVM/NVMe)**: Single-digit milliseconds; p99 typically well under 10 ms on modern hardware. Most turn submissions will see sub-5 ms overhead.
+- **Rotational disk (HDD)**: Seek time dominates; p50 ~5–15 ms, p99 can reach 50–100 ms under load. A busy server with many concurrent submissions may see queueing effects.
+- **Docker/overlay filesystems**: fsync latency depends on the container storage driver and the backing host filesystem. Write-through and copy-on-write semantics can introduce additional overhead; p95 may be 10–50 ms in typical containerized deployments, though exact figures vary by configuration and host load.
+
+These ranges are order-of-magnitude guidance, not benchmarks. Exact figures depend on hardware, kernel version, filesystem mount options, and concurrent load. Do not commit specific millisecond claims to documentation without measured evidence.
+
+### Benchmark guidance for maintainers
+
+If evidence suggests the synchronous write is a bottleneck, measure before changing anything:
+
+1. Instrument the `append_turn_journal_event` helper to record wall-clock time for each event type (submitted, worker_started, etc.).
+2. Capture p50/p95/p99 append/fsync latency over a representative workload (e.g., at least 1,000 submitted turns under realistic concurrency).
+3. Isolate the fsync component: on Linux, use `strace -e fsync` or kernel tracing (`ftrace`, `perf`) to confirm where time is spent.
+4. Check for patterns: if most submissions are under 5 ms but the p99 is 200 ms due to occasional disk contention, async writes help the tail but not the median. The tradeoff must be evaluated in context of your recovery guarantees.
+
+### Future follow-up: async lifecycle-event journaling
+
+Making journal writes asynchronous is a valid future optimization, but it requires:
+
+- A reliable flush strategy (e.g., time-bounded flush every N seconds, flush on session close, flush after K pending events).
+- Recovery logic that handles partial flush windows: if a crash occurs before the flush, the last few submitted events may be missing from the journal. Recovery must account for that ambiguity.
+- Tests that verify the flush correctness under crash injection.
+
+Async journal writes are **not** part of the initial implementation. They belong in a follow-up RFC once the synchronous baseline is proven stable and the recovery semantics are well-understood.
+
+## Startup recovery semantics
+
+On startup, for each journal file:
+
+- Latest event is `completed`: no action.
+- Latest event is `submitted` or `worker_started` and no matching user message exists in sidecar:
+  - append/recover the user message into the session sidecar with a recovery marker.
+- Latest event is `submitted`, `worker_started`, or `assistant_started` and no completed assistant turn exists:
+  - add a visible interruption marker, not a fake assistant answer.
+- Existing `.json.bak` and `state.db` recovery still run first so the sidecar is as complete as possible before journal reconciliation.
+
+## Audit additions
+
+`audit_session_recovery()` can report:
+
+- `turn_journal_pending_turn` — repairable if the user message is absent from sidecar.
+- `turn_journal_interrupted_turn` — ok/warn depending on whether a visible marker exists.
+- `turn_journal_malformed_event` — manual review.
+
+Safe repair should only materialize submitted user messages and interruption markers when the journal event content is valid JSON and the target message is absent.
+
+## API surface
+
+Initial read-only endpoint can be folded into the existing recovery audit:
+
+```text
+GET /api/session/recovery/audit
+```
+
+Later, if needed:
+
+```text
+GET /api/session/turn-journal?session_id=<id>
+```
+
+The latter should be diagnostic-only and redact or omit large attachment payloads.
+
+## Rollout plan
+
+1. Land backup/sidecar recovery and audit primitives.
+2. Add this journal writer in the turn-submission path behind no config flag; it is local-only and append-only.
+3. Add read-only audit reporting for pending journal turns.
+4. Add safe repair for missing user messages and interruption markers.
+5. Once stable, consider pruning completed journal entries older than a retention window, but only after sidecar/index recovery has no findings.
+
+## Open questions
+
+- Exact place to define `turn_id` so browser retry and server retry do not duplicate the same user message.
+- Whether attachment files need their own durable manifest entry or whether metadata-only is enough for v1.
+- How much of the assistant partial output, if any, should be recoverable after `assistant_started` but before `completed`.
+- Whether completed journal entries should be compacted into a per-session checkpoint file.
+
+## Minimal implementation slice
+
+The first implementation PR should be deliberately small:
+
+- helper: `append_turn_journal_event(session_id, event)`
+- helper: `read_turn_journal(session_id)`
+- unit tests for atomic append, malformed-line tolerance, and state derivation
+- one call site: append `submitted` before worker start
+- audit-only report of pending journal turns
+
+Do **not** combine the first implementation with replay/repair. Replay is where most of the bugs in WAL systems live; ship the writer and audit first, prove the format, then add repair.

package/vendor/agent-frontend-shell/docs/rfcs/webui-run-state-consistency-contract.md

@@ -0,0 +1,157 @@
+# WebUI Run State Consistency Contract
+
+- **Status:** Proposed
+- **Author:** @franksong2702
+- **Created:** 2026-05-16
+- **Tracking issue:** [#2361](https://github.com/nesquena/hermes-webui/issues/2361)
+- **Related architecture:** [#1925](https://github.com/nesquena/hermes-webui/issues/1925), [`hermes-run-adapter-contract.md`](hermes-run-adapter-contract.md)
+
+## Problem
+
+A single WebUI agent turn is represented by several overlapping state layers:
+
+- the visible transcript the user can read,
+- the model context / `context_messages` the agent actually receives,
+- `pending_user_message` and active stream metadata,
+- live SSE events and in-memory stream state,
+- durable run journal / replay state,
+- automatic compression summaries and active-task handoff text,
+- the browser's live timeline DOM/cache,
+- sidebar ordering, unread state, and `updated_at` metadata.
+
+Those layers are not independent. When they drift apart, the user sees failures
+that look unrelated: a prompt is visible but missing from recovered model
+context, a live run loses or reorders thinking/tool cards after switching
+sessions, cleanup makes old sessions look newly active, replay duplicates content,
+or automatic compression reference material appears inside the active turn.
+
+This RFC defines a consistency contract for those layers. It complements the
+larger run adapter direction in #1925 by documenting what must remain coherent
+while WebUI still has multiple overlapping state stores.
+
+## Goals
+
+- Define the state layers involved in active and recovered WebUI turns.
+- Make the source-of-truth expectations explicit for each layer.
+- Give reviewers a checklist for streaming, replay, compression, recovery,
+  model-context, and sidebar changes.
+- Map recent real issues to reusable invariants so future fixes do not solve the
+  same class of bug one symptom at a time.
+
+## Non-goals
+
+- Do not implement a runner process, sidecar, or new runtime boundary here.
+- Do not replace #1925 or the run adapter contract.
+- Do not rewrite the streaming protocol in this RFC.
+- Do not reopen already-fixed narrow bugs.
+- Do not make this a catch-all for unrelated UI polish.
+
+## State Layers
+
+| Layer | Purpose | Source-of-truth expectation | Must not do |
+|---|---|---|---|
+| Visible transcript | Shows what the user and assistant said | Session transcript plus live replay should produce one chronological user-visible story | Hide the user turn that started active work, or show internal recovery text as current user intent |
+| Model context / `context_messages` | Supplies conversation state to the agent | Must include the current visible user turn unless deliberately excluded with a user-visible reason | Let the agent resume from context that contradicts what the user can see |
+| Pending turn metadata | Bridges submitted-but-not-yet-finalized user input | Must identify the user turn and stream that own active work | Become a permanent duplicate transcript row after recovery |
+| Live stream / SSE | Delivers active runtime events to the browser | Must remain an observation path, not the only durable truth for already-emitted events | Lose the visible scene on refresh, reconnect, or session switch |
+| Run journal / replay | Rebuilds emitted runtime events after reconnect or restart | Must be cursor-safe and idempotent | Duplicate assistant text, thinking text, tool cards, or compression cards |
+| Compression summary / handoff | Gives the agent recovery context after automatic compression | Must remain agent-facing recovery material unless explicitly rendered as history | Pollute the active turn or become implicit current user intent |
+| Live UI scene/cache | Preserves expanded rows, in-progress cards, local scroll, and transient grouping | May optimize presentation but must be rebuildable or degradable from transcript/replay | Become the only place where chronological ordering exists |
+| Sidebar/session metadata | Helps the user find active and recent sessions | Must reflect meaningful user or assistant activity | Treat background cleanup as a fresh user-facing update |
+
+## Core Invariants
+
+1. **Visible current turns enter model context.** If the user can see a current
+   prompt and WebUI asks the model to continue that work, the prompt must be in
+   the reconstructed model context unless WebUI shows an explicit reason it was
+   excluded.
+2. **Active turn UI keeps its owner.** The user turn that started active work
+   must remain visible before assistant text, thinking cards, tool cards, or
+   activity groups that belong to that work.
+3. **Reattach preserves order or degrades clearly.** Refresh, reconnect, and
+   session switch must preserve chronological live-scene order. If WebUI cannot
+   restore the exact live scene, it should downgrade to an explicit structured
+   replay state instead of silently reordering content.
+4. **Maintenance is not activity.** Runtime maintenance such as stale-stream
+   cleanup, orphan repair, or background compression must not refresh sidebar
+   ordering, unread markers, or active-session affordances as if the user or
+   assistant just acted.
+5. **Replay is idempotent.** Replaying a run from a cursor must not duplicate
+   transcript rows, thinking content, interim assistant text, tool cards, or
+   compression cards. Replayed long-task events should enter the same
+   browser-facing timeline renderer as live SSE events so recovery does not
+   downgrade a structured Thinking / progress / tool / compression turn into a
+   separate flattened presentation.
+   Visible interim assistant progress must remain visible timeline content; a
+   compact Activity disclosure may summarize adjacent tool/debug detail, but it
+   must not be the only place where the user can see emitted progress text.
+6. **Compression is not current intent.** Automatic compression summaries and
+   reference cards are recovery/handoff material. They must not be treated as a
+   new user request, active-turn content, or the default visible explanation for
+   the current answer.
+7. **Observation has a degraded path.** Long-running or many-session observation
+   should expose enough heartbeat/degraded status that the UI does not appear
+   silent and ordinary APIs do not stall behind active streams.
+8. **Every mutation names its layer.** A PR touching streaming, recovery,
+   context reconstruction, compression, replay, or sidebar metadata should state
+   which layer it changes and what regression proves the invariant still holds.
+
+## Review Checklist
+
+Use this checklist for PRs that touch run state, streaming, replay, compression,
+context reconstruction, or session metadata:
+
+- Which state layers does this PR read or write?
+- Which layer is the source of truth after this change?
+- Can the visible transcript and model context diverge? If yes, is that
+  deliberate and user-visible?
+- What happens after browser refresh, session switch, SSE reconnect, and WebUI
+  restart?
+- Does replay rebuild the same scene without duplicates?
+- Does replay use the same timeline-rendering path as live SSE for thinking,
+  interim assistant text, tool cards, compression cards, and terminal states?
+- Can this change move a session in the sidebar without meaningful user or
+  assistant activity?
+- Can automatic compression or recovery text become visible active-turn content?
+- What test or manual evidence proves the invariant?
+
+## Existing Issue Map
+
+| Example | State boundary exposed | Relevant invariant |
+|---|---|---|
+| [#2341](https://github.com/nesquena/hermes-webui/issues/2341) / [#2342](https://github.com/nesquena/hermes-webui/pull/2342) | Active reattach could show agent activity without the pending user turn that started it | 2 |
+| [#2344](https://github.com/nesquena/hermes-webui/issues/2344) / [#2347](https://github.com/nesquena/hermes-webui/pull/2347) | Session switching could lose or reorder the live thinking/tool/interim timeline | 3, 5 |
+| [#2345](https://github.com/nesquena/hermes-webui/issues/2345) / [#2349](https://github.com/nesquena/hermes-webui/pull/2349) | Stale stream cleanup could mutate `updated_at` and resurface old sessions | 4 |
+| [#2346](https://github.com/nesquena/hermes-webui/issues/2346) / [#2348](https://github.com/nesquena/hermes-webui/pull/2348) | Thinking cards could repeat interim assistant progress text | 5 |
+| [#2353](https://github.com/nesquena/hermes-webui/issues/2353) / [#2354](https://github.com/nesquena/hermes-webui/pull/2354) | Recovered pending user turns could be visible but missing from model context | 1 |
+| [#2355](https://github.com/nesquena/hermes-webui/issues/2355) / [#2357](https://github.com/nesquena/hermes-webui/pull/2357) | Auto-compression rotation could leave reference-only cards in the active conversation tail | 3, 6 |
+| [#2308](https://github.com/nesquena/hermes-webui/issues/2308) / [#2309](https://github.com/nesquena/hermes-webui/pull/2309) | Compressed sessions could resume stale agent tasks when the user starts an ordinary fresh chat | 6 |
+| [#2283](https://github.com/nesquena/hermes-webui/pull/2283) | Run event journal replay provides the foundation for ordered recovery | 5 |
+
+These references are evidence for the contract. This RFC does not make the
+linked implementation PRs dependent on this document, and it does not close the
+tracking issue by itself.
+
+## Relationship To The Run Adapter RFC
+
+The run adapter RFC defines the longer-term event/control boundary for WebUI and
+Hermes runtime ownership. This RFC defines the consistency rules that the current
+WebUI and any future adapter-backed implementation must preserve.
+
+The two documents should be read together:
+
+- The adapter contract answers: "Where should execution ownership live?"
+- This consistency contract answers: "How do transcript, context, streams,
+  replay, compression, and UI metadata stay coherent while execution is active
+  or being recovered?"
+
+## Rollout Plan
+
+1. Land this RFC as a reviewable draft and refine it through PR discussion.
+2. Link future streaming/recovery/compression/sidebar PRs back to the invariant
+   they intentionally preserve or change.
+3. Convert recurring checklist items into focused regression tests where
+   practical.
+4. If #1925 introduces a new adapter-backed runtime layer, update this RFC or
+   replace it with the accepted implementation contract so these invariants do
+   not live only in historical discussion.

package/vendor/agent-frontend-shell/docs/supervisor.md

@@ -0,0 +1,280 @@
+# Running Hermes Web UI under a process supervisor
+
+Use a process supervisor (launchd, systemd, supervisord, runit, s6) when you
+want the Web UI to start at boot, restart on crash, or be managed alongside
+other services.
+
+## TL;DR
+
+Pass ``--foreground`` to ``bootstrap.py`` (or ``bash start.sh``):
+
+```bash
+bash start.sh --foreground
+```
+
+Or set ``HERMES_WEBUI_FOREGROUND=1`` in the environment. The Web UI will
+auto-detect launchd / systemd / supervisord even without the flag, but being
+explicit is safer.
+
+**Important (launchd on macOS):** if the ``com.parantoux.hermes-webui`` LaunchAgent is enabled, treat launchd as the single source of truth for WebUI lifecycle. Do **not** also run ``./ctl.sh start``, ``bash start.sh``, ``python bootstrap.py``, or ``python server.py`` against the same state dir/port, or you can create a second WebUI instance and trigger port-8787 restart churn.
+
+## Why ``--foreground`` matters
+
+Without it, ``bootstrap.py`` does this:
+
+1. Spawn ``server.py`` as a detached subprocess (``start_new_session=True``)
+2. Probe ``/health`` until the server is up
+3. Exit 0
+
+That works for an interactive shell run (``./start.sh`` returns to your
+prompt with the server alive in the background). It is **broken** under any
+process supervisor: the supervisor sees its tracked PID exit, marks the job
+as completed, and respawns ``bootstrap.py``. The respawn fails to bind port
+8787 (the orphaned server still has it), exits non-zero, supervisor
+respawns again — loop.
+
+In foreground mode, ``bootstrap.py`` does its setup work and then calls
+``os.execv`` to replace its own process with ``server.py``. The supervisor
+sees the long-lived server as the original child. ``KeepAlive=true`` /
+``Restart=always`` work correctly.
+
+## launchd (macOS)
+
+``~/Library/LaunchAgents/com.example.hermes-webui.plist``:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.example.hermes-webui</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/Users/yourname/hermes-webui/start.sh</string>
+        <string>--foreground</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>/Users/yourname/hermes-webui</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/yourname/.hermes/webui/launchd-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/Users/yourname/.hermes/webui/launchd-stderr.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>/Users/yourname</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>
+```
+
+Load:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.example.hermes-webui.plist
+launchctl print gui/$(id -u)/com.example.hermes-webui   # check state
+```
+
+Reload after editing the plist:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.example.hermes-webui.plist
+launchctl load   ~/Library/LaunchAgents/com.example.hermes-webui.plist
+```
+
+launchd sets ``XPC_SERVICE_NAME`` automatically, so even without the
+``--foreground`` argument the Web UI will auto-promote to foreground mode.
+The flag is still recommended as documentation of intent.
+
+## systemd (Linux)
+
+``~/.config/systemd/user/hermes-webui.service``:
+
+```ini
+[Unit]
+Description=Hermes Web UI
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/hermes-webui
+ExecStart=/bin/bash %h/hermes-webui/start.sh --foreground
+Restart=on-failure
+RestartSec=5
+
+# Optional: route stdout/stderr to journald instead of files
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+Enable + start:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now hermes-webui.service
+journalctl --user -u hermes-webui.service -f
+```
+
+systemd sets ``INVOCATION_ID`` and ``JOURNAL_STREAM`` (when stdio is wired to
+the journal), both of which auto-promote to foreground mode.
+
+## supervisord (cross-platform)
+
+``/etc/supervisor/conf.d/hermes-webui.conf``:
+
+```ini
+[program:hermes-webui]
+command=/bin/bash /home/youruser/hermes-webui/start.sh --foreground
+directory=/home/youruser/hermes-webui
+user=youruser
+autostart=true
+autorestart=true
+stopsignal=TERM
+stopwaitsecs=10
+stdout_logfile=/var/log/hermes-webui.out.log
+stderr_logfile=/var/log/hermes-webui.err.log
+environment=HOME="/home/youruser",PATH="/usr/local/bin:/usr/bin:/bin"
+```
+
+Reload + start:
+
+```bash
+sudo supervisorctl reread
+sudo supervisorctl update
+sudo supervisorctl status hermes-webui
+```
+
+supervisord sets ``SUPERVISOR_ENABLED``, which auto-promotes to foreground
+mode.
+
+## Auto-detected env vars (full list)
+
+These trigger ``--foreground`` behavior even when the flag is not passed:
+
+| Env var | Set by | Notes |
+|---|---|---|
+| ``INVOCATION_ID`` | systemd | Set on every service activation |
+| ``JOURNAL_STREAM`` | systemd | Set when stdio is wired to journald |
+| ``NOTIFY_SOCKET`` | systemd ``Type=notify`` / s6 | sd_notify-style notification socket |
+| ``XPC_SERVICE_NAME`` | launchd | Set to the plist Label — narrowed to ``com.<rdns>.<svc>`` form (see below) |
+| ``SUPERVISOR_ENABLED`` | supervisord | Always set under supervisord |
+| ``HERMES_WEBUI_FOREGROUND`` | you | Explicit opt-in; accepts ``1`` / ``true`` / ``yes`` / ``on`` |
+
+### XPC_SERVICE_NAME noise filter
+
+macOS launchd sets ``XPC_SERVICE_NAME`` in **every Terminal-spawned shell**,
+not just real services. Typical noise values:
+
+- ``0`` — set on launchd descendants generally
+- ``application.com.apple.Terminal.<UUID>`` — Terminal.app shells
+- ``application.com.googlecode.iterm2`` — iTerm2
+- ``application.com.microsoft.VSCode`` — VSCode integrated terminal
+
+A bare existence check on this var would auto-promote interactive
+``./start.sh`` runs to foreground mode on every Mac dev machine, breaking
+the most common installation path. We narrow detection to launchd
+**Label-style** names (typically reverse-DNS like ``com.example.foo``).
+Real launchd plists always use this form. If you ever see
+``XPC_SERVICE_NAME=0`` in your service environment, the auto-detect will
+ignore it — set ``HERMES_WEBUI_FOREGROUND=1`` or pass ``--foreground``
+explicitly to be safe.
+
+### Supervisors that are NOT auto-detected
+
+The following set no env var that we can reliably detect. Pass
+``--foreground`` (or ``HERMES_WEBUI_FOREGROUND=1``) explicitly:
+
+- **runit** (without sd_notify) — pure runit chains
+- **daemontools** / ``svc``
+- **PM2** (Node.js process manager occasionally repurposed for Python)
+- **Foreman** / **Honcho** (Procfile-style)
+- **Docker** with a custom CMD entrypoint that doesn't already use ``exec``
+- **Custom shell-script supervisors** that fork-and-wait
+
+If your supervisor isn't in the auto-detect list and you see the orphan-PID
+respawn loop, set ``HERMES_WEBUI_FOREGROUND=1`` in the service environment.
+
+## Diagnostic recipe
+
+If the Web UI keeps getting respawned and you suspect the double-fork loop:
+
+```bash
+# Check the running PID for the server
+lsof -iTCP:8787 -sTCP:LISTEN
+
+# Get its parent — should be the supervisor itself, NOT init (PID 1)
+PID=$(lsof -tiTCP:8787 -sTCP:LISTEN)
+ps -p "$PID" -o pid,ppid,cmd
+ps -p "$(ps -o ppid= -p "$PID" | tr -d ' ')" -o pid,cmd
+```
+
+A healthy foreground-mode setup looks like:
+
+```
+PID    PPID  CMD
+12345  6789  /path/to/python /path/to/server.py
+6789   1     /sbin/launchd        # or /usr/lib/systemd/systemd, etc.
+```
+
+If PPID is ``1`` (init) when it should be the supervisor, the orphan-server
+loop is happening — re-check that ``--foreground`` (or one of the env vars)
+is reaching the process.
+
+## HTTP watchdog / deep health
+
+``KeepAlive`` / ``Restart=always`` only recover a process that exits. If the
+process is still listening on the port but request handling is wedged, pair your
+supervisor with an HTTP probe and force a restart when the probe fails.
+
+Hermes Web UI exposes two health levels:
+
+- ``/health`` — cheap liveness probe with ``active_streams``, uptime, and an
+  ``accept_loop`` heartbeat counter.
+- ``/health?deep=1`` — readiness probe that briefly acquires the stream lock,
+  reads the sidebar/session path, reads projects state, and touches Hermes
+  ``state.db`` if it exists. Use this for watchdogs.
+
+At startup the server also tries to raise its file-descriptor soft limit to
+4096 on platforms that support ``RLIMIT_NOFILE``. That is defense in depth for
+persistent hosts: leaks should still be fixed, but a higher soft limit gives
+you more diagnostic headroom before request handling falls over.
+
+Minimal macOS launchd watchdog script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+LABEL="com.example.hermes-webui"
+BASE="http://127.0.0.1:8787"
+
+if ! curl -fsS --max-time 10 "$BASE/health?deep=1" >/dev/null; then
+  launchctl kickstart -k "gui/$(id -u)/$LABEL"
+fi
+```
+
+Run it every few minutes from a separate ``StartInterval`` LaunchAgent. For
+systemd, prefer a timer/service pair that runs the same curl probe and
+``systemctl --user restart hermes-webui.service`` on failure.
+
+The ``accept_loop.requests_total`` value should increase when probes arrive. If
+it stays flat while the process is still alive, the server accept loop is not
+making progress; capture logs/thread samples before restarting if you are
+collecting diagnostics for a bug report.