Sessions Diagnostic Tree

Decision tree: identify your session symptom → follow to the fix

Session issue disappears / stuck / won't rename / won't delete / all gone Session disappears from sidebar list after reload / missing Agent down Fix: start agent pnpm dev reload page Wrong URL Fix: Settings → Agent → Reconnect Stale cache Fix: hard refresh Cmd+Shift+R Ctrl+Shift+F5 Stuck on "Loading…" SSE stream not opening indefinite spinner Reload page SSE reconnect transient failures resolve on retry Proxy / VPN strips SSE use direct connection Won't rename rename has no effect silently fails Sessions API missing Fix: check startup probe "sessions" in core list? update agent if not Won't delete or reappears after delete generic error / 503 Kanban DB timestamp ISO string in created_at Fix: restart agent If persists: restore kanban.db.bak.* All sessions gone every session disappeared after agent restart sessions.db corrupted data may be lost Fix: restore backup ~/.hermes/sessions.db or accept fresh start Normal session lifecycle (no issues) UI loads page load Probe gateway GET /health + capabilities Fetch sessions GET /api/sessions Sidebar renders session list shown Click session SSE stream opens History loads messages from sessions.db Symptom colors Symptom node Fix / cause Known bug (kanban DB timestamp) Data loss risk

Session disappears

  • • Agent not running → start agent, reload page
  • • Wrong gateway URL → Settings → Agent → Reconnect
  • • Capability probe failed → check console for [gateway] log
  • • Stale cache → hard refresh (Cmd+Shift+R)

Delete fails / reappears

  • • Kanban DB ISO timestamp poisoning bug
  • • Direct DB write bypasses int coercion → 503 errors
  • • Fix: restart agent process
  • • Persists? Restore ~/.hermes/kanban.db.bak.*

All sessions gone

  • • sessions.db corrupted after agent crash
  • • Check ~/.hermes/ for .bak backup files
  • • Copy most recent backup → sessions.db → restart
  • • No backup: accept fresh start, data is lost

Hermes Switch UI • sessions diagnostic • identify symptom → find cause → apply fix