Address review feedback: docstring formatting, test reorganization

- Reformat session_idle_timeout docstring to use 4-space continuation
  indent and fill to 120 chars
- Move idle timeout tests from tests/issues/ into
  tests/server/test_streamable_http_manager.py alongside existing
  session manager tests
- Remove redundant/unnecessary tests (6 dropped, 5 kept)
- Replace sleep-based test assertions with event-based polling
  using anyio.fail_after for deterministic behavior

Github-Issue: #1283

Author: felixweinberger

CLAUDE.md

@@ -24,6 +24,11 @@ This document contains critical information about working with this codebase. Fo
    - Coverage: test edge cases and errors
    - New features require tests
    - Bug fixes require regression tests
+   - NEVER use `anyio.sleep()` with a fixed duration as a synchronization mechanism. Instead:
+     - Use `anyio.Event` — set it in the callback/handler, `await event.wait()` in the test
+     - For stream messages, use `await stream.receive()` instead of `sleep()` + `receive_nowait()`
+     - Wrap waits in `anyio.fail_after(5)` as a timeout guard
+     - If a sleep seems unnecessary, just remove it
 
 - For commits fixing bugs or adding features based on user reports add:
 

src/mcp/server/streamable_http_manager.py

@@ -56,14 +56,15 @@ class StreamableHTTPSessionManager:
         security_settings: Optional transport security settings.
         retry_interval: Retry interval in milliseconds to suggest to clients in SSE
                        retry field. Used for SSE polling behavior.
-        session_idle_timeout: Optional idle timeout in seconds for stateful sessions.
-                            If set, sessions that receive no HTTP requests for this
-                            duration will be automatically terminated and removed.
-                            When retry_interval is also configured, ensure the idle
-                            timeout comfortably exceeds the retry interval to avoid
-                            reaping sessions during normal SSE polling gaps.
-                            Default is None (no timeout). A value of 1800
-                            (30 minutes) is recommended for most deployments.
+        session_idle_timeout: Optional idle timeout in seconds for stateful
+                              sessions. If set, sessions that receive no HTTP
+                              requests for this duration will be automatically
+                              terminated and removed. When retry_interval is
+                              also configured, ensure the idle timeout
+                              comfortably exceeds the retry interval to avoid
+                              reaping sessions during normal SSE polling gaps.
+                              Default is None (no timeout). A value of 1800
+                              (30 minutes) is recommended for most deployments.
     """
 
     def __init__(

tests/issues/test_1283_idle_session_cleanup.py

@@ -313,3 +313,74 @@ async def mock_receive():
         assert error_data["id"] == "server-error"
         assert error_data["error"]["code"] == INVALID_REQUEST
         assert error_data["error"]["message"] == "Session not found"
+
+
+@pytest.mark.anyio
+async def test_idle_session_is_reaped():
+    """Idle timeout sets a cancel scope deadline and reaps the session when it fires."""
+    idle_timeout = 300
+    app = Server("test-idle-reap")
+    manager = StreamableHTTPSessionManager(app=app, session_idle_timeout=idle_timeout)
+
+    async with manager.run():
+        sent_messages: list[Message] = []
+
+        async def mock_send(message: Message):
+            sent_messages.append(message)
+
+        scope = {
+            "type": "http",
+            "method": "POST",
+            "path": "/mcp",
+            "headers": [(b"content-type", b"application/json")],
+        }
+
+        async def mock_receive():  # pragma: no cover
+            return {"type": "http.request", "body": b"", "more_body": False}
+
+        before = anyio.current_time()
+        await manager.handle_request(scope, mock_receive, mock_send)
+
+        session_id = None
+        for msg in sent_messages:  # pragma: no branch
+            if msg["type"] == "http.response.start":  # pragma: no branch
+                for header_name, header_value in msg.get("headers", []):  # pragma: no branch
+                    if header_name.decode().lower() == MCP_SESSION_ID_HEADER.lower():
+                        session_id = header_value.decode()
+                        break
+                if session_id:  # pragma: no branch
+                    break
+
+        assert session_id is not None, "Session ID not found in response headers"
+        assert session_id in manager._server_instances
+
+        # Verify the idle deadline was set correctly
+        transport = manager._server_instances[session_id]
+        assert transport.idle_scope is not None
+        assert transport.idle_scope.deadline >= before + idle_timeout
+
+        # Simulate time passing by expiring the deadline
+        transport.idle_scope.deadline = anyio.current_time()
+
+        with anyio.fail_after(5):
+            while session_id in manager._server_instances:
+                await anyio.sleep(0)
+
+        assert session_id not in manager._server_instances
+
+        # Verify terminate() is idempotent
+        await transport.terminate()
+        assert transport.is_terminated
+
+
+@pytest.mark.parametrize(
+    "kwargs,match",
+    [
+        ({"session_idle_timeout": -1}, "positive number"),
+        ({"session_idle_timeout": 0}, "positive number"),
+        ({"session_idle_timeout": 30, "stateless": True}, "not supported in stateless"),
+    ],
+)
+def test_session_idle_timeout_validation(kwargs: dict[str, Any], match: str):
+    with pytest.raises(ValueError, match=match):
+        StreamableHTTPSessionManager(app=Server("test"), **kwargs)