hermes - 💡(How to fix) Fix Add CLI/TUI session lineage tree viewer for parent/child sessions

Summary

Hermes already stores session lineage (parent_session_id) and has internal helpers for compression tips / resume redirection, but the user-facing CLI/TUI does not expose a clear way to inspect the session tree.

This makes it hard to answer basic questions such as:

• Which child session contains the original messages for a particular task?
• Is this child a compression continuation, a branch, a subagent run, a background-review fork, or a resume/runtime continuation?
• What is the current active tip for a logical conversation?
• Why does a title like side-main #2 appear, and how does it relate to side-main and side-main #3?

Current behavior

The CLI currently exposes:

hermes sessions list
hermes sessions browse
hermes sessions export
hermes sessions rename
hermes sessions delete
hermes sessions prune
hermes sessions optimize
hermes sessions stats

There is no built-in command such as:

hermes sessions tree <id-or-title>
hermes sessions lineage <id-or-title>
hermes sessions children <id-or-title>
hermes sessions tip <id-or-title>

hermes sessions list calls SessionDB.list_sessions_rich(...) without exposing include_children=True, so child sessions are hidden by default. The API server has partial support via GET /api/sessions?include_children=true, but that still returns a flat list and does not explain lineage semantics.

Why this matters

Hermes session lineage is a DAG/tree in practice, not a simple linear history.

A single parent session can have multiple child sessions, for example:

side-main
├─ side-main #2
└─ side-main #3

Those children may represent different semantic relationships:

• context compression continuation
• explicit /branch or /fork
• subagent/delegate run
• background review fork
• resume/runtime continuation
• gateway/TUI/API handoff

Today, all of these are represented primarily through parent_session_id, with relation type inferred indirectly from fields such as end_reason, timestamps, source, title numbering, and message patterns.

This creates user confusion. For example, a user trying to find the original record for “the SOUL.md change” may see multiple sibling sessions with the same title lineage and a [CONTEXT COMPACTION — REFERENCE ONLY] marker. That marker indicates a handoff message was injected into the session, but does not by itself mean that this child is the canonical compression continuation or that it contains the original record.

Existing internal pieces

Relevant internal support already exists:

• sessions.parent_session_id
• SessionDB.get_compression_tip(session_id)
• SessionDB.resolve_resume_session_id(session_id)
• SessionDB.list_sessions_rich(include_children=True)
• API Server: /api/sessions?include_children=true
• /branch already creates a child session and auto-numbers titles with get_next_title_in_lineage()

So this seems mostly like a missing CLI/TUI/API presentation layer rather than a missing storage primitive.

Proposed UX

Add a first-class lineage/tree view, for example:

hermes sessions tree <id-or-title>

Example output:

side-main  20260605_151301_c070cf  source=tui  end_reason=branched/compression/none  cwd=...
├─ side-main #2  20260605_193706_0564bd  relation=branch-or-resume-child  messages=129  last_active=...
└─ side-main #3  20260606_075018_5775ee  relation=current-runtime-child  messages=23  last_active=...

Useful columns/annotations:

• session id
• title
• source
• parent id
• inferred relation type
• end_reason
• message_count
• tool_call_count
• cwd
• started_at / ended_at / last_active
• whether it is a compression tip
• whether it is the current runtime session if available
• optional keyword hit count, e.g. --contains "SOUL.md"

Possible commands:

hermes sessions tree <id-or-title>
hermes sessions lineage <id-or-title>
hermes sessions children <id-or-title>
hermes sessions tip <id-or-title>
hermes sessions list --include-children

Possible TUI additions:

• show parent/children in /status or session info
• add a /sessions tree view
• annotate #2, #3 title variants with their parent and relation

Relation type inference

Short term, relation type can be inferred:

• parent.end_reason == 'compression' and child started after parent ended → compression-continuation
• explicit /branch end_reason or copied transcript → branch
• source/tool metadata or delegate hooks → subagent
• background review fork source/sentinel → background-review
• otherwise → child/unknown

Longer term, this likely wants persisted metadata such as:

parent_relation_type TEXT
lineage_root_id TEXT
logical_conversation_id TEXT

Related issues

This request is related to, but narrower than, existing provenance/classification issues:

• #26952 Session trajectory JSON files carry no session_type or lineage metadata
• #28412 persist session kind/provenance metadata
• #17926 Expose canonical user-visible session classification for dashboards
• #35542 TUI resume listing hides message-bearing child sessions
• #6507 session_search drops child/continuation-session hits by summarizing only the lineage root

This issue is specifically about giving users a built-in way to inspect session lineage/tree so they do not have to query SQLite manually.

Acceptance criteria

• A user can inspect the full parent/child tree for a session/title from the CLI.
• Child sessions are not silently hidden when the user explicitly asks for lineage.
• The output distinguishes at least compression continuations from ordinary branches/children where possible.
• The command makes it clear which session id contains the original messages vs which one is just a handoff/continuation.
• Documentation or help text explains that [CONTEXT COMPACTION — REFERENCE ONLY] is a handoff marker and not, by itself, proof that the session is the canonical compression continuation.