Summary

Ports the session artifact auto-pruning concept from qwibitai/nanoclaw#1632, adapted to hermes-agent's Python architecture.

Problem

hermes-agent accumulates disk artifacts that are never automatically cleaned up:

• Session transcript JSON files (session_*.json) — ~5,000 files, ~2 GB on a typical install
• API request debug dumps (request_dump_*.json) — ~180 files, ~32 MB
• Filesystem checkpoint shadow repos (~/.hermes/checkpoints/) — ~1,100 dirs, ~12 GB
• Gateway JSONL transcript files (*.jsonl)

The existing hermes sessions prune command only deletes DB rows, leaving all disk files behind forever.

What Changed

1. New tools/session_cleanup.py module — Core cleanup logic with safety guards:

   • Only deletes files older than configurable retention period (default: 30 days for sessions, 14 days for checkpoints)
   • Never deletes files belonging to active (non-ended) sessions
   • Never touches sessions.json state file
   • Dry-run mode for previewing what would be deleted

2. Enhanced hermes sessions prune — Three new flags:

   • --include-files: Also clean disk artifacts alongside DB pruning
   • --files-only: Only clean disk files, skip DB pruning
   • --dry-run: Preview what would be deleted without actually deleting

3. Enhanced hermes sessions stats — Now shows disk artifact counts and sizes, with a tip about cleanup

4. Automated daily cleanup in gateway — The existing _session_expiry_watcher now runs disk artifact cleanup once every 24 hours, reclaiming space automatically for long-running gateway deployments

5. 28 new tests covering all cleanup paths, safety guards, active session protection, and edge cases

Architectural Differences from NanoClaw

NanoClaw uses a bash script + Node.js timer. Our implementation is pure Python:

• prune_session_files() handles session transcripts and request dumps with active-session-ID protection
• prune_checkpoints() handles checkpoint shadow repos with age-based deletion
• prune_all_artifacts() orchestrates both
• Gateway integration runs in the existing _session_expiry_watcher async loop via run_in_executor

Test Plan

# Run the 28 new tests
python -m pytest tests/tools/test_session_cleanup.py -n0 -q

# Verify existing session tests still pass
python -m pytest tests/hermes_cli/test_sessions_delete.py -n0 -q

# Manual: hermes sessions stats (see disk artifact counts)
# Manual: hermes sessions prune --dry-run --include-files (preview)
# Manual: hermes sessions prune --include-files -y (actual cleanup)