fix(sidebar): keep manual forks out of compaction snapshot lineage swaps (#3799)

[rodboev]

Thinking Path

• Manual forks are user-visible branches, but the sidebar compaction-grouping path was still walking through them as if they were compression continuations.
• The direct fix is to respect explicit fork boundaries in the sidebar lineage-root logic, but that must not hide child-session rows that attach under hidden compression segments through enriched lineage metadata.
• The final change therefore narrows the fork boundary to explicit manual forks while keeping enriched child-session rows independently visible until the later attachment pass.

What Changed

• api/models.py: keep explicit manual forks as lineage boundaries in the sidebar snapshot-grouping path, enrich lineage metadata before grouping, and treat enriched child_session rows as their own temporary roots so hidden-compression descendants remain visible.
• tests/test_session_index.py: add focused regressions for the visible fork child case and the child-under-hidden-compression case.

Why It Matters

Forks are user-visible branches, not implementation-detail continuations. They should remain independently discoverable instead of being collapsed away by compaction snapshot heuristics from their parent lineage.

Verification

• Targeted: pytest tests/test_session_index.py tests/test_session_lineage_collapse.py tests/test_session_lineage_full_transcript.py tests/test_session_lineage_metadata_api.py tests/test_session_lineage_report.py -v --timeout=60
  Result: passed with an isolated HERMES_WEBUI_TEST_STATE_DIR, 84 passed in 4.76s.
• Full suite command for reviewer use: pytest tests/ -v --timeout=60
  Result: not run locally in this session.

Risks / Follow-ups

This remains intentionally scoped to sidebar lineage-root parity and hidden-child visibility. It does not add a broader compaction-history discoverability UI, which should stay separate from this correctness fix.

Model Used

GPT-5 via Codex CLI

[greptile-apps]

Greptile Summary

This PR fixes the sidebar compaction-grouping path so manual forks are treated as lineage boundaries rather than transparent compression continuations. It also hardens the background index-rebuild thread against late SESSION_DIR switches and eliminates the SESSION_DIR global re-resolution during a full index rebuild.

• Sidebar lineage root logic (_sidebar_lineage_root_id): adds three early-return guards — explicit _lineage_root_id, relationship_type == 'child_session', and session_source == 'fork' — so forks remain independently discoverable and enriched child-session rows stay visible as their own roots.
• Ordering fix (all_sessions): _enrich_sidebar_lineage_metadata is now called before _prefer_fuller_snapshots_for_sidebar so enrichment-supplied metadata is available during snapshot grouping on both the index path and the full-scan fallback path.
• TOCTOU fix (_rebuild_session_index_background): the background thread captures its target (SESSION_DIR, SESSION_INDEX_FILE) at spawn time, validates them inside the lock before writing, and uses _load_session_from_path to load session files from the explicit captured path, preventing a mid-flight session-dir switch from redirecting the write.

Confidence Score: 5/5

Safe to merge; the logic changes are well-scoped and the new background-rebuild guard correctly prevents cross-directory index writes.

The three new branches in _sidebar_lineage_root_id are additive and ordered correctly after enrichment. The explicit-path threading fix eliminates the TOCTOU window identified in a previous review cycle. No pre-existing interface is broken.

tests/test_session_index.py — the integration assertion for the fork test is missing a total-row count check.

Important Files Changed

Filename	Overview
api/models.py	Moves _enrich_sidebar_lineage_metadata before _prefer_fuller_snapshots_for_sidebar, adds fork/child_session early-returns to _sidebar_lineage_root_id, adds _load_session_from_path to avoid SESSION_DIR re-resolution in full rebuild, and hardens background rebuild thread with captured target tracking to prevent cross-dir writes.
tests/test_session_index.py	Adds two new tests: fork visibility regression and late session-dir-switch write guard. The fork test mixes an integration call with direct unit assertions on _sidebar_lineage_root_id; the integration half is missing a len(rows) assertion.

Sequence Diagram

sequenceDiagram
    participant C as all_sessions()
    participant E as _enrich_sidebar_lineage_metadata
    participant P as _prefer_fuller_snapshots_for_sidebar
    participant L as _sidebar_lineage_root_id

    C->>E: result (all non-empty sessions)
    Note over E: sets _lineage_root_id,<br/>relationship_type on entries
    E-->>C: (mutates in-place)
    C->>P: enriched result
    P->>L: per-session root lookup
    L-->>P: explicit _lineage_root_id OR child_session own sid OR fork own sid OR walk parent chain
    P-->>C: snapshot-grouped result
    C->>C: filter hidden, strip flags, backfill profile
    C-->>C: return visible sessions

Loading

_{Reviews (4): Last reviewed commit: "Requeue the flaky Python 3.13 shard afte..." | Re-trigger Greptile}

[nesquena-hermes]

Absorbed and shipped in v0.51.344 (Release LH, deployed live) via the release #3893 — your commit was applied with attribution (rebased onto fresh master, content byte-identical to your PR head, full-suite + Codex + Opus gated). Closes #3799. I also folded in the greptile TOCTOU concern (your threading refactor already addressed it) and applied one Opus-suggested defensive follow-up (propagating the rebuild target through the fast-path fallback); filed #3894 for a remaining low-severity thread-ownership cleanup. Thanks @rodboev! 🙏