docs(sessions): clarify sessions.json is the gateway routing index, not the session list (#51726)

Users who inspect ~/.hermes/sessions/sessions.json see only gateway entries
(e.g. agent:main:whatsapp:dm:...) and mistake it for the session index that
hermes sessions list / /sessions read — which is actually state.db. Issue
#49361 reported CLI sessions as 'invisible' on this premise.

- gateway/session.py: write a self-documenting _README sentinel at the top of
  sessions.json explaining it's the gateway routing index and that ALL sessions
  (CLI/TUI/gateway) live in state.db; skip _-prefixed keys on load so the
  sentinel never round-trips into a SessionEntry.
- Harden every sessions.json reader against the sentinel: mcp_serve loader,
  gateway/mirror.py, gateway/channel_directory.py all skip _-prefixed keys.
- docs/user-guide/sessions.md: warning callout naming the exact symptom.
- tests: assert prune ignores metadata sentinels; add round-trip coverage.
This commit is contained in:
Teknium
2026-06-23 23:56:36 -07:00
committed by GitHub
parent 7ff48a6291
commit 0ef86febe2
6 changed files with 101 additions and 4 deletions
+8 -1
View File
@@ -89,7 +89,14 @@ def _load_sessions_index() -> dict:
return {}
try:
with open(sessions_file, "r", encoding="utf-8") as f:
return json.load(f)
data = json.load(f)
# Drop documentation/metadata sentinels (keys starting with "_", e.g.
# the "_README" note the gateway writes into the index). They are not
# session entries and would break consumers that treat every value as
# an entry dict.
if isinstance(data, dict):
return {k: v for k, v in data.items() if not str(k).startswith("_")}
return {}
except Exception as e:
logger.debug("Failed to load sessions.json: %s", e)
return {}