[salma2vec]

Summary

Fixes #1437.

Persistent HTTP sessions remained open after normal application shutdown: their MCP contexts, environments and per-session executors were never closed. Shutdown now waits for the idle reaper to finish any cleanup already underway, closes the remaining sessions through _destroy_session(), and then stops the shared executor.

The reaper stops cooperatively so shutdown cannot interrupt cleanup after a session has already been removed from the registry; session-creation cancellation (#1301), forced shutdown and timeout policy remain outside this fix.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

Both changed files pass usort, Ruff lint and Ruff formatting. The project-wide formatting check on this base reports unrelated formatting/import-order failures, recorded separately during #1436; those files are unchanged here. The full repository test suite was not run.

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: #___
• RFC needed (will create before merge)

Test Plan

Six new cases fail before the fix and pass afterward: normal shutdown, continued cleanup after an ordinary close failure, and shutdown while the real idle reaper is inside MCP context cleanup. Each runs with both per-session and shared executors.

The tests create sessions through HTTP inside the actual application lifespan. They retain real in-process FastMCP clients and check disconnection, MCP exit before environment close, constructor-thread affinity, executor shutdown and empty session bookkeeping. A session explicitly closed before shutdown is not closed again. The existing best-effort retry after a failing close() is preserved.

On Python 3.12:

PYTHONPATH=src:envs python -m pytest -q \
  tests/core/test_production_mode_routes.py \
  tests/core/test_harness_ws_route.py \
  tests/core/test_simulation_mode_preserves_api.py \
  tests/core/test_production_mode_mcp.py \
  tests/core/test_mcp/test_mcp_environment.py

Across these modules, validated in three groups: 134 passed, 1 skipped. The skip is an existing disabled implementation-detail test. No external model, hosted environment or container was used.

Claude Code Review

N/A. Codex was used for investigation, implementation and testing.

---

Note

Medium Risk
Changes core session lifecycle and shutdown ordering for production HTTP MCP; incorrect teardown could leave resources open or block shutdown, but behavior is covered by new lifespan tests.

Overview
Fixes graceful shutdown so persistent HTTP MCP sessions are torn down instead of leaking MCP contexts, environments, and executors after the app stops.

Shutdown path: FastAPI on_shutdown now runs _shutdown_sessions, which cooperatively stops the idle reaper, calls _destroy_session for every remaining session, then shuts down the shared session executor. The reaper uses _reaper_stop_event and asyncio.wait_for on that event instead of fixed sleep plus task cancellation, so stop returns promptly and in-flight reaper cleanup can finish before shutdown proceeds.

Tests: New TestHTTPMCPSessionShutdown covers lifespan shutdown (MCP disconnect, teardown order, executor shutdown), cleanup when close() fails, and shutdown while the reaper is mid–MCP exit; reaper stop is asserted to complete without cancellation.

^{Reviewed by Cursor Bugbot for commit 3987779. Bugbot is set up for automated code reviews on this repo. Configure here.}