feat(sessions): add configurable auto-cleanup for old agent sessions

[DeryFerd]

Problem

Evonic stores agent sessions indefinitely. For a long-running instance, this means the chat_sessions table and session JSONL files grow without bound. Over time, this can:

• Slow down queries that scan the sessions table
• Fill up disk space with old conversation logs
• Keep personal conversation data longer than necessary

Most sessions stop being useful after a few months. Someone who tried Evonic once in January probably isn't coming back to resume that session in July. But without auto-cleanup, those dead sessions sit there forever.

What Changed

This PR adds configurable automatic cleanup of old agent sessions:

1. New database methods (models/chat.py):

   • get_old_sessions(max_age_days) - queries sessions older than a threshold
   • delete_old_sessions(max_age_days, dry_run=False) - removes old sessions with optional dry-run mode for safety

2. Scheduled cleanup job (backend/scheduler.py):

   • Runs daily at 04:00 (low-traffic time)
   • Uses EVONIC_SESSION_MAX_AGE_DAYS from environment (default: 90 days)
   • Cleanup can be disabled by setting EVONIC_SESSION_MAX_AGE_DAYS=0
   • Logs deleted session count for audit trail

3. Configuration (.env.example):

   • Documents EVONIC_SESSION_MAX_AGE_DAYS with clear explanation
   • Explains the 0 = disabled behavior
   • Shows sensible default (90 days)

4. Test coverage (unit_tests/test_session_cleanup.py):

   • Covers old session detection by timestamp threshold
   • Covers actual deletion vs. dry-run mode
   • Covers scheduled job integration with APScheduler
   • All 5 tests passing with TDD approach (red → green → refactor)

The implementation is conservative:

• Dry-run mode lets admins preview what would be deleted
• Default threshold (90 days) is generous
• Admins can disable cleanup entirely
• The scheduled job only runs once per day, not continuously

Why 90 Days?

The default is a guess. It's long enough that most active users won't lose recent sessions, but short enough to prevent unbounded growth on a busy instance.

Admins can adjust this. If you run a personal instance with one user, you might want 365 days or even 0 (disabled). If you run a shared instance with hundreds of users, 30 days might make more sense.

How It Works

The cleanup job runs at 04:00 every day (configurable in scheduler.py if needed). It:

1. Reads EVONIC_SESSION_MAX_AGE_DAYS from environment
2. If set to 0, skips cleanup
3. Otherwise, calls delete_old_sessions(max_age_days)
4. Logs how many sessions were deleted

Sessions are considered "old" based on last_updated timestamp. If a session hasn't been touched in 90+ days (or whatever threshold is configured), it gets deleted. This removes both the database row and the JSONL file.

Backward Compatibility

• No breaking changes
• Cleanup is opt-in via environment variable (defaults to 90 days, but admins can set 0 to disable)
• Existing sessions are not touched until they exceed the age threshold
• If EVONIC_SESSION_MAX_AGE_DAYS is not set, defaults to 90 days (not 0)

Testing

All tests pass:

pytest unit_tests/test_session_cleanup.py -v

Tested scenarios:

• Creating sessions with different timestamps
• Querying only old sessions (doesn't accidentally grab recent ones)
• Dry-run mode (reports what would be deleted without actually deleting)
• Actual deletion (removes old sessions and leaves recent ones intact)
• Scheduler integration (cleanup job starts when scheduler starts)

The tests use an in-memory SQLite database and temporary JSONL files, so they don't affect real data.

Manual Testing

To test manually on a development instance:

1. Set EVONIC_SESSION_MAX_AGE_DAYS=30 in .env
2. Start Evonic
3. Check logs for [SESSION_CLEANUP] messages at 04:00
4. Or trigger immediately in Python console:

   from models.chat import cleanup_old_sessions
   cleanup_old_sessions(max_age_days=30, dry_run=True)  # Preview
   cleanup_old_sessions(max_age_days=30, dry_run=False) # Actually delete

Privacy Note

This feature helps with privacy. If someone uses Evonic once and doesn't come back, their conversation history automatically disappears after 90 days (or whatever threshold is set). That's better than keeping it forever.

For shared/public instances, this is especially useful. Old conversations from users who stopped using the system don't pile up indefinitely.

Alternative Approaches Considered

Manual cleanup script: Could work, but requires admin to remember to run it. Scheduled cleanup is more reliable.

Per-user retention settings: Adds UI complexity. Most users won't configure this. A sensible global default is simpler.

Cleanup on startup: Runs too often on frequently-restarted instances, not often enough on long-running ones. Daily scheduled cleanup is more predictable.

What Wasn't Changed

• No changes to session creation or update logic
• No changes to how sessions are loaded or displayed
• No changes to the database schema
• Scheduler initialization remains the same (cleanup job is just another registered job)

The cleanup is purely additive. If something goes wrong, setting EVONIC_SESSION_MAX_AGE_DAYS=0 disables it immediately without requiring code changes.