fix: harden session cache mtime handling and address PR #90 review

Re-read mtime after parse and only cache when the file was stable during
the read; skip cache writes when max_entries is 0. Move get_cached_session
to module-level import in projects.py; improve mtime/LRU tests; document
concurrent cold-miss behavior.

stop search scan after max_results across projects

Author: clean6378-max-it

api/projects.py

@@ -7,6 +7,7 @@
 from models.project import ProjectSessionRowDict, SessionListItemDict
 from models.session import SessionDict
 from utils.exclusion_rules import is_session_excluded
+from utils.session_cache import get_cached_session
 from utils.session_path import get_claude_projects_dir, list_projects, list_sessions, safe_join
 
 projects_bp = Blueprint("projects", __name__)
@@ -80,9 +81,6 @@ def get_project_sessions(project_name: str) -> FlaskReturn:
     except ValueError:
         return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
     sessions = list_sessions(project_dir)
-    # Add summary preview for each session
-    from utils.session_cache import get_cached_session
-
     rules = current_app.config.get("EXCLUSION_RULES") or []
     result: list[ProjectSessionRowDict] = []
     for s in sessions:

api/search.py

@@ -49,6 +49,8 @@ def search() -> FlaskReturn:
     rules = current_app.config.get("EXCLUSION_RULES") or []
     results: list[SearchHitDict] = []
     for project in projects:
+        if len(results) >= max_results:
+            break
         sessions = list_sessions(project["path"])
         for sess_info in sessions:
             if len(results) >= max_results:

tests/test_error_propagation.py

@@ -179,9 +179,7 @@ def test_per_session_error_card_omits_error_detail(self, tmp_path, client, monke
         def _boom(*args, **kwargs):
             raise KeyError("internal_secret_field_id")
 
-        # api/projects.py imports parse_session inside the handler body,
-        # so patch the source module rather than the consumer.
-        monkeypatch.setattr("utils.session_cache.get_cached_session", _boom)
+        monkeypatch.setattr("api.projects.get_cached_session", _boom)
 
         resp = client.get("/api/projects/myproj/sessions")
         # Pin the response shape so a future wrapper change (e.g. {"sessions": [...]})

tests/test_session_cache.py

@@ -48,13 +48,25 @@ def counting_parse(p: str):
     assert calls == 0
 
 
-def test_cache_invalidates_on_mtime_change(sample_session: Path) -> None:
+def test_cache_invalidates_on_mtime_change(
+    sample_session: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
     path = str(sample_session)
-    first = get_cached_session(path)
+    get_cached_session(path)
+
+    calls = 0
+
+    def counting_parse(p: str):
+        nonlocal calls
+        calls += 1
+        return parse_session(p)
+
+    monkeypatch.setattr("utils.session_cache.parse_session", counting_parse)
+
     stat = sample_session.stat()
     os.utime(sample_session, (stat.st_mtime + 1, stat.st_mtime + 1))
-    second = get_cached_session(path)
-    assert first is not second
+    get_cached_session(path)
+    assert calls == 1
 
 
 def test_cache_normalizes_relative_and_absolute_paths(
@@ -83,7 +95,9 @@ def counting_parse(p: str):
         os.chdir(original_cwd)
 
 
-def test_lru_eviction(sample_session: Path, tmp_path: Path) -> None:
+def test_lru_eviction(
+    sample_session: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
     set_max_entries(2)
     content = sample_session.read_text(encoding="utf-8")
     paths = []
@@ -102,17 +116,13 @@ def counting_parse(p: str):
         calls += 1
         return parse_session(p)
 
-    monkeypatch = pytest.MonkeyPatch()
     monkeypatch.setattr("utils.session_cache.parse_session", counting_parse)
-    try:
-        get_cached_session(str(paths[2]))
-        assert calls == 0
-        get_cached_session(str(paths[1]))
-        assert calls == 0
-        get_cached_session(str(paths[0]))
-        assert calls == 1
-    finally:
-        monkeypatch.undo()
+    get_cached_session(str(paths[2]))
+    assert calls == 0
+    get_cached_session(str(paths[1]))
+    assert calls == 0
+    get_cached_session(str(paths[0]))
+    assert calls == 1
 
 
 def test_set_max_entries_rejects_negative() -> None:

utils/session_cache.py

@@ -17,20 +17,28 @@
 
 
 def get_cached_session(path: str) -> SessionDict:
-    """Return a parsed session, reusing the cache when mtime is unchanged."""
+    """Return a parsed session, reusing the cache when mtime is unchanged.
+
+    Concurrent requests for different paths proceed in parallel.
+    Concurrent misses on the *same* path will each parse independently;
+    the last writer wins. This is safe but may parse the file more than
+    once under high concurrency for a cold key.
+    """
     abspath = os.path.abspath(path)
-    mtime = os.path.getmtime(abspath)
+    mtime_before = os.path.getmtime(abspath)
     with _lock:
         hit = _cache.get(abspath)
-        if hit is not None and hit[0] == mtime:
+        if hit is not None and hit[0] == mtime_before:
             _cache.move_to_end(abspath)
             return hit[1]
     parsed = parse_session(abspath)
+    mtime_after = os.path.getmtime(abspath)
     with _lock:
-        _cache[abspath] = (mtime, parsed)
-        _cache.move_to_end(abspath)
-        while len(_cache) > _max_entries:
-            _cache.popitem(last=False)
+        if _max_entries > 0 and mtime_after == mtime_before:
+            _cache[abspath] = (mtime_after, parsed)
+            _cache.move_to_end(abspath)
+            while len(_cache) > _max_entries:
+                _cache.popitem(last=False)
     return parsed
 
 
@@ -41,7 +49,10 @@ def clear_cache() -> None:
 
 
 def set_max_entries(max_entries: int) -> None:
-    """Override the LRU capacity (primarily for tests)."""
+    """Override the LRU capacity (primarily for tests).
+
+    A value of 0 disables caching entirely — every access will parse from disk.
+    """
     if max_entries < 0:
         raise ValueError(f"max_entries must be non-negative, got {max_entries}")
     global _max_entries