fix(projects): batch the summary queries — the fan-out was exhausting the pool

Reported live: Projects and Snippets showed skeletons that never resolved,
/knowledge worked intermittently. The logs named it exactly:

    QueuePool limit of size 5 overflow 10 reached, connection timed out, 30.00
    GET /api/settings  500  30584.0ms
    GET /api/projects  200  30882.9ms

/api/projects was not hanging — it was waiting out the 30-second checkout
timeout and then returning 200 with summaries silently missing, because
_attach swallowed the TimeoutError. Nobody waits 31 seconds, so it read as a
hang.

THE SHAPE: routes/projects.py ran asyncio.gather over every project. Each
_attach called get_project_summary, which opened its own session for three
queries and then called get_project_milestone_summary — which opened one more
session PER MILESTONE. So 25 projects asked for roughly 250 concurrent
checkouts against a pool of 15 (SQLAlchemy's default 5 + 10 overflow).

That is why unrelated routes failed too. Snippets and /knowledge were never
broken; they queued behind the burst and inherited its timeout. /api/settings
returning 500 while /api/projects returned 200 is the same cause wearing two
faces.

The comment above the gather said "one backend pass instead of N+1 frontend
calls". It did remove the N+1 from the network — and recreated it against the
connection pool, where it is worse, because the browser had at least been
serialising those calls.

Now: get_project_summaries() does all projects in four queries and one session,
and get_project_milestone_summaries() does all milestones in two. Two sessions
total for the whole page, independent of how many projects exist.

The progress calculation is extracted to _progress_from_counts and shared by
both the batch and single paths, so the cancelled-exclusion rule cannot drift
into two versions that disagree about whether a milestone is finished.

Tests assert the SESSION COUNT, not just the values. An implementation that
returned identical output while opening a session per project would pass a
correctness test and reproduce the outage.

Deliberately NOT done: raising pool_size. It would move the cliff rather than
remove it, and this endpoint now needs two connections regardless of scale.

Closes #2384.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs

src/scribe/routes/projects.py

@@ -1,5 +1,4 @@
 """Project management routes."""
-import asyncio
 import logging
 
 from quart import Blueprint, jsonify, request
@@ -13,6 +12,7 @@ from scribe.services.projects import (
     delete_project,
     get_project,
     get_project_for_user,
+    get_project_summaries,
     get_project_summary,
     list_projects_for_user,
     update_project,
@@ -31,16 +31,28 @@ async def list_projects_route():
     include_summary = request.args.get("include_summary", "").lower() in ("1", "true")
     projects = await list_projects_for_user(uid, status=status)
     if include_summary:
-        # Fetch all summaries in parallel — one backend pass instead of N+1 frontend calls
-        async def _attach(project_dict: dict) -> dict:
+        # Batched: four queries plus two, in two sessions, for ALL projects.
+        # This replaced an asyncio.gather over a per-project summary that opened
+        # its own session and then one more per milestone — ~250 concurrent
+        # checkouts against a pool of 15, all waiting out the 30s timeout and
+        # starving every other route on the instance (#2384).
+        #
+        # Grouped by OWNER because a shared project's counts belong to its
+        # owner's records, matching what the per-project path passed.
+        by_owner: dict[int, list[dict]] = {}
+        for p in projects:
+            by_owner.setdefault(p.get("user_id") or uid, []).append(p)
+        for owner_uid, owned in by_owner.items():
             try:
-                owner_uid = project_dict.get("user_id") or uid  # user_id now in to_dict()
-                summary = await get_project_summary(owner_uid, project_dict["id"])
-                project_dict["summary"] = summary
+                summaries = await get_project_summaries(
+                    owner_uid, [p["id"] for p in owned]
+                )
             except Exception:
-                pass
-            return project_dict
-        projects = list(await asyncio.gather(*[_attach(p) for p in projects]))
+                logger.warning("Project summaries failed", exc_info=True)
+                continue
+            for p in owned:
+                if p["id"] in summaries:
+                    p["summary"] = summaries[p["id"]]
     return jsonify({"projects": projects})