PR #20102: fix(gateway): reconcile orphaned session files on startup (#20098)

• Repository: NousResearch/hermes-agent
• Author: Bartok9
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/20102

Description (problem / solution / changelog)

Summary

Fixes #20098

Root Cause

On every gateway restart, a new session JSON file is created in sessions_dir (e.g. ~/.hermes/sessions/session_20260505_063027_d6ec06.json) but old ones are never removed. After N restarts, sessions_dir accumulates N stale session files while sessions.json only tracks the current session. The index desync means session context from old sessions can contaminate new ones — manifesting as invalid tool call id errors when the gateway serves a new Telegram session but mistakenly locates an old CLI session's tool call IDs.

Fix

Add SessionStore.reconcile_orphaned_json_files():

def reconcile_orphaned_json_files(self) -> int:
    """Remove session JSON/JSONL files not tracked in sessions.json."""
    known_ids = {entry.session_id for entry in self._entries.values()}
    # scan sessions_dir, delete *.json / *.jsonl not in known_ids
    # skips: sessions.json itself, dot-prefix temp files, directories, other extensions

Called automatically during start_gateway() startup, immediately after suspend_recently_active(), so sessions_dir is clean before any new platform connections are established.

Example (issue reporter's case)

Before fix — 8 files, only 1 tracked:

session_20260505_053804_914eb0.json   ← orphan (removed)
session_20260505_054636_3956ed.json   ← orphan (removed)
session_20260505_055014_52e486.json   ← orphan (removed)
session_20260505_055040_43da0617.json ← orphan (removed)
session_20260505_061146_1acbd7.json   ← orphan (removed)
session_20260505_062453_2804db.json   ← orphan (removed)
session_20260505_063027_d6ec06.json   ← orphan (removed)
session_20260505_063204_f24f96d5.json ← LIVE (kept)
sessions.json                         ← index (never touched)

After fix — sessions_dir cleaned up on next gateway start; sessions.json stays consistent.

Tests

9 new tests in tests/gateway/test_session_orphan_reconciliation.py:

• Orphaned .json removal
• Orphaned .jsonl removal
• No-op when all files are tracked
• Index (sessions.json) never deleted
• Dot-prefixed temp files never deleted
• Multi-orphan batch (7 orphans at once — reproduces the reporter's scenario exactly)
• Empty sessions_dir is safe
• Unknown-extension files skipped (request_dump_* etc.)
• Works when sessions.json does not exist yet (fresh install)

Changed files

• gateway/run.py (modified, +11/-0)
• gateway/session.py (modified, +68/-0)
• tests/gateway/test_session_orphan_reconciliation.py (added, +213/-0)

PR #20462: fix(gateway): clean up orphaned session transcript files

• Repository: NousResearch/hermes-agent
• Author: liuhao1024
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/20462

Description (problem / solution / changelog)

Summary

Delete legacy JSONL transcript files when sessions are reset or pruned, and clean up orphaned transcripts on gateway startup.

Root Cause

SessionStore.get_or_create_session() replaces old SessionEntry objects when a session is reset (via reset policy, suspend, or force_new), but never deleted the corresponding transcript file ({session_id}.jsonl). Over multiple gateway restarts, orphaned transcript files accumulated in ~/.hermes/sessions/ while sessions.json only tracked the latest session per channel.

The existing prune_old_entries() method had the same gap — it removed entries from the index but left transcript files on disk.

Fix

1. _delete_transcript(session_id) — safe helper that removes a JSONL file, ignoring missing files and permission errors
2. get_or_create_session() — deletes the old transcript when a session is reset or replaced via force_new
3. prune_old_entries() — deletes transcript files for pruned entries
4. cleanup_orphaned_transcripts() — new method that scans sessions_dir for *.jsonl files with no matching session entry
5. gateway/run.py — calls cleanup_orphaned_transcripts() on startup after stuck-loop detection

Regression Coverage

12 tests in test_session_transcript_cleanup.py:

• _delete_transcript: existing file, missing file, permission error
• get_or_create_session: old transcript deleted on reset, not deleted on reuse
• prune_old_entries: transcript files deleted for pruned entries, handles missing files
• cleanup_orphaned_transcripts: removes orphans, preserves active, ignores non-JSONL, handles empty dir, handles multiple orphans

Testing

tests/gateway/test_session_transcript_cleanup.py — 12 passed
tests/gateway/test_session_store_prune.py — 18 passed (no regressions)
tests/gateway/test_session.py — 63 passed (no regressions)
tests/gateway/test_session_hygiene.py — 18 passed (no regressions)
tests/gateway/test_session_state_cleanup.py — 11 passed (no regressions)

Fixes [Bug]: Gateway session store leaks orphaned JSON files and desyncs sessions.json index #20098

Changed files

• gateway/platforms/whatsapp.py (modified, +4/-1)
• gateway/run.py (modified, +8/-0)
• gateway/session.py (modified, +56/-0)
• tests/gateway/test_session_transcript_cleanup.py (added, +261/-0)
• tests/tools/test_file_tools.py (modified, +37/-0)
• tools/file_tools.py (modified, +6/-6)