Fix: Enforce session capacity on restore and prevent session-creation race

[OmShrivastava19]

This pull request adds a background cleanup mechanism to automatically unload long-idle sessions from memory, improves session resource management, and introduces robust session capacity checks to prevent server overload. It also adds new unit tests to verify session capacity logic. The most important changes are:

Session Idle Unloading and Resource Management:

• Introduced a background task (_unload_inactive_sessions_loop) in SessionManager that periodically (every 10 minutes) unloads sessions idle for more than 24 hours, persisting their state and freeing server memory. The task is started on manager startup and properly cancelled on shutdown. [1] [2] [3]
• Added and updated the last_access attribute in AgentSession to track the last time a session was used, ensuring accurate idle detection. This timestamp is updated on session creation, restoration, and access. [1] [2] [3] [4] [5] [6]

Session Capacity Enforcement:

• Enhanced session creation logic to reserve capacity slots with lightweight placeholder AgentSession objects, preventing race conditions where more than the allowed number of sessions could be created concurrently. [1] [2] [3]
• Updated session restoration (ensure_session_loaded) to check server capacity before loading a session from persistence, denying restoration if the server is at maximum session capacity and logging a warning.

Testing:

• Added new unit tests in tests/unit/test_session_capacity.py to verify that session restoration is denied when at capacity and allowed when under capacity, ensuring correct enforcement of session limits.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds session capacity protections and automatic cleanup of idle sessions, plus unit tests around restoring sessions at capacity.

Changes:

• Track per-session last_access and introduce a background loop to unload/persist sessions idle > 24 hours.
• Add a placeholder “reservation” session during create_session() to avoid concurrent creations exceeding MAX_SESSIONS.
• Add tests for ensure_session_loaded() behavior when restoring at/under server capacity.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.

File	Description
tests/unit/test_session_capacity.py	New async unit tests validating restore behavior at capacity and under capacity.
backend/session_manager.py	Implements idle unloading, last_access tracking, restore capacity check, and capacity reservation placeholder during creation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.