feat(chat): keep-alive + reattach for dashboard terminal sessions (#50084 salvage)

[teknium1]

Summary

Dashboard chat sessions now survive browser refreshes, sleep/wake, and network drops: the /api/pty PTY can outlive its WebSocket and be reattached with full output replay, instead of the running agent being killed on every disconnect.

Salvages PR #50084 by @TinkerOfThings (rebase-merge, authorship preserved) onto current main, resolving the cluster behind #22027 / #50074 / #15915 / #53839.

Infographic

Root cause

pty_ws ties the PTY 1:1 to the WebSocket — spawn on connect, bridge.close() on disconnect. Any transport drop kills the running agent mid-reply; reconnect spawns a fresh PTY (the session-id breadcrumb resumes the conversation, but the in-flight turn and scrollback are lost).

Changes

• hermes_cli/pty_session.py (new): RingBuffer (1MB), PtySession (single drain task, attach/detach, EOF → WS close 4410), PtySessionRegistry (token-keyed reattach, 16-session cap, 30-min idle reap), run_reaper.
• hermes_cli/web_server.py: keep-alive path on /api/pty behind ?attach=<token>; no-token path factored into _legacy_pump byte-identical to today's behavior; reaper wired into the app lifespan.
• web/src/pages/ChatPage.tsx: persistent per-browser attach token (localStorage), sent on every connect; close-code contract 4410 = process exited (restart affordance), 4409 = superseded tab (quiet), anything else = transient → existing backoff reconnect now reattaches to the living PTY.
• Tests: tests/test_pty_session.py (10 unit), tests/test_pty_keepalive_ws.py (WS integration).

Follow-up fixes on top of the salvage (integrating with main's post-#50084 hardening):

• Registry spawn + bridge.close() go through asyncio.to_thread (event-loop stall protection, fix(dashboard): offload PTY spawn/close off the event loop #53227).
• Legacy pump keeps main's [Bug]: FD leak regression after PTY reconnect PRs (#52962 #53227) #54028 semantics verbatim (reader-EOF → server-side ws.close(), half-open-socket FD-leak protection) plus the RuntimeError guard on ws.receive().
• PtySession.detach ignores a superseded socket's late detach so a session with a live viewer can't be marked idle and reaped.
• Forced-fresh starts (?fresh=1) rotate the attach token so "Start new session" never reattaches the old PTY.

Validation

Check	Result
scripts/run_tests.sh tests/test_pty_session.py tests/test_pty_keepalive_ws.py	11/11 pass
scripts/run_tests.sh tests/hermes_cli/test_pty_bridge.py tests/hermes_cli/test_web_server.py	pass
web: tsc -b --force + npm run build	green
Live E2E (real uvicorn + real websockets client + real bash PTY child)	6/6 pass

Live E2E specifics: hard transport abort mid-session → PTY survives; reconnect with same token → ring buffer replays and the SAME shell process is reattached (env var set before the drop still present); child exit → close 4410; no-token legacy path → PTY killed on disconnect, unchanged.

Non-goals (as designed in #50084)

No cross-device handoff (token is per-browser localStorage), no multi-viewer (last-attach-wins via 4409), no persistence across a dashboard restart (in-process registry). The token never bypasses auth — all existing per-connect auth/host/origin gates run before any reattach.

Credit: @TinkerOfThings (design doc + implementation, PR #50084). Related earlier attempts: #34039 by @cpmidnite, #37682, #47297.

Fixes #50074. Closes #22027. Closes #15915. Addresses the web-dashboard half of #53839.