feat: load full lineage segments on demand

[dso2ng]

Thinking Path

• The sidebar can already show N segments for collapsed compression lineage rows (fix: show collapsed session segment count #1906) and expand client-materialized segments (feat: expand collapsed session lineage segments #1943).
• The backend read-only report endpoint is now shipped (feat: add read-only session lineage report endpoint #2012), and fix: keep explicit forks out of lineage report #2063 aligned it with explicit-fork semantics across the backend projection paths.
• Some rows only have a backend _compression_segment_count from /api/sessions; the browser may not have the older segment rows materialized, so clicking the badge cannot reveal the full bounded list.
• This PR keeps ordinary sidebar refresh cheap and fetches /api/session/lineage/report only when the user expands such a row.

What Changed

• Added a small per-sidebar-cache lineage-report cache/inflight map in static/sessions.js.
• Invalidates that cache on each fresh /api/sessions refresh.
• On segment-badge expand, fetches GET /api/session/lineage/report?session_id=<tip> only when _sessionSegmentCount(s) exceeds the locally materialized _lineage_segments count.
• Merges returned report segments by session_id with existing client-materialized segments, skipping the visible tip and any child_session rows.
• Leaves report children out of the compression-segment list so subagent/fork child semantics remain separate.
• Added regression coverage for fetch-needed detection, report-segment merging/deduplication, endpoint construction, and in-flight/cache de-duping.

Visual / Interaction Evidence

Expected network behavior:

• Initial sidebar refresh still uses the existing /api/sessions path and does not call /api/session/lineage/report.
• First expansion of a backend-count-only lineage badge makes exactly one bounded lineage-report request.
• The result is cached until the next /api/sessions refresh.

Why It Matters

This completes the read-only lineage ladder without adding prefetch, polling, archive/delete controls, storage migration, or a broader session-management surface. Users can inspect old compression segments when the sidebar only has a count, while the common sidebar polling path remains unchanged.

Verification

• RED first:
  • python -m pytest tests/test_session_lineage_collapse.py::test_lineage_segment_expansion_static_contract tests/test_session_lineage_collapse.py::test_lineage_report_fetch_is_needed_only_when_backend_count_exceeds_materialized_segments tests/test_session_lineage_collapse.py::test_cached_lineage_report_segments_merge_with_materialized_segments_without_duplicates_or_children -q -o addopts= -> failed with missing cache/helpers/report endpoint wiring.
• GREEN / targeted:
  • python -m pytest tests/test_session_lineage_collapse.py tests/test_session_lineage_report.py tests/test_session_lineage_metadata_api.py -q -o addopts= -> 29 passed
  • python -m py_compile api/agent_sessions.py api/routes.py api/models.py
  • node --check static/sessions.js
  • git diff --check
  • non-ASCII diff guard -> non_ascii_added_lines=0
• Asset check:
  • raw PNG URL returns HTTP 200 with content-type: image/png.

Risks / Follow-ups

• feat: Add toggleable session lineage indicators setting #2072 is an open held UX PR for a Show session lineage indicators setting. This PR intentionally does not add a settings surface. If feat: Add toggleable session lineage indicators setting #2072 lands first, this branch should rebase and ensure toggle-off hides the badge/expansion affordance and therefore performs no lazy lineage-report fetch.
• Fix manual compression proxy timeouts #2128 also touches static/sessions.js for manual compression timeout handling; it is a rebase risk but does not overlap this lineage-report contract.
• This PR does not add loading/error copy to avoid new i18n surface. Failed report fetches are caught, logged, and the sidebar remains usable with the existing materialized list.

Model Used

Prepared with assistance from Hermes Agent using OpenAI Codex gpt-5.5.