fix(session-summary): address yellow review — stale-sidecar docs, subpath skip note, conformance clock alignment

- sessions.py: fast-path doctring note + inline return comment now say
  'complete and fresh' sidecars never short-page; a present-but-stale
  sidecar (summary.mtime < list_sessions.mtime) is routed through the
  same gap-fill as a missing one and can short-page.
- types.py: SessionStore.list_session_summaries docstring explicitly
  notes that subagent (subpath) keys must be skipped by the fold and
  that results are scoped to project_key like list_sessions.
- conformance: replace tautological 'refolded[mtime] >= summ[mtime]'
  check (the fold preserves prev mtime verbatim) with an explicit
  equality, and add a clock-alignment assertion under has_list_sessions
  that catches adapters deriving sidecar mtime from entry ISO timestamps
  (which would make every sidecar look stale to the fast-path freshness
  check).
- test: pin test_limit_offset_applied_after_sidechain_filter to the
  slow path (list_session_summaries -> NotImplementedError) so it keeps
  covering slow-path filter-THEN-paginate — the fast path deliberately
  locks in paginate-THEN-drop for summary-backed sidechain slots.

Author: qing-ant

src/claude_agent_sdk/_internal/sessions.py

@@ -1602,11 +1602,12 @@ async def list_sessions_from_store(
     .. note::
         If the store implements ``list_session_summaries``, this is one batch
         summary call plus one cheap ``list_sessions()`` enumeration to
-        gap-fill sessions missing a sidecar — zero per-session ``load()``
-        calls when sidecars are complete. Otherwise falls back to one
-        ``store.load()`` per session (bounded at 16 concurrent), which on
-        remote backends with many or large sessions can be expensive (e.g.,
-        S3 egress, Postgres large-row reads).
+        gap-fill sessions missing a sidecar or whose sidecar is stale
+        (``summary.mtime < list_sessions.mtime``) — zero per-session
+        ``load()`` calls when sidecars are complete and fresh. Otherwise
+        falls back to one ``store.load()`` per session (bounded at 16
+        concurrent), which on remote backends with many or large sessions
+        can be expensive (e.g., S3 egress, Postgres large-row reads).
 
         Gap-fill requires ``list_sessions``: if the store implements
         ``list_session_summaries`` but not ``list_sessions``, sessions
@@ -1697,7 +1698,9 @@ async def list_sessions_from_store(
             # extractable summary after load) are dropped here, AFTER
             # pagination — that case alone can short-page. Summary-backed
             # slots were already pre-filtered above, so a store with complete
-            # sidecars never short-pages.
+            # and fresh sidecars never short-pages; a present-but-stale
+            # sidecar is routed through gap-fill (same as a missing one) and
+            # can short-page if load() yields no extractable summary.
             return [sl["info"] for sl in page if sl["info"] is not None]
 
     if not has_list_sessions:

src/claude_agent_sdk/testing/session_store_conformance.py

@@ -195,13 +195,27 @@ async def fresh() -> SessionStore:
         summ = by_id["summ-sess"]
         # mtime must be epoch-ms; >1e12 rules out epoch-seconds.
         assert math.isfinite(summ["mtime"]) and summ["mtime"] > 1e12
+        # Clock alignment: sidecar mtime is storage write time (adapter-
+        # stamped at persist), and must share a clock with
+        # list_sessions().mtime for the same session. Adapters that derive
+        # sidecar mtime from entry ISO timestamps would report a strictly
+        # older value than list_sessions()'s storage-time mtime and make
+        # every sidecar look stale to the fast-path freshness check in
+        # list_sessions_from_store(); this assertion catches that.
+        if has_list_sessions:
+            ls_by_id = {
+                e["session_id"]: e["mtime"] for e in await store.list_sessions("proj")
+            }
+            assert summ["mtime"] >= ls_by_id["summ-sess"]
         # data is opaque; the contract is that it round-trips into the fold.
         assert isinstance(summ["data"], dict)
         refolded = fold_session_summary(
             summ, key, [_e({"timestamp": "2024-01-01T00:00:03.000Z"})]
         )
         assert refolded["session_id"] == "summ-sess"
-        assert refolded["mtime"] >= summ["mtime"]
+        # The fold preserves prev["mtime"] verbatim — mtime is stamped by
+        # the adapter after persisting, not by the fold.
+        assert refolded["mtime"] == summ["mtime"]
         # Subagent appends must NOT affect the main session's summary.
         await store.append(
             {**key, "subpath": "subagents/agent-1"},

src/claude_agent_sdk/types.py

@@ -1266,7 +1266,11 @@ async def list_session_summaries(
         """Return incrementally-maintained summaries for all sessions in one call.
 
         Stores should maintain these via :func:`fold_session_summary` inside
-        :meth:`append`.
+        :meth:`append`. Skip the fold for keys with a ``subpath`` — subagent
+        transcripts must not contribute to the main session's summary.
+
+        Like :meth:`list_sessions`, results are scoped to a single
+        ``project_key`` and exclude ``subpath`` entries.
 
         Optional — if unimplemented, ``list_sessions_from_store()`` falls back
         to ``list_sessions()`` + per-session ``load()``.

tests/test_session_helpers_store.py

@@ -157,8 +157,20 @@ async def test_limit_offset_applied_after_sidechain_filter(self) -> None:
         first and ``_apply_sort_limit_offset`` paginates the filtered set, so
         ``limit=N`` returns N rows even when sidechains exist. The store path
         must do the same — paginating before filtering would return short
-        pages and let sidechains consume page slots."""
-        store = InMemorySessionStore()
+        pages and let sidechains consume page slots.
+
+        Pinned to the slow path (``list_session_summaries`` suppressed)
+        because the fast path deliberately locks in paginate-THEN-drop for
+        sidechain-shaped summary slots (see
+        ``test_sidechain_summary_short_pages``); slow-path filter-THEN-
+        paginate is what this test covers.
+        """
+
+        class SlowPathStore(InMemorySessionStore):
+            async def list_session_summaries(self, project_key):  # type: ignore[override]
+                raise NotImplementedError
+
+        store = SlowPathStore()
         valid_sids: list[str] = []
         for _ in range(5):
             sid = str(uuid_mod.uuid4())