diff --git a/claude_code_log/cli.py b/claude_code_log/cli.py
index 2c6e3afc..2433744e 100644
--- a/claude_code_log/cli.py
+++ b/claude_code_log/cli.py
@@ -506,6 +506,11 @@ def _clear_output_files(input_path: Path, all_projects: bool, file_ext: str) ->
     default=2000,
     help="Maximum messages per page for combined transcript (default: 2000). Sessions are never split across pages.",
 )
+@click.option(
+    "--shallow",
+    is_flag=True,
+    help="Render only user and assistant text messages (no tools, system, or thinking)",
+)
 @click.option(
     "--debug",
     is_flag=True,
@@ -528,6 +533,7 @@ def main(
     output_format: str,
     image_export_mode: Optional[str],
     page_size: int,
+    shallow: bool,
     debug: bool,
 ) -> None:
     """Convert Claude transcript JSONL files to HTML or Markdown.
@@ -685,6 +691,7 @@ def main(
                 output_format,
                 image_export_mode,
                 page_size=page_size,
+                shallow=shallow,
             )
 
             # Count processed projects
@@ -737,6 +744,7 @@ def main(
             not no_cache,
             image_export_mode=image_export_mode,
             page_size=page_size,
+            shallow=shallow,
         )
         if input_path.is_file():
             click.echo(f"Successfully converted {input_path} to {output_path}")
diff --git a/claude_code_log/converter.py b/claude_code_log/converter.py
index 2a673080..a09d0bea 100644
--- a/claude_code_log/converter.py
+++ b/claude_code_log/converter.py
@@ -15,7 +15,9 @@
 
 from .utils import (
     format_timestamp_range,
+    get_parent_session_id,
     get_project_display_name,
+    is_agent_session,
     should_use_as_session_starter,
     create_session_preview,
     get_warmup_session_ids,
@@ -29,13 +31,17 @@
 from .parser import parse_timestamp
 from .factories import create_transcript_entry
 from .models import (
+    BaseTranscriptEntry,
+    PassthroughTranscriptEntry,
     TranscriptEntry,
     AssistantTranscriptEntry,
+    QueueOperationTranscriptEntry,
     SummaryTranscriptEntry,
     SystemTranscriptEntry,
     UserTranscriptEntry,
     ToolResultContent,
 )
+from .dag import SessionTree, build_dag_from_entries, traverse_session_tree
 from .renderer import get_renderer, is_html_outdated
 
 
@@ -47,6 +53,118 @@ def get_file_extension(format: str) -> str:
     return "md" if format in ("md", "markdown") else format
 
 
+# =============================================================================
+# Progress Chain Repair
+# =============================================================================
+
+
+def _scan_file_progress(path: Path, chain: dict[str, Optional[str]]) -> None:
+    """Extract progress entry uuid->parentUuid from a single JSONL file."""
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                if "progress" not in line:  # Fast pre-filter
+                    continue
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    raw = json.loads(line)
+                    if not isinstance(raw, dict):
+                        continue
+                    d = cast(dict[str, Any], raw)
+                    if d.get("type") == "progress":
+                        uuid = d.get("uuid")
+                        if isinstance(uuid, str):
+                            chain[uuid] = d.get("parentUuid")
+                except json.JSONDecodeError:
+                    continue
+    except FileNotFoundError:
+        pass  # Race condition: file may have been deleted
+
+
+def _scan_progress_chains(*paths: Path) -> dict[str, Optional[str]]:
+    """Fast scan of JSONL files for progress entry uuid->parentUuid mappings."""
+    chain: dict[str, Optional[str]] = {}
+    for path in paths:
+        if path.is_file():
+            _scan_file_progress(path, chain)
+        elif path.is_dir():
+            for f in path.glob("*.jsonl"):
+                _scan_file_progress(f, chain)
+            # Also scan subagent directories
+            for f in path.glob("*/subagents/*.jsonl"):
+                _scan_file_progress(f, chain)
+    return chain
+
+
+def _scan_sidechain_uuids(directory: Path) -> set[str]:
+    """Collect UUIDs from sidechain/subagent files not loaded into the DAG.
+
+    Some subagent files (e.g. aprompt_suggestion) are never referenced
+    via agentId in the main session, so they aren't loaded by
+    load_transcript(). Their UUIDs are needed to suppress false orphan
+    warnings when main-chain entries reference sidechain parents.
+    """
+    uuids: set[str] = set()
+    for f in directory.glob("*/subagents/*.jsonl"):
+        try:
+            with open(f, "r", encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        raw = json.loads(line)
+                        if isinstance(raw, dict):
+                            uuid = cast(dict[str, Any], raw).get("uuid")
+                            if isinstance(uuid, str):
+                                uuids.add(uuid)
+                    except json.JSONDecodeError:
+                        continue
+        except FileNotFoundError:
+            pass
+    return uuids
+
+
+def _repair_parent_chains(
+    messages: list[TranscriptEntry],
+    progress_chain: dict[str, Optional[str]],
+) -> None:
+    """Repair parentUuid fields that point to dropped progress entries.
+
+    Walks the progress chain to find the nearest non-progress ancestor.
+    Only repairs links to progress entries that are NOT in the messages
+    list (i.e. those that were truly dropped, not preserved as
+    PassthroughTranscriptEntry).
+    Mutates entries in place (Pydantic v2 models are mutable by default).
+    """
+    if not progress_chain:
+        return
+    # Filter out progress UUIDs that are present as parsed entries —
+    # those are PassthroughTranscriptEntry nodes in the DAG and valid parents.
+    present_uuids = {getattr(m, "uuid", None) for m in messages}
+    dropped_progress = {
+        uuid: parent
+        for uuid, parent in progress_chain.items()
+        if uuid not in present_uuids
+    }
+    if not dropped_progress:
+        return
+    for msg in messages:
+        parent = getattr(msg, "parentUuid", None)
+        if parent and parent in dropped_progress:
+            current: Optional[str] = parent
+            seen: set[str] = set()
+            while current is not None and current in dropped_progress:
+                if current in seen:
+                    current = None
+                    break
+                seen.add(current)
+                current = dropped_progress[current]
+            msg.parentUuid = current  # type: ignore[union-attr]
+
+
 # =============================================================================
 # Transcript Loading Functions
 # =============================================================================
@@ -208,19 +326,20 @@ def load_transcript(
                         # Parse using Pydantic models
                         entry = create_transcript_entry(entry_dict)
                         messages.append(entry)
-                    elif (
-                        entry_type
-                        in [
-                            "file-history-snapshot",  # Internal Claude Code file backup metadata
-                            "progress",  # Real-time progress updates (hook_progress, bash_progress)
-                        ]
-                    ):
-                        # Silently skip internal message types we don't render
-                        pass
-                    else:
-                        display_line = line[:1000] + "..." if len(line) > 1000 else line
-                        print(
-                            f"Line {line_no} of {jsonl_path} is not a recognised message type: {display_line}"
+                    elif entry_dict.get("uuid") and entry_dict.get("sessionId"):
+                        # Unknown type with DAG-relevant fields — create a
+                        # PassthroughTranscriptEntry to preserve DAG chain
+                        # continuity (e.g. "attachment", "permission-mode").
+                        messages.append(
+                            PassthroughTranscriptEntry(
+                                uuid=entry_dict["uuid"],
+                                parentUuid=entry_dict.get("parentUuid"),
+                                sessionId=entry_dict["sessionId"],
+                                timestamp=entry_dict.get("timestamp", ""),
+                                type=entry_type,
+                                isSidechain=entry_dict.get("isSidechain", False),
+                                agentId=entry_dict.get("agentId"),
+                            )
                         )
                 except json.JSONDecodeError as e:
                     print(
@@ -309,14 +428,70 @@ def load_transcript(
     return messages
 
 
+def _integrate_agent_entries(messages: list[TranscriptEntry]) -> None:
+    """Parent agent entries and assign synthetic session IDs.
+
+    Agent (sidechain) entries share sessionId with their parent session
+    but form separate conversation threads. This function:
+
+    1. Builds a map of agentId -> anchor UUID (the main-session User entry
+       whose agentId matches, i.e. the tool_result that references the agent)
+    2. For each agent's root entry (parentUuid=None, isSidechain=True),
+       sets parentUuid to the anchor UUID
+    3. Assigns a synthetic sessionId ("{sessionId}#agent-{agentId}") to all
+       agent entries so they form separate DAG-lines
+
+    Mutates entries in place (Pydantic v2 models are mutable by default).
+    """
+    # Build agentId -> anchor UUID map.
+    # An anchor is any entry whose agentId references a sidechain transcript.
+    # Prefer non-sidechain anchors (main session), but also accept sidechain
+    # anchors (nested agents: agent A spawns agent B, so B's anchor lives
+    # inside A's sidechain).
+    agent_anchors: dict[str, str] = {}
+    agent_anchors_from_sidechain: dict[str, str] = {}
+    for msg in messages:
+        if not isinstance(msg, (BaseTranscriptEntry, PassthroughTranscriptEntry)):
+            continue
+        if not msg.agentId:
+            continue
+        if msg.isSidechain:
+            agent_anchors_from_sidechain.setdefault(msg.agentId, msg.uuid)
+        else:
+            agent_anchors[msg.agentId] = msg.uuid
+    # Merge: non-sidechain anchors take priority
+    for agent_id, uuid in agent_anchors_from_sidechain.items():
+        agent_anchors.setdefault(agent_id, uuid)
+
+    if not agent_anchors:
+        return
+
+    # Process sidechain entries: parent roots and assign synthetic sessionIds
+    for msg in messages:
+        if not isinstance(msg, (BaseTranscriptEntry, PassthroughTranscriptEntry)):
+            continue
+        if not msg.isSidechain or not msg.agentId:
+            continue
+        agent_id = msg.agentId
+        # Assign synthetic session ID to separate from main session
+        msg.sessionId = f"{msg.sessionId}#agent-{agent_id}"
+        # Parent the root entry to the anchor
+        if msg.parentUuid is None and agent_id in agent_anchors:
+            msg.parentUuid = agent_anchors[agent_id]
+
+
 def load_directory_transcripts(
     directory_path: Path,
     cache_manager: Optional["CacheManager"] = None,
     from_date: Optional[str] = None,
     to_date: Optional[str] = None,
     silent: bool = False,
-) -> list[TranscriptEntry]:
-    """Load all JSONL transcript files from a directory and combine them."""
+) -> tuple[list[TranscriptEntry], SessionTree]:
+    """Load all JSONL transcript files from a directory and combine them.
+
+    Returns (messages, session_tree) — the tree is reused by the renderer
+    to avoid rebuilding the DAG.
+    """
     all_messages: list[TranscriptEntry] = []
 
     # Find all .jsonl files, excluding agent files (they are loaded via load_transcript
@@ -331,14 +506,32 @@ def load_directory_transcripts(
         )
         all_messages.extend(messages)
 
-    # Sort all messages chronologically
-    def get_timestamp(entry: TranscriptEntry) -> str:
-        if hasattr(entry, "timestamp"):
-            return entry.timestamp  # type: ignore
-        return ""
+    # Repair parent chains: progress entries create UUID gaps
+    progress_chain = _scan_progress_chains(directory_path)
+    _repair_parent_chains(all_messages, progress_chain)
+
+    # Parent agent entries and assign synthetic session IDs so they
+    # form separate DAG-lines spliced at their anchor points.
+    _integrate_agent_entries(all_messages)
+
+    # Collect UUIDs from unloaded subagent files (e.g. aprompt_suggestion
+    # agents never referenced via agentId) to suppress orphan warnings
+    unloaded_sidechain_uuids = _scan_sidechain_uuids(directory_path)
+
+    # Build DAG and traverse (entries grouped by session, depth-first)
+    tree = build_dag_from_entries(
+        all_messages, sidechain_uuids=unloaded_sidechain_uuids
+    )
+    dag_ordered = traverse_session_tree(tree)
+
+    # Re-add summaries/queue-ops (excluded from DAG since they lack uuid)
+    non_dag_entries: list[TranscriptEntry] = [
+        e
+        for e in all_messages
+        if isinstance(e, (SummaryTranscriptEntry, QueueOperationTranscriptEntry))
+    ]
 
-    all_messages.sort(key=get_timestamp)
-    return all_messages
+    return dag_ordered + non_dag_entries, tree
 
 
 # =============================================================================
@@ -406,12 +599,18 @@ def deduplicate_messages(messages: list[TranscriptEntry]) -> list[TranscriptEntr
                     content_key = item.tool_use_id
                     break
             else:
-                # No tool result found - this is a user text message
+                # No tool result found - this is a user text message.
+                # Use uuid to keep distinct messages (even at same timestamp)
+                # so DAG parent references remain valid.
                 is_user_text = True
-                # content_key stays empty (dedupe by timestamp alone)
+                content_key = message.uuid
         elif isinstance(message, SummaryTranscriptEntry):
             # Summaries have no timestamp or uuid - use leafUuid to keep them distinct
             content_key = message.leafUuid
+        elif isinstance(message, PassthroughTranscriptEntry):
+            # Passthrough entries are DAG chain nodes — use uuid to prevent
+            # false dedup of entries with the same timestamp (e.g. attachments)
+            content_key = message.uuid
 
         # Create deduplication key
         dedup_key = (message_type, timestamp, is_meta, session_id, content_key)
@@ -614,11 +813,11 @@ def _build_session_data_from_messages(
     sessions: Dict[str, Dict[str, Any]] = {}
     for message in messages:
         if not hasattr(message, "sessionId") or isinstance(
-            message, SummaryTranscriptEntry
+            message, (SummaryTranscriptEntry, PassthroughTranscriptEntry)
         ):
             continue
 
-        session_id = getattr(message, "sessionId", "")
+        session_id = get_parent_session_id(getattr(message, "sessionId", ""))
         if not session_id or session_id in warmup_session_ids:
             continue
 
@@ -698,6 +897,8 @@ def _generate_paginated_html(
     session_data: Dict[str, SessionCacheData],
     working_directories: List[str],
     silent: bool = False,
+    session_tree: Optional[SessionTree] = None,
+    shallow: bool = False,
 ) -> Path:
     """Generate paginated HTML files for combined transcript.
 
@@ -714,7 +915,7 @@ def _generate_paginated_html(
     Returns:
         Path to the first page (combined_transcripts.html)
     """
-    from .html.renderer import generate_html
+    from .html.renderer import HtmlRenderer
     from .utils import format_timestamp
 
     # Check if page size changed - if so, invalidate all pages
@@ -747,14 +948,16 @@ def _generate_paginated_html(
             if orphan_path.exists():
                 orphan_path.unlink()
 
-    # Group messages by session for fast lookup
+    # Group messages by session for fast lookup (agent messages grouped
+    # under their parent session since they don't have their own pages)
     messages_by_session: Dict[str, List[TranscriptEntry]] = {}
     for msg in messages:
         session_id = getattr(msg, "sessionId", None)
         if session_id:
-            if session_id not in messages_by_session:
-                messages_by_session[session_id] = []
-            messages_by_session[session_id].append(msg)
+            key = get_parent_session_id(session_id)
+            if key not in messages_by_session:
+                messages_by_session[key] = []
+            messages_by_session[key].append(msg)
 
     first_page_path = output_dir / _get_page_html_path(1)
 
@@ -851,11 +1054,14 @@ def _generate_paginated_html(
 
         # Generate HTML for this page
         page_title = f"{title} - Page {page_num}" if page_num > 1 else title
-        html_content = generate_html(
+        page_renderer = HtmlRenderer()
+        page_renderer.shallow = shallow
+        html_content = page_renderer.generate(
             page_messages,
             page_title,
             page_info=page_info,
             page_stats=page_stats,
+            session_tree=session_tree,
         )
         page_file.write_text(html_content, encoding="utf-8")
 
@@ -915,6 +1121,7 @@ def convert_jsonl_to(
     silent: bool = False,
     image_export_mode: Optional[str] = None,
     page_size: int = 2000,
+    shallow: bool = False,
 ) -> Path:
     """Convert JSONL transcript(s) to the specified format.
 
@@ -930,6 +1137,7 @@ def convert_jsonl_to(
         image_export_mode: Image export mode ("placeholder", "embedded", "referenced").
         page_size: Maximum messages per page for combined transcript pagination.
             If None, uses format default (embedded for HTML, referenced for Markdown).
+        shallow: If True, render only user and assistant text messages.
     """
     if not input_path.exists():
         raise FileNotFoundError(f"Input path not found: {input_path}")
@@ -948,11 +1156,21 @@ def convert_jsonl_to(
     # Initialize working_directories for both branches (used by pagination in directory mode)
     working_directories: List[str] = []
 
+    # session_tree is populated in directory mode (DAG already built);
+    # None in single-file mode (renderer builds it on demand)
+    session_tree: Optional[SessionTree] = None
+
     if input_path.is_file():
         # Single file mode - cache only available for directory mode
         if output_path is None:
             output_path = input_path.with_suffix(f".{ext}")
         messages = load_transcript(input_path, silent=silent)
+        # Repair progress chain gaps for single-file mode
+        progress_chain = _scan_progress_chains(input_path)
+        _repair_parent_chains(messages, progress_chain)
+        # Parent agent entries and assign synthetic session IDs (same as
+        # directory mode) so DAG-based ordering handles sidechain placement.
+        _integrate_agent_entries(messages)
         title = f"Claude Transcript - {input_path.stem}"
         cache_was_updated = False  # No cache in single file mode
     else:
@@ -988,7 +1206,7 @@ def convert_jsonl_to(
                     return output_path
 
         # Phase 2: Load messages (will use fresh cache when available)
-        messages = load_directory_transcripts(
+        messages, session_tree = load_directory_transcripts(
             input_path, cache_manager, from_date, to_date, silent
         )
 
@@ -1018,7 +1236,7 @@ def convert_jsonl_to(
 
     # Generate combined output file (check if regeneration needed)
     assert output_path is not None
-    renderer = get_renderer(format, image_export_mode)
+    renderer = get_renderer(format, image_export_mode, shallow=shallow)
 
     # Decide whether to use pagination (HTML only, directory mode, no date filter)
     use_pagination = False
@@ -1047,7 +1265,11 @@ def convert_jsonl_to(
             current_session_ids: set[str] = set()
             for message in messages:
                 session_id = getattr(message, "sessionId", "")
-                if session_id and session_id not in warmup_session_ids:
+                if (
+                    session_id
+                    and session_id not in warmup_session_ids
+                    and not is_agent_session(session_id)
+                ):
                     current_session_ids.add(session_id)
             session_data = {
                 session_id: session_cache
@@ -1065,6 +1287,8 @@ def convert_jsonl_to(
             session_data,
             working_directories,
             silent=silent,
+            session_tree=session_tree,
+            shallow=shallow,
         )
     else:
         # Use single-file generation for small projects or filtered views
@@ -1091,7 +1315,9 @@ def convert_jsonl_to(
         if should_regenerate:
             # For referenced images, pass the output directory
             output_dir = output_path.parent
-            content = renderer.generate(messages, title, output_dir=output_dir)
+            content = renderer.generate(
+                messages, title, output_dir=output_dir, session_tree=session_tree
+            )
             assert content is not None
             output_path.write_text(content, encoding="utf-8")
 
@@ -1117,44 +1343,13 @@ def convert_jsonl_to(
             cache_was_updated,
             image_export_mode,
             silent=silent,
+            session_tree=session_tree,
+            shallow=shallow,
         )
 
     return output_path
 
 
-def has_cache_changes(
-    project_dir: Path,
-    cache_manager: Optional[CacheManager],
-    from_date: Optional[str] = None,
-    to_date: Optional[str] = None,
-) -> bool:
-    """Check if cache needs updating (fast mtime comparison only).
-
-    Returns True if there are modified files or cache is stale.
-    Does NOT load any messages - that's deferred to ensure_fresh_cache.
-    """
-    if cache_manager is None:
-        return True  # No cache means we need to process
-
-    jsonl_files = list(project_dir.glob("*.jsonl"))
-    if not jsonl_files:
-        return False
-
-    # Get cached project data
-    cached_project_data = cache_manager.get_cached_project_data()
-
-    # Check various invalidation conditions
-    modified_files = cache_manager.get_modified_files(jsonl_files)
-
-    return (
-        cached_project_data is None
-        or from_date is not None
-        or to_date is not None
-        or bool(modified_files)
-        or (cached_project_data.total_message_count == 0 and bool(jsonl_files))
-    )
-
-
 def ensure_fresh_cache(
     project_dir: Path,
     cache_manager: Optional[CacheManager],
@@ -1165,7 +1360,6 @@ def ensure_fresh_cache(
     """Ensure cache is fresh and populated. Returns True if cache was updated.
 
     This does the heavy lifting of loading and parsing files.
-    Call has_cache_changes() first for a fast check.
     """
     if cache_manager is None:
         return False
@@ -1201,7 +1395,7 @@ def ensure_fresh_cache(
     # Load and process messages to populate cache
     if not silent:
         print(f"Updating cache for {project_dir.name}...")
-    messages = load_directory_transcripts(
+    messages, _tree = load_directory_transcripts(
         project_dir, cache_manager, from_date, to_date, silent
     )
 
@@ -1271,7 +1465,7 @@ def _update_cache_with_session_data(
         if hasattr(message, "sessionId") and not isinstance(
             message, SummaryTranscriptEntry
         ):
-            session_id = getattr(message, "sessionId", "")
+            session_id = get_parent_session_id(getattr(message, "sessionId", ""))
             if not session_id:
                 continue
 
@@ -1308,7 +1502,7 @@ def _update_cache_with_session_data(
         if message.type == "assistant" and hasattr(message, "message"):
             assistant_message = getattr(message, "message")
             request_id = getattr(message, "requestId", None)
-            session_id = getattr(message, "sessionId", "")
+            session_id = get_parent_session_id(getattr(message, "sessionId", ""))
 
             if (
                 hasattr(assistant_message, "usage")
@@ -1405,13 +1599,14 @@ def _collect_project_sessions(messages: list[TranscriptEntry]) -> list[dict[str,
             ):
                 session_summaries[uuid_to_session_backup[leaf_uuid]] = message.summary
 
-    # Group messages by session (excluding warmup-only sessions)
+    # Group messages by session (excluding warmup-only sessions,
+    # coalescing agent sessions into their parent)
     sessions: dict[str, dict[str, Any]] = {}
     for message in messages:
         if hasattr(message, "sessionId") and not isinstance(
             message, SummaryTranscriptEntry
         ):
-            session_id = getattr(message, "sessionId", "")
+            session_id = get_parent_session_id(getattr(message, "sessionId", ""))
             if not session_id or session_id in warmup_session_ids:
                 continue
 
@@ -1479,6 +1674,8 @@ def _generate_individual_session_files(
     cache_was_updated: bool = False,
     image_export_mode: Optional[str] = None,
     silent: bool = False,
+    session_tree: Optional[SessionTree] = None,
+    shallow: bool = False,
 ) -> int:
     """Generate individual files for each session in the specified format.
 
@@ -1489,12 +1686,16 @@ def _generate_individual_session_files(
     # Pre-compute warmup sessions to exclude them
     warmup_session_ids = get_warmup_session_ids(messages)
 
-    # Find all unique session IDs (excluding warmup sessions)
+    # Find all unique session IDs (excluding warmup and agent sessions)
     session_ids: set[str] = set()
     for message in messages:
         if hasattr(message, "sessionId"):
             session_id: str = getattr(message, "sessionId")
-            if session_id and session_id not in warmup_session_ids:
+            if (
+                session_id
+                and session_id not in warmup_session_ids
+                and not is_agent_session(session_id)
+            ):
                 session_ids.add(session_id)
 
     # Get session data from cache for better titles
@@ -1514,7 +1715,7 @@ def _generate_individual_session_files(
     project_title = get_project_display_name(output_dir.name, working_directories)
 
     # Get renderer once outside the loop
-    renderer = get_renderer(format, image_export_mode)
+    renderer = get_renderer(format, image_export_mode, shallow=shallow)
     regenerated_count = 0
 
     # Generate HTML file for each session
@@ -1577,7 +1778,12 @@ def _generate_individual_session_files(
         if should_regenerate_session:
             # Generate session content
             session_content = renderer.generate_session(
-                messages, session_id, session_title, cache_manager, output_dir
+                messages,
+                session_id,
+                session_title,
+                cache_manager,
+                output_dir,
+                session_tree=session_tree,
             )
             assert session_content is not None
             # Write session file
@@ -1662,6 +1868,7 @@ def process_projects_hierarchy(
     image_export_mode: Optional[str] = None,
     silent: bool = True,
     page_size: int = 2000,
+    shallow: bool = False,
 ) -> Path:
     """Process the entire ~/.claude/projects/ hierarchy and create linked output files.
 
@@ -1818,6 +2025,7 @@ def process_projects_hierarchy(
                     silent=silent,
                     image_export_mode=image_export_mode,
                     page_size=page_size,
+                    shallow=shallow,
                 )
 
                 # Track timing
@@ -1897,7 +2105,7 @@ def process_projects_hierarchy(
             print(
                 f"Warning: No cached data available for {project_dir.name}, using fallback processing"
             )
-            messages = load_directory_transcripts(
+            messages, _tree = load_directory_transcripts(
                 project_dir, cache_manager, from_date, to_date, silent=silent
             )
             # Ensure cache is populated with session data (including working directories)
diff --git a/claude_code_log/dag.py b/claude_code_log/dag.py
new file mode 100644
index 00000000..cf90aa46
--- /dev/null
+++ b/claude_code_log/dag.py
@@ -0,0 +1,650 @@
+"""DAG-based message ordering for Claude Code transcripts.
+
+Replaces timestamp-based ordering with parentUuid → uuid graph traversal.
+Works at the TranscriptEntry level (before factory/rendering).
+
+See dev-docs/dag.md for the full architecture spec.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .models import (
+    TranscriptEntry,
+    SummaryTranscriptEntry,
+    QueueOperationTranscriptEntry,
+    UserTranscriptEntry,
+    AssistantTranscriptEntry,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Data Structures
+# =============================================================================
+
+
+@dataclass
+class MessageNode:
+    """A deduplicated message in the DAG."""
+
+    uuid: str
+    parent_uuid: Optional[str]
+    session_id: str
+    timestamp: str
+    entry: TranscriptEntry
+    children_uuids: list[str] = field(default_factory=lambda: [])
+
+
+@dataclass
+class SessionDAGLine:
+    """A session's ordered chain of unique messages."""
+
+    session_id: str
+    uuids: list[str]  # Ordered by parent→child chain traversal
+    first_timestamp: str
+    parent_session_id: Optional[str] = None
+    attachment_uuid: Optional[str] = None  # UUID in parent where this attaches
+    is_branch: bool = False  # True for within-session fork branches
+    original_session_id: Optional[str] = None  # Original session_id before fork split
+    is_sidechain: bool = False  # True for agent transcript sessions
+
+
+@dataclass
+class JunctionPoint:
+    """A message where other sessions fork or continue."""
+
+    uuid: str
+    session_id: str  # The session this message belongs to
+    target_sessions: list[str] = field(default_factory=lambda: [])
+
+
+@dataclass
+class SessionTree:
+    """The complete session hierarchy for a project."""
+
+    nodes: dict[str, MessageNode]
+    sessions: dict[str, SessionDAGLine]
+    roots: list[str]  # Root session IDs (no parent session)
+    junction_points: dict[str, JunctionPoint]
+
+
+# =============================================================================
+# Step 1: Load and Index
+# =============================================================================
+
+
+def build_message_index(
+    entries: list[TranscriptEntry],
+) -> dict[str, MessageNode]:
+    """Build a deduplicated message index from transcript entries.
+
+    Skips SummaryTranscriptEntry (no uuid/sessionId) and
+    QueueOperationTranscriptEntry (no uuid). For duplicate uuids,
+    keeps the entry from the earliest session (by first entry timestamp).
+    """
+    # First pass: determine earliest timestamp per session
+    session_first_ts: dict[str, str] = {}
+    for entry in entries:
+        if isinstance(entry, (SummaryTranscriptEntry, QueueOperationTranscriptEntry)):
+            continue
+        sid = entry.sessionId
+        ts = entry.timestamp
+        if sid not in session_first_ts or ts < session_first_ts[sid]:
+            session_first_ts[sid] = ts
+
+    # Second pass: build nodes, deduplicating by uuid (earliest session wins)
+    nodes: dict[str, MessageNode] = {}
+    for entry in entries:
+        if isinstance(entry, (SummaryTranscriptEntry, QueueOperationTranscriptEntry)):
+            continue
+        uuid = entry.uuid
+        sid = entry.sessionId
+        if uuid in nodes:
+            existing = nodes[uuid]
+            existing_session_ts = session_first_ts.get(existing.session_id, "")
+            new_session_ts = session_first_ts.get(sid, "")
+            if new_session_ts < existing_session_ts:
+                # Replace with entry from earlier session
+                nodes[uuid] = MessageNode(
+                    uuid=uuid,
+                    parent_uuid=entry.parentUuid,
+                    session_id=sid,
+                    timestamp=entry.timestamp,
+                    entry=entry,
+                )
+        else:
+            nodes[uuid] = MessageNode(
+                uuid=uuid,
+                parent_uuid=entry.parentUuid,
+                session_id=sid,
+                timestamp=entry.timestamp,
+                entry=entry,
+            )
+
+    return nodes
+
+
+# =============================================================================
+# Step 2: Build DAG (parent→children links)
+# =============================================================================
+
+
+def build_dag(
+    nodes: dict[str, MessageNode],
+    sidechain_uuids: set[str] | None = None,
+) -> None:
+    """Populate children_uuids on each node. Mutates nodes in place.
+
+    Warns about orphan nodes (parentUuid points outside loaded data)
+    and validates acyclicity. Parents known to be in unloaded sidechain
+    data (e.g. aprompt_suggestion agents) are silently promoted to root
+    without warning.
+    """
+    _sidechain_uuids = sidechain_uuids or set()
+
+    # Clear existing children
+    for node in nodes.values():
+        node.children_uuids = []
+
+    # Build parent→children links
+    for node in nodes.values():
+        if node.parent_uuid is not None:
+            parent = nodes.get(node.parent_uuid)
+            if parent is not None:
+                parent.children_uuids.append(node.uuid)
+            else:
+                if node.parent_uuid not in _sidechain_uuids:
+                    logger.warning(
+                        "Orphan node %s: parentUuid %s not found in loaded"
+                        " data (promoting to root)",
+                        node.uuid,
+                        node.parent_uuid,
+                    )
+                # Clear the dangling parent so this node becomes a root
+                # and can participate in DAG walks
+                node.parent_uuid = None
+
+    # Validate: no cycles (walk parent chain for each node)
+    for node in nodes.values():
+        visited: set[str] = set()
+        current: Optional[str] = node.uuid
+        while current is not None:
+            if current in visited:
+                logger.warning("Cycle detected in parent chain at uuid %s", current)
+                nodes[current].parent_uuid = None
+                break
+            visited.add(current)
+            parent = nodes.get(current)
+            if parent is None:
+                break
+            current = parent.parent_uuid
+
+
+# =============================================================================
+# Step 3: Extract Session DAG-lines
+# =============================================================================
+
+
+def _collect_descendants(
+    uuid: str,
+    session_uuids: set[str],
+    nodes: dict[str, MessageNode],
+    result: set[str],
+) -> None:
+    """Recursively collect a node and all its same-session descendants."""
+    if uuid in result:
+        return
+    result.add(uuid)
+    node = nodes.get(uuid)
+    if node is None:
+        return
+    for child in node.children_uuids:
+        if child in session_uuids:
+            _collect_descendants(child, session_uuids, nodes, result)
+
+
+def _is_subtree_dead_end(
+    uuid: str,
+    session_uuids: set[str],
+    nodes: dict[str, MessageNode],
+    max_depth: int = 20,
+) -> bool:
+    """Check if a node's subtree eventually terminates (no continuation).
+
+    A subtree is a dead end if every leaf within the session has no
+    same-session children.  Walks depth-first with a depth limit to
+    avoid runaway traversals.
+    """
+    stack: list[tuple[str, int]] = [(uuid, 0)]
+    while stack:
+        current, depth = stack.pop()
+        children = [c for c in nodes[current].children_uuids if c in session_uuids]
+        if not children:
+            continue  # Leaf — dead end, keep checking siblings
+        if depth >= max_depth:
+            return False  # Too deep to tell — assume not dead end
+        for c in children:
+            stack.append((c, depth + 1))
+    return True
+
+
+def _stitch_tool_results(
+    children: list[str],
+    session_uuids: set[str],
+    nodes: dict[str, MessageNode],
+) -> Optional[list[str]]:
+    """Detect and stitch tool-result side-branches into a linear chain.
+
+    When the assistant makes multiple tool calls in one turn, the JSONL
+    records both the next tool_use and the tool_result as children of the
+    current tool_use entry, creating a false fork.  Two variants:
+
+    Variant 1 — User child is immediate dead end:
+        A(tool_use) → U(tool_result)   [dead-end side-branch]
+                    → A(next tool_use) [main chain continues]
+
+    Variant 2 — User child continues, Assistant subtree dead-ends:
+        A(tool_use) → U(tool_result) → A(response) → ...  [main chain]
+                    → A(tool_use) → ... → dead ends       [progress artifact]
+
+    Returns a stitched ordering placing dead-end children first, then
+    the single continuation child.  Returns None if the pattern doesn't
+    match.
+    """
+    # Separate into user (tool_result) and assistant (continuation) children
+    user_children = [
+        c for c in children if isinstance(nodes[c].entry, UserTranscriptEntry)
+    ]
+    assistant_children = [
+        c for c in children if isinstance(nodes[c].entry, AssistantTranscriptEntry)
+    ]
+
+    if not user_children or not assistant_children:
+        return None  # Not the tool_result pattern
+
+    # Check variant 1: all user children are immediate dead ends
+    user_all_dead = all(
+        not any(c in session_uuids for c in nodes[uc].children_uuids)
+        for uc in user_children
+    )
+
+    if user_all_dead:
+        # Variant 1: user dead ends + single assistant continuation
+        if len(assistant_children) != 1:
+            return None
+        user_children.sort(key=lambda c: nodes[c].timestamp)
+        return user_children + assistant_children
+
+    # Check variant 2: assistant subtrees are dead ends,
+    # exactly one user child continues
+    user_with_cont = [
+        uc
+        for uc in user_children
+        if any(c in session_uuids for c in nodes[uc].children_uuids)
+    ]
+    if len(user_with_cont) != 1:
+        return None  # Ambiguous — multiple user continuations
+
+    # Verify all assistant children's subtrees are dead ends
+    for ac in assistant_children:
+        if not _is_subtree_dead_end(ac, session_uuids, nodes):
+            return None
+
+    # Verify remaining user children (without continuation) are dead ends
+    user_dead = [uc for uc in user_children if uc not in user_with_cont]
+    for uc in user_dead:
+        if not _is_subtree_dead_end(uc, session_uuids, nodes):
+            return None
+
+    # Stitch: dead-end children first, then the continuing user child
+    dead_ends = user_dead + assistant_children
+    dead_ends.sort(key=lambda c: nodes[c].timestamp)
+    return dead_ends + user_with_cont
+
+
+def _walk_session_with_forks(
+    root: MessageNode,
+    session_id: str,
+    session_uuids: set[str],
+    nodes: dict[str, MessageNode],
+) -> tuple[list[SessionDAGLine], set[str]]:
+    """Walk a session's DAG from root, splitting into separate DAG-lines at fork points.
+
+    Uses a queue-based approach to handle nested forks:
+    1. Start with (root_uuid, session_id, None) in the queue
+    2. Walk chain following single same-session children
+    3. On fork (multiple same-session children): stop chain at fork point,
+       push each child as a new branch
+    4. Update MessageNode.session_id for branch nodes
+
+    Returns:
+        Tuple of (DAG-line list, set of UUIDs intentionally skipped as
+        compaction replays).
+    """
+    # Queue entries: (start_uuid, dag_line_id, parent_dag_line_id)
+    queue: list[tuple[str, str, Optional[str]]] = [(root.uuid, session_id, None)]
+    result: list[SessionDAGLine] = []
+    skipped: set[str] = set()  # Compaction replay UUIDs
+
+    while queue:
+        start_uuid, line_id, parent_line_id = queue.pop(0)
+        chain: list[str] = []
+        current: Optional[MessageNode] = nodes[start_uuid]
+        is_branch = line_id != session_id
+
+        while current is not None:
+            chain.append(current.uuid)
+            # Update session_id for branch nodes (needed for build_session_tree)
+            if is_branch:
+                current.session_id = line_id
+
+            # Find children in the original session
+            same_session_children = [
+                c for c in current.children_uuids if c in session_uuids
+            ]
+            if len(same_session_children) == 0:
+                current = None
+            elif len(same_session_children) == 1:
+                current = nodes[same_session_children[0]]
+            else:
+                # Multiple same-session children. Distinguish real forks
+                # from artifacts (see dev-docs/dag.md caveats).
+                same_session_children.sort(key=lambda c: nodes[c].timestamp)
+
+                stitched = _stitch_tool_results(
+                    same_session_children, session_uuids, nodes
+                )
+                if stitched is not None:
+                    # Tool-result side-branches were stitched into the
+                    # chain. The last element is the continuation; all
+                    # others are dead-end nodes whose subtree descendants
+                    # must be skipped.
+                    for su in stitched[:-1]:
+                        if is_branch:
+                            nodes[su].session_id = line_id
+                        _collect_descendants(su, session_uuids, nodes, skipped)
+                    chain.extend(stitched[:-1])
+                    current = nodes[stitched[-1]]
+                else:
+                    unique_timestamps = {
+                        nodes[c].timestamp for c in same_session_children
+                    }
+                    if len(unique_timestamps) == 1:
+                        # Same timestamp = compaction replay: follow only
+                        # the first child (original chain), skip replays
+                        # and all their descendants.
+                        current = nodes[same_session_children[0]]
+                        for sc in same_session_children[1:]:
+                            _collect_descendants(sc, session_uuids, nodes, skipped)
+                    else:
+                        # Different timestamps = real fork (rewind).
+                        # Stop chain here, push each child as a branch.
+                        for child_uuid in same_session_children:
+                            branch_id = f"{line_id}@{child_uuid[:12]}"
+                            queue.append((child_uuid, branch_id, line_id))
+                        current = None
+
+        if chain:
+            first_ts = nodes[chain[0]].timestamp
+            dag_line = SessionDAGLine(
+                session_id=line_id,
+                uuids=chain,
+                first_timestamp=first_ts,
+                is_branch=is_branch,
+                original_session_id=session_id if is_branch else None,
+            )
+            # Set parent/attachment for branches
+            if is_branch and parent_line_id is not None:
+                parent_uuid = nodes[chain[0]].parent_uuid
+                dag_line.parent_session_id = parent_line_id
+                dag_line.attachment_uuid = parent_uuid
+            result.append(dag_line)
+
+    return result, skipped
+
+
+def extract_session_dag_lines(
+    nodes: dict[str, MessageNode],
+) -> dict[str, SessionDAGLine]:
+    """Extract per-session ordered chains from the DAG.
+
+    For each session, finds the root node (parent_uuid is null or points
+    to a different session), then walks forward via children_uuids filtering
+    to same-session children.
+
+    Within-session forks (multiple same-session children) produce additional
+    DAG-lines with synthetic IDs (e.g., "s1@child_uuid12").
+    Falls back to timestamp sort only when no root is found.
+    """
+    # Group nodes by session
+    session_nodes: dict[str, list[MessageNode]] = {}
+    for node in nodes.values():
+        session_nodes.setdefault(node.session_id, []).append(node)
+
+    sessions: dict[str, SessionDAGLine] = {}
+    for session_id, snodes in session_nodes.items():
+        session_uuids = {n.uuid for n in snodes}
+
+        # Find root(s): nodes whose parent_uuid is null or outside this session
+        roots = [
+            n
+            for n in snodes
+            if n.parent_uuid is None or n.parent_uuid not in session_uuids
+        ]
+
+        if not roots:
+            logger.warning(
+                "Session %s: no root found, falling back to timestamp sort",
+                session_id,
+            )
+            sorted_nodes = sorted(snodes, key=lambda n: n.timestamp)
+            sessions[session_id] = SessionDAGLine(
+                session_id=session_id,
+                uuids=[n.uuid for n in sorted_nodes],
+                first_timestamp=sorted_nodes[0].timestamp,
+            )
+            continue
+
+        # Sort roots by timestamp (earliest first = primary root)
+        roots.sort(key=lambda n: n.timestamp)
+        if len(roots) > 1:
+            logger.warning(
+                "Session %s: %d roots found, walking all from earliest (%s)",
+                session_id,
+                len(roots),
+                roots[0].uuid,
+            )
+
+        # Walk from ALL roots to maximize coverage (orphan-promoted roots
+        # create disconnected subtrees that must each be walked)
+        dag_lines: list[SessionDAGLine] = []
+        walked_uuids: set[str] = set()
+        skipped_uuids: set[str] = set()
+        for root in roots:
+            if root.uuid in walked_uuids:
+                continue
+            root_lines, root_skipped = _walk_session_with_forks(
+                root, session_id, session_uuids, nodes
+            )
+            for dl in root_lines:
+                walked_uuids.update(dl.uuids)
+            skipped_uuids.update(root_skipped)
+            dag_lines.extend(root_lines)
+
+        # Check coverage: walked + intentionally skipped (compaction replays)
+        covered = len(walked_uuids | skipped_uuids)
+        if covered < len(snodes):
+            logger.warning(
+                "Session %s: DAG walk covers %d of %d nodes, "
+                "falling back to timestamp sort",
+                session_id,
+                covered,
+                len(snodes),
+            )
+            sorted_nodes = sorted(snodes, key=lambda n: n.timestamp)
+            sessions[session_id] = SessionDAGLine(
+                session_id=session_id,
+                uuids=[n.uuid for n in sorted_nodes],
+                first_timestamp=sorted_nodes[0].timestamp,
+            )
+        else:
+            # Merge non-branch DAG-lines that share the same session_id
+            # (happens when multiple roots exist due to orphan promotion)
+            trunk_lines = [dl for dl in dag_lines if dl.session_id == session_id]
+            branch_lines = [dl for dl in dag_lines if dl.session_id != session_id]
+            if trunk_lines:
+                # Merge all trunk lines into one, ordered by first_timestamp
+                trunk_lines.sort(key=lambda dl: dl.first_timestamp)
+                merged_uuids: list[str] = []
+                for tl in trunk_lines:
+                    merged_uuids.extend(tl.uuids)
+                sessions[session_id] = SessionDAGLine(
+                    session_id=session_id,
+                    uuids=merged_uuids,
+                    first_timestamp=trunk_lines[0].first_timestamp,
+                )
+            for dag_line in branch_lines:
+                sessions[dag_line.session_id] = dag_line
+
+    return sessions
+
+
+# =============================================================================
+# Step 4: Build Session Tree
+# =============================================================================
+
+
+def build_session_tree(
+    nodes: dict[str, MessageNode],
+    sessions: dict[str, SessionDAGLine],
+) -> SessionTree:
+    """Build the session hierarchy and identify junction points.
+
+    For each session's DAG-line, the first message's parent_uuid determines
+    the parent session:
+    - null → root session
+    - points to node in different session → child of that session
+    """
+    roots: list[str] = []
+    junction_points: dict[str, JunctionPoint] = {}
+
+    for session_id, dag_line in sessions.items():
+        if not dag_line.uuids:
+            roots.append(session_id)
+            continue
+
+        first_uuid = dag_line.uuids[0]
+        first_node = nodes[first_uuid]
+        parent_uuid = first_node.parent_uuid
+
+        if parent_uuid is None or parent_uuid not in nodes:
+            # Root session (or orphan parent)
+            roots.append(session_id)
+            dag_line.parent_session_id = None
+            dag_line.attachment_uuid = None
+        else:
+            parent_node = nodes[parent_uuid]
+            if parent_node.session_id == session_id:
+                # Parent is in same session - this is a root
+                roots.append(session_id)
+                dag_line.parent_session_id = None
+                dag_line.attachment_uuid = None
+            else:
+                # Child session: attaches to parent session at parent_uuid
+                dag_line.parent_session_id = parent_node.session_id
+                dag_line.attachment_uuid = parent_uuid
+
+                # Record junction point
+                if parent_uuid not in junction_points:
+                    junction_points[parent_uuid] = JunctionPoint(
+                        uuid=parent_uuid,
+                        session_id=parent_node.session_id,
+                    )
+                junction_points[parent_uuid].target_sessions.append(session_id)
+
+    # Order roots chronologically
+    roots.sort(key=lambda sid: sessions[sid].first_timestamp)
+
+    # Order junction point target_sessions chronologically
+    for jp in junction_points.values():
+        jp.target_sessions.sort(key=lambda sid: sessions[sid].first_timestamp)
+
+    return SessionTree(
+        nodes=nodes,
+        sessions=sessions,
+        roots=roots,
+        junction_points=junction_points,
+    )
+
+
+# =============================================================================
+# Step 5: Ordered Traversal
+# =============================================================================
+
+
+def traverse_session_tree(tree: SessionTree) -> list[TranscriptEntry]:
+    """Depth-first traversal of session tree producing rendering order.
+
+    For each session: yields its DAG-line's entries in chain order.
+    Children are visited in chronological order (by first_timestamp).
+    """
+    result: list[TranscriptEntry] = []
+    visited_sessions: set[str] = set()
+
+    def _visit_session(session_id: str) -> None:
+        if session_id in visited_sessions:
+            return
+        visited_sessions.add(session_id)
+
+        dag_line = tree.sessions.get(session_id)
+        if dag_line is None:
+            return
+
+        # Build map: attachment_uuid → [child session IDs] for this session
+        children_at: dict[str, list[str]] = {}
+        for sid, sline in tree.sessions.items():
+            if sline.parent_session_id == session_id and sline.attachment_uuid:
+                children_at.setdefault(sline.attachment_uuid, []).append(sid)
+        for child_sids in children_at.values():
+            child_sids.sort(key=lambda sid: tree.sessions[sid].first_timestamp)
+
+        # Emit entries, visiting child sessions at junction points
+        for uuid in dag_line.uuids:
+            node = tree.nodes[uuid]
+            result.append(node.entry)
+            # After emitting this message, visit any child sessions
+            # that attach here (in chronological order)
+            if uuid in children_at:
+                for child_sid in children_at[uuid]:
+                    _visit_session(child_sid)
+
+    # Visit root sessions in chronological order
+    for root_sid in tree.roots:
+        _visit_session(root_sid)
+
+    return result
+
+
+# =============================================================================
+# Convenience: Full Pipeline
+# =============================================================================
+
+
+def build_dag_from_entries(
+    entries: list[TranscriptEntry],
+    sidechain_uuids: set[str] | None = None,
+) -> SessionTree:
+    """Build a complete SessionTree from raw transcript entries.
+
+    Convenience function that runs Steps 1-4 in sequence.
+    ``sidechain_uuids`` suppresses orphan warnings for parents known
+    to be in unloaded sidechain data (e.g. aprompt_suggestion agents
+    that are never referenced via agentId in the main session).
+    """
+    nodes = build_message_index(entries)
+    build_dag(nodes, sidechain_uuids=sidechain_uuids)
+    sessions = extract_session_dag_lines(nodes)
+    return build_session_tree(nodes, sessions)
diff --git a/claude_code_log/factories/transcript_factory.py b/claude_code_log/factories/transcript_factory.py
index ae3a22d7..f7a8d539 100644
--- a/claude_code_log/factories/transcript_factory.py
+++ b/claude_code_log/factories/transcript_factory.py
@@ -24,6 +24,7 @@
     # Transcript entry types
     AssistantTranscriptEntry,
     MessageType,
+    PassthroughTranscriptEntry,
     QueueOperationTranscriptEntry,
     SummaryTranscriptEntry,
     SystemTranscriptEntry,
@@ -233,6 +234,17 @@ def create_transcript_entry(data: dict[str, Any]) -> TranscriptEntry:
     """
     entry_type = data.get("type")
     creator = ENTRY_CREATORS.get(entry_type)  # type: ignore[arg-type]
-    if creator is None:
-        raise ValueError(f"Unknown transcript entry type: {entry_type}")
-    return creator(data)
+    if creator is not None:
+        return creator(data)
+    # Fall back to PassthroughTranscriptEntry for unknown types with DAG fields
+    if data.get("uuid") and data.get("sessionId"):
+        return PassthroughTranscriptEntry(
+            uuid=data["uuid"],
+            parentUuid=data.get("parentUuid"),
+            sessionId=data["sessionId"],
+            timestamp=data.get("timestamp", ""),
+            type=entry_type,
+            isSidechain=data.get("isSidechain", False),
+            agentId=data.get("agentId"),
+        )
+    raise ValueError(f"Unknown transcript entry type: {entry_type}")
diff --git a/claude_code_log/html/renderer.py b/claude_code_log/html/renderer.py
index 8d22a374..2a48bdd5 100644
--- a/claude_code_log/html/renderer.py
+++ b/claude_code_log/html/renderer.py
@@ -5,6 +5,9 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional, Tuple, cast
 
+if TYPE_CHECKING:
+    from ..dag import SessionTree
+
 from ..cache import get_library_version
 from ..models import (
     AssistantTextMessage,
@@ -516,6 +519,7 @@ def generate(
         title: Optional[str] = None,
         combined_transcript_link: Optional[str] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
         page_info: Optional[dict[str, Any]] = None,
         page_stats: Optional[dict[str, Any]] = None,
     ) -> str:
@@ -528,6 +532,7 @@ def generate(
             output_dir: Optional output directory for referenced images.
             page_info: Optional pagination info (page_number, prev_link, next_link).
             page_stats: Optional page statistics (message_count, date_range, token_summary).
+            session_tree: Optional pre-built SessionTree (avoids rebuilding DAG).
         """
         import time
 
@@ -541,7 +546,9 @@ def generate(
             title = "Claude Transcript"
 
         # Get root messages (tree) and session navigation from format-neutral renderer
-        root_messages, session_nav, _ = generate_template_messages(messages)
+        root_messages, session_nav, _ = generate_template_messages(
+            messages, session_tree=session_tree, shallow=self.shallow
+        )
 
         # Flatten tree via pre-order traversal, formatting content along the way
         with log_timing("Content formatting (pre-order)", t_start):
@@ -579,6 +586,7 @@ def generate_session(
         title: Optional[str] = None,
         cache_manager: Optional["CacheManager"] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
     ) -> str:
         """Generate HTML for a single session."""
         # Filter messages for this session (SummaryTranscriptEntry.sessionId is always None)
@@ -599,6 +607,7 @@ def generate_session(
             title or f"Session {session_id[:8]}",
             combined_transcript_link=combined_link,
             output_dir=output_dir,
+            session_tree=session_tree,
         )
 
     def generate_projects_index(
@@ -645,6 +654,7 @@ def generate_html(
     combined_transcript_link: Optional[str] = None,
     page_info: Optional[dict[str, Any]] = None,
     page_stats: Optional[dict[str, Any]] = None,
+    session_tree: Optional["SessionTree"] = None,
 ) -> str:
     """Generate HTML from transcript messages using Jinja2 templates.
 
@@ -656,6 +666,7 @@ def generate_html(
         combined_transcript_link: Optional link to combined transcript.
         page_info: Optional pagination info (page_number, prev_link, next_link).
         page_stats: Optional page statistics (message_count, date_range, token_summary).
+        session_tree: Optional pre-built SessionTree (avoids rebuilding DAG).
     """
     return HtmlRenderer().generate(
         messages,
@@ -663,6 +674,7 @@ def generate_html(
         combined_transcript_link,
         page_info=page_info,
         page_stats=page_stats,
+        session_tree=session_tree,
     )
 
 
diff --git a/claude_code_log/html/system_formatters.py b/claude_code_log/html/system_formatters.py
index 08807033..fd3a5468 100644
--- a/claude_code_log/html/system_formatters.py
+++ b/claude_code_log/html/system_formatters.py
@@ -88,6 +88,49 @@ def format_session_header_content(content: SessionHeaderMessage) -> str:
         HTML for the session header display
     """
     escaped_title = html.escape(content.title)
+    if content.is_branch and content.parent_message_index is not None:
+        # Branch header: compact with back-reference to fork point
+        # Show session info for cross-session branches (different real session)
+        session_info = ""
+        if content.original_session_id and content.parent_session_id:
+            parent_real_sid = content.parent_session_id.split("@")[0]
+            if content.original_session_id != parent_real_sid:
+                esc_sid = html.escape(content.original_session_id[:8])
+                session_info = (
+                    f' <span class="branch-session">(in Session {esc_sid})</span>'
+                )
+        fork_backref = ""
+        if content.parent_session_summary:
+            escaped_fork = html.escape(content.parent_session_summary)
+            fork_backref = (
+                f'<div class="branch-from">'
+                f'from <a href="#msg-d-{content.parent_message_index}" '
+                f'class="branch-backlink">'
+                f"&#x2442; Fork point &bull; {escaped_fork}</a></div>"
+            )
+        else:
+            fork_backref = (
+                f'<div class="branch-from">'
+                f'from <a href="#msg-d-{content.parent_message_index}" '
+                f'class="branch-backlink">'
+                f"&#x2442; Fork point</a></div>"
+            )
+        return f"{escaped_title}{session_info}{fork_backref}"
+    if content.parent_session_id:
+        parent_label = content.parent_session_summary or content.parent_session_id[:8]
+        escaped_parent = html.escape(parent_label)
+        if content.parent_message_index is not None:
+            link = (
+                f'<a href="#msg-d-{content.parent_message_index}" '
+                f'class="session-backlink">&#x21b3; continues from '
+                f"{escaped_parent}</a>"
+            )
+        else:
+            link = (
+                f'<span class="session-backlink">&#x21b3; continues from '
+                f"{escaped_parent}</span>"
+            )
+        return f"{link}{escaped_title}"
     return escaped_title
 
 
diff --git a/claude_code_log/html/templates/components/global_styles.css b/claude_code_log/html/templates/components/global_styles.css
index eed4503c..c9bcbb75 100644
--- a/claude_code_log/html/templates/components/global_styles.css
+++ b/claude_code_log/html/templates/components/global_styles.css
@@ -38,6 +38,10 @@
     --system-error-color: #f44336;
     --tool-use-color: #4caf50;
 
+    /* Fork/branch structural colors */
+    --fork-point-color: #adb5bd;
+    --branch-point-color: #adb5bd;
+
     /* Question/answer tool colors */
     --question-accent: #f5a623;
     --question-bg: #fffbf0;
@@ -230,6 +234,21 @@ pre {
     bottom: 200px;
 }
 
+.debug-toggle.floating-btn {
+    bottom: 260px;
+    border-radius: 6px;
+    width: 38px;
+    height: 28px;
+    font-size: 0.65em;
+    font-family: 'SFMono-Regular', Consolas, monospace;
+    font-weight: 600;
+}
+
+.debug-toggle.floating-btn.active {
+    background-color: #d4e8f7;
+    color: #333;
+}
+
 @media (max-width: 1280px) {
     .header > span:first-child {
         flex: auto;
diff --git a/claude_code_log/html/templates/components/message_styles.css b/claude_code_log/html/templates/components/message_styles.css
index abdd30c4..966bf3b9 100644
--- a/claude_code_log/html/templates/components/message_styles.css
+++ b/claude_code_log/html/templates/components/message_styles.css
@@ -565,6 +565,26 @@
     font-size: 1.2em;
 }
 
+/* Branch headers (within-session forks) — indent set via inline
+   style based on tree depth (margin-left: depth*2em). */
+.branch-header {
+    background-color: transparent;
+    box-shadow: none;
+    border: none;
+    border-left: 3px solid var(--branch-point-color);
+    padding: 8px 14px;
+    margin: 2em 0 1em 0;
+}
+
+.branch-header .header {
+    font-size: 1em;
+    margin-bottom: 0;
+}
+
+.branch-header .fold-bar[data-border-color="session-header"] .fold-bar-section.folded {
+    border-bottom-color: var(--branch-point-color);
+}
+
 .session-subtitle {
     font-size: 0.9em;
     color: var(--text-muted);
@@ -892,6 +912,20 @@ details summary {
 .ansi-bg-cyan { background-color: #11a8cd; }
 .ansi-bg-white { background-color: #e5e5e5; }
 
+/* Debug UUID info */
+.debug-info {
+    display: none;
+    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+    font-size: 0.7em;
+    color: #999;
+    padding: 2px 0;
+    letter-spacing: 0.02em;
+}
+
+.show-debug-info .debug-info {
+    display: block;
+}
+
 /* Bright background colors */
 .ansi-bg-bright-black { background-color: #666666; }
 .ansi-bg-bright-red { background-color: #f14c4c; }
diff --git a/claude_code_log/html/templates/components/session_nav.html b/claude_code_log/html/templates/components/session_nav.html
index 143d4a89..4316b5bd 100644
--- a/claude_code_log/html/templates/components/session_nav.html
+++ b/claude_code_log/html/templates/components/session_nav.html
@@ -12,26 +12,50 @@ <h2>Session Navigation</h2>
 
     <div class='session-nav'>
         {% for session in sessions %}
-        <a href='{{ link_prefix }}{% if mode == "expandable" %}session-{{ session.id }}.html{% else %}#msg-d-{{ session.message_index }}{% endif %}'
-            class='session-link'>
-            <div class='session-link-title'>
-                {% if session.summary %}
-                {{ session.summary }} •
-                {% endif %}
-                {{ session.id[:8] }}
-            </div>
-            <div class='session-link-meta'>
-                <span class="timestamp"{% if session.first_timestamp %} data-timestamp="{{ session.first_timestamp }}"{% endif %}{% if session.last_timestamp and session.last_timestamp != session.first_timestamp %} data-timestamp-end="{{ session.last_timestamp }}"{% endif %}>{{ session.timestamp_range }}</span> • {{ session.message_count }} messages
-                {% if session.token_summary %}
-                <br>{{ session.token_summary }}
-                {% endif %}
-            </div>
-            {% if session.first_user_message %}
-            <pre class='session-preview'>
-                {{- session.first_user_message|e -}}
-            </pre>
+        {% if session.is_fork_point is defined and session.is_fork_point %}
+        <div class='session-nav-item session-fork-point'
+            style='margin-left: {{ session.depth * 24 }}px'>
+            <a href='#msg-d-{{ session.message_index }}' class='fork-link'>
+                &#x2442; {{ session.first_user_message }}
+            </a>
+        </div>
+        {% elif session.is_branch is defined and session.is_branch %}
+        <div class='session-nav-item session-branch'
+            style='margin-left: {{ session.depth * 24 }}px'>
+            <a href='#msg-d-{{ session.message_index }}' class='branch-link'>
+                &#x21b3; {{ session.first_user_message }}
+            </a>
+        </div>
+        {% else %}
+        <div class='session-nav-item{% if session.depth|default(0) > 0 %} session-child{% endif %}'
+            {% if session.depth|default(0) > 0 %}style='margin-left: {{ session.depth * 24 }}px'{% endif %}>
+            {% if session.parent_session_id and mode == "toc" and session.parent_message_index is defined and session.parent_message_index is not none %}
+            <a href='#msg-d-{{ session.parent_message_index }}' class='session-backlink'>&#x21b3; continues from {{ session.parent_session_id[:8] }}</a>
+            {% elif session.parent_session_id %}
+            <span class='session-backlink'>&#x21b3; continues from {{ session.parent_session_id[:8] }}</span>
             {% endif %}
-        </a>
+            <a href='{{ link_prefix }}{% if mode == "expandable" %}session-{{ session.id }}.html{% else %}#msg-d-{{ session.message_index }}{% endif %}'
+                class='session-link'>
+                <div class='session-link-title'>
+                    {% if session.summary %}
+                    {{ session.summary }} •
+                    {% endif %}
+                    {{ session.id[:8] }}
+                </div>
+                <div class='session-link-meta'>
+                    <span class="timestamp"{% if session.first_timestamp %} data-timestamp="{{ session.first_timestamp }}"{% endif %}{% if session.last_timestamp and session.last_timestamp != session.first_timestamp %} data-timestamp-end="{{ session.last_timestamp }}"{% endif %}>{{ session.timestamp_range }}</span> • {{ session.message_count }} messages
+                    {% if session.token_summary %}
+                    <br>{{ session.token_summary }}
+                    {% endif %}
+                </div>
+                {% if session.first_user_message %}
+                <pre class='session-preview'>
+                    {{- session.first_user_message|e -}}
+                </pre>
+                {% endif %}
+            </a>
+        </div>
+        {% endif %}
         {% endfor %}
     </div>
 </div>
diff --git a/claude_code_log/html/templates/components/session_nav_styles.css b/claude_code_log/html/templates/components/session_nav_styles.css
index a69c4d35..2216b535 100644
--- a/claude_code_log/html/templates/components/session_nav_styles.css
+++ b/claude_code_log/html/templates/components/session_nav_styles.css
@@ -24,6 +24,7 @@
 }
 
 .session-link {
+    display: block;
     padding: 8px 12px;
     background-color: var(--white-dimmed);
     border: 1px solid #dee2e6;
@@ -48,6 +49,25 @@
     margin-top: 2px;
 }
 
+/* Child session hierarchy */
+.session-nav-item.session-child {
+    border-left: 3px solid var(--accent-color, #6c757d);
+    padding-left: 8px;
+}
+
+.session-backlink {
+    font-size: 0.75em;
+    color: #6c757d;
+    display: block;
+    margin-bottom: 2px;
+    text-decoration: none;
+}
+
+a.session-backlink:hover {
+    color: var(--text-secondary);
+    text-decoration: underline;
+}
+
 /* Project-specific session navigation */
 .project-sessions {
     margin-top: 15px;
@@ -103,4 +123,84 @@
 .session-preview {
     font-size: 0.75em;
     line-height: 1.3;
+}
+
+/* Fork point element — standalone structural element after a fork message */
+.fork-point {
+    margin: 8px 0 2em 0;
+    padding: 8px 14px;
+    font-size: 0.85em;
+    color: var(--text-muted, #6c757d);
+    border-left: 3px solid var(--fork-point-color);
+    border-radius: 8px;
+}
+
+.fork-point-header {
+    font-weight: 600;
+    margin-bottom: 4px;
+    color: var(--text-secondary, #495057);
+}
+
+.fork-point-branches {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding-left: 12px;
+}
+
+.fork-point-branch {
+    display: block;
+    text-decoration: none;
+    color: var(--text-muted, #6c757d);
+    padding: 2px 0;
+    transition: color 0.2s;
+}
+
+.fork-point-branch:hover {
+    color: var(--text-secondary, #495057);
+}
+
+/* Branch header back-reference to fork point */
+.branch-from {
+    font-size: 0.85em;
+    color: var(--text-muted, #6c757d);
+    margin-top: 2px;
+}
+
+.branch-backlink {
+    text-decoration: none;
+    color: var(--text-muted, #6c757d);
+    transition: color 0.2s;
+}
+
+.branch-backlink:hover {
+    color: var(--text-secondary, #495057);
+}
+
+/* Fork point and branch nav items — lightweight text links, not cards */
+.session-fork-point,
+.session-branch {
+    padding-left: 8px;
+}
+
+.session-fork-point {
+    border-left: 2px dashed #888;
+}
+
+.session-branch {
+    border-left: 2px dashed #666;
+}
+
+.fork-link,
+.branch-link {
+    display: block;
+    text-decoration: none;
+    color: #6c757d;
+    padding: 2px 0;
+    font-size: 0.85em;
+}
+
+.fork-link:hover,
+.branch-link:hover {
+    color: var(--text-secondary);
 }
\ No newline at end of file
diff --git a/claude_code_log/html/templates/transcript.html b/claude_code_log/html/templates/transcript.html
index 5863b50c..9a1564cf 100644
--- a/claude_code_log/html/templates/transcript.html
+++ b/claude_code_log/html/templates/transcript.html
@@ -98,9 +98,9 @@ <h3>🔍 Search & Filter</h3>
 
     {% for message, message_title, html_content, formatted_timestamp in messages %}
     {% if is_session_header(message) %}
-    <div class="session-divider"></div>
-    <div class='message session-header' data-message-id='{{ message.message_id }}' data-session-id='{{ message.session_id }}' id='msg-{{ message.message_id }}'>
-        <div class='header'>Session: {{ html_content }}</div>
+    {% if not message.is_branch_header %}<div class="session-divider"></div>{% endif %}
+    <div class='message session-header{% if message.is_branch_header %} branch-header{% endif %}' data-message-id='{{ message.message_id }}' data-session-id='{{ message.session_id }}' id='msg-{{ message.message_id }}'{% if message.branch_depth %} style='margin-left: {{ message.branch_depth * 2 }}em'{% endif %}>
+        <div class='header'>{% if message.is_branch_header %}&#x21b3; {% else %}Session: {% endif %}{{ html_content|safe }}</div>
         {% if message.has_children %}
         <div class='fold-bar' data-message-id='{{ message.message_id }}' data-border-color='session-header'>
             {% if message.immediate_children_count == message.total_descendants_count %}
@@ -141,6 +141,7 @@ <h3>🔍 Search & Filter</h3>
                 {% endif %}
             </div>
         </div>
+        {% if message.meta %}<div class='debug-info'>{{ message.meta.uuid[:12] }}{% if message.meta.parent_uuid %} &rarr; {{ message.meta.parent_uuid[:12] }}{% endif %}</div>{% endif %}
         <div class='content{% if markdown %} markdown{% endif %}'>{{ html_content | safe }}</div>
         {% if message.has_children %}
         <div class='fold-bar' data-message-id='{{ message.message_id }}' data-border-color='{{ msg_css_class }}'>
@@ -165,11 +166,23 @@ <h3>🔍 Search & Filter</h3>
         {% endif %}
     </div>
     {% endif %}
+    {% if message.junction_forward_links %}
+    {# Fork point element — rendered OUTSIDE the message box as a structural navigation element #}
+    <div class='fork-point{% for ancestor_index in message.ancestry %} d-{{ ancestor_index }}{% endfor %}'>
+        <div class='fork-point-header'>&#x2442; Fork point{% if message.fork_point_preview %} &bull; {{ message.fork_point_preview }}{% endif %}</div>
+        <div class='fork-point-branches'>
+            {% for branch_sid, branch_idx, branch_preview in message.junction_forward_links %}
+            <a href='#msg-d-{{ branch_idx }}' class='fork-point-branch'>&#x21b3; Branch{% if branch_preview %} &bull; {{ branch_preview }}{% endif %}</a>
+            {% endfor %}
+        </div>
+    </div>
+    {% endif %}
     {% endfor %}
 
     <button class="timeline-toggle floating-btn" id="toggleTimeline" title="Show timeline">📆</button>
     <button class="filter-messages floating-btn" id="filterMessages" title="Search & Filter">🔍</button>
     <button class="toggle-details floating-btn" id="toggleDetails" title="Toggle all details">📋</button>
+    <button class="debug-toggle floating-btn" id="toggleDebug" title="Show UUIDs">uuid</button>
     <a class="scroll-top floating-btn" title="Scroll to top" href="#title">🔝</a>
 
     <script>
@@ -177,6 +190,7 @@ <h3>🔍 Search & Filter</h3>
             const toggleButton = document.getElementById('toggleDetails');
             const timelineButton = document.getElementById('toggleTimeline');
             const filterButton = document.getElementById('filterMessages');
+            const debugButton = document.getElementById('toggleDebug');
             const filterToolbar = document.querySelector('.filter-toolbar');
             const selectAllButton = document.getElementById('selectAll');
             const selectNoneButton = document.getElementById('selectNone');
@@ -186,6 +200,12 @@ <h3>🔍 Search & Filter</h3>
             // Timezone conversion (included as component)
             {% include 'components/timezone_converter.js' %}
 
+            // Debug UUID toggle
+            debugButton.addEventListener('click', function () {
+                document.body.classList.toggle('show-debug-info');
+                debugButton.classList.toggle('active');
+            });
+
             // Parse URL parameters
             function getUrlParams() {
                 const params = new URLSearchParams(window.location.search);
diff --git a/claude_code_log/markdown/renderer.py b/claude_code_log/markdown/renderer.py
index 23c7e411..31e3fbbe 100644
--- a/claude_code_log/markdown/renderer.py
+++ b/claude_code_log/markdown/renderer.py
@@ -68,6 +68,7 @@
 
 if TYPE_CHECKING:
     from ..cache import CacheManager
+    from ..dag import SessionTree
 
 
 class MarkdownRenderer(Renderer):
@@ -867,6 +868,7 @@ def generate(
         title: Optional[str] = None,
         combined_transcript_link: Optional[str] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
     ) -> str:
         """Generate Markdown from transcript messages."""
         self._output_dir = output_dir
@@ -876,7 +878,9 @@ def generate(
             title = "Claude Transcript"
 
         # Get root messages (tree), session navigation, and rendering context
-        root_messages, session_nav, ctx = generate_template_messages(messages)
+        root_messages, session_nav, ctx = generate_template_messages(
+            messages, session_tree=session_tree, shallow=self.shallow
+        )
         self._ctx = ctx
 
         parts = [f"<!-- Generated by claude-code-log v{get_library_version()} -->", ""]
@@ -905,6 +909,7 @@ def generate_session(
         title: Optional[str] = None,
         cache_manager: Optional["CacheManager"] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
     ) -> str:
         """Generate Markdown for a single session."""
         session_messages = [msg for msg in messages if msg.sessionId == session_id]
@@ -914,6 +919,7 @@ def generate_session(
             title or f"Session {session_id[:8]}",
             combined_transcript_link=combined_link,
             output_dir=output_dir,
+            session_tree=session_tree,
         )
 
     def generate_projects_index(
diff --git a/claude_code_log/models.py b/claude_code_log/models.py
index 47278945..0ae70e87 100644
--- a/claude_code_log/models.py
+++ b/claude_code_log/models.py
@@ -220,12 +220,31 @@ class QueueOperationTranscriptEntry(BaseModel):
     )
 
 
+class PassthroughTranscriptEntry(BaseModel):
+    """Structural-only entry for DAG chain continuity.
+
+    Captures entries like "attachment", "permission-mode", etc. that have
+    uuid/parentUuid and participate in the DAG chain but are not rendered.
+    Without these, messages whose parentUuid points to a dropped entry
+    become false roots in the DAG.
+    """
+
+    uuid: str
+    parentUuid: Optional[str] = None
+    sessionId: str
+    timestamp: str
+    type: Optional[str] = None  # Original type (e.g. "attachment")
+    isSidechain: bool = False
+    agentId: Optional[str] = None
+
+
 TranscriptEntry = Union[
     UserTranscriptEntry,
     AssistantTranscriptEntry,
     SummaryTranscriptEntry,
     SystemTranscriptEntry,
     QueueOperationTranscriptEntry,
+    PassthroughTranscriptEntry,
 ]
 
 
@@ -655,12 +674,21 @@ class SessionHeaderMessage(MessageContent):
     """Content for session headers in transcript rendering.
 
     Represents the header displayed at the start of each session
-    with session title and optional summary.
+    with session title and optional summary. Includes hierarchy
+    fields for parent/child session relationships.
     """
 
     title: str
     session_id: str
     summary: Optional[str] = None
+    parent_session_id: Optional[str] = None
+    parent_session_summary: Optional[str] = None
+    parent_message_index: Optional[int] = None  # d-{N} index for backlink
+    depth: int = 0  # 0 = root, 1 = child, etc.
+    attachment_uuid: Optional[str] = None
+    is_branch: bool = False  # True for within-session fork branches
+    original_session_id: Optional[str] = None  # Original session_id before fork split
+    first_uuid: Optional[str] = None  # First UUID in this branch (for forward links)
 
     @property
     def message_type(self) -> str:
diff --git a/claude_code_log/renderer.py b/claude_code_log/renderer.py
index 1f3c3496..794ca151 100644
--- a/claude_code_log/renderer.py
+++ b/claude_code_log/renderer.py
@@ -12,16 +12,20 @@
 
 if TYPE_CHECKING:
     from .cache import CacheManager
+    from .dag import SessionTree
 
 from .models import (
     MessageContent,
     MessageMeta,
     MessageType,
     TranscriptEntry,
+    AssistantMessageModel,
     AssistantTranscriptEntry,
+    PassthroughTranscriptEntry,
     SystemTranscriptEntry,
     SummaryTranscriptEntry,
     QueueOperationTranscriptEntry,
+    UserMessageModel,
     UserTranscriptEntry,
     ContentItem,
     TextContent,
@@ -65,7 +69,9 @@
 from .utils import (
     format_timestamp,
     format_timestamp_range,
+    get_parent_session_id,
     get_project_display_name,
+    is_agent_session,
     should_skip_message,
     should_use_as_session_starter,
     create_session_preview,
@@ -100,6 +106,9 @@ class RenderingContext:
     session_first_message: dict[str, int] = field(
         default_factory=lambda: {}  # type: dict[str, int]
     )
+    junction_targets: dict[str, list[str]] = field(
+        default_factory=lambda: {}  # type: dict[str, list[str]]
+    )
 
     def register(self, message: "TemplateMessage") -> int:
         """Register a TemplateMessage and assign its message_index.
@@ -185,6 +194,16 @@ def __init__(
         # Children for tree-based rendering
         self.children: list["TemplateMessage"] = []
 
+        # Within-session fork tracking: effective session/branch ID for grouping
+        self._render_session_id: Optional[str] = None
+
+        # Junction forward links: [(branch_sid, branch_header_msg_index, branch_preview)]
+        # Set on messages that are fork points, for rendering forward links
+        self.junction_forward_links: list[tuple[str, Optional[int], str]] = []
+
+        # Fork point preview text (short excerpt of fork point message content)
+        self.fork_point_preview: str = ""
+
     # -- Properties derived from content/meta --
 
     @property
@@ -197,6 +216,18 @@ def is_session_header(self) -> bool:
         """Check if this message is a session header."""
         return isinstance(self.content, SessionHeaderMessage)
 
+    @property
+    def is_branch_header(self) -> bool:
+        """Check if this is a branch (within-session fork) header."""
+        return isinstance(self.content, SessionHeaderMessage) and self.content.is_branch
+
+    @property
+    def branch_depth(self) -> int:
+        """Depth of this branch header in the session tree (0 for non-branches)."""
+        if isinstance(self.content, SessionHeaderMessage) and self.content.is_branch:
+            return self.content.depth
+        return 0
+
     @property
     def has_children(self) -> bool:
         """Check if this message has any children."""
@@ -248,6 +279,19 @@ def session_id(self) -> str:
         """Get session_id from meta."""
         return self.meta.session_id
 
+    @property
+    def render_session_id(self) -> str:
+        """Get effective session/branch ID for grouping.
+
+        Returns render_session_id if set (for within-session fork branches),
+        otherwise falls back to meta.session_id.
+        """
+        return self._render_session_id or self.meta.session_id
+
+    @render_session_id.setter
+    def render_session_id(self, value: str) -> None:
+        self._render_session_id = value
+
     @property
     def parent_uuid(self) -> Optional[str]:
         """Get parent_uuid from meta."""
@@ -524,6 +568,8 @@ def __init__(self, project_summaries: list[dict[str, Any]]):
 
 def generate_template_messages(
     messages: list[TranscriptEntry],
+    session_tree: Optional["SessionTree"] = None,
+    shallow: bool = False,
 ) -> Tuple[list[TemplateMessage], list[dict[str, Any]], RenderingContext]:
     """Generate root messages and session navigation from transcript messages.
 
@@ -532,6 +578,8 @@ def generate_template_messages(
 
     Args:
         messages: List of transcript entries to process.
+        session_tree: Optional pre-built SessionTree from DAG construction.
+            When provided, avoids an expensive DAG rebuild.
 
     Returns:
         A tuple of (root_messages, session_nav, context) where:
@@ -558,10 +606,21 @@ def generate_template_messages(
     with log_timing("Session summary processing", t_start):
         session_summaries = prepare_session_summaries(messages)
 
+    # Extract session hierarchy from DAG (reuse pre-built tree when available)
+    with log_timing("Extract session hierarchy", t_start):
+        session_hierarchy, junction_targets = _extract_session_hierarchy(
+            messages, session_tree=session_tree
+        )
+
     # Filter messages (removes summaries, warmup, empty, etc.)
     with log_timing("Filter messages", t_start):
         filtered_messages = _filter_messages(messages)
 
+    # Shallow mode: keep only user and assistant text messages (no tools, system, thinking)
+    if shallow:
+        with log_timing("Shallow filter", t_start):
+            filtered_messages = _filter_shallow(filtered_messages)
+
     # Pass 1: Collect session metadata and token tracking
     with log_timing("Collect session info", t_start):
         sessions, session_order, show_tokens_for_message = _collect_session_info(
@@ -573,14 +632,71 @@ def generate_template_messages(
     with log_timing(
         lambda: f"Render messages ({len(ctx.messages) if ctx else 0} messages)", t_start
     ):
-        ctx = _render_messages(filtered_messages, sessions, show_tokens_for_message)
+        ctx = _render_messages(
+            filtered_messages,
+            sessions,
+            show_tokens_for_message,
+            session_hierarchy,
+            session_summaries,
+            junction_targets,
+        )
+
+    # Populate junction forward links on fork-point messages
+    if ctx.junction_targets:
+        # Build UUID → TemplateMessage index for fast lookup
+        uuid_to_msg: dict[str, TemplateMessage] = {}
+        # Build msg_index → TemplateMessage for branch preview lookup
+        idx_to_msg: dict[int, TemplateMessage] = {}
+        for msg in ctx.messages:
+            if msg.meta.uuid:
+                uuid_to_msg[msg.meta.uuid] = msg
+            if msg.message_index is not None:
+                idx_to_msg[msg.message_index] = msg
+        for uuid, target_sids in ctx.junction_targets.items():
+            # Only add forward links for within-session fork branches
+            branch_targets = [sid for sid in target_sids if "@" in sid]
+            if branch_targets and uuid in uuid_to_msg:
+                fork_msg = uuid_to_msg[uuid]
+                fork_msg.fork_point_preview = _fork_point_preview(fork_msg, ctx)
+                for branch_sid in branch_targets:
+                    branch_idx = ctx.session_first_message.get(branch_sid)
+                    if branch_idx is not None:
+                        # Get branch preview from the branch header title
+                        branch_preview = ""
+                        branch_header = idx_to_msg.get(branch_idx)
+                        if branch_header and isinstance(
+                            branch_header.content, SessionHeaderMessage
+                        ):
+                            # Extract preview from branch title (e.g. "Branch • preview...")
+                            title = branch_header.content.title
+                            if " • " in title:
+                                preview = title.split(" • ", 1)[1]
+                                # Distinguish real content from UUID fallback
+                                uuid_fragment = branch_sid.split("@")[-1][:8]
+                                if preview != uuid_fragment:
+                                    branch_preview = preview
+                        fork_msg.junction_forward_links.append(
+                            (branch_sid, branch_idx, branch_preview)
+                        )
+                # Elide fork points without at least 2 non-empty branches
+                non_empty = sum(1 for _, _, p in fork_msg.junction_forward_links if p)
+                if non_empty < 2:
+                    fork_msg.junction_forward_links.clear()
+                    fork_msg.fork_point_preview = ""
+
+    # Shallow post-render: remove text-derived types (bash, slash commands, etc.)
+    if shallow:
+        with log_timing("Shallow post-render filter", t_start):
+            ctx.messages = _filter_shallow_template_messages(ctx.messages)
 
     # Prepare session navigation data (uses ctx for session header indices)
     session_nav: list[dict[str, Any]] = []
     with log_timing(
         lambda: f"Session navigation building ({len(session_nav)} sessions)", t_start
     ):
-        session_nav = prepare_session_navigation(sessions, session_order, ctx)
+        session_nav = prepare_session_navigation(
+            sessions, session_order, ctx, session_hierarchy
+        )
 
     # Reorder messages so each session's messages follow their session header
     # This fixes interleaving that occurs when sessions are resumed
@@ -595,11 +711,6 @@ def generate_template_messages(
     with log_timing("Reorder paired messages", t_start):
         template_messages = _reorder_paired_messages(template_messages)
 
-    # Reorder sidechains to appear after their Task results
-    # This must happen AFTER pair reordering, since that moves tool_results
-    with log_timing("Reorder sidechain messages", t_start):
-        template_messages = _reorder_sidechain_template_messages(template_messages)
-
     # Build hierarchy (message_id and ancestry) based on final order
     # This must happen AFTER all reordering to get correct parent-child relationships
     with log_timing("Build message hierarchy", t_start):
@@ -627,6 +738,59 @@ def generate_template_messages(
 # -- Session Utilities --------------------------------------------------------
 
 
+def _extract_session_hierarchy(
+    messages: list[TranscriptEntry],
+    session_tree: Optional["SessionTree"] = None,
+) -> tuple[dict[str, dict[str, Any]], dict[str, list[str]]]:
+    """Extract session hierarchy from DAG for rendering.
+
+    Args:
+        messages: Transcript entries (used to build DAG if tree not provided).
+        session_tree: Pre-built SessionTree to reuse (avoids expensive rebuild).
+
+    Returns:
+        (hierarchy, junction_targets) where:
+        - hierarchy: session_id -> {parent_session_id, attachment_uuid, depth}
+        - junction_targets: uuid -> [target session IDs]
+    """
+    if session_tree is not None:
+        tree = session_tree
+    else:
+        from .dag import build_dag_from_entries
+
+        tree = build_dag_from_entries(messages)
+
+    depth_cache: dict[str, int] = {}
+
+    def _depth(sid: str) -> int:
+        if sid in depth_cache:
+            return depth_cache[sid]
+        dl = tree.sessions.get(sid)
+        if dl is None or dl.parent_session_id is None:
+            depth_cache[sid] = 0
+            return 0
+        d = 1 + _depth(dl.parent_session_id)
+        depth_cache[sid] = d
+        return d
+
+    hierarchy: dict[str, dict[str, Any]] = {}
+    for sid, dag_line in tree.sessions.items():
+        hierarchy[sid] = {
+            "parent_session_id": dag_line.parent_session_id,
+            "attachment_uuid": dag_line.attachment_uuid,
+            "depth": _depth(sid),
+            "is_branch": dag_line.is_branch,
+            "original_session_id": dag_line.original_session_id,
+            "first_uuid": dag_line.uuids[0] if dag_line.uuids else None,
+        }
+
+    junction_targets: dict[str, list[str]] = {}
+    for uuid, jp in tree.junction_points.items():
+        junction_targets[uuid] = jp.target_sessions
+
+    return hierarchy, junction_targets
+
+
 def prepare_session_summaries(messages: list[TranscriptEntry]) -> dict[str, str]:
     """Extract session summaries from messages.
 
@@ -665,10 +829,53 @@ def prepare_session_summaries(messages: list[TranscriptEntry]) -> dict[str, str]
     return session_summaries
 
 
+def _fork_point_preview(fork_msg: "TemplateMessage", ctx: RenderingContext) -> str:
+    """Get a meaningful preview for a fork point message.
+
+    If the fork point is a system hook (common with /rewind), walk up
+    to the parent message to find more descriptive content.
+    """
+    msg = fork_msg
+    # Walk up past system hooks to find a meaningful message
+    for _ in range(3):  # limit walk depth
+        if not isinstance(
+            msg.content, (SystemMessage, HookSummaryMessage, SessionHeaderMessage)
+        ):
+            break
+        # Find parent by looking at parent_uuid
+        parent_uuid = msg.meta.parent_uuid
+        if not parent_uuid:
+            break
+        parent = next((m for m in ctx.messages if m.meta.uuid == parent_uuid), None)
+        if parent is None:
+            break
+        msg = parent
+
+    # Extract text from the found message
+    content = msg.content
+    if isinstance(content, AssistantTextMessage):
+        parts = [item.text for item in content.items if isinstance(item, TextContent)]
+        text = " ".join(parts).strip()
+    elif isinstance(content, UserTextMessage):
+        parts = [item.text for item in content.items if isinstance(item, TextContent)]
+        text = " ".join(parts).strip()
+    else:
+        return ""
+
+    if not text:
+        return ""
+    # Truncate for nav display
+    short = text[:80]
+    if len(text) > 80:
+        short += "..."
+    return short
+
+
 def prepare_session_navigation(
     sessions: dict[str, dict[str, Any]],
     session_order: list[str],
     ctx: RenderingContext,
+    session_hierarchy: dict[str, dict[str, Any]] | None = None,
 ) -> list[dict[str, Any]]:
     """Prepare session navigation data for template rendering.
 
@@ -676,6 +883,7 @@ def prepare_session_navigation(
         sessions: Dictionary mapping session_id to session info dict
         session_order: List of session IDs in display order
         ctx: RenderingContext with session_first_message indices
+        session_hierarchy: Optional hierarchy data from _extract_session_hierarchy()
 
     Returns:
         List of session navigation dicts for template rendering
@@ -683,6 +891,9 @@ def prepare_session_navigation(
     session_nav: list[dict[str, Any]] = []
 
     for session_id in session_order:
+        # Skip agent sidechain sessions (they appear inline, not in nav)
+        if is_agent_session(session_id):
+            continue
         session_info = sessions[session_id]
 
         # Skip empty sessions (agent-only, no user messages)
@@ -716,6 +927,13 @@ def prepare_session_navigation(
         # Get message_index for session header (for unified d-{index} links)
         message_index = ctx.session_first_message.get(session_id)
 
+        # Get hierarchy data
+        hier = (session_hierarchy or {}).get(session_id, {})
+        parent_sid = hier.get("parent_session_id")
+        parent_message_index = (
+            ctx.session_first_message.get(parent_sid) if parent_sid else None
+        )
+
         session_nav.append(
             {
                 "id": session_id,
@@ -729,9 +947,122 @@ def prepare_session_navigation(
                 if session_info["first_user_message"] != ""
                 else "[No user message found in session.]",
                 "token_summary": token_summary,
+                "parent_session_id": parent_sid,
+                "parent_message_index": parent_message_index,
+                "depth": hier.get("depth", 0),
             }
         )
 
+    # Add branch pseudo-sessions from hierarchy
+    if session_hierarchy:
+        # Collect first user message preview for each branch
+        branch_previews: dict[str, str] = {}
+        for msg in ctx.messages:
+            rsid = msg.render_session_id
+            if rsid in branch_previews or not isinstance(msg.content, UserTextMessage):
+                continue
+            hier = session_hierarchy.get(rsid, {})
+            if hier.get("is_branch"):
+                # Extract text from UserTextMessage items
+                preview_parts: list[str] = []
+                for item in msg.content.items:
+                    if isinstance(item, TextContent):
+                        preview_parts.append(item.text)
+                preview = " ".join(preview_parts).strip()
+                if preview:
+                    branch_previews[rsid] = create_session_preview(preview)
+
+        # Group branches by their junction point (attachment_uuid)
+        junction_branches: dict[str, list[dict[str, Any]]] = {}
+        for sid, hier in session_hierarchy.items():
+            if hier.get("is_branch"):
+                attachment = hier.get("attachment_uuid", "")
+                junction_branches.setdefault(attachment, []).append(
+                    {"sid": sid, **hier}
+                )
+
+        # For each junction point, insert fork-point and branch nav items
+        for attachment_uuid, branches in junction_branches.items():
+            # Find the session nav item that contains this junction
+            parent_sid = branches[0].get("parent_session_id", "")
+            parent_nav_idx = next(
+                (i for i, n in enumerate(session_nav) if n["id"] == parent_sid),
+                None,
+            )
+            if parent_nav_idx is None:
+                continue
+
+            parent_depth = session_nav[parent_nav_idx]["depth"]
+            insert_pos = parent_nav_idx + 1
+            # Skip past any existing children of this parent
+            while (
+                insert_pos < len(session_nav)
+                and session_nav[insert_pos].get("depth", 0) > parent_depth
+            ):
+                insert_pos += 1
+
+            # Fork point nav item — find the junction message and a
+            # meaningful preview (walk up past system hooks to find it)
+            fork_msg_idx = ctx.session_first_message.get(parent_sid)
+            fork_preview = ""
+            fork_msg = None
+            for msg in ctx.messages:
+                if msg.meta.uuid == attachment_uuid and msg.message_index is not None:
+                    fork_msg_idx = msg.message_index
+                    fork_msg = msg
+                    break
+            if fork_msg is not None:
+                fork_preview = _fork_point_preview(fork_msg, ctx)
+
+            fork_label = (
+                f"Fork point • {fork_preview}"
+                if fork_preview
+                else f"Fork point ({len(branches)} branches)"
+            )
+
+            fork_nav = {
+                "id": f"fork-{attachment_uuid[:12]}",
+                "message_index": fork_msg_idx,
+                "summary": None,
+                "timestamp_range": "",
+                "first_timestamp": "",
+                "last_timestamp": "",
+                "message_count": 0,
+                "first_user_message": fork_label,
+                "token_summary": "",
+                "parent_session_id": parent_sid,
+                "parent_message_index": ctx.session_first_message.get(parent_sid),
+                "depth": parent_depth + 1,
+                "is_fork_point": True,
+            }
+            session_nav.insert(insert_pos, fork_nav)
+            insert_pos += 1
+
+            # Branch nav items
+            for branch in branches:
+                branch_sid = branch["sid"]
+                branch_msg_idx = ctx.session_first_message.get(branch_sid)
+                branch_nav = {
+                    "id": branch_sid,
+                    "message_index": branch_msg_idx,
+                    "summary": None,
+                    "timestamp_range": "",
+                    "first_timestamp": "",
+                    "last_timestamp": "",
+                    "message_count": 0,
+                    "first_user_message": branch_previews.get(
+                        branch_sid,
+                        f"Branch {branch_sid.split('@')[-1][:8]}",
+                    ),
+                    "token_summary": "",
+                    "parent_session_id": parent_sid,
+                    "parent_message_index": fork_msg_idx,
+                    "depth": parent_depth + 2,
+                    "is_branch": True,
+                }
+                session_nav.insert(insert_pos, branch_nav)
+                insert_pos += 1
+
     return session_nav
 
 
@@ -1379,14 +1710,15 @@ def _reorder_session_template_messages(
         if message.is_session_header:
             session_headers.append(message)
             # Initialize the list for this session (preserves session order)
-            if message.session_id and message.session_id not in session_messages_map:
-                session_messages_map[message.session_id] = []
+            sid = message.render_session_id
+            if sid and sid not in session_messages_map:
+                session_messages_map[sid] = []
         else:
-            session_id = message.session_id
-            if session_id:
-                if session_id not in session_messages_map:
-                    session_messages_map[session_id] = []
-                session_messages_map[session_id].append(message)
+            sid = message.render_session_id
+            if sid:
+                if sid not in session_messages_map:
+                    session_messages_map[sid] = []
+                session_messages_map[sid].append(message)
 
     # If no session headers, return original order
     if not session_headers:
@@ -1398,97 +1730,21 @@ def _reorder_session_template_messages(
 
     for header in session_headers:
         result.append(header)
-        session_id = header.session_id
+        sid = header.render_session_id
 
-        if session_id and session_id in session_messages_map:
+        if sid and sid in session_messages_map:
             # Messages are already in timestamp order from original processing
-            result.extend(session_messages_map[session_id])
-            used_sessions.add(session_id)
+            result.extend(session_messages_map[sid])
+            used_sessions.add(sid)
 
     # Append any messages that weren't matched to a session header (shouldn't happen normally)
-    for session_id, msgs in session_messages_map.items():
-        if session_id not in used_sessions:
+    for sid, msgs in session_messages_map.items():
+        if sid not in used_sessions:
             result.extend(msgs)
 
     return result
 
 
-def _reorder_sidechain_template_messages(
-    messages: list[TemplateMessage],
-) -> list[TemplateMessage]:
-    """Reorder template messages to place sidechains immediately after their Task results.
-
-    When parallel Task agents run, their sidechain messages may appear in arbitrary
-    order based on when each agent finishes. This function reorders messages so that
-    each sidechain's messages appear right after the Task result that references them.
-
-    Note: Deduplication of sidechain content (first user message = Task input,
-    last assistant message = Task output) is handled later by _cleanup_sidechain_duplicates
-    after the tree structure is built.
-
-    This must be called AFTER _reorder_paired_messages, since that function moves
-    tool_results next to their tool_uses, which changes where the agentId-bearing
-    messages end up.
-
-    Args:
-        messages: Template messages including sidechains
-
-    Returns:
-        Reordered messages with sidechains properly placed after their Task results
-    """
-    # First pass: extract sidechains grouped by agent_id
-    main_messages: list[TemplateMessage] = []
-    sidechain_map: dict[str, list[TemplateMessage]] = {}
-
-    for message in messages:
-        is_sidechain = message.is_sidechain
-        agent_id = message.agent_id
-
-        if is_sidechain and agent_id:
-            # Group sidechain messages by agent_id
-            if agent_id not in sidechain_map:
-                sidechain_map[agent_id] = []
-            sidechain_map[agent_id].append(message)
-        else:
-            main_messages.append(message)
-
-    # If no sidechains, return original order
-    if not sidechain_map:
-        return messages
-
-    # Second pass: insert sidechains after their Task result messages
-    result: list[TemplateMessage] = []
-    used_agents: set[str] = set()
-
-    for message in main_messages:
-        result.append(message)
-
-        # Check if this is a Task tool_result that references a sidechain (via agent_id)
-        # We only insert after tool_result (not tool_use) to avoid duplicates if
-        # tool_use ever gets agent_id in the future
-        agent_id = message.agent_id
-
-        # Only insert sidechain if not already inserted (handles case where
-        # multiple tool_results have the same agent_id)
-        if (
-            agent_id
-            and message.type == MessageType.TOOL_RESULT
-            and agent_id in sidechain_map
-            and agent_id not in used_agents
-        ):
-            # Insert the sidechain messages for this agent right after this message
-            # Note: ancestry will be rebuilt by _build_message_hierarchy() later
-            result.extend(sidechain_map[agent_id])
-            used_agents.add(agent_id)
-
-    # Append any sidechains that weren't matched (shouldn't happen normally)
-    for agent_id, sidechain_msgs in sidechain_map.items():
-        if agent_id not in used_agents:
-            result.extend(sidechain_msgs)
-
-    return result
-
-
 def _filter_messages(messages: list[TranscriptEntry]) -> list[TranscriptEntry]:
     """Filter messages to those that should be rendered.
 
@@ -1516,6 +1772,10 @@ def _filter_messages(messages: list[TranscriptEntry]) -> list[TranscriptEntry]:
         if isinstance(message, SummaryTranscriptEntry):
             continue
 
+        # Skip passthrough entries (structural DAG nodes, not rendered)
+        if isinstance(message, PassthroughTranscriptEntry):
+            continue
+
         # Skip most queue operations - only process 'remove' for counts
         if isinstance(message, QueueOperationTranscriptEntry):
             if message.operation != "remove":
@@ -1558,6 +1818,72 @@ def _filter_messages(messages: list[TranscriptEntry]) -> list[TranscriptEntry]:
     return filtered
 
 
+def _filter_shallow(messages: list[TranscriptEntry]) -> list[TranscriptEntry]:
+    """Filter messages for shallow mode: keep only user and assistant text.
+
+    Strips tool items from user entries and thinking/tool items from assistant
+    entries. System, summary, queue-operation, and sidechain entries are removed.
+    """
+    from copy import copy
+
+    _strip_types = (ThinkingContent, ToolUseContent, ToolResultContent)
+    filtered: list[TranscriptEntry] = []
+    for message in messages:
+        if not isinstance(message, (UserTranscriptEntry, AssistantTranscriptEntry)):
+            continue
+        # Drop sidechain (subagent) messages
+        if message.isSidechain:
+            continue
+        text_items: list[ContentItem] = [
+            item
+            for item in message.message.content
+            if not isinstance(item, _strip_types)
+        ]
+        if text_items:
+            msg_copy = copy(message)
+            msg_model = copy(message.message)
+            msg_model.content = text_items
+            if isinstance(msg_copy, UserTranscriptEntry):
+                msg_copy.message = cast("UserMessageModel", msg_model)
+            else:
+                msg_copy.message = cast("AssistantMessageModel", msg_model)
+            filtered.append(msg_copy)
+    return filtered
+
+
+# Content classes to exclude in shallow mode post-render.
+# These are text-derived types created by the user factory that we don't want
+# in a shallow view (bash commands, slash command prompts, compacted summaries).
+# We check by class rather than message_type string because several of these
+# classes (SlashCommandMessage, CommandOutputMessage, CompactedSummaryMessage)
+# return "user" as their message_type.
+_SHALLOW_EXCLUDE_CLASSES = (
+    BashInputMessage,
+    BashOutputMessage,
+    SlashCommandMessage,
+    UserSlashCommandMessage,
+    CommandOutputMessage,
+    CompactedSummaryMessage,
+)
+
+
+def _filter_shallow_template_messages(
+    messages: list[TemplateMessage],
+) -> list[TemplateMessage]:
+    """Post-render filter for shallow mode: remove text-derived message types.
+
+    After _render_messages creates TemplateMessages, some user text content
+    gets classified into special types (bash commands, slash commands, etc.)
+    that should be excluded from shallow output.
+    """
+    return [
+        msg
+        for msg in messages
+        if not isinstance(msg.content, _SHALLOW_EXCLUDE_CLASSES)
+        and not msg.is_sidechain
+    ]
+
+
 def _collect_session_info(
     messages: list[TranscriptEntry],
     session_summaries: dict[str, str],
@@ -1683,11 +2009,15 @@ def _render_messages(
     messages: list[TranscriptEntry],
     sessions: dict[str, dict[str, Any]],
     show_tokens_for_message: set[str],
+    session_hierarchy: dict[str, dict[str, Any]] | None = None,
+    session_summaries: dict[str, str] | None = None,
+    junction_targets: dict[str, list[str]] | None = None,
 ) -> RenderingContext:
     """Pass 2: Render pre-filtered messages to TemplateMessage objects.
 
     This pass creates the actual TemplateMessage objects for rendering:
     - Creates session headers when entering new sessions
+    - Creates branch headers at within-session fork points
     - Processes text content into HTML
     - Handles tool use, tool result, thinking, and image content
     - Collects timing statistics
@@ -1699,24 +2029,133 @@ def _render_messages(
         messages: Pre-filtered list of transcript entries from _collect_session_info
         sessions: Session metadata from _collect_session_info
         show_tokens_for_message: Set of message UUIDs that should display tokens
+        session_hierarchy: Optional hierarchy data from _extract_session_hierarchy()
+        session_summaries: Optional session summaries for parent backlinks
+        junction_targets: Optional junction target data from _extract_session_hierarchy()
 
     Returns:
         RenderingContext with all TemplateMessage objects registered
     """
     # Create rendering context for this operation
     ctx = RenderingContext()
+    if junction_targets:
+        ctx.junction_targets = junction_targets
+
+    # Build branch_start_uuids: map first UUID of each branch → branch pseudo-session ID
+    branch_start_uuids: dict[str, str] = {}
+    if session_hierarchy:
+        for sid, hier in session_hierarchy.items():
+            if hier.get("is_branch") and hier.get("first_uuid"):
+                branch_start_uuids[hier["first_uuid"]] = sid
 
     # Track which sessions have had headers added
     seen_sessions: set[str] = set()
+    # Track current effective render session (for branch assignment)
+    current_render_session: Optional[str] = None
 
     for message in messages:
         message_type = message.type
 
+        # Determine if this message belongs to an agent sidechain session.
+        # Agent messages use the parent session's render_session_id so they
+        # stay grouped with the correct session (trunk or branch).
+        msg_session_id = getattr(message, "sessionId", "") or ""
+        agent_parent_session: Optional[str] = None
+        if is_agent_session(msg_session_id):
+            # Use session hierarchy to find the actual parent (may be a branch
+            # pseudo-session if the anchor is inside a within-session fork)
+            if session_hierarchy:
+                hier = session_hierarchy.get(msg_session_id, {})
+                agent_parent_session = hier.get("parent_session_id")
+            if not agent_parent_session:
+                # Fallback: extract original session from synthetic ID
+                agent_parent_session = get_parent_session_id(msg_session_id)
+
+        # Check if this message starts a new branch (within-session fork)
+        # Must happen before system/summary handling so branch state is
+        # correct when tagging those messages with render_session_id.
+        message_uuid = getattr(message, "uuid", "")
+        if message_uuid and message_uuid in branch_start_uuids:
+            branch_sid = branch_start_uuids[message_uuid]
+            if branch_sid not in seen_sessions:
+                seen_sessions.add(branch_sid)
+                current_render_session = branch_sid
+
+                # Create branch header
+                b_hier = (session_hierarchy or {}).get(branch_sid, {})
+                parent_sid = b_hier.get("parent_session_id")
+                # Look up the fork point message index (attachment_uuid),
+                # not the parent session header
+                attachment_uuid = b_hier.get("attachment_uuid")
+                parent_msg_idx = None
+                if attachment_uuid:
+                    for msg in ctx.messages:
+                        if (
+                            msg.meta.uuid == attachment_uuid
+                            and msg.message_index is not None
+                        ):
+                            parent_msg_idx = msg.message_index
+                            break
+                if parent_msg_idx is None and parent_sid:
+                    parent_msg_idx = ctx.session_first_message.get(parent_sid)
+                original_sid = b_hier.get("original_session_id", message.sessionId)
+                branch_summary = (session_summaries or {}).get(original_sid)
+                # Extract preview from the branch's first user message
+                branch_preview = ""
+                user_entry = as_user_entry(message)
+                if user_entry is not None:
+                    branch_text = extract_text_content(user_entry.message.content)
+                    if branch_text:
+                        branch_preview = create_session_preview(branch_text)
+                # Truncate for header title (keep full preview for nav)
+                if branch_preview:
+                    short = branch_preview[:80]
+                    if len(branch_preview) > 80:
+                        short += "..."
+                    branch_title = f"Branch • {short}"
+                else:
+                    branch_title = f"Branch • {branch_sid.split('@')[-1][:8]}"
+
+                branch_header_meta = MessageMeta(
+                    session_id=branch_sid,
+                    timestamp="",
+                    uuid="",
+                )
+                # Get fork point preview for backlink text
+                fork_context = ""
+                if attachment_uuid:
+                    for fmsg in ctx.messages:
+                        if fmsg.meta.uuid == attachment_uuid:
+                            fork_context = _fork_point_preview(fmsg, ctx)
+                            break
+
+                branch_header_content = SessionHeaderMessage(
+                    branch_header_meta,
+                    title=branch_title,
+                    session_id=branch_sid,
+                    summary=branch_summary,
+                    parent_session_id=parent_sid,
+                    parent_session_summary=fork_context or None,
+                    parent_message_index=parent_msg_idx,
+                    depth=b_hier.get("depth", 0),
+                    attachment_uuid=b_hier.get("attachment_uuid"),
+                    is_branch=True,
+                    original_session_id=original_sid,
+                    first_uuid=message_uuid,
+                )
+                branch_header = TemplateMessage(branch_header_content)
+                branch_header.render_session_id = branch_sid
+                msg_index = ctx.register(branch_header)
+                ctx.session_first_message[branch_sid] = msg_index
+
         # Handle system messages (already filtered in pass 1)
         if isinstance(message, SystemTranscriptEntry):
             system_content = create_system_message(message)
             if system_content:
                 system_msg = TemplateMessage(system_content)
+                effective_session = agent_parent_session or current_render_session
+                if effective_session:
+                    system_msg.render_session_id = effective_session
                 ctx.register(system_msg)
             continue
 
@@ -1762,31 +2201,47 @@ def _render_messages(
         session_summary = sessions.get(session_id, {}).get("summary")
 
         # Add session header if this is a new session
+        # Skip headers for agent sidechain sessions (they appear inline)
+        is_agent = is_agent_session(session_id)
         if session_id not in seen_sessions:
             seen_sessions.add(session_id)
-            current_session_summary = session_summary
-            session_title = (
-                f"{current_session_summary} • {session_id[:8]}"
-                if current_session_summary
-                else session_id[:8]
-            )
+            if not is_agent:
+                current_render_session = None  # Reset branch tracking
+                current_session_summary = session_summary
+                session_title = (
+                    f"{current_session_summary} • {session_id[:8]}"
+                    if current_session_summary
+                    else session_id[:8]
+                )
 
-            # Create meta with session_id for the session header
-            session_header_meta = MessageMeta(
-                session_id=session_id,
-                timestamp="",
-                uuid="",
-            )
-            session_header_content = SessionHeaderMessage(
-                session_header_meta,
-                title=session_title,
-                session_id=session_id,
-                summary=current_session_summary,
-            )
-            # Register and track session's first message
-            session_header = TemplateMessage(session_header_content)
-            msg_index = ctx.register(session_header)
-            ctx.session_first_message[session_id] = msg_index
+                # Create meta with session_id for the session header
+                session_header_meta = MessageMeta(
+                    session_id=session_id,
+                    timestamp="",
+                    uuid="",
+                )
+                hier = (session_hierarchy or {}).get(session_id, {})
+                parent_sid = hier.get("parent_session_id")
+                parent_msg_idx = (
+                    ctx.session_first_message.get(parent_sid) if parent_sid else None
+                )
+                session_header_content = SessionHeaderMessage(
+                    session_header_meta,
+                    title=session_title,
+                    session_id=session_id,
+                    summary=current_session_summary,
+                    parent_session_id=parent_sid,
+                    parent_session_summary=(session_summaries or {}).get(parent_sid)
+                    if parent_sid
+                    else None,
+                    parent_message_index=parent_msg_idx,
+                    depth=hier.get("depth", 0),
+                    attachment_uuid=hier.get("attachment_uuid"),
+                )
+                # Register and track session's first message
+                session_header = TemplateMessage(session_header_content)
+                msg_index = ctx.register(session_header)
+                ctx.session_first_message[session_id] = msg_index
 
         # Extract token usage for assistant messages
         # Only show token usage for the first message with each requestId to avoid duplicates
@@ -1844,6 +2299,9 @@ def _render_messages(
                     continue
 
                 chunk_msg = TemplateMessage(content_model)
+                effective_session = agent_parent_session or current_render_session
+                if effective_session:
+                    chunk_msg.render_session_id = effective_session
                 ctx.register(chunk_msg)
 
             else:
@@ -1892,6 +2350,9 @@ def _render_messages(
                     continue
 
                 tool_msg = TemplateMessage(tool_result.content)
+                effective_session = agent_parent_session or current_render_session
+                if effective_session:
+                    tool_msg.render_session_id = effective_session
                 ctx.register(tool_msg)
 
     return ctx
@@ -2014,6 +2475,8 @@ class Renderer:
     - Subclasses override methods to implement format-specific rendering
     """
 
+    shallow: bool = False
+
     def _dispatch_format(self, obj: Any, message: TemplateMessage) -> str:
         """Dispatch to format_{ClassName}(obj, message) based on object type."""
         for cls in type(obj).__mro__:
@@ -2230,6 +2693,7 @@ def generate(
         title: Optional[str] = None,
         combined_transcript_link: Optional[str] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
     ) -> Optional[str]:
         """Generate output from transcript messages.
 
@@ -2238,6 +2702,7 @@ def generate(
             title: Optional title for the output.
             combined_transcript_link: Optional link to combined transcript.
             output_dir: Optional output directory for referenced images.
+            session_tree: Optional pre-built SessionTree (avoids rebuilding DAG).
 
         Returns None by default; subclasses override to return formatted output.
         """
@@ -2250,6 +2715,7 @@ def generate_session(
         title: Optional[str] = None,
         cache_manager: Optional["CacheManager"] = None,
         output_dir: Optional[Path] = None,
+        session_tree: Optional["SessionTree"] = None,
     ) -> Optional[str]:
         """Generate output for a single session.
 
@@ -2259,6 +2725,7 @@ def generate_session(
             title: Optional title for the output.
             cache_manager: Optional cache manager.
             output_dir: Optional output directory for referenced images.
+            session_tree: Optional pre-built SessionTree (avoids rebuilding DAG).
 
         Returns None by default; subclasses override to return formatted output.
         """
@@ -2284,13 +2751,18 @@ def is_outdated(self, file_path: Path) -> Optional[bool]:
         return None
 
 
-def get_renderer(format: str, image_export_mode: Optional[str] = None) -> Renderer:
+def get_renderer(
+    format: str,
+    image_export_mode: Optional[str] = None,
+    shallow: bool = False,
+) -> Renderer:
     """Get a renderer instance for the specified format.
 
     Args:
         format: The output format ("html", "md", or "markdown").
         image_export_mode: Image export mode ("placeholder", "embedded", "referenced").
             If None, defaults to "embedded" for HTML and "referenced" for Markdown.
+        shallow: If True, render only user and assistant text messages.
 
     Returns:
         A Renderer instance for the specified format.
@@ -2303,14 +2775,17 @@ def get_renderer(format: str, image_export_mode: Optional[str] = None) -> Render
 
         # For HTML, default to embedded mode (current behavior)
         mode = image_export_mode or "embedded"
-        return HtmlRenderer(image_export_mode=mode)
+        renderer = HtmlRenderer(image_export_mode=mode)
     elif format in ("md", "markdown"):
         from .markdown.renderer import MarkdownRenderer
 
         # For Markdown, default to referenced mode
         mode = image_export_mode or "referenced"
-        return MarkdownRenderer(image_export_mode=mode)
-    raise ValueError(f"Unsupported format: {format}")
+        renderer = MarkdownRenderer(image_export_mode=mode)
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+    renderer.shallow = shallow
+    return renderer
 
 
 def is_html_outdated(html_file_path: Path) -> bool:
diff --git a/claude_code_log/tui.py b/claude_code_log/tui.py
index 47c59592..a55b4c4e 100644
--- a/claude_code_log/tui.py
+++ b/claude_code_log/tui.py
@@ -1834,7 +1834,7 @@ def _ensure_session_file(
                 messages = self.cache_manager.load_session_entries(session_id)
             else:
                 # Load from JSONL files for current sessions
-                messages = load_directory_transcripts(
+                messages, _tree = load_directory_transcripts(
                     self.project_path, self.cache_manager, silent=True
                 )
             if not messages:
diff --git a/claude_code_log/utils.py b/claude_code_log/utils.py
index 4a7241d0..11a97a6a 100644
--- a/claude_code_log/utils.py
+++ b/claude_code_log/utils.py
@@ -4,10 +4,7 @@
 import re
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional
-
-if TYPE_CHECKING:
-    from .cache import SessionCacheData
+from typing import Optional
 
 from .models import ContentItem, TextContent, TranscriptEntry, UserTranscriptEntry
 from .factories import (
@@ -188,44 +185,6 @@ def extract_text_content_length(content: list[ContentItem]) -> int:
     return total_length
 
 
-def extract_working_directories(
-    entries: "list[TranscriptEntry] | list[SessionCacheData] | list[Any]",
-) -> list[str]:
-    """Extract unique working directories from a list of entries.
-
-    Ordered by timestamp (most recent first).
-
-    Args:
-        entries: List of TranscriptEntry or SessionCacheData to extract working directories from
-
-    Returns:
-        List of unique working directory paths found in the entries
-    """
-    # Import here to avoid circular dependency at runtime
-    from .cache import SessionCacheData
-
-    working_directories: dict[str, str] = {}
-
-    for entry in entries:
-        cwd = getattr(entry, "cwd", None)
-        if not cwd:
-            continue
-
-        # Get appropriate timestamp based on entry type
-        if isinstance(entry, SessionCacheData):
-            timestamp = entry.last_timestamp
-        elif hasattr(entry, "timestamp"):
-            timestamp = getattr(entry, "timestamp", "")
-        else:
-            timestamp = ""
-
-        working_directories[cwd] = timestamp
-
-    # Sort by timestamp (most recent first) and return just the paths
-    sorted_dirs = sorted(working_directories.items(), key=lambda x: x[1], reverse=True)
-    return [path for path, _ in sorted_dirs]
-
-
 # IDE tag patterns imported from factories for compact preview rendering
 
 
@@ -329,6 +288,24 @@ def _extract_file_path(content: str) -> str | None:
     return text_content
 
 
+def is_agent_session(session_id: str) -> bool:
+    """Check if a session ID is a synthetic agent session.
+
+    Agent sessions use the format ``{sessionId}#agent-{agentId}``,
+    assigned by ``_integrate_agent_entries()`` during DAG construction.
+    """
+    return "#agent-" in session_id
+
+
+def get_parent_session_id(session_id: str) -> str:
+    """Return the parent session ID for an agent session, or the ID itself.
+
+    For ``{sessionId}#agent-{agentId}`` returns ``{sessionId}``.
+    For non-agent sessions returns the input unchanged.
+    """
+    return session_id.split("#agent-")[0] if "#agent-" in session_id else session_id
+
+
 def get_warmup_session_ids(messages: list[TranscriptEntry]) -> set[str]:
     """Get set of session IDs that are warmup-only sessions.
 
diff --git a/dev-docs/dag.md b/dev-docs/dag.md
new file mode 100644
index 00000000..a4cfec36
--- /dev/null
+++ b/dev-docs/dag.md
@@ -0,0 +1,376 @@
+# DAG-Based Message Architecture
+
+Replaces timestamp-based ordering with `parentUuid` → `uuid` graph traversal.
+
+Reference: [Messages as Commits: Claude Code's Git-Like DAG of Conversations](https://piebald.ai/blog/messages-as-commits-claude-codes-git-like-dag-of-conversations)
+
+Related issues: #79, #85, #90, #91
+
+---
+
+## Motivation
+
+Currently, messages are sorted by timestamp and then patched with post-hoc
+fixups (pair reordering, sidechain reordering by `agentId`). This is fragile:
+
+- **Sync agents**: Works "well enough" because timestamps align with causality
+- **Async agents** (#90): Agent runs in background; launch and notification
+  are temporally distant; agent transcript interleaves arbitrarily
+- **Teammates** (#91): Multiple agents send messages concurrently
+- **Resume/fork** (#85): Conversation branches share a prefix; timestamp
+  ordering can't express the branching structure
+
+The transcript data already contains the structural information we need:
+each message's `parentUuid` points to its predecessor, forming a DAG.
+
+---
+
+## Core Concepts
+
+### The DAG
+
+Every message has a `uuid` and a `parentUuid` (null for first messages).
+Together they form a directed acyclic graph. The graph is the authoritative
+ordering; timestamps are metadata, not structure.
+
+### Sessions and DAG-lines
+
+A **session** is the set of messages sharing a `sessionId`. Each session
+forms a single contiguous chain in the DAG — its **DAG-line**. A session's
+DAG-line contains only the messages unique to that session (after
+deduplication).
+
+**Assertion**: Within a session, the default `parentUuid` chain is linear.
+Explicit rewinds create within-session forks that are rendered as branch
+pseudo-sessions. Unexpected non-rewind branching logs a warning.
+
+### Junction Points
+
+A **junction point** is a message whose `uuid` is referenced as
+`parentUuid` by messages from **different sessions**. This is where
+resume/fork happens.
+
+Junction points are **annotations on messages**, not splits of DAG-lines.
+A session's DAG-line remains intact; the junction point simply records
+"session N forks/continues from here."
+
+### Session Tree
+
+Sessions form a tree:
+
+- **Root sessions**: Their first message has `parentUuid: null` (or points
+  to a message not in any loaded session, e.g. after a `/clear`)
+- **Child sessions**: Their first unique message's `parentUuid` points into
+  a parent session's DAG-line
+
+Children are ordered chronologically (by their first message's timestamp).
+
+Example:
+
+```
+Session 1: a → b → c → d → e → f → g
+                             ↑           ↑
+                             |           |
+Session 3: k → l → m        Session 2: h → i → j
+(fork from e)                (continues from g)
+```
+
+Session tree:
+```
+- Session 1
+  - Session 2 (continues from g)
+  - Session 3 (forks from e)
+```
+
+Rendered message sequence (depth-first, chronological children):
+```
+s1, a, b, c, d, e, f, g, s2, h, i, j, s3, k, l, m
+```
+
+Where `s1`, `s2`, `s3` are synthesized session header messages.
+
+### Navigation Links
+
+- **Forward links** on junction points: "Session N forks/continues here"
+  (shown on message `e` and `g` in the example above)
+- **Backlinks** on session headers: "Continues from message X in Session Y"
+  (shown on `s2` and `s3`)
+
+#### Current: `d-{index}` anchors (combined transcript only)
+
+Backlinks use `#msg-d-{N}` anchors which are sequential indices assigned
+during rendering. These are stable within a single render pass (the
+combined transcript is always regenerated whole), but shift when any
+session grows.
+
+This works for the combined transcript because all links and targets are
+on the same page. Individual session pages have independent indices.
+
+#### Future: UUID-based anchors for cross-page linking
+
+Each session's DAG-line can grow independently. If session B grows and
+its page is regenerated, `d-{index}` values shift — breaking any link
+from session A's (cached) page into B.
+
+When cross-session-page links are needed (e.g. session page A links to
+a junction point in session page B), add stable UUID-based anchors:
+
+```html
+<div id="msg-{uuid}" ...>  <!-- stable, never shifts -->
+```
+
+Use `msg-{uuid}` on junction points and attachment messages. Keep
+`msg-d-{N}` for everything else (session nav, timeline, etc.).
+
+### Deduplication
+
+When session 2 resumes session 1, Claude Code may replay prefix messages
+(d', e', f', g') into session 2's file. These duplicates share the same
+`uuid` but have a different `sessionId`.
+
+Resolution: deduplicate by `uuid`, keeping the instance from the
+**earliest session** (by first message timestamp). The "new" messages in
+session 2 (those with previously-unseen `uuid`) form its DAG-line.
+
+### Agent Transcripts
+
+Agent transcripts also form DAG-lines. They come in two flavors:
+
+1. **Continuing agents**: Their `parentUuid` chains into a previous agent's
+   DAG-line (same session, different `agentId`). These naturally fit the
+   DAG.
+
+2. **Top-level agents**: `parentUuid` is null. These need explicit
+   **parenting** — splicing them into the main session's DAG-line at the
+   appropriate point.
+
+   For `x → y → z` where `y` is a Task, and agent transcript `u → v` needs
+   to be rooted at `y`, the result is: `x → y → u → v → z`.
+
+**Parenting strategies** (by agent type):
+
+| Agent type | Link mechanism | Parent at |
+|------------|---------------|-----------|
+| Sync Task | `agentId` on tool_result | Task tool_result message |
+| Async Task (#90) | `agentId` on launch tool_result, `task-id` in `<task-notification>` | Launch tool_result |
+| Teammate (#91) | `team_name` + agent name | TBD — likely TeamCreate or Task-with-team |
+
+---
+
+## Algorithm
+
+### Phase 1: Load All Sessions
+
+Load **all** `.jsonl` files for a project directory. Build a unified message
+index:
+
+```python
+messages_by_uuid: dict[str, TranscriptEntry]   # uuid → entry (oldest wins)
+children_by_uuid: dict[str, list[str]]          # parentUuid → [child uuids]
+sessions: dict[str, list[str]]                  # sessionId → [uuids in chain order]
+```
+
+When targeting a single session, still load all files but only render
+that session's subtree. Optionally warn that context from other sessions
+is available.
+
+### Phase 2: Build DAG and Deduplicate
+
+1. Parse all entries, index by `uuid`
+2. For duplicate `uuid`s, keep the one from the earliest `sessionId`
+3. Build `children_by_uuid` from `parentUuid` links
+4. Group messages by `sessionId`
+
+### Phase 3: Extract Session DAG-lines
+
+For each session:
+1. Identify the session's unique messages (those whose authoritative
+   `sessionId` matches)
+2. Order them by following `parentUuid` chains (not timestamps)
+3. Verify linearity (no branching within a session)
+
+### Phase 4: Build Session Tree
+
+1. For each session, find where its DAG-line attaches to the DAG:
+   - Walk back from the session's first unique message via `parentUuid`
+   - The first message belonging to a **different** session is the
+     attachment point
+2. The session whose message is the attachment point is the parent session
+3. Root sessions have no attachment point (first message is `parentUuid: null`
+   or points outside loaded data)
+4. Order children chronologically
+
+### Phase 5: Identify Junction Points
+
+A message is a junction point if `children_by_uuid[msg.uuid]` contains
+messages from multiple sessions, or from a session different than the
+message's own.
+
+Annotate junction points with their target sessions for forward-link
+rendering.
+
+### Phase 6: Splice Agent Transcripts
+
+For each agent transcript (identified by `agentId`):
+1. Determine parenting strategy (see table above)
+2. Find the anchor message in the main session's DAG-line
+3. Splice the agent's DAG-line after the anchor
+
+This replaces the current `_reorder_sidechain_template_messages` approach
+with a principled graph operation.
+
+### Phase 7: Process and Render
+
+Within each DAG-line, apply existing processing:
+- Pairing (tool_use+tool_result, thinking+assistant, etc.)
+- Hierarchy building
+- Tree construction
+
+Pairing should be **scoped to DAG-lines** — no pairing across session
+boundaries. This is both correct and faster.
+
+---
+
+## Caveats
+
+### Context Compaction Replays
+
+When Claude Code compacts context (inserting a `SummaryTranscriptEntry`), it
+**replays** the conversation from a certain point with **new UUIDs** but the
+**same `parentUuid` and timestamp** as the original entries. This creates
+multiple same-session children from a single parent — structurally identical
+to a user rewind (fork), but semantically a replay.
+
+**Distinguishing heuristic**: timestamps.
+
+- **Real fork (rewind)**: the user goes back and types a new message at a
+  different time → children have **different** timestamps.
+- **Compaction replay**: the system re-emits the same turn → children share
+  the **same** timestamp as the original.
+
+When `_walk_session_with_forks()` encounters a node with multiple same-session
+children that all share the same timestamp, it follows only the **first**
+child (the original chain) and ignores the later replay chains. This avoids
+creating hundreds of false branch pseudo-sessions in long-running sessions
+with frequent compaction.
+
+The heuristic is validated on real data: across all fork points, forks
+partition cleanly into same-timestamp (compaction) vs different-timestamp
+(rewind) groups, with no mixed cases observed.
+
+### Tool-Result Side-Branches
+
+When the assistant makes **multiple tool calls** in one turn, the JSONL
+records both the next `tool_use` and the previous `tool_result` as children
+of the same parent entry. Two variants exist:
+
+**Variant 1** — User child is immediate dead end:
+```
+A(tool_use₁) → U(tool_result₁)   [dead-end side-branch]
+             → A(tool_use₂)      [main chain continues]
+```
+
+**Variant 2** — User child continues, Assistant subtree dead-ends:
+```
+A(tool_use₁) → U(tool_result₁) → A(response) → ...  [main chain]
+             → A(tool_use₂) → ... → dead ends        [progress artifact]
+```
+
+Both variants create false forks. The fix (`_stitch_tool_results()`) detects
+the pattern and stitches dead-end children into the chain before the
+continuation child. Subtree descendants of dead-end children are collected
+into the `skipped` set for coverage accounting.
+
+Detection criteria:
+- At least one User child and at least one Assistant child
+- Variant 1: all User children are immediate dead ends + single Assistant
+- Variant 2: exactly one User child has continuation, all Assistant subtrees
+  are dead ends (checked recursively via `_is_subtree_dead_end()`)
+
+---
+
+## Assertions / Invariants
+
+These should be checked at runtime (log warnings, don't crash):
+
+1. **Session linearity**: Each session's messages form a single chain
+   (no branching within a `sessionId`), except for explicit user rewinds
+   which create within-session forks rendered as branch pseudo-sessions
+2. **DAG acyclicity**: No cycles in `parentUuid` chains
+3. **Unique ownership**: After deduplication, each `uuid` belongs to
+   exactly one session
+4. **Agent parenting**: Every top-level agent transcript has an identifiable
+   anchor in the main session
+
+---
+
+## Impact on Existing Code
+
+### What changes
+
+| Component | Current | After |
+|-----------|---------|-------|
+| `converter.py` | Load single file + agent files; timestamp sort | Load all project files; build DAG |
+| `renderer.py` message ordering | Timestamp sort + pair reorder + sidechain reorder | DAG-line traversal; pairing within DAG-lines |
+| Session index | Flat list sorted by timestamp | Session tree with parent/child relationships |
+| Agent handling | `agentId`-based insertion after timestamp sort | Agent DAG-line splicing at anchor points |
+
+### What stays
+
+- Factory layer (transcript entry → MessageContent)
+- TemplateMessage wrapper and RenderingContext
+- Hierarchy building within sessions (user → assistant → tools)
+- Renderer dispatch and format_* methods
+- HTML templates and JavaScript (fold, timeline, filters)
+- Deduplication heuristics (sidechain cleanup, etc.) — may simplify over time
+
+---
+
+## Implementation Plan
+
+### Phase A: DAG Infrastructure (new module: `dag.py`)
+
+1. **Message indexing**: Load all session files, build `uuid` index,
+   deduplicate
+2. **DAG construction**: Build parent→children graph
+3. **Session extraction**: Group by `sessionId`, extract DAG-lines,
+   verify linearity
+4. **Session tree**: Build parent/child session relationships, identify
+   junction points
+
+This phase is purely additive — new code alongside existing. Tests can
+validate DAG construction against known transcripts.
+
+### Phase B: Integration with Rendering Pipeline
+
+1. Replace `load_transcript` / `load_directory_transcripts` with
+   DAG-based loading in `converter.py`
+2. Pass DAG-lines (per session) into `generate_template_messages`
+3. Scope pairing to DAG-lines
+4. Generate session headers with navigation links (forward/back)
+5. Update session index from flat to hierarchical
+
+### Phase C: Agent Transcript Rework (Steps 1-2 done)
+
+1. ~~Implement parenting strategies for each agent type~~ — Done:
+   `_integrate_agent_entries()` parents agent roots to anchors and assigns
+   synthetic session IDs (`{sessionId}#agent-{agentId}`)
+2. ~~Replace `_reorder_sidechain_template_messages` with DAG-line splicing~~
+   — Done: agents are now DAG-ordered; the old function is kept as fallback
+3. Simplify or remove `_cleanup_sidechain_duplicates` (dedup now
+   happens at DAG level) — TODO
+4. Agent tool renderer (separate PR, `dev/user-sidechain` branch) — TODO
+
+### Phase D: Async Agent and Teammate Support
+
+1. Parse `<task-notification>` to extract `task-id` for async agent linking
+2. Implement teammate parenting strategy (#91)
+3. This is where #90 and #91 get properly resolved
+
+---
+
+## Related Documentation
+
+- [rendering-architecture.md](rendering-architecture.md) — Current pipeline
+- [messages.md](messages.md) — Message type reference
+- [rendering-next.md](rendering-next.md) — Future rendering improvements
diff --git a/dev-docs/rendering-architecture.md b/dev-docs/rendering-architecture.md
index 3b8e4d54..1deadf20 100644
--- a/dev-docs/rendering-architecture.md
+++ b/dev-docs/rendering-architecture.md
@@ -344,3 +344,4 @@ Note that `meta.uuid` is the original transcript entry's UUID. Since a single en
 - [messages.md](messages.md) - Complete message type reference
 - [css-classes.md](css-classes.md) - CSS class combinations and rules
 - [FOLD_STATE_DIAGRAM.md](FOLD_STATE_DIAGRAM.md) - Fold/unfold state machine
+- [dag.md](dag.md) - DAG-based message architecture (replaces timestamp-based ordering)
diff --git a/test/__snapshots__/test_snapshot_html.ambr b/test/__snapshots__/test_snapshot_html.ambr
index c7a8cc2b..a87e5fc7 100644
--- a/test/__snapshots__/test_snapshot_html.ambr
+++ b/test/__snapshots__/test_snapshot_html.ambr
@@ -50,6 +50,10 @@
       --system-error-color: #f44336;
       --tool-use-color: #4caf50;
   
+      /* Fork/branch structural colors */
+      --fork-point-color: #adb5bd;
+      --branch-point-color: #adb5bd;
+  
       /* Question/answer tool colors */
       --question-accent: #f5a623;
       --question-bg: #fffbf0;
@@ -242,6 +246,21 @@
       bottom: 200px;
   }
   
+  .debug-toggle.floating-btn {
+      bottom: 260px;
+      border-radius: 6px;
+      width: 38px;
+      height: 28px;
+      font-size: 0.65em;
+      font-family: 'SFMono-Regular', Consolas, monospace;
+      font-weight: 600;
+  }
+  
+  .debug-toggle.floating-btn.active {
+      background-color: #d4e8f7;
+      color: #333;
+  }
+  
   @media (max-width: 1280px) {
       .header > span:first-child {
           flex: auto;
@@ -273,6 +292,7 @@
   }
   
   .session-link {
+      display: block;
       padding: 8px 12px;
       background-color: var(--white-dimmed);
       border: 1px solid #dee2e6;
@@ -297,6 +317,25 @@
       margin-top: 2px;
   }
   
+  /* Child session hierarchy */
+  .session-nav-item.session-child {
+      border-left: 3px solid var(--accent-color, #6c757d);
+      padding-left: 8px;
+  }
+  
+  .session-backlink {
+      font-size: 0.75em;
+      color: #6c757d;
+      display: block;
+      margin-bottom: 2px;
+      text-decoration: none;
+  }
+  
+  a.session-backlink:hover {
+      color: var(--text-secondary);
+      text-decoration: underline;
+  }
+  
   /* Project-specific session navigation */
   .project-sessions {
       margin-top: 15px;
@@ -353,6 +392,86 @@
       font-size: 0.75em;
       line-height: 1.3;
   }
+  
+  /* Fork point element — standalone structural element after a fork message */
+  .fork-point {
+      margin: 8px 0 2em 0;
+      padding: 8px 14px;
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      border-left: 3px solid var(--fork-point-color);
+      border-radius: 8px;
+  }
+  
+  .fork-point-header {
+      font-weight: 600;
+      margin-bottom: 4px;
+      color: var(--text-secondary, #495057);
+  }
+  
+  .fork-point-branches {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      padding-left: 12px;
+  }
+  
+  .fork-point-branch {
+      display: block;
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      padding: 2px 0;
+      transition: color 0.2s;
+  }
+  
+  .fork-point-branch:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Branch header back-reference to fork point */
+  .branch-from {
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      margin-top: 2px;
+  }
+  
+  .branch-backlink {
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      transition: color 0.2s;
+  }
+  
+  .branch-backlink:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Fork point and branch nav items — lightweight text links, not cards */
+  .session-fork-point,
+  .session-branch {
+      padding-left: 8px;
+  }
+  
+  .session-fork-point {
+      border-left: 2px dashed #888;
+  }
+  
+  .session-branch {
+      border-left: 2px dashed #666;
+  }
+  
+  .fork-link,
+  .branch-link {
+      display: block;
+      text-decoration: none;
+      color: #6c757d;
+      padding: 2px 0;
+      font-size: 0.85em;
+  }
+  
+  .fork-link:hover,
+  .branch-link:hover {
+      color: var(--text-secondary);
+  }
   /* Project card styles for index page */
   .project-list {
       display: grid;
@@ -1733,22 +1852,28 @@
   
       <div class='session-nav'>
           
-          <a href='-Users-test-project-alpha/session-session-abc12345.html'
-              class='session-link'>
-              <div class='session-link-title'>
-                  
-                  Test session summary •
+          
+          <div class='session-nav-item'
+              >
+              
+              <a href='-Users-test-project-alpha/session-session-abc12345.html'
+                  class='session-link'>
+                  <div class='session-link-title'>
+                      
+                      Test session summary •
+                      
+                      session-
+                  </div>
+                  <div class='session-link-meta'>
+                      <span class="timestamp">2025-01-15 10:00:00</span> • 10 messages
+                      
+                  </div>
                   
-                  session-
-              </div>
-              <div class='session-link-meta'>
-                  <span class="timestamp">2025-01-15 10:00:00</span> • 10 messages
+                  <pre class='session-preview'>Hello, this is a test</pre>
                   
-              </div>
-              
-              <pre class='session-preview'>Hello, this is a test</pre>
-              
-          </a>
+              </a>
+          </div>
+          
           
       </div>
   </div>
@@ -1935,6 +2060,10 @@
       --system-error-color: #f44336;
       --tool-use-color: #4caf50;
   
+      /* Fork/branch structural colors */
+      --fork-point-color: #adb5bd;
+      --branch-point-color: #adb5bd;
+  
       /* Question/answer tool colors */
       --question-accent: #f5a623;
       --question-bg: #fffbf0;
@@ -2127,6 +2256,21 @@
       bottom: 200px;
   }
   
+  .debug-toggle.floating-btn {
+      bottom: 260px;
+      border-radius: 6px;
+      width: 38px;
+      height: 28px;
+      font-size: 0.65em;
+      font-family: 'SFMono-Regular', Consolas, monospace;
+      font-weight: 600;
+  }
+  
+  .debug-toggle.floating-btn.active {
+      background-color: #d4e8f7;
+      color: #333;
+  }
+  
   @media (max-width: 1280px) {
       .header > span:first-child {
           flex: auto;
@@ -2699,6 +2843,26 @@
       font-size: 1.2em;
   }
   
+  /* Branch headers (within-session forks) — indent set via inline
+     style based on tree depth (margin-left: depth*2em). */
+  .branch-header {
+      background-color: transparent;
+      box-shadow: none;
+      border: none;
+      border-left: 3px solid var(--branch-point-color);
+      padding: 8px 14px;
+      margin: 2em 0 1em 0;
+  }
+  
+  .branch-header .header {
+      font-size: 1em;
+      margin-bottom: 0;
+  }
+  
+  .branch-header .fold-bar[data-border-color="session-header"] .fold-bar-section.folded {
+      border-bottom-color: var(--branch-point-color);
+  }
+  
   .session-subtitle {
       font-size: 0.9em;
       color: var(--text-muted);
@@ -3026,6 +3190,20 @@
   .ansi-bg-cyan { background-color: #11a8cd; }
   .ansi-bg-white { background-color: #e5e5e5; }
   
+  /* Debug UUID info */
+  .debug-info {
+      display: none;
+      font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+      font-size: 0.7em;
+      color: #999;
+      padding: 2px 0;
+      letter-spacing: 0.02em;
+  }
+  
+  .show-debug-info .debug-info {
+      display: block;
+  }
+  
   /* Bright background colors */
   .ansi-bg-bright-black { background-color: #666666; }
   .ansi-bg-bright-red { background-color: #f14c4c; }
@@ -3161,6 +3339,7 @@
   }
   
   .session-link {
+      display: block;
       padding: 8px 12px;
       background-color: var(--white-dimmed);
       border: 1px solid #dee2e6;
@@ -3185,6 +3364,25 @@
       margin-top: 2px;
   }
   
+  /* Child session hierarchy */
+  .session-nav-item.session-child {
+      border-left: 3px solid var(--accent-color, #6c757d);
+      padding-left: 8px;
+  }
+  
+  .session-backlink {
+      font-size: 0.75em;
+      color: #6c757d;
+      display: block;
+      margin-bottom: 2px;
+      text-decoration: none;
+  }
+  
+  a.session-backlink:hover {
+      color: var(--text-secondary);
+      text-decoration: underline;
+  }
+  
   /* Project-specific session navigation */
   .project-sessions {
       margin-top: 15px;
@@ -3241,6 +3439,86 @@
       font-size: 0.75em;
       line-height: 1.3;
   }
+  
+  /* Fork point element — standalone structural element after a fork message */
+  .fork-point {
+      margin: 8px 0 2em 0;
+      padding: 8px 14px;
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      border-left: 3px solid var(--fork-point-color);
+      border-radius: 8px;
+  }
+  
+  .fork-point-header {
+      font-weight: 600;
+      margin-bottom: 4px;
+      color: var(--text-secondary, #495057);
+  }
+  
+  .fork-point-branches {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      padding-left: 12px;
+  }
+  
+  .fork-point-branch {
+      display: block;
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      padding: 2px 0;
+      transition: color 0.2s;
+  }
+  
+  .fork-point-branch:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Branch header back-reference to fork point */
+  .branch-from {
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      margin-top: 2px;
+  }
+  
+  .branch-backlink {
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      transition: color 0.2s;
+  }
+  
+  .branch-backlink:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Fork point and branch nav items — lightweight text links, not cards */
+  .session-fork-point,
+  .session-branch {
+      padding-left: 8px;
+  }
+  
+  .session-fork-point {
+      border-left: 2px dashed #888;
+  }
+  
+  .session-branch {
+      border-left: 2px dashed #666;
+  }
+  
+  .fork-link,
+  .branch-link {
+      display: block;
+      text-decoration: none;
+      color: #6c757d;
+      padding: 2px 0;
+      font-size: 0.85em;
+  }
+  
+  .fork-link:hover,
+  .branch-link:hover {
+      color: var(--text-secondary);
+  }
   /* Filter toolbar and controls */
   .filter-toolbar {
       background-color: var(--neutral-dimmed);
@@ -5081,6 +5359,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-1' id='msg-d-1'>
           <div class='header'>
               <span>🤷 User</span>
@@ -5091,6 +5370,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_001</div>
           <div class='content'><pre>Hello Claude! Can you help me understand how Python decorators work?</pre></div>
           
           <div class='fold-bar' data-message-id='d-1' data-border-color='user'>
@@ -5108,6 +5388,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-1' data-message-id='d-2' id='msg-d-2'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -5120,6 +5401,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_002</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>I'd be happy to help you understand Python decorators! A decorator is a design pattern that allows you to modify or extend the behavior of functions or classes without permanently modifying their code.</p>
   <p>Here's a simple example:</p>
   <div class="highlight"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">my_decorator</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
@@ -5147,6 +5429,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-3' id='msg-d-3'>
           <div class='header'>
               <span>🤷 User</span>
@@ -5157,6 +5440,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_003</div>
           <div class='content'><pre>Great! Can you also show me how to create a decorator that takes parameters?</pre></div>
           
           <div class='fold-bar' data-message-id='d-3' data-border-color='user'>
@@ -5174,6 +5458,7 @@
       
       
       
+      
       <div class='message tool_use pair_first d-0 d-3' data-message-id='d-4' id='msg-d-4'>
           <div class='header'>
               <span title="ID: tool_001">📝 Edit <span class='tool-summary'>/tmp/decorator_example.py</span></span>
@@ -5184,6 +5469,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_004</div>
           <div class='content'><div class='edit-tool-content'><div class='edit-diff'><div class='diff-line diff-added'><span class='diff-marker'>+</span>def repeat(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    def decorator(func):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        def wrapper(*args, **kwargs):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            for _ in range(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>                result = func(*args, **kwargs)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            return result</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        return wrapper</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    return decorator</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>@repeat(3)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>def greet(name):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    print(f&quot;Hello, {name}!&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>greet(&quot;Alice&quot;)</div></div></div></div>
           
       </div>
@@ -5191,6 +5477,7 @@
       
       
       
+      
       <div class='message tool_result pair_last d-0 d-3' data-message-id='d-5' id='msg-d-5'>
           <div class='header'>
               <span title="ID: tool_001"></span>
@@ -5201,6 +5488,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_005</div>
           <div class='content'><pre>File created successfully at: /tmp/decorator_example.py</pre></div>
           
       </div>
@@ -5208,6 +5496,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-3' data-message-id='d-6' id='msg-d-6'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -5220,6 +5509,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_006</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! I've created an example of a parameterized decorator. Here's how it works:</p>
   <ol>
   <li><strong><code>repeat(times)</code></strong> - This is the decorator factory that takes parameters</li>
@@ -5240,6 +5530,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-7' id='msg-d-7'>
           <div class='header'>
               <span>🤷 User</span>
@@ -5250,6 +5541,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_007</div>
           <div class='content'><pre>Can you run that example to show the output?</pre></div>
           
           <div class='fold-bar' data-message-id='d-7' data-border-color='user'>
@@ -5267,6 +5559,7 @@
       
       
       
+      
       <div class='message tool_use pair_first d-0 d-7' data-message-id='d-8' id='msg-d-8'>
           <div class='header'>
               <span title="ID: tool_002">💻 Bash <span class='tool-summary'>Run the decorator example to show output</span></span>
@@ -5277,6 +5570,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_008</div>
           <div class='content'><div class='bash-tool-content'><pre class='bash-tool-command'>python /tmp/decorator_example.py</pre></div></div>
           
       </div>
@@ -5284,6 +5578,7 @@
       
       
       
+      
       <div class='message tool_result pair_last d-0 d-7' data-message-id='d-9' id='msg-d-9'>
           <div class='header'>
               <span title="ID: tool_002"></span>
@@ -5294,6 +5589,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_009</div>
           <div class='content'><pre>Hello, Alice!
   Hello, Alice!
   Hello, Alice!</pre></div>
@@ -5303,6 +5599,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-7' data-message-id='d-10' id='msg-d-10'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -5315,6 +5612,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_010</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! As you can see, the <code>@repeat(3)</code> decorator successfully made the <code>greet</code> function execute three times, printing &quot;Hello, Alice!&quot; three times.</p>
   <p>This demonstrates the power of parameterized decorators - you can customize their behavior by passing arguments to the decorator factory. Some common use cases include:</p>
   <ul>
@@ -5331,6 +5629,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-11' id='msg-d-11'>
           <div class='header'>
               <span>🤷 User</span>
@@ -5341,15 +5640,18 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_011</div>
           <div class='content'><pre>This is really helpful! Let me try to implement a timing decorator myself. Can you help me if I get stuck?</pre></div>
           
       </div>
       
       
+      
   
       <button class="timeline-toggle floating-btn" id="toggleTimeline" title="Show timeline">📆</button>
       <button class="filter-messages floating-btn" id="filterMessages" title="Search & Filter">🔍</button>
       <button class="toggle-details floating-btn" id="toggleDetails" title="Toggle all details">📋</button>
+      <button class="debug-toggle floating-btn" id="toggleDebug" title="Show UUIDs">uuid</button>
       <a class="scroll-top floating-btn" title="Scroll to top" href="#title">🔝</a>
   
       <script>
@@ -5357,6 +5659,7 @@
               const toggleButton = document.getElementById('toggleDetails');
               const timelineButton = document.getElementById('toggleTimeline');
               const filterButton = document.getElementById('filterMessages');
+              const debugButton = document.getElementById('toggleDebug');
               const filterToolbar = document.querySelector('.filter-toolbar');
               const selectAllButton = document.getElementById('selectAll');
               const selectNoneButton = document.getElementById('selectNone');
@@ -5480,6 +5783,12 @@
       convertTimestampsToLocalTimezone();
   })();
   
+              // Debug UUID toggle
+              debugButton.addEventListener('click', function () {
+                  document.body.classList.toggle('show-debug-info');
+                  debugButton.classList.toggle('active');
+              });
+  
               // Parse URL parameters
               function getUrlParams() {
                   const params = new URLSearchParams(window.location.search);
@@ -6907,6 +7216,10 @@
       --system-error-color: #f44336;
       --tool-use-color: #4caf50;
   
+      /* Fork/branch structural colors */
+      --fork-point-color: #adb5bd;
+      --branch-point-color: #adb5bd;
+  
       /* Question/answer tool colors */
       --question-accent: #f5a623;
       --question-bg: #fffbf0;
@@ -7099,6 +7412,21 @@
       bottom: 200px;
   }
   
+  .debug-toggle.floating-btn {
+      bottom: 260px;
+      border-radius: 6px;
+      width: 38px;
+      height: 28px;
+      font-size: 0.65em;
+      font-family: 'SFMono-Regular', Consolas, monospace;
+      font-weight: 600;
+  }
+  
+  .debug-toggle.floating-btn.active {
+      background-color: #d4e8f7;
+      color: #333;
+  }
+  
   @media (max-width: 1280px) {
       .header > span:first-child {
           flex: auto;
@@ -7671,6 +7999,26 @@
       font-size: 1.2em;
   }
   
+  /* Branch headers (within-session forks) — indent set via inline
+     style based on tree depth (margin-left: depth*2em). */
+  .branch-header {
+      background-color: transparent;
+      box-shadow: none;
+      border: none;
+      border-left: 3px solid var(--branch-point-color);
+      padding: 8px 14px;
+      margin: 2em 0 1em 0;
+  }
+  
+  .branch-header .header {
+      font-size: 1em;
+      margin-bottom: 0;
+  }
+  
+  .branch-header .fold-bar[data-border-color="session-header"] .fold-bar-section.folded {
+      border-bottom-color: var(--branch-point-color);
+  }
+  
   .session-subtitle {
       font-size: 0.9em;
       color: var(--text-muted);
@@ -7998,6 +8346,20 @@
   .ansi-bg-cyan { background-color: #11a8cd; }
   .ansi-bg-white { background-color: #e5e5e5; }
   
+  /* Debug UUID info */
+  .debug-info {
+      display: none;
+      font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+      font-size: 0.7em;
+      color: #999;
+      padding: 2px 0;
+      letter-spacing: 0.02em;
+  }
+  
+  .show-debug-info .debug-info {
+      display: block;
+  }
+  
   /* Bright background colors */
   .ansi-bg-bright-black { background-color: #666666; }
   .ansi-bg-bright-red { background-color: #f14c4c; }
@@ -8133,6 +8495,7 @@
   }
   
   .session-link {
+      display: block;
       padding: 8px 12px;
       background-color: var(--white-dimmed);
       border: 1px solid #dee2e6;
@@ -8157,6 +8520,25 @@
       margin-top: 2px;
   }
   
+  /* Child session hierarchy */
+  .session-nav-item.session-child {
+      border-left: 3px solid var(--accent-color, #6c757d);
+      padding-left: 8px;
+  }
+  
+  .session-backlink {
+      font-size: 0.75em;
+      color: #6c757d;
+      display: block;
+      margin-bottom: 2px;
+      text-decoration: none;
+  }
+  
+  a.session-backlink:hover {
+      color: var(--text-secondary);
+      text-decoration: underline;
+  }
+  
   /* Project-specific session navigation */
   .project-sessions {
       margin-top: 15px;
@@ -8213,6 +8595,86 @@
       font-size: 0.75em;
       line-height: 1.3;
   }
+  
+  /* Fork point element — standalone structural element after a fork message */
+  .fork-point {
+      margin: 8px 0 2em 0;
+      padding: 8px 14px;
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      border-left: 3px solid var(--fork-point-color);
+      border-radius: 8px;
+  }
+  
+  .fork-point-header {
+      font-weight: 600;
+      margin-bottom: 4px;
+      color: var(--text-secondary, #495057);
+  }
+  
+  .fork-point-branches {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      padding-left: 12px;
+  }
+  
+  .fork-point-branch {
+      display: block;
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      padding: 2px 0;
+      transition: color 0.2s;
+  }
+  
+  .fork-point-branch:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Branch header back-reference to fork point */
+  .branch-from {
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      margin-top: 2px;
+  }
+  
+  .branch-backlink {
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      transition: color 0.2s;
+  }
+  
+  .branch-backlink:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Fork point and branch nav items — lightweight text links, not cards */
+  .session-fork-point,
+  .session-branch {
+      padding-left: 8px;
+  }
+  
+  .session-fork-point {
+      border-left: 2px dashed #888;
+  }
+  
+  .session-branch {
+      border-left: 2px dashed #666;
+  }
+  
+  .fork-link,
+  .branch-link {
+      display: block;
+      text-decoration: none;
+      color: #6c757d;
+      padding: 2px 0;
+      font-size: 0.85em;
+  }
+  
+  .fork-link:hover,
+  .branch-link:hover {
+      color: var(--text-secondary);
+  }
   /* Filter toolbar and controls */
   .filter-toolbar {
       background-color: var(--neutral-dimmed);
@@ -10053,6 +10515,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-1' id='msg-d-1'>
           <div class='header'>
               <span>🤷 User</span>
@@ -10063,6 +10526,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_001</div>
           <div class='content'><pre>Here&#x27;s a message with some **markdown** formatting, `inline code`, and even a [link](https://example.com). Let&#x27;s see how it renders!</pre></div>
           
           <div class='fold-bar' data-message-id='d-1' data-border-color='user'>
@@ -10080,6 +10544,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-1' data-message-id='d-2' id='msg-d-2'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -10092,6 +10557,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_002</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Great example! Markdown formatting is indeed supported. Here are some more examples:</p>
   <h2>Headers work too</h2>
   <h3>Sublevel headers</h3>
@@ -10138,6 +10604,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-3' id='msg-d-3'>
           <div class='header'>
               <span>🤷 User</span>
@@ -10148,6 +10615,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_003</div>
           <div class='content'><pre>Let&#x27;s test a very long message to see how it handles text wrapping and layout. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.</pre></div>
           
           <div class='fold-bar' data-message-id='d-3' data-border-color='user'>
@@ -10165,6 +10633,7 @@
       
       
       
+      
       <div class='message tool_use pair_first d-0 d-3' data-message-id='d-4' id='msg-d-4'>
           <div class='header'>
               <span title="ID: tool_edge_001">🛠️ FailingTool</span>
@@ -10175,6 +10644,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_004</div>
           <div class='content'><table class='tool-params-table'>
               <tr>
                   <td class='tool-param-key'>test_param</td>
@@ -10187,6 +10657,7 @@
       
       
       
+      
       <div class='message tool_result error pair_last d-0 d-3' data-message-id='d-5' id='msg-d-5'>
           <div class='header'>
               <span title="ID: tool_edge_001">🚨 Error</span>
@@ -10197,6 +10668,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_005</div>
           <div class='content'><pre>Error: Tool execution failed with error: Command not found</pre></div>
           
       </div>
@@ -10204,6 +10676,7 @@
       
       
       
+      
       <div class='message user slash-command pair_first d-0' data-message-id='d-6' id='msg-d-6'>
           <div class='header'>
               <span>🤷 Slash Command</span>
@@ -10214,6 +10687,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_007</div>
           <div class='content'><code>test-command</code><br><strong>Args:</strong> --verbose --output /tmp/test.log<br><strong>Content:</strong><pre>This is the actual command content with some JSON structure and escaped characters: &quot;quotes&quot; and 
   line breaks
   </pre></div>
@@ -10223,6 +10697,7 @@
       
       
       
+      
       <div class='message user command-output pair_last d-0' data-message-id='d-7' id='msg-d-7'>
           <div class='header'>
               <span></span>
@@ -10233,6 +10708,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_008</div>
           <div class='content'><pre class='command-output-content'>Command output here:
   Line 1 of output
   Line 2 of output
@@ -10259,6 +10735,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-7' data-message-id='d-8' id='msg-d-8'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -10271,6 +10748,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_009</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>I see the long Lorem ipsum text wraps nicely! Long text handling is important for readability. The CSS should handle word wrapping automatically.</p>
   </div></div>
           
@@ -10289,6 +10767,7 @@
       
       
       
+      
       <div class='message tool_use d-0 d-7 d-8' data-message-id='d-9' id='msg-d-9'>
           <div class='header'>
               <span title="ID: tool_edge_002">🛠️ MultiEdit</span>
@@ -10299,6 +10778,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_009</div>
           <div class='content'><div class='multiedit-tool-content'><div class='multiedit-file-path'>📝 /tmp/complex_example.py</div><div class='multiedit-count'>Applying 1 edits</div><div class='multiedit-item'><div class='multiedit-item-header'>Edit #1</div><div class='edit-diff'><div class='diff-line diff-added'><span class='diff-marker'>+</span>#!/usr/bin/env python3</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>&quot;&quot;&quot;</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>Complex example with multiple operations.</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>&quot;&quot;&quot;</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>import json</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>import sys</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>from typing import List, Dict, Any</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>def process_data(items: List[Dict[str, Any]]) -&gt; None:</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    &quot;&quot;&quot;</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    Process a list of data items.</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    &quot;&quot;&quot;</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    for item in items:</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        print(f&quot;Processing: {item[&#x27;name&#x27;]}&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        if item.get(&#x27;active&#x27;, False):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            print(f&quot;  Status: Active&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        else:</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            print(f&quot;  Status: Inactive&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>if __name__ == &quot;__main__&quot;:</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    sample_data = [</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        {&quot;name&quot;: &quot;Item 1&quot;, &quot;active&quot;: True},</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        {&quot;name&quot;: &quot;Item 2&quot;, &quot;active&quot;: False},</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        {&quot;name&quot;: &quot;Item 3&quot;, &quot;active&quot;: True}</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    ]</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    process_data(sample_data)</div></div></div></div></div>
           
       </div>
@@ -10306,6 +10786,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-10' id='msg-d-10'>
           <div class='header'>
               <span>🤷 User</span>
@@ -10316,6 +10797,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_011</div>
           <div class='content'><pre>Testing special characters: café, naïve, résumé, 中文, العربية, русский, 🎉 emojis 🚀 and symbols ∑∆√π∞</pre></div>
           
       </div>
@@ -10323,6 +10805,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-13' id='msg-d-13'>
           <div class='header'>
               <span>🤷 User</span>
@@ -10333,12 +10816,14 @@
                   
               </div>
           </div>
+          <div class='debug-info'>edge_010</div>
           <div class='content'><pre>wow error</pre></div>
           
       </div>
       
       
       
+      
       <div class="session-divider"></div>
       <div class='message session-header' data-message-id='d-11' data-session-id='todowrite_session' id='msg-d-11'>
           <div class='header'>Session: todowrit</div>
@@ -10358,6 +10843,7 @@
       
       
       
+      
       <div class='message tool_use d-11' data-message-id='d-12' id='msg-d-12'>
           <div class='header'>
               <span title="ID: toolu_todowrite_002">🛠️ TodoWrite</span>
@@ -10368,6 +10854,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>assistant_00 &rarr; assistant_00</div>
           <div class='content'><table class='tool-params-table'>
               <tr>
                   <td class='tool-param-key'>todos</td>
@@ -10414,10 +10901,12 @@
       </div>
       
       
+      
   
       <button class="timeline-toggle floating-btn" id="toggleTimeline" title="Show timeline">📆</button>
       <button class="filter-messages floating-btn" id="filterMessages" title="Search & Filter">🔍</button>
       <button class="toggle-details floating-btn" id="toggleDetails" title="Toggle all details">📋</button>
+      <button class="debug-toggle floating-btn" id="toggleDebug" title="Show UUIDs">uuid</button>
       <a class="scroll-top floating-btn" title="Scroll to top" href="#title">🔝</a>
   
       <script>
@@ -10425,6 +10914,7 @@
               const toggleButton = document.getElementById('toggleDetails');
               const timelineButton = document.getElementById('toggleTimeline');
               const filterButton = document.getElementById('filterMessages');
+              const debugButton = document.getElementById('toggleDebug');
               const filterToolbar = document.querySelector('.filter-toolbar');
               const selectAllButton = document.getElementById('selectAll');
               const selectNoneButton = document.getElementById('selectNone');
@@ -10548,6 +11038,12 @@
       convertTimestampsToLocalTimezone();
   })();
   
+              // Debug UUID toggle
+              debugButton.addEventListener('click', function () {
+                  document.body.classList.toggle('show-debug-info');
+                  debugButton.classList.toggle('active');
+              });
+  
               // Parse URL parameters
               function getUrlParams() {
                   const params = new URLSearchParams(window.location.search);
@@ -11975,6 +12471,10 @@
       --system-error-color: #f44336;
       --tool-use-color: #4caf50;
   
+      /* Fork/branch structural colors */
+      --fork-point-color: #adb5bd;
+      --branch-point-color: #adb5bd;
+  
       /* Question/answer tool colors */
       --question-accent: #f5a623;
       --question-bg: #fffbf0;
@@ -12167,6 +12667,21 @@
       bottom: 200px;
   }
   
+  .debug-toggle.floating-btn {
+      bottom: 260px;
+      border-radius: 6px;
+      width: 38px;
+      height: 28px;
+      font-size: 0.65em;
+      font-family: 'SFMono-Regular', Consolas, monospace;
+      font-weight: 600;
+  }
+  
+  .debug-toggle.floating-btn.active {
+      background-color: #d4e8f7;
+      color: #333;
+  }
+  
   @media (max-width: 1280px) {
       .header > span:first-child {
           flex: auto;
@@ -12739,6 +13254,26 @@
       font-size: 1.2em;
   }
   
+  /* Branch headers (within-session forks) — indent set via inline
+     style based on tree depth (margin-left: depth*2em). */
+  .branch-header {
+      background-color: transparent;
+      box-shadow: none;
+      border: none;
+      border-left: 3px solid var(--branch-point-color);
+      padding: 8px 14px;
+      margin: 2em 0 1em 0;
+  }
+  
+  .branch-header .header {
+      font-size: 1em;
+      margin-bottom: 0;
+  }
+  
+  .branch-header .fold-bar[data-border-color="session-header"] .fold-bar-section.folded {
+      border-bottom-color: var(--branch-point-color);
+  }
+  
   .session-subtitle {
       font-size: 0.9em;
       color: var(--text-muted);
@@ -13066,6 +13601,20 @@
   .ansi-bg-cyan { background-color: #11a8cd; }
   .ansi-bg-white { background-color: #e5e5e5; }
   
+  /* Debug UUID info */
+  .debug-info {
+      display: none;
+      font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+      font-size: 0.7em;
+      color: #999;
+      padding: 2px 0;
+      letter-spacing: 0.02em;
+  }
+  
+  .show-debug-info .debug-info {
+      display: block;
+  }
+  
   /* Bright background colors */
   .ansi-bg-bright-black { background-color: #666666; }
   .ansi-bg-bright-red { background-color: #f14c4c; }
@@ -13201,6 +13750,7 @@
   }
   
   .session-link {
+      display: block;
       padding: 8px 12px;
       background-color: var(--white-dimmed);
       border: 1px solid #dee2e6;
@@ -13225,6 +13775,25 @@
       margin-top: 2px;
   }
   
+  /* Child session hierarchy */
+  .session-nav-item.session-child {
+      border-left: 3px solid var(--accent-color, #6c757d);
+      padding-left: 8px;
+  }
+  
+  .session-backlink {
+      font-size: 0.75em;
+      color: #6c757d;
+      display: block;
+      margin-bottom: 2px;
+      text-decoration: none;
+  }
+  
+  a.session-backlink:hover {
+      color: var(--text-secondary);
+      text-decoration: underline;
+  }
+  
   /* Project-specific session navigation */
   .project-sessions {
       margin-top: 15px;
@@ -13281,6 +13850,86 @@
       font-size: 0.75em;
       line-height: 1.3;
   }
+  
+  /* Fork point element — standalone structural element after a fork message */
+  .fork-point {
+      margin: 8px 0 2em 0;
+      padding: 8px 14px;
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      border-left: 3px solid var(--fork-point-color);
+      border-radius: 8px;
+  }
+  
+  .fork-point-header {
+      font-weight: 600;
+      margin-bottom: 4px;
+      color: var(--text-secondary, #495057);
+  }
+  
+  .fork-point-branches {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      padding-left: 12px;
+  }
+  
+  .fork-point-branch {
+      display: block;
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      padding: 2px 0;
+      transition: color 0.2s;
+  }
+  
+  .fork-point-branch:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Branch header back-reference to fork point */
+  .branch-from {
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      margin-top: 2px;
+  }
+  
+  .branch-backlink {
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      transition: color 0.2s;
+  }
+  
+  .branch-backlink:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Fork point and branch nav items — lightweight text links, not cards */
+  .session-fork-point,
+  .session-branch {
+      padding-left: 8px;
+  }
+  
+  .session-fork-point {
+      border-left: 2px dashed #888;
+  }
+  
+  .session-branch {
+      border-left: 2px dashed #666;
+  }
+  
+  .fork-link,
+  .branch-link {
+      display: block;
+      text-decoration: none;
+      color: #6c757d;
+      padding: 2px 0;
+      font-size: 0.85em;
+  }
+  
+  .fork-link:hover,
+  .branch-link:hover {
+      color: var(--text-secondary);
+  }
   /* Filter toolbar and controls */
   .filter-toolbar {
       background-color: var(--neutral-dimmed);
@@ -15105,41 +15754,53 @@
   
       <div class='session-nav'>
           
-          <a href='#msg-d-0'
-              class='session-link'>
-              <div class='session-link-title'>
-                  
-                  session_
-              </div>
-              <div class='session-link-meta'>
-                  <span class="timestamp" data-timestamp="2025-07-03T15:50:07.874717Z" data-timestamp-end="2025-07-03T15:54:07.874717Z">2025-07-03 15:50:07 - 2025-07-03 15:54:07</span> • 3 messages
-                  
-                  <br>Token usage – Input: 20 | Output: 35
-                  
-              </div>
-              
-              <pre class='session-preview'>This is from a different session file to test multi-session handling.</pre>
-              
-          </a>
           
-          <a href='#msg-d-2'
-              class='session-link'>
-              <div class='session-link-title'>
+          <div class='session-nav-item'
+              >
+              
+              <a href='#msg-d-0'
+                  class='session-link'>
+                  <div class='session-link-title'>
+                      
+                      session_
+                  </div>
+                  <div class='session-link-meta'>
+                      <span class="timestamp" data-timestamp="2025-07-03T15:50:07.874717Z" data-timestamp-end="2025-07-03T15:54:07.874717Z">2025-07-03 15:50:07 - 2025-07-03 15:54:07</span> • 3 messages
+                      
+                      <br>Token usage – Input: 20 | Output: 35
+                      
+                  </div>
                   
-                  User learned about Python decorators, including basic decorators and parameterized decorators. Created and ran examples showing how decorators work with functions. User is now ready to implement their own timing decorator. •
+                  <pre class='session-preview'>This is from a different session file to test multi-session handling.</pre>
                   
-                  test_ses
-              </div>
-              <div class='session-link-meta'>
-                  <span class="timestamp" data-timestamp="2025-07-03T15:50:07.874907Z" data-timestamp-end="2025-07-03T16:10:07.874907Z">2025-07-03 15:50:07 - 2025-07-03 16:10:07</span> • 11 messages
+              </a>
+          </div>
+          
+          
+          
+          <div class='session-nav-item'
+              >
+              
+              <a href='#msg-d-4'
+                  class='session-link'>
+                  <div class='session-link-title'>
+                      
+                      User learned about Python decorators, including basic decorators and parameterized decorators. Created and ran examples showing how decorators work with functions. User is now ready to implement their own timing decorator. •
+                      
+                      test_ses
+                  </div>
+                  <div class='session-link-meta'>
+                      <span class="timestamp" data-timestamp="2025-07-03T15:50:07.874907Z" data-timestamp-end="2025-07-03T16:10:07.874907Z">2025-07-03 15:50:07 - 2025-07-03 16:10:07</span> • 11 messages
+                      
+                      <br>Token usage – Input: 218 | Output: 445
+                      
+                  </div>
                   
-                  <br>Token usage – Input: 218 | Output: 445
+                  <pre class='session-preview'>Hello Claude! Can you help me understand how Python decorators work?</pre>
                   
-              </div>
-              
-              <pre class='session-preview'>Hello Claude! Can you help me understand how Python decorators work?</pre>
-              
-          </a>
+              </a>
+          </div>
+          
           
       </div>
   </div>
@@ -15172,6 +15833,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-1' id='msg-d-1'>
           <div class='header'>
               <span>🤷 User</span>
@@ -15182,6 +15844,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>session_b_00</div>
           <div class='content'><pre>This is from a different session file to test multi-session handling.</pre></div>
           
           <div class='fold-bar' data-message-id='d-1' data-border-color='user'>
@@ -15199,7 +15862,8 @@
       
       
       
-      <div class='message assistant d-0 d-1' data-message-id='d-4' id='msg-d-4'>
+      
+      <div class='message assistant d-0 d-1' data-message-id='d-2' id='msg-d-2'>
           <div class='header'>
               <span>🤖 Assistant</span>
               <div class='header-info'>
@@ -15211,6 +15875,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>session_b_00</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Indeed! This message is from a different JSONL file, which should help test the session divider logic. Only the first session should show a divider.</p>
   </div></div>
           
@@ -15219,7 +15884,8 @@
       
       
       
-      <div class='message user d-0' data-message-id='d-6' id='msg-d-6'>
+      
+      <div class='message user d-0' data-message-id='d-3' id='msg-d-3'>
           <div class='header'>
               <span>🤷 User</span>
               <div class='header-info'>
@@ -15229,24 +15895,26 @@
                   
               </div>
           </div>
+          <div class='debug-info'>session_b_00</div>
           <div class='content'><pre>Perfect! This should appear without any session divider above it.</pre></div>
           
       </div>
       
       
       
+      
       <div class="session-divider"></div>
-      <div class='message session-header' data-message-id='d-2' data-session-id='test_session' id='msg-d-2'>
+      <div class='message session-header' data-message-id='d-4' data-session-id='test_session' id='msg-d-4'>
           <div class='header'>Session: User learned about Python decorators, including basic decorators and parameterized decorators. Created and ran examples showing how decorators work with functions. User is now ready to implement their own timing decorator. • test_ses</div>
           
-          <div class='fold-bar' data-message-id='d-2' data-border-color='session-header'>
+          <div class='fold-bar' data-message-id='d-4' data-border-color='session-header'>
               
               
-              <div class='fold-bar-section fold-one-level' data-action='fold-one' data-target='d-2' data-title-unfolded='Fold (all levels) all 9 descendants' data-title-folded='Unfold (1st level) 4 users' title='Fold (all levels) all 9 descendants'>
+              <div class='fold-bar-section fold-one-level' data-action='fold-one' data-target='d-4' data-title-unfolded='Fold (all levels) all 9 descendants' data-title-folded='Unfold (1st level) 4 users' title='Fold (all levels) all 9 descendants'>
                   <span class='fold-icon'>▼</span>
                   <span class='fold-label'>4 users</span>
               </div>
-              <div class='fold-bar-section fold-all-levels' data-action='fold-all' data-target='d-2' data-title-unfolded='Fold (to 1st level) 4 users' data-title-folded='Unfold (all levels) all 9 descendants' title='Fold (to 1st level) 4 users'>
+              <div class='fold-bar-section fold-all-levels' data-action='fold-all' data-target='d-4' data-title-unfolded='Fold (to 1st level) 4 users' data-title-folded='Unfold (all levels) all 9 descendants' title='Fold (to 1st level) 4 users'>
                   <span class='fold-icon'>▼▼</span>
                   <span class='fold-label'>4 users, 3 assistants, 2 more total</span>
               </div>
@@ -15258,7 +15926,8 @@
       
       
       
-      <div class='message user d-2' data-message-id='d-3' id='msg-d-3'>
+      
+      <div class='message user d-4' data-message-id='d-5' id='msg-d-5'>
           <div class='header'>
               <span>🤷 User</span>
               <div class='header-info'>
@@ -15268,12 +15937,13 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_001</div>
           <div class='content'><pre>Hello Claude! Can you help me understand how Python decorators work?</pre></div>
           
-          <div class='fold-bar' data-message-id='d-3' data-border-color='user'>
+          <div class='fold-bar' data-message-id='d-5' data-border-color='user'>
               
               
-              <div class='fold-bar-section fold-one-level full-width' data-action='fold-one' data-target='d-3' data-title-unfolded='Fold 1 assistant' data-title-folded='Unfold (1st level) 1 assistant' title='Fold 1 assistant'>
+              <div class='fold-bar-section fold-one-level full-width' data-action='fold-one' data-target='d-5' data-title-unfolded='Fold 1 assistant' data-title-folded='Unfold (1st level) 1 assistant' title='Fold 1 assistant'>
                   <span class='fold-icon'>▼</span>
                   <span class='fold-label'>1 assistant</span>
               </div>
@@ -15285,7 +15955,8 @@
       
       
       
-      <div class='message assistant d-2 d-3' data-message-id='d-5' id='msg-d-5'>
+      
+      <div class='message assistant d-4 d-5' data-message-id='d-6' id='msg-d-6'>
           <div class='header'>
               <span>🤖 Assistant</span>
               <div class='header-info'>
@@ -15297,6 +15968,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_002</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>I'd be happy to help you understand Python decorators! A decorator is a design pattern that allows you to modify or extend the behavior of functions or classes without permanently modifying their code.</p>
   <p>Here's a simple example:</p>
   <div class="highlight"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">my_decorator</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
@@ -15324,7 +15996,8 @@
       
       
       
-      <div class='message user d-2' data-message-id='d-7' id='msg-d-7'>
+      
+      <div class='message user d-4' data-message-id='d-7' id='msg-d-7'>
           <div class='header'>
               <span>🤷 User</span>
               <div class='header-info'>
@@ -15334,6 +16007,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_003</div>
           <div class='content'><pre>Great! Can you also show me how to create a decorator that takes parameters?</pre></div>
           
           <div class='fold-bar' data-message-id='d-7' data-border-color='user'>
@@ -15351,7 +16025,8 @@
       
       
       
-      <div class='message tool_use pair_first d-2 d-7' data-message-id='d-8' id='msg-d-8'>
+      
+      <div class='message tool_use pair_first d-4 d-7' data-message-id='d-8' id='msg-d-8'>
           <div class='header'>
               <span title="ID: tool_001">📝 Edit <span class='tool-summary'>/tmp/decorator_example.py</span></span>
               <div class='header-info'>
@@ -15361,6 +16036,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_004</div>
           <div class='content'><div class='edit-tool-content'><div class='edit-diff'><div class='diff-line diff-added'><span class='diff-marker'>+</span>def repeat(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    def decorator(func):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        def wrapper(*args, **kwargs):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            for _ in range(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>                result = func(*args, **kwargs)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            return result</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        return wrapper</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    return decorator</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>@repeat(3)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>def greet(name):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    print(f&quot;Hello, {name}!&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>greet(&quot;Alice&quot;)</div></div></div></div>
           
       </div>
@@ -15368,7 +16044,8 @@
       
       
       
-      <div class='message tool_result pair_last d-2 d-7' data-message-id='d-9' id='msg-d-9'>
+      
+      <div class='message tool_result pair_last d-4 d-7' data-message-id='d-9' id='msg-d-9'>
           <div class='header'>
               <span title="ID: tool_001"></span>
               <div class='header-info'>
@@ -15378,6 +16055,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_005</div>
           <div class='content'><pre>File created successfully at: /tmp/decorator_example.py</pre></div>
           
       </div>
@@ -15385,7 +16063,8 @@
       
       
       
-      <div class='message assistant d-2 d-7' data-message-id='d-10' id='msg-d-10'>
+      
+      <div class='message assistant d-4 d-7' data-message-id='d-10' id='msg-d-10'>
           <div class='header'>
               <span>🤖 Assistant</span>
               <div class='header-info'>
@@ -15397,6 +16076,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_006</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! I've created an example of a parameterized decorator. Here's how it works:</p>
   <ol>
   <li><strong><code>repeat(times)</code></strong> - This is the decorator factory that takes parameters</li>
@@ -15417,7 +16097,8 @@
       
       
       
-      <div class='message user d-2' data-message-id='d-11' id='msg-d-11'>
+      
+      <div class='message user d-4' data-message-id='d-11' id='msg-d-11'>
           <div class='header'>
               <span>🤷 User</span>
               <div class='header-info'>
@@ -15427,6 +16108,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_007</div>
           <div class='content'><pre>Can you run that example to show the output?</pre></div>
           
           <div class='fold-bar' data-message-id='d-11' data-border-color='user'>
@@ -15444,7 +16126,8 @@
       
       
       
-      <div class='message tool_use pair_first d-2 d-11' data-message-id='d-12' id='msg-d-12'>
+      
+      <div class='message tool_use pair_first d-4 d-11' data-message-id='d-12' id='msg-d-12'>
           <div class='header'>
               <span title="ID: tool_002">💻 Bash <span class='tool-summary'>Run the decorator example to show output</span></span>
               <div class='header-info'>
@@ -15454,6 +16137,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_008</div>
           <div class='content'><div class='bash-tool-content'><pre class='bash-tool-command'>python /tmp/decorator_example.py</pre></div></div>
           
       </div>
@@ -15461,7 +16145,8 @@
       
       
       
-      <div class='message tool_result pair_last d-2 d-11' data-message-id='d-13' id='msg-d-13'>
+      
+      <div class='message tool_result pair_last d-4 d-11' data-message-id='d-13' id='msg-d-13'>
           <div class='header'>
               <span title="ID: tool_002"></span>
               <div class='header-info'>
@@ -15471,6 +16156,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_009</div>
           <div class='content'><pre>Hello, Alice!
   Hello, Alice!
   Hello, Alice!</pre></div>
@@ -15480,7 +16166,8 @@
       
       
       
-      <div class='message assistant d-2 d-11' data-message-id='d-14' id='msg-d-14'>
+      
+      <div class='message assistant d-4 d-11' data-message-id='d-14' id='msg-d-14'>
           <div class='header'>
               <span>🤖 Assistant</span>
               <div class='header-info'>
@@ -15492,6 +16179,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_010</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! As you can see, the <code>@repeat(3)</code> decorator successfully made the <code>greet</code> function execute three times, printing &quot;Hello, Alice!&quot; three times.</p>
   <p>This demonstrates the power of parameterized decorators - you can customize their behavior by passing arguments to the decorator factory. Some common use cases include:</p>
   <ul>
@@ -15508,7 +16196,8 @@
       
       
       
-      <div class='message user d-2' data-message-id='d-15' id='msg-d-15'>
+      
+      <div class='message user d-4' data-message-id='d-15' id='msg-d-15'>
           <div class='header'>
               <span>🤷 User</span>
               <div class='header-info'>
@@ -15518,15 +16207,18 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_011</div>
           <div class='content'><pre>This is really helpful! Let me try to implement a timing decorator myself. Can you help me if I get stuck?</pre></div>
           
       </div>
       
       
+      
   
       <button class="timeline-toggle floating-btn" id="toggleTimeline" title="Show timeline">📆</button>
       <button class="filter-messages floating-btn" id="filterMessages" title="Search & Filter">🔍</button>
       <button class="toggle-details floating-btn" id="toggleDetails" title="Toggle all details">📋</button>
+      <button class="debug-toggle floating-btn" id="toggleDebug" title="Show UUIDs">uuid</button>
       <a class="scroll-top floating-btn" title="Scroll to top" href="#title">🔝</a>
   
       <script>
@@ -15534,6 +16226,7 @@
               const toggleButton = document.getElementById('toggleDetails');
               const timelineButton = document.getElementById('toggleTimeline');
               const filterButton = document.getElementById('filterMessages');
+              const debugButton = document.getElementById('toggleDebug');
               const filterToolbar = document.querySelector('.filter-toolbar');
               const selectAllButton = document.getElementById('selectAll');
               const selectNoneButton = document.getElementById('selectNone');
@@ -15657,6 +16350,12 @@
       convertTimestampsToLocalTimezone();
   })();
   
+              // Debug UUID toggle
+              debugButton.addEventListener('click', function () {
+                  document.body.classList.toggle('show-debug-info');
+                  debugButton.classList.toggle('active');
+              });
+  
               // Parse URL parameters
               function getUrlParams() {
                   const params = new URLSearchParams(window.location.search);
@@ -17084,6 +17783,10 @@
       --system-error-color: #f44336;
       --tool-use-color: #4caf50;
   
+      /* Fork/branch structural colors */
+      --fork-point-color: #adb5bd;
+      --branch-point-color: #adb5bd;
+  
       /* Question/answer tool colors */
       --question-accent: #f5a623;
       --question-bg: #fffbf0;
@@ -17276,6 +17979,21 @@
       bottom: 200px;
   }
   
+  .debug-toggle.floating-btn {
+      bottom: 260px;
+      border-radius: 6px;
+      width: 38px;
+      height: 28px;
+      font-size: 0.65em;
+      font-family: 'SFMono-Regular', Consolas, monospace;
+      font-weight: 600;
+  }
+  
+  .debug-toggle.floating-btn.active {
+      background-color: #d4e8f7;
+      color: #333;
+  }
+  
   @media (max-width: 1280px) {
       .header > span:first-child {
           flex: auto;
@@ -17848,6 +18566,26 @@
       font-size: 1.2em;
   }
   
+  /* Branch headers (within-session forks) — indent set via inline
+     style based on tree depth (margin-left: depth*2em). */
+  .branch-header {
+      background-color: transparent;
+      box-shadow: none;
+      border: none;
+      border-left: 3px solid var(--branch-point-color);
+      padding: 8px 14px;
+      margin: 2em 0 1em 0;
+  }
+  
+  .branch-header .header {
+      font-size: 1em;
+      margin-bottom: 0;
+  }
+  
+  .branch-header .fold-bar[data-border-color="session-header"] .fold-bar-section.folded {
+      border-bottom-color: var(--branch-point-color);
+  }
+  
   .session-subtitle {
       font-size: 0.9em;
       color: var(--text-muted);
@@ -18175,6 +18913,20 @@
   .ansi-bg-cyan { background-color: #11a8cd; }
   .ansi-bg-white { background-color: #e5e5e5; }
   
+  /* Debug UUID info */
+  .debug-info {
+      display: none;
+      font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+      font-size: 0.7em;
+      color: #999;
+      padding: 2px 0;
+      letter-spacing: 0.02em;
+  }
+  
+  .show-debug-info .debug-info {
+      display: block;
+  }
+  
   /* Bright background colors */
   .ansi-bg-bright-black { background-color: #666666; }
   .ansi-bg-bright-red { background-color: #f14c4c; }
@@ -18310,6 +19062,7 @@
   }
   
   .session-link {
+      display: block;
       padding: 8px 12px;
       background-color: var(--white-dimmed);
       border: 1px solid #dee2e6;
@@ -18334,6 +19087,25 @@
       margin-top: 2px;
   }
   
+  /* Child session hierarchy */
+  .session-nav-item.session-child {
+      border-left: 3px solid var(--accent-color, #6c757d);
+      padding-left: 8px;
+  }
+  
+  .session-backlink {
+      font-size: 0.75em;
+      color: #6c757d;
+      display: block;
+      margin-bottom: 2px;
+      text-decoration: none;
+  }
+  
+  a.session-backlink:hover {
+      color: var(--text-secondary);
+      text-decoration: underline;
+  }
+  
   /* Project-specific session navigation */
   .project-sessions {
       margin-top: 15px;
@@ -18390,6 +19162,86 @@
       font-size: 0.75em;
       line-height: 1.3;
   }
+  
+  /* Fork point element — standalone structural element after a fork message */
+  .fork-point {
+      margin: 8px 0 2em 0;
+      padding: 8px 14px;
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      border-left: 3px solid var(--fork-point-color);
+      border-radius: 8px;
+  }
+  
+  .fork-point-header {
+      font-weight: 600;
+      margin-bottom: 4px;
+      color: var(--text-secondary, #495057);
+  }
+  
+  .fork-point-branches {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+      padding-left: 12px;
+  }
+  
+  .fork-point-branch {
+      display: block;
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      padding: 2px 0;
+      transition: color 0.2s;
+  }
+  
+  .fork-point-branch:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Branch header back-reference to fork point */
+  .branch-from {
+      font-size: 0.85em;
+      color: var(--text-muted, #6c757d);
+      margin-top: 2px;
+  }
+  
+  .branch-backlink {
+      text-decoration: none;
+      color: var(--text-muted, #6c757d);
+      transition: color 0.2s;
+  }
+  
+  .branch-backlink:hover {
+      color: var(--text-secondary, #495057);
+  }
+  
+  /* Fork point and branch nav items — lightweight text links, not cards */
+  .session-fork-point,
+  .session-branch {
+      padding-left: 8px;
+  }
+  
+  .session-fork-point {
+      border-left: 2px dashed #888;
+  }
+  
+  .session-branch {
+      border-left: 2px dashed #666;
+  }
+  
+  .fork-link,
+  .branch-link {
+      display: block;
+      text-decoration: none;
+      color: #6c757d;
+      padding: 2px 0;
+      font-size: 0.85em;
+  }
+  
+  .fork-link:hover,
+  .branch-link:hover {
+      color: var(--text-secondary);
+  }
   /* Filter toolbar and controls */
   .filter-toolbar {
       background-color: var(--neutral-dimmed);
@@ -20230,6 +21082,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-1' id='msg-d-1'>
           <div class='header'>
               <span>🤷 User</span>
@@ -20240,6 +21093,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_001</div>
           <div class='content'><pre>Hello Claude! Can you help me understand how Python decorators work?</pre></div>
           
           <div class='fold-bar' data-message-id='d-1' data-border-color='user'>
@@ -20257,6 +21111,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-1' data-message-id='d-2' id='msg-d-2'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -20269,6 +21124,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_002</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>I'd be happy to help you understand Python decorators! A decorator is a design pattern that allows you to modify or extend the behavior of functions or classes without permanently modifying their code.</p>
   <p>Here's a simple example:</p>
   <div class="highlight"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">my_decorator</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
@@ -20296,6 +21152,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-3' id='msg-d-3'>
           <div class='header'>
               <span>🤷 User</span>
@@ -20306,6 +21163,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_003</div>
           <div class='content'><pre>Great! Can you also show me how to create a decorator that takes parameters?</pre></div>
           
           <div class='fold-bar' data-message-id='d-3' data-border-color='user'>
@@ -20323,6 +21181,7 @@
       
       
       
+      
       <div class='message tool_use pair_first d-0 d-3' data-message-id='d-4' id='msg-d-4'>
           <div class='header'>
               <span title="ID: tool_001">📝 Edit <span class='tool-summary'>/tmp/decorator_example.py</span></span>
@@ -20333,6 +21192,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_004</div>
           <div class='content'><div class='edit-tool-content'><div class='edit-diff'><div class='diff-line diff-added'><span class='diff-marker'>+</span>def repeat(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    def decorator(func):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        def wrapper(*args, **kwargs):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            for _ in range(times):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>                result = func(*args, **kwargs)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>            return result</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>        return wrapper</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    return decorator</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>@repeat(3)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>def greet(name):</div><div class='diff-line diff-added'><span class='diff-marker'>+</span>    print(f&quot;Hello, {name}!&quot;)</div><div class='diff-line diff-added'><span class='diff-marker'>+</span></div><div class='diff-line diff-added'><span class='diff-marker'>+</span>greet(&quot;Alice&quot;)</div></div></div></div>
           
       </div>
@@ -20340,6 +21200,7 @@
       
       
       
+      
       <div class='message tool_result pair_last d-0 d-3' data-message-id='d-5' id='msg-d-5'>
           <div class='header'>
               <span title="ID: tool_001"></span>
@@ -20350,6 +21211,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_005</div>
           <div class='content'><pre>File created successfully at: /tmp/decorator_example.py</pre></div>
           
       </div>
@@ -20357,6 +21219,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-3' data-message-id='d-6' id='msg-d-6'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -20369,6 +21232,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_006</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! I've created an example of a parameterized decorator. Here's how it works:</p>
   <ol>
   <li><strong><code>repeat(times)</code></strong> - This is the decorator factory that takes parameters</li>
@@ -20389,6 +21253,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-7' id='msg-d-7'>
           <div class='header'>
               <span>🤷 User</span>
@@ -20399,6 +21264,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_007</div>
           <div class='content'><pre>Can you run that example to show the output?</pre></div>
           
           <div class='fold-bar' data-message-id='d-7' data-border-color='user'>
@@ -20416,6 +21282,7 @@
       
       
       
+      
       <div class='message tool_use pair_first d-0 d-7' data-message-id='d-8' id='msg-d-8'>
           <div class='header'>
               <span title="ID: tool_002">💻 Bash <span class='tool-summary'>Run the decorator example to show output</span></span>
@@ -20426,6 +21293,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_008</div>
           <div class='content'><div class='bash-tool-content'><pre class='bash-tool-command'>python /tmp/decorator_example.py</pre></div></div>
           
       </div>
@@ -20433,6 +21301,7 @@
       
       
       
+      
       <div class='message tool_result pair_last d-0 d-7' data-message-id='d-9' id='msg-d-9'>
           <div class='header'>
               <span title="ID: tool_002"></span>
@@ -20443,6 +21312,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_009</div>
           <div class='content'><pre>Hello, Alice!
   Hello, Alice!
   Hello, Alice!</pre></div>
@@ -20452,6 +21322,7 @@
       
       
       
+      
       <div class='message assistant d-0 d-7' data-message-id='d-10' id='msg-d-10'>
           <div class='header'>
               <span>🤖 Assistant</span>
@@ -20464,6 +21335,7 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_010</div>
           <div class='content markdown'><div class="assistant-text markdown"><p>Perfect! As you can see, the <code>@repeat(3)</code> decorator successfully made the <code>greet</code> function execute three times, printing &quot;Hello, Alice!&quot; three times.</p>
   <p>This demonstrates the power of parameterized decorators - you can customize their behavior by passing arguments to the decorator factory. Some common use cases include:</p>
   <ul>
@@ -20480,6 +21352,7 @@
       
       
       
+      
       <div class='message user d-0' data-message-id='d-11' id='msg-d-11'>
           <div class='header'>
               <span>🤷 User</span>
@@ -20490,15 +21363,18 @@
                   
               </div>
           </div>
+          <div class='debug-info'>msg_011</div>
           <div class='content'><pre>This is really helpful! Let me try to implement a timing decorator myself. Can you help me if I get stuck?</pre></div>
           
       </div>
       
       
+      
   
       <button class="timeline-toggle floating-btn" id="toggleTimeline" title="Show timeline">📆</button>
       <button class="filter-messages floating-btn" id="filterMessages" title="Search & Filter">🔍</button>
       <button class="toggle-details floating-btn" id="toggleDetails" title="Toggle all details">📋</button>
+      <button class="debug-toggle floating-btn" id="toggleDebug" title="Show UUIDs">uuid</button>
       <a class="scroll-top floating-btn" title="Scroll to top" href="#title">🔝</a>
   
       <script>
@@ -20506,6 +21382,7 @@
               const toggleButton = document.getElementById('toggleDetails');
               const timelineButton = document.getElementById('toggleTimeline');
               const filterButton = document.getElementById('filterMessages');
+              const debugButton = document.getElementById('toggleDebug');
               const filterToolbar = document.querySelector('.filter-toolbar');
               const selectAllButton = document.getElementById('selectAll');
               const selectNoneButton = document.getElementById('selectNone');
@@ -20629,6 +21506,12 @@
       convertTimestampsToLocalTimezone();
   })();
   
+              // Debug UUID toggle
+              debugButton.addEventListener('click', function () {
+                  document.body.classList.toggle('show-debug-info');
+                  debugButton.classList.toggle('active');
+              });
+  
               // Parse URL parameters
               function getUrlParams() {
                   const params = new URLSearchParams(window.location.search);
diff --git a/test/test_cache_integration.py b/test/test_cache_integration.py
index 5e633766..a8a8bb23 100644
--- a/test/test_cache_integration.py
+++ b/test/test_cache_integration.py
@@ -567,7 +567,7 @@ def test_get_archived_sessions_with_some_files_remaining(
         project_dir = temp_projects_dir / "partial-archived"
         project_dir.mkdir()
 
-        # Create two session files
+        # Create two independent session files (unique UUIDs, as in real transcripts)
         for session_id in ["session-1", "session-2"]:
             jsonl_file = project_dir / f"{session_id}.jsonl"
             with open(jsonl_file, "w") as f:
@@ -575,6 +575,8 @@ def test_get_archived_sessions_with_some_files_remaining(
                     entry_copy = entry.copy()
                     if "sessionId" in entry_copy:
                         entry_copy["sessionId"] = session_id
+                    if "uuid" in entry_copy:
+                        entry_copy["uuid"] = f"{entry_copy['uuid']}-{session_id}"
                     f.write(json.dumps(entry_copy) + "\n")
 
         # Process to populate cache
@@ -703,7 +705,8 @@ def test_archived_session_count_in_converter(
         project_dir = temp_projects_dir / "count-test"
         project_dir.mkdir()
 
-        # Create two sessions so one remains after deletion
+        # Create two independent sessions so one remains after deletion
+        # (unique UUIDs per session, as in real transcripts)
         for session_id in ["session-1", "session-2"]:
             jsonl_file = project_dir / f"{session_id}.jsonl"
             with open(jsonl_file, "w") as f:
@@ -711,6 +714,8 @@ def test_archived_session_count_in_converter(
                     entry_copy = entry.copy()
                     if "sessionId" in entry_copy:
                         entry_copy["sessionId"] = session_id
+                    if "uuid" in entry_copy:
+                        entry_copy["uuid"] = f"{entry_copy['uuid']}-{session_id}"
                     f.write(json.dumps(entry_copy) + "\n")
 
         # Process to cache (as part of all-projects hierarchy)
diff --git a/test/test_dag.py b/test/test_dag.py
new file mode 100644
index 00000000..3e42a2d0
--- /dev/null
+++ b/test/test_dag.py
@@ -0,0 +1,1106 @@
+"""Tests for the DAG-based message ordering module."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from claude_code_log.dag import (
+    SessionTree,
+    build_dag,
+    build_dag_from_entries,
+    build_message_index,
+    extract_session_dag_lines,
+    traverse_session_tree,
+)
+from claude_code_log.factories import create_transcript_entry
+from claude_code_log.models import (
+    SummaryTranscriptEntry,
+    TranscriptEntry,
+)
+
+TEST_DATA = Path(__file__).parent / "test_data"
+REAL_PROJECTS = TEST_DATA / "real_projects"
+
+
+def load_entries_from_jsonl(path: Path) -> list[TranscriptEntry]:
+    """Load transcript entries from a JSONL file, skipping unparseable lines."""
+    entries: list[TranscriptEntry] = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            data = json.loads(line)
+            entry_type = data.get("type")
+            if entry_type in (
+                "user",
+                "assistant",
+                "summary",
+                "system",
+                "queue-operation",
+            ):
+                entries.append(create_transcript_entry(data))
+    return entries
+
+
+def load_project_entries(project_dir: Path) -> list[TranscriptEntry]:
+    """Load all entries from a project directory (excluding agent files)."""
+    entries: list[TranscriptEntry] = []
+    for jsonl_file in sorted(project_dir.glob("*.jsonl")):
+        if jsonl_file.name.startswith("agent-"):
+            continue
+        entries.extend(load_entries_from_jsonl(jsonl_file))
+    return entries
+
+
+# =============================================================================
+# Test: Single session (dag_simple.jsonl)
+# =============================================================================
+
+
+class TestSingleSession:
+    """Tests using dag_simple.jsonl: a→b→c→d→e in session s1."""
+
+    @pytest.fixture()
+    def tree(self) -> SessionTree:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        return build_dag_from_entries(entries)
+
+    def test_single_session_one_dagline(self, tree: SessionTree) -> None:
+        assert len(tree.sessions) == 1
+        assert "s1" in tree.sessions
+
+    def test_single_session_chain_order(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s1"]
+        assert dag_line.uuids == ["a", "b", "c", "d", "e"]
+
+    def test_single_session_is_root(self, tree: SessionTree) -> None:
+        assert tree.roots == ["s1"]
+
+    def test_single_session_no_junction_points(self, tree: SessionTree) -> None:
+        assert tree.junction_points == {}
+
+    def test_single_session_traversal(self, tree: SessionTree) -> None:
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "e"]
+
+    def test_single_session_first_timestamp(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s1"]
+        assert dag_line.first_timestamp == "2025-07-01T10:00:00.000Z"
+
+    def test_single_session_no_parent(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s1"]
+        assert dag_line.parent_session_id is None
+        assert dag_line.attachment_uuid is None
+
+
+# =============================================================================
+# Test: Resume session (dag_resume.jsonl)
+# =============================================================================
+
+
+class TestResumeSession:
+    """Tests using dag_resume.jsonl: s1(a→b→c→d→e), s2(f→g→h) where f.parent=e."""
+
+    @pytest.fixture()
+    def tree(self) -> SessionTree:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_resume.jsonl")
+        return build_dag_from_entries(entries)
+
+    def test_two_sessions(self, tree: SessionTree) -> None:
+        assert len(tree.sessions) == 2
+        assert "s1" in tree.sessions
+        assert "s2" in tree.sessions
+
+    def test_s1_chain(self, tree: SessionTree) -> None:
+        assert tree.sessions["s1"].uuids == ["a", "b", "c", "d", "e"]
+
+    def test_s2_chain(self, tree: SessionTree) -> None:
+        assert tree.sessions["s2"].uuids == ["f", "g", "h"]
+
+    def test_s1_is_root(self, tree: SessionTree) -> None:
+        assert tree.roots == ["s1"]
+
+    def test_s2_parent_is_s1(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s2"]
+        assert dag_line.parent_session_id == "s1"
+        assert dag_line.attachment_uuid == "e"
+
+    def test_junction_at_e(self, tree: SessionTree) -> None:
+        assert "e" in tree.junction_points
+        jp = tree.junction_points["e"]
+        assert jp.session_id == "s1"
+        assert jp.target_sessions == ["s2"]
+
+    def test_traversal_order(self, tree: SessionTree) -> None:
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "e", "f", "g", "h"]
+
+
+# =============================================================================
+# Test: Fork session (dag_fork.jsonl)
+# =============================================================================
+
+
+class TestForkSession:
+    """Tests using dag_fork.jsonl: s1(a→e), s2(f→h from e), s3(i→k from c)."""
+
+    @pytest.fixture()
+    def tree(self) -> SessionTree:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_fork.jsonl")
+        return build_dag_from_entries(entries)
+
+    def test_three_sessions(self, tree: SessionTree) -> None:
+        assert len(tree.sessions) == 3
+
+    def test_s1_chain(self, tree: SessionTree) -> None:
+        assert tree.sessions["s1"].uuids == ["a", "b", "c", "d", "e"]
+
+    def test_s2_chain(self, tree: SessionTree) -> None:
+        assert tree.sessions["s2"].uuids == ["f", "g", "h"]
+
+    def test_s3_chain(self, tree: SessionTree) -> None:
+        assert tree.sessions["s3"].uuids == ["i", "j", "k"]
+
+    def test_only_s1_is_root(self, tree: SessionTree) -> None:
+        assert tree.roots == ["s1"]
+
+    def test_s2_attaches_at_e(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s2"]
+        assert dag_line.parent_session_id == "s1"
+        assert dag_line.attachment_uuid == "e"
+
+    def test_s3_attaches_at_c(self, tree: SessionTree) -> None:
+        dag_line = tree.sessions["s3"]
+        assert dag_line.parent_session_id == "s1"
+        assert dag_line.attachment_uuid == "c"
+
+    def test_two_junction_points(self, tree: SessionTree) -> None:
+        assert len(tree.junction_points) == 2
+        assert "c" in tree.junction_points
+        assert "e" in tree.junction_points
+
+    def test_junction_c_targets_s3(self, tree: SessionTree) -> None:
+        jp = tree.junction_points["c"]
+        assert jp.session_id == "s1"
+        assert jp.target_sessions == ["s3"]
+
+    def test_junction_e_targets_s2(self, tree: SessionTree) -> None:
+        jp = tree.junction_points["e"]
+        assert jp.session_id == "s1"
+        assert jp.target_sessions == ["s2"]
+
+    def test_traversal_depth_first(self, tree: SessionTree) -> None:
+        """Depth-first: s1 entries, then at junction c visit s3 (fork),
+        continue s1, then at junction e visit s2 (continue)."""
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        # s1: a,b,c → s3: i,j,k → s1: d,e → s2: f,g,h
+        assert uuids == ["a", "b", "c", "i", "j", "k", "d", "e", "f", "g", "h"]
+
+
+# =============================================================================
+# Test: Deduplication
+# =============================================================================
+
+
+class TestDeduplication:
+    """Test that duplicate uuids are resolved by keeping earliest session."""
+
+    def test_dedup_keeps_earliest_session(self) -> None:
+        """Same uuid in two sessions; entry from earlier session wins."""
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        # Manually add a duplicate of uuid "c" with a later session
+        dup_data = {
+            "type": "user",
+            "timestamp": "2025-07-02T10:00:00.000Z",
+            "parentUuid": "b",
+            "isSidechain": False,
+            "userType": "human",
+            "cwd": "/tmp",
+            "sessionId": "s_later",
+            "version": "1.0.0",
+            "uuid": "c",
+            "message": {"role": "user", "content": [{"type": "text", "text": "Dup"}]},
+        }
+        entries.append(create_transcript_entry(dup_data))
+
+        nodes = build_message_index(entries)
+        # "c" should belong to s1 (timestamp 2025-07-01) not s_later (2025-07-02)
+        assert nodes["c"].session_id == "s1"
+
+    def test_dedup_replaces_with_earlier(self) -> None:
+        """If later-loaded entry is from an earlier session, it replaces."""
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        # Add a duplicate of uuid "c" from an EARLIER session
+        dup_data = {
+            "type": "user",
+            "timestamp": "2025-06-30T10:00:00.000Z",
+            "parentUuid": "b",
+            "isSidechain": False,
+            "userType": "human",
+            "cwd": "/tmp",
+            "sessionId": "s_earlier",
+            "version": "1.0.0",
+            "uuid": "c",
+            "message": {
+                "role": "user",
+                "content": [{"type": "text", "text": "Earlier"}],
+            },
+        }
+        entries.append(create_transcript_entry(dup_data))
+
+        nodes = build_message_index(entries)
+        # "c" should now belong to s_earlier
+        assert nodes["c"].session_id == "s_earlier"
+
+
+# =============================================================================
+# Test: Junction Points
+# =============================================================================
+
+
+class TestJunctionPoints:
+    """Detailed junction point tests."""
+
+    def test_no_junctions_single_session(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        tree = build_dag_from_entries(entries)
+        assert len(tree.junction_points) == 0
+
+    def test_single_junction_resume(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_resume.jsonl")
+        tree = build_dag_from_entries(entries)
+        assert len(tree.junction_points) == 1
+        assert "e" in tree.junction_points
+
+    def test_multiple_junctions_fork(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_fork.jsonl")
+        tree = build_dag_from_entries(entries)
+        assert len(tree.junction_points) == 2
+        # Both c and e are junctions
+        assert set(tree.junction_points.keys()) == {"c", "e"}
+
+    def test_junction_target_sessions_ordered_chronologically(self) -> None:
+        """If multiple sessions fork from the same point, targets are ordered."""
+        # Create data where two sessions both fork from the same message
+        base = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        fork1_data = {
+            "type": "user",
+            "timestamp": "2025-07-02T10:00:00.000Z",
+            "parentUuid": "c",
+            "isSidechain": False,
+            "userType": "human",
+            "cwd": "/tmp",
+            "sessionId": "s_fork1",
+            "version": "1.0.0",
+            "uuid": "f1",
+            "message": {
+                "role": "user",
+                "content": [{"type": "text", "text": "Fork 1"}],
+            },
+        }
+        fork2_data = {
+            "type": "user",
+            "timestamp": "2025-07-01T12:00:00.000Z",
+            "parentUuid": "c",
+            "isSidechain": False,
+            "userType": "human",
+            "cwd": "/tmp",
+            "sessionId": "s_fork2",
+            "version": "1.0.0",
+            "uuid": "f2",
+            "message": {
+                "role": "user",
+                "content": [{"type": "text", "text": "Fork 2"}],
+            },
+        }
+        base.append(create_transcript_entry(fork1_data))
+        base.append(create_transcript_entry(fork2_data))
+
+        tree = build_dag_from_entries(base)
+        jp = tree.junction_points["c"]
+        # s_fork2 is earlier (2025-07-01T12:00) than s_fork1 (2025-07-02T10:00)
+        assert jp.target_sessions == ["s_fork2", "s_fork1"]
+
+
+# =============================================================================
+# Test: Traversal Order
+# =============================================================================
+
+
+class TestTraversalOrder:
+    """Test depth-first session tree traversal produces correct order."""
+
+    def test_simple_traversal(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        assert len(result) == 5
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "e"]
+
+    def test_resume_traversal(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_resume.jsonl")
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "e", "f", "g", "h"]
+
+    def test_fork_traversal(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_fork.jsonl")
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        # Depth-first: at junction c (after emitting c), visit s3 first
+        # then continue s1, at junction e visit s2
+        assert uuids == ["a", "b", "c", "i", "j", "k", "d", "e", "f", "g", "h"]
+
+    def test_traversal_returns_entries(self) -> None:
+        """Verify traversal returns actual TranscriptEntry objects."""
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        for entry in result:
+            assert hasattr(entry, "type")
+            assert hasattr(entry, "uuid")
+
+
+# =============================================================================
+# Test: Real project data
+# =============================================================================
+
+
+EXPERIMENTS_DIR = REAL_PROJECTS / "-src-experiments-claude_p"
+
+
+@pytest.mark.skipif(
+    not EXPERIMENTS_DIR.exists(),
+    reason="Real project test data not available",
+)
+class TestRealProjectExperiments:
+    """Test DAG construction against real project data.
+
+    The -src-experiments-claude_p project has 4 independent sessions
+    with no cross-session references, so should produce 4 root sessions.
+    """
+
+    @pytest.fixture()
+    def tree(self) -> SessionTree:
+        entries = load_project_entries(EXPERIMENTS_DIR)
+        return build_dag_from_entries(entries)
+
+    def test_loads_multiple_sessions(self, tree: SessionTree) -> None:
+        assert len(tree.sessions) >= 4
+
+    def test_all_sessions_are_roots(self, tree: SessionTree) -> None:
+        """Independent sessions should all be roots."""
+        # All sessions with DAG-lines should be root (no cross-refs)
+        for session_id in tree.sessions:
+            dag_line = tree.sessions[session_id]
+            assert dag_line.parent_session_id is None, (
+                f"Session {session_id} unexpectedly has parent "
+                f"{dag_line.parent_session_id}"
+            )
+
+    def test_no_junction_points(self, tree: SessionTree) -> None:
+        """Independent sessions should have no junction points."""
+        assert len(tree.junction_points) == 0
+
+    def test_each_session_has_entries(self, tree: SessionTree) -> None:
+        """Each session's DAG-line should have at least one message."""
+        for session_id, dag_line in tree.sessions.items():
+            assert len(dag_line.uuids) > 0, f"Session {session_id} has empty DAG-line"
+
+    def test_traversal_covers_all_entries(self, tree: SessionTree) -> None:
+        """Traversal should include all entries from all sessions."""
+        total_in_daglines = sum(len(dl.uuids) for dl in tree.sessions.values())
+        result = traverse_session_tree(tree)
+        assert len(result) == total_in_daglines
+
+    def test_sessions_ordered_chronologically(self, tree: SessionTree) -> None:
+        """Root sessions should be ordered by first_timestamp."""
+        timestamps = [tree.sessions[sid].first_timestamp for sid in tree.roots]
+        assert timestamps == sorted(timestamps)
+
+
+# =============================================================================
+# Test: Edge cases
+# =============================================================================
+
+
+class TestOrphanParent:
+    """Test handling of parentUuid pointing to unknown uuid."""
+
+    def test_orphan_treated_as_root(self) -> None:
+        """A session whose first message has parentUuid pointing to
+        an unknown uuid should be treated as a root session."""
+        orphan_data = {
+            "type": "user",
+            "timestamp": "2025-07-01T10:00:00.000Z",
+            "parentUuid": "nonexistent_uuid",
+            "isSidechain": False,
+            "userType": "human",
+            "cwd": "/tmp",
+            "sessionId": "s_orphan",
+            "version": "1.0.0",
+            "uuid": "orphan_a",
+            "message": {
+                "role": "user",
+                "content": [{"type": "text", "text": "Orphan"}],
+            },
+        }
+        entries: list[TranscriptEntry] = [create_transcript_entry(orphan_data)]
+        tree = build_dag_from_entries(entries)
+
+        assert "s_orphan" in tree.sessions
+        assert tree.roots == ["s_orphan"]
+        dag_line = tree.sessions["s_orphan"]
+        assert dag_line.parent_session_id is None
+
+    def test_orphan_with_children(self) -> None:
+        """Orphan node still chains correctly within its session."""
+        data = [
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:00:00.000Z",
+                "parentUuid": "nonexistent",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "x",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Start"}],
+                },
+            },
+            {
+                "type": "assistant",
+                "timestamp": "2025-07-01T10:01:00.000Z",
+                "parentUuid": "x",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "y",
+                "requestId": "req_1",
+                "message": {
+                    "id": "y",
+                    "type": "message",
+                    "role": "assistant",
+                    "model": "claude-3-sonnet",
+                    "content": [{"type": "text", "text": "Reply"}],
+                    "stop_reason": "end_turn",
+                    "usage": {"input_tokens": 10, "output_tokens": 5},
+                },
+            },
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        assert tree.sessions["s1"].uuids == ["x", "y"]
+        assert tree.roots == ["s1"]
+
+
+class TestSummaryEntriesSkipped:
+    """Test that SummaryTranscriptEntry entries are excluded from DAG."""
+
+    def test_summary_not_in_nodes(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        # Add a summary entry
+        summary_data = {
+            "type": "summary",
+            "summary": "A test summary",
+            "leafUuid": "e",
+            "timestamp": "2025-07-01T10:05:00.000Z",
+        }
+        entries.append(create_transcript_entry(summary_data))
+
+        nodes = build_message_index(entries)
+        # Summary has no uuid, so it can't be in nodes
+        for node in nodes.values():
+            assert not isinstance(node.entry, SummaryTranscriptEntry)
+
+    def test_summary_not_in_traversal(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        summary_data = {
+            "type": "summary",
+            "summary": "A test summary",
+            "leafUuid": "e",
+            "timestamp": "2025-07-01T10:05:00.000Z",
+        }
+        entries.append(create_transcript_entry(summary_data))
+
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        # Should still be 5 entries (a-e), summary excluded
+        assert len(result) == 5
+        for entry in result:
+            assert not isinstance(entry, SummaryTranscriptEntry)
+
+
+class TestQueueOperationSkipped:
+    """Test that QueueOperationTranscriptEntry entries are excluded from DAG."""
+
+    def test_queue_op_not_in_nodes(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        queue_data = {
+            "type": "queue-operation",
+            "operation": "dequeue",
+            "timestamp": "2025-07-01T09:59:00.000Z",
+            "sessionId": "s1",
+        }
+        entries.append(create_transcript_entry(queue_data))
+
+        nodes = build_message_index(entries)
+        # queue-operation has no uuid field
+        assert len(nodes) == 5  # Only a,b,c,d,e
+
+
+# =============================================================================
+# Test: Individual algorithm steps
+# =============================================================================
+
+
+class TestBuildMessageIndex:
+    """Test build_message_index in isolation."""
+
+    def test_indexes_all_entries(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        nodes = build_message_index(entries)
+        assert set(nodes.keys()) == {"a", "b", "c", "d", "e"}
+
+    def test_preserves_entry_data(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        nodes = build_message_index(entries)
+        assert nodes["a"].session_id == "s1"
+        assert nodes["a"].parent_uuid is None
+        assert nodes["b"].parent_uuid == "a"
+
+    def test_empty_entries(self) -> None:
+        nodes = build_message_index([])
+        assert nodes == {}
+
+
+class TestBuildDAG:
+    """Test build_dag (parent→children links)."""
+
+    def test_children_populated(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        assert nodes["a"].children_uuids == ["b"]
+        assert nodes["b"].children_uuids == ["c"]
+        assert nodes["e"].children_uuids == []
+
+    def test_root_has_no_parent(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        assert nodes["a"].parent_uuid is None
+
+    def test_cross_session_children(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_resume.jsonl")
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        # "e" has child "f" which is in a different session
+        assert "f" in nodes["e"].children_uuids
+
+
+class TestExtractSessionDAGLines:
+    """Test extract_session_dag_lines."""
+
+    def test_single_session_chain(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_simple.jsonl")
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        sessions = extract_session_dag_lines(nodes)
+        assert sessions["s1"].uuids == ["a", "b", "c", "d", "e"]
+
+    def test_multi_session_chains(self) -> None:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_resume.jsonl")
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        sessions = extract_session_dag_lines(nodes)
+        assert sessions["s1"].uuids == ["a", "b", "c", "d", "e"]
+        assert sessions["s2"].uuids == ["f", "g", "h"]
+
+
+# =============================================================================
+# Test: Degenerate parentUuid (all null)
+# =============================================================================
+
+
+class TestDegenerateParentUuid:
+    """Test handling of entries where all parentUuid values are null.
+
+    This is the common case for existing test data and older transcripts
+    that lack parentUuid chains. The DAG should fall back to timestamp sort.
+    """
+
+    @pytest.fixture()
+    def entries(self) -> list[TranscriptEntry]:
+        """Create 5 entries with parentUuid=null, out of timestamp order."""
+        data = [
+            {
+                "type": "user",
+                "timestamp": f"2025-07-01T10:0{i}:00.000Z",
+                "parentUuid": None,
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": f"msg_{i}",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": f"Message {i}"}],
+                },
+            }
+            for i in [3, 1, 4, 0, 2]  # Out of order
+        ]
+        return [create_transcript_entry(d) for d in data]
+
+    def test_all_null_parent_uuid_falls_back_to_timestamp(
+        self, entries: list[TranscriptEntry]
+    ) -> None:
+        """All 5 entries with parentUuid=null should appear in timestamp order."""
+        nodes = build_message_index(entries)
+        build_dag(nodes)
+        sessions = extract_session_dag_lines(nodes)
+
+        dag_line = sessions["s1"]
+        assert len(dag_line.uuids) == 5
+        # Should be sorted by timestamp
+        assert dag_line.uuids == ["msg_0", "msg_1", "msg_2", "msg_3", "msg_4"]
+
+    def test_all_null_traversal_returns_all_entries(
+        self, entries: list[TranscriptEntry]
+    ) -> None:
+        """Traversal should return all 5 entries, none dropped."""
+        tree = build_dag_from_entries(entries)
+        result = traverse_session_tree(tree)
+        assert len(result) == 5
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["msg_0", "msg_1", "msg_2", "msg_3", "msg_4"]
+
+
+# =============================================================================
+# Test: Within-session fork (dag_within_fork.jsonl)
+# =============================================================================
+
+
+class TestWithinSessionFork:
+    """Tests using dag_within_fork.jsonl: s1(a→b→c) with fork at c.
+
+    c has two same-session children: d→e→f (branch 1) and d'→e' (branch 2).
+    This produces three DAG-lines: trunk (a,b,c), branch 1 (d,e,f), branch 2 (d',e').
+    """
+
+    @pytest.fixture()
+    def tree(self) -> SessionTree:
+        entries = load_entries_from_jsonl(TEST_DATA / "dag_within_fork.jsonl")
+        return build_dag_from_entries(entries)
+
+    def test_trunk_stops_at_fork(self, tree: SessionTree) -> None:
+        """Trunk DAG-line stops at fork point c."""
+        assert "s1" in tree.sessions
+        assert tree.sessions["s1"].uuids == ["a", "b", "c"]
+
+    def test_branch_sessions_created(self, tree: SessionTree) -> None:
+        """Two branch pseudo-sessions are created."""
+        branch_ids = [sid for sid in tree.sessions if "@" in sid]
+        assert len(branch_ids) == 2
+
+    def test_branch1_chain(self, tree: SessionTree) -> None:
+        """Branch 1 (d→e→f) has correct chain."""
+        branch1_id = "s1@d"
+        assert branch1_id in tree.sessions
+        assert tree.sessions[branch1_id].uuids == ["d", "e", "f"]
+
+    def test_branch2_chain(self, tree: SessionTree) -> None:
+        """Branch 2 (d'→e') has correct chain."""
+        branch2_id = "s1@d_prime"
+        assert branch2_id in tree.sessions
+        assert tree.sessions[branch2_id].uuids == ["d_prime", "e_prime"]
+
+    def test_branches_are_marked(self, tree: SessionTree) -> None:
+        """Branch DAG-lines have is_branch=True and original_session_id set."""
+        for sid in tree.sessions:
+            if "@" in sid:
+                dl = tree.sessions[sid]
+                assert dl.is_branch is True
+                assert dl.original_session_id == "s1"
+            else:
+                dl = tree.sessions[sid]
+                assert dl.is_branch is False
+                assert dl.original_session_id is None
+
+    def test_trunk_is_root(self, tree: SessionTree) -> None:
+        """Only trunk s1 is a root session."""
+        assert tree.roots == ["s1"]
+
+    def test_branches_parent_is_trunk(self, tree: SessionTree) -> None:
+        """Both branches have parent_session_id = trunk."""
+        for sid in tree.sessions:
+            if "@" in sid:
+                assert tree.sessions[sid].parent_session_id == "s1"
+                assert tree.sessions[sid].attachment_uuid == "c"
+
+    def test_junction_at_fork_point(self, tree: SessionTree) -> None:
+        """Fork point c is a junction point with both branches as targets."""
+        assert "c" in tree.junction_points
+        jp = tree.junction_points["c"]
+        assert jp.session_id == "s1"
+        assert len(jp.target_sessions) == 2
+        assert "s1@d" in jp.target_sessions
+        assert "s1@d_prime" in jp.target_sessions
+
+    def test_traversal_order(self, tree: SessionTree) -> None:
+        """Depth-first: trunk, then branch 1 at junction, then branch 2."""
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "e", "f", "d_prime", "e_prime"]
+
+    def test_node_session_ids_updated(self, tree: SessionTree) -> None:
+        """MessageNode.session_id is updated for branch nodes."""
+        assert tree.nodes["a"].session_id == "s1"
+        assert tree.nodes["b"].session_id == "s1"
+        assert tree.nodes["c"].session_id == "s1"
+        assert tree.nodes["d"].session_id == "s1@d"
+        assert tree.nodes["e"].session_id == "s1@d"
+        assert tree.nodes["f"].session_id == "s1@d"
+        assert tree.nodes["d_prime"].session_id == "s1@d_prime"
+        assert tree.nodes["e_prime"].session_id == "s1@d_prime"
+
+    def test_traversal_covers_all_entries(self, tree: SessionTree) -> None:
+        """All 8 entries should appear in traversal."""
+        result = traverse_session_tree(tree)
+        assert len(result) == 8
+
+
+class TestNestedFork:
+    """Test nested within-session forks (fork within a fork)."""
+
+    def test_nested_fork(self) -> None:
+        """Session with fork at b, then nested fork at d within first branch."""
+        # a → b (fork) → d (fork) → f, g
+        #             → e
+        data = [
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:00:00.000Z",
+                "parentUuid": None,
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "a",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Start"}],
+                },
+            },
+            {
+                "type": "assistant",
+                "timestamp": "2025-07-01T10:01:00.000Z",
+                "parentUuid": "a",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "b",
+                "requestId": "req_1",
+                "message": {
+                    "id": "b",
+                    "type": "message",
+                    "role": "assistant",
+                    "model": "claude-3-sonnet",
+                    "content": [{"type": "text", "text": "Fork point 1"}],
+                    "stop_reason": "end_turn",
+                    "usage": {"input_tokens": 10, "output_tokens": 5},
+                },
+            },
+            # Branch 1 from b: c → d (fork)
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:02:00.000Z",
+                "parentUuid": "b",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "c",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Branch 1"}],
+                },
+            },
+            {
+                "type": "assistant",
+                "timestamp": "2025-07-01T10:03:00.000Z",
+                "parentUuid": "c",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "d",
+                "requestId": "req_2",
+                "message": {
+                    "id": "d",
+                    "type": "message",
+                    "role": "assistant",
+                    "model": "claude-3-sonnet",
+                    "content": [{"type": "text", "text": "Fork point 2"}],
+                    "stop_reason": "end_turn",
+                    "usage": {"input_tokens": 10, "output_tokens": 5},
+                },
+            },
+            # Nested branch 1a from d
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:04:00.000Z",
+                "parentUuid": "d",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "f",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Nested branch 1a"}],
+                },
+            },
+            # Nested branch 1b from d
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:05:00.000Z",
+                "parentUuid": "d",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "g",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Nested branch 1b"}],
+                },
+            },
+            # Branch 2 from b
+            {
+                "type": "user",
+                "timestamp": "2025-07-01T10:06:00.000Z",
+                "parentUuid": "b",
+                "isSidechain": False,
+                "userType": "human",
+                "cwd": "/tmp",
+                "sessionId": "s1",
+                "version": "1.0.0",
+                "uuid": "e",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": "Branch 2"}],
+                },
+            },
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Trunk: a, b (stops at fork)
+        assert tree.sessions["s1"].uuids == ["a", "b"]
+
+        # Branch 1 from b: c, d (stops at nested fork)
+        branch1_id = "s1@c"
+        assert branch1_id in tree.sessions
+        assert tree.sessions[branch1_id].uuids == ["c", "d"]
+
+        # Nested branches from d (within branch 1)
+        nested1a_id = f"{branch1_id}@f"
+        nested1b_id = f"{branch1_id}@g"
+        assert nested1a_id in tree.sessions
+        assert tree.sessions[nested1a_id].uuids == ["f"]
+        assert nested1b_id in tree.sessions
+        assert tree.sessions[nested1b_id].uuids == ["g"]
+
+        # Branch 2 from b
+        branch2_id = "s1@e"
+        assert branch2_id in tree.sessions
+        assert tree.sessions[branch2_id].uuids == ["e"]
+
+        # Traversal
+        result = traverse_session_tree(tree)
+        uuids = [e.uuid for e in result]  # type: ignore[union-attr]
+        assert uuids == ["a", "b", "c", "d", "f", "g", "e"]
+
+
+def _make_entry(
+    etype: str,
+    uuid: str,
+    parent: str | None,
+    ts: str,
+    session: str = "s1",
+    text: str = "",
+) -> dict:
+    """Helper to build a minimal transcript entry dict."""
+    base = {
+        "type": etype,
+        "timestamp": ts,
+        "parentUuid": parent,
+        "isSidechain": False,
+        "userType": "human",
+        "cwd": "/tmp",
+        "sessionId": session,
+        "version": "1.0.0",
+        "uuid": uuid,
+    }
+    if etype == "user":
+        base["message"] = {
+            "role": "user",
+            "content": [{"type": "text", "text": text or uuid}],
+        }
+    elif etype == "assistant":
+        base["requestId"] = f"req_{uuid}"
+        base["message"] = {
+            "id": uuid,
+            "type": "message",
+            "role": "assistant",
+            "model": "claude-3-sonnet",
+            "content": [{"type": "text", "text": text or uuid}],
+            "stop_reason": "end_turn",
+            "usage": {"input_tokens": 10, "output_tokens": 5},
+        }
+    elif etype == "system":
+        base["message"] = {"content": []}
+    return base
+
+
+class TestCompactionReplay:
+    """Context compaction replays should not create branches."""
+
+    def test_same_timestamp_children_not_forked(self) -> None:
+        """Multiple children with identical timestamps are compaction replays."""
+        # a → sys → replay1, replay2, replay3 (all same ts)
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("system", "sys", "a", "2025-07-01T10:01:00.000Z"),
+            _make_entry("assistant", "r1", "sys", "2025-07-01T10:02:00.000Z"),
+            _make_entry("assistant", "r2", "sys", "2025-07-01T10:02:00.000Z"),
+            _make_entry("assistant", "r3", "sys", "2025-07-01T10:02:00.000Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Should be a single linear session, no branches
+        assert "s1" in tree.sessions
+        assert tree.sessions["s1"].uuids == ["a", "sys", "r1"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 0
+
+    def test_different_timestamps_create_branches(self) -> None:
+        """Children with different timestamps are real forks (rewinds)."""
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("assistant", "b", "a", "2025-07-01T10:01:00.000Z"),
+            _make_entry("user", "c", "b", "2025-07-01T10:02:00.000Z"),
+            _make_entry("user", "d", "b", "2025-07-01T10:05:00.000Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Trunk stops at b, two branches
+        assert tree.sessions["s1"].uuids == ["a", "b"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 2
+
+
+class TestToolResultStitching:
+    """Tool-result side-branches should be stitched into the main chain."""
+
+    def test_single_tool_result_stitched(self) -> None:
+        """A(tool_use) → U(result) + A(next) should become linear."""
+        # a → tool_use → tool_result (dead end) + next_assistant
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("assistant", "tool1", "a", "2025-07-01T10:01:00.000Z"),
+            _make_entry("user", "result1", "tool1", "2025-07-01T10:01:00.100Z"),
+            _make_entry("assistant", "tool2", "tool1", "2025-07-01T10:01:00.200Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Should be linear: a → tool1 → result1 → tool2
+        assert tree.sessions["s1"].uuids == ["a", "tool1", "result1", "tool2"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 0
+
+    def test_multiple_tool_results_stitched(self) -> None:
+        """Multiple parallel tool_use with results should all be stitched."""
+        # a → tool1 → result1 (dead end) + result2 (dead end) + tool2
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("assistant", "tool1", "a", "2025-07-01T10:01:00.000Z"),
+            _make_entry("user", "res1", "tool1", "2025-07-01T10:01:00.100Z"),
+            _make_entry("user", "res2", "tool1", "2025-07-01T10:01:00.150Z"),
+            _make_entry("assistant", "tool2", "tool1", "2025-07-01T10:01:00.200Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Should be linear: a → tool1 → res1 → res2 → tool2
+        assert tree.sessions["s1"].uuids == ["a", "tool1", "res1", "res2", "tool2"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 0
+
+    def test_user_child_with_continuation_stitched(self) -> None:
+        """Variant 2: User child continues, Assistant subtree dead-ends.
+        Should stitch linearly with dead-end first, then continuation."""
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("assistant", "b", "a", "2025-07-01T10:01:00.000Z"),
+            _make_entry("user", "c", "b", "2025-07-01T10:02:00.000Z"),
+            _make_entry("assistant", "d", "b", "2025-07-01T10:03:00.000Z"),
+            # c continues (not a dead end), d is a leaf (dead end)
+            _make_entry("assistant", "e", "c", "2025-07-01T10:04:00.000Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # Should stitch: dead-end d first, then continuing c
+        assert tree.sessions["s1"].uuids == ["a", "b", "d", "c", "e"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 0
+
+    def test_assistant_subtree_dead_end_stitched(self) -> None:
+        """Variant 2 with deeper dead-end: Assistant child has a subtree
+        that eventually terminates, User child continues."""
+        data = [
+            _make_entry("user", "a", None, "2025-07-01T10:00:00.000Z"),
+            _make_entry("assistant", "b", "a", "2025-07-01T10:01:00.000Z"),
+            # b forks into assistant d (dead-end subtree) and user c (continues)
+            _make_entry("assistant", "d", "b", "2025-07-01T10:02:00.000Z"),
+            _make_entry("user", "c", "b", "2025-07-01T10:02:50.000Z"),
+            # d's subtree: d → d2 → d3 (all dead ends)
+            _make_entry("assistant", "d2", "d", "2025-07-01T10:02:01.000Z"),
+            _make_entry("user", "d3", "d2", "2025-07-01T10:02:02.000Z"),
+            # c continues the main chain
+            _make_entry("assistant", "e", "c", "2025-07-01T10:03:00.000Z"),
+        ]
+        entries = [create_transcript_entry(d) for d in data]
+        tree = build_dag_from_entries(entries)
+
+        # d's subtree dead-ends, c continues: stitch d first, then c
+        assert tree.sessions["s1"].uuids == ["a", "b", "d", "c", "e"]
+        branch_count = sum(1 for s in tree.sessions.values() if s.is_branch)
+        assert branch_count == 0
diff --git a/test/test_dag_integration.py b/test/test_dag_integration.py
new file mode 100644
index 00000000..4fda8bb0
--- /dev/null
+++ b/test/test_dag_integration.py
@@ -0,0 +1,1358 @@
+"""Integration tests for DAG-based ordering in the rendering pipeline.
+
+Tests that DAG ordering in load_directory_transcripts() produces correct
+results when wired into the converter's directory-mode loading.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+
+from claude_code_log.converter import (
+    load_directory_transcripts,
+    _build_session_data_from_messages,
+    _scan_progress_chains,
+    _repair_parent_chains,
+)
+from claude_code_log.models import (
+    BaseTranscriptEntry,
+    SummaryTranscriptEntry,
+    QueueOperationTranscriptEntry,
+)
+
+
+def _write_jsonl(path: Path, entries: list[dict[str, Any]]) -> None:
+    """Write entries as JSONL lines to a file."""
+    with open(path, "w") as f:
+        for entry in entries:
+            f.write(json.dumps(entry) + "\n")
+
+
+def _make_user_entry(
+    uuid: str,
+    session_id: str,
+    timestamp: str,
+    parent_uuid: str | None = None,
+    text: str = "msg",
+    is_sidechain: bool = False,
+    agent_id: str | None = None,
+) -> dict[str, Any]:
+    """Helper to create a user transcript entry dict."""
+    entry: dict[str, Any] = {
+        "type": "user",
+        "timestamp": timestamp,
+        "parentUuid": parent_uuid,
+        "isSidechain": is_sidechain,
+        "userType": "human",
+        "cwd": "/tmp",
+        "sessionId": session_id,
+        "version": "1.0.0",
+        "uuid": uuid,
+        "message": {"role": "user", "content": [{"type": "text", "text": text}]},
+    }
+    if agent_id is not None:
+        entry["agentId"] = agent_id
+    return entry
+
+
+def _make_assistant_entry(
+    uuid: str,
+    session_id: str,
+    timestamp: str,
+    parent_uuid: str | None = None,
+    text: str = "reply",
+    is_sidechain: bool = False,
+    agent_id: str | None = None,
+) -> dict[str, Any]:
+    """Helper to create an assistant transcript entry dict."""
+    entry: dict[str, Any] = {
+        "type": "assistant",
+        "timestamp": timestamp,
+        "parentUuid": parent_uuid,
+        "isSidechain": is_sidechain,
+        "userType": "human",
+        "cwd": "/tmp",
+        "sessionId": session_id,
+        "version": "1.0.0",
+        "uuid": uuid,
+        "requestId": f"req_{uuid}",
+        "message": {
+            "id": uuid,
+            "type": "message",
+            "role": "assistant",
+            "model": "claude-3-sonnet",
+            "content": [{"type": "text", "text": text}],
+            "stop_reason": "end_turn",
+            "usage": {"input_tokens": 10, "output_tokens": 5},
+        },
+    }
+    if agent_id is not None:
+        entry["agentId"] = agent_id
+    return entry
+
+
+# =============================================================================
+# Test: DAG ordering in load_directory_transcripts
+# =============================================================================
+
+
+class TestLoadDirectoryDagOrdering:
+    """Test that load_directory_transcripts uses DAG ordering."""
+
+    def test_load_directory_dag_ordering(self, tmp_path: Path) -> None:
+        """Split dag_resume entries across two files, verify session grouping."""
+        # File 1: session s1 entries (a→b→c→d→e)
+        file1_entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            _make_user_entry("c", "s1", "2025-07-01T10:02:00.000Z", "b"),
+            _make_assistant_entry("d", "s1", "2025-07-01T10:03:00.000Z", "c"),
+            _make_user_entry("e", "s1", "2025-07-01T10:04:00.000Z", "d"),
+        ]
+        # File 2: session s2 entries (f→g→h, f.parent=e)
+        file2_entries = [
+            _make_user_entry("f", "s2", "2025-07-01T11:00:00.000Z", "e", "Resume"),
+            _make_assistant_entry("g", "s2", "2025-07-01T11:01:00.000Z", "f"),
+            _make_user_entry("h", "s2", "2025-07-01T11:02:00.000Z", "g"),
+        ]
+
+        _write_jsonl(tmp_path / "session1.jsonl", file1_entries)
+        _write_jsonl(tmp_path / "session2.jsonl", file2_entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+
+        # Should have all 8 entries in DAG order (s1 then s2)
+        uuids = [getattr(e, "uuid", None) for e in result]
+        assert uuids == ["a", "b", "c", "d", "e", "f", "g", "h"]
+
+    def test_load_directory_with_sidechains(self, tmp_path: Path) -> None:
+        """Sidechain entries are integrated into DAG at their structural position."""
+        main_entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+        ]
+        sidechain_entries = [
+            _make_user_entry(
+                "sc1",
+                "s1",
+                "2025-07-01T10:00:30.000Z",
+                "a",
+                "Sidechain msg",
+                is_sidechain=True,
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + sidechain_entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+        uuids = [getattr(e, "uuid", None) for e in result]
+
+        # Sidechain is now part of the DAG: sc1 is a child of a (tool-result
+        # side-branch), stitched before the continuation child b
+        assert uuids == ["a", "sc1", "b"]
+
+    def test_load_directory_with_summaries(self, tmp_path: Path) -> None:
+        """Summary entries should be preserved in output."""
+        entries: list[dict[str, Any]] = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            {
+                "type": "summary",
+                "summary": "A test summary",
+                "leafUuid": "b",
+                "timestamp": "2025-07-01T10:05:00.000Z",
+            },
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+
+        # Should have 2 DAG entries + 1 summary
+        summary_entries = [e for e in result if isinstance(e, SummaryTranscriptEntry)]
+        assert len(summary_entries) == 1
+        assert summary_entries[0].summary == "A test summary"
+
+        # DAG entries should be present
+        dag_uuids = [
+            getattr(e, "uuid", None)
+            for e in result
+            if not isinstance(e, SummaryTranscriptEntry)
+        ]
+        assert "a" in dag_uuids
+        assert "b" in dag_uuids
+
+    def test_load_directory_degenerate_parentuuid(self, tmp_path: Path) -> None:
+        """All parentUuid=null entries should be returned, none lost."""
+        entries = [
+            _make_user_entry(
+                f"msg_{i}", "s1", f"2025-07-01T10:0{i}:00.000Z", None, f"Msg {i}"
+            )
+            for i in range(5)
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+
+        # All 5 entries should be present
+        uuids = [getattr(e, "uuid", None) for e in result]
+        assert len(uuids) == 5
+        # Should be timestamp-ordered (fallback)
+        assert uuids == ["msg_0", "msg_1", "msg_2", "msg_3", "msg_4"]
+
+    def test_load_directory_with_queue_operations(self, tmp_path: Path) -> None:
+        """Queue operation entries should be preserved in output."""
+        entries: list[dict[str, Any]] = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            {
+                "type": "queue-operation",
+                "operation": "dequeue",
+                "timestamp": "2025-07-01T10:00:30.000Z",
+                "sessionId": "s1",
+            },
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+
+        queue_entries = [
+            e for e in result if isinstance(e, QueueOperationTranscriptEntry)
+        ]
+        assert len(queue_entries) == 1
+        assert queue_entries[0].operation == "dequeue"
+
+
+# =============================================================================
+# Test: End-to-end with generate_template_messages
+# =============================================================================
+
+
+class TestEndToEndHtmlWithDag:
+    """Test full pipeline from DAG-ordered directory input to template messages."""
+
+    def test_end_to_end_html_with_dag(self, tmp_path: Path) -> None:
+        """Full generate_template_messages() with DAG-ordered directory input."""
+        from claude_code_log.renderer import generate_template_messages
+
+        # Two sessions: s1 (earlier), s2 (later, resumes from s1)
+        file1_entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Hello"),
+            _make_assistant_entry(
+                "b", "s1", "2025-07-01T10:01:00.000Z", "a", "Hi there"
+            ),
+        ]
+        file2_entries = [
+            _make_user_entry("c", "s2", "2025-07-01T11:00:00.000Z", "b", "Resume"),
+            _make_assistant_entry(
+                "d", "s2", "2025-07-01T11:01:00.000Z", "c", "Resumed"
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session1.jsonl", file1_entries)
+        _write_jsonl(tmp_path / "session2.jsonl", file2_entries)
+
+        # Load via DAG ordering
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # Run through template message generation (reuse pre-built tree)
+        root_messages, session_nav, context = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        # Extract session headers and verify order
+        from claude_code_log.models import SessionHeaderMessage
+
+        session_headers = [
+            tm for tm in root_messages if isinstance(tm.content, SessionHeaderMessage)
+        ]
+
+        # Should have session headers
+        assert len(session_headers) >= 2
+        # s1 header should come before s2 header
+        s1_idx = next(
+            i
+            for i, tm in enumerate(root_messages)
+            if isinstance(tm.content, SessionHeaderMessage)
+            and tm.content.session_id == "s1"
+        )
+        s2_idx = next(
+            i
+            for i, tm in enumerate(root_messages)
+            if isinstance(tm.content, SessionHeaderMessage)
+            and tm.content.session_id == "s2"
+        )
+        assert s1_idx < s2_idx
+
+    def test_session_header_hierarchy_fields(self, tmp_path: Path) -> None:
+        """Session headers carry hierarchy fields (parent, depth) from DAG."""
+        from claude_code_log.renderer import generate_template_messages
+        from claude_code_log.models import SessionHeaderMessage
+
+        # s1 is root, s2 resumes from s1 (c.parent=b), s3 resumes from s2
+        entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            _make_user_entry("c", "s2", "2025-07-01T11:00:00.000Z", "b", "Resume"),
+            _make_assistant_entry("d", "s2", "2025-07-01T11:01:00.000Z", "c"),
+            _make_user_entry("e", "s3", "2025-07-01T12:00:00.000Z", "d", "Resume2"),
+            _make_assistant_entry("f", "s3", "2025-07-01T12:01:00.000Z", "e"),
+        ]
+
+        _write_jsonl(tmp_path / "sessions.jsonl", entries)
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        root_messages, session_nav, _ctx = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        headers = {
+            tm.content.session_id: tm.content
+            for tm in root_messages
+            if isinstance(tm.content, SessionHeaderMessage)
+        }
+
+        # s1 is root
+        assert headers["s1"].parent_session_id is None
+        assert headers["s1"].depth == 0
+
+        # s2 is child of s1
+        assert headers["s2"].parent_session_id == "s1"
+        assert headers["s2"].depth == 1
+
+        # s3 is grandchild (child of s2)
+        assert headers["s3"].parent_session_id == "s2"
+        assert headers["s3"].depth == 2
+
+    def test_session_nav_hierarchy_fields(self, tmp_path: Path) -> None:
+        """Session nav entries carry hierarchy data for template rendering."""
+        from claude_code_log.renderer import generate_template_messages
+
+        entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            _make_user_entry("c", "s2", "2025-07-01T11:00:00.000Z", "b", "Resume"),
+            _make_assistant_entry("d", "s2", "2025-07-01T11:01:00.000Z", "c"),
+        ]
+
+        _write_jsonl(tmp_path / "sessions.jsonl", entries)
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        _root, session_nav, _ctx = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        nav_by_id = {s["id"]: s for s in session_nav}
+
+        # s1 root
+        assert nav_by_id["s1"]["parent_session_id"] is None
+        assert nav_by_id["s1"]["depth"] == 0
+
+        # s2 child
+        assert nav_by_id["s2"]["parent_session_id"] == "s1"
+        assert nav_by_id["s2"]["depth"] == 1
+
+    def test_degenerate_data_no_hierarchy(self, tmp_path: Path) -> None:
+        """Degenerate data (all null parentUuid) has no hierarchy."""
+        from claude_code_log.renderer import generate_template_messages
+        from claude_code_log.models import SessionHeaderMessage
+
+        entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None, "Msg"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", None),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        root_messages, session_nav, _ctx = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        header = next(
+            tm.content
+            for tm in root_messages
+            if isinstance(tm.content, SessionHeaderMessage)
+        )
+        assert header.parent_session_id is None
+        assert header.depth == 0
+
+        assert session_nav[0]["depth"] == 0
+        assert session_nav[0]["parent_session_id"] is None
+
+    def test_end_to_end_degenerate_data_matches_timestamp_sort(
+        self, tmp_path: Path
+    ) -> None:
+        """Degenerate data (all null parentUuid) produces same order as timestamp sort."""
+        from claude_code_log.renderer import generate_template_messages
+
+        # 3 entries with parentUuid=null
+        entries = [
+            _make_user_entry("x", "s1", "2025-07-01T10:00:00.000Z", None, "First"),
+            _make_assistant_entry("y", "s1", "2025-07-01T10:01:00.000Z", None, "Mid"),
+            _make_user_entry("z", "s1", "2025-07-01T10:02:00.000Z", None, "Last"),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # Verify order matches timestamps
+        uuids = [getattr(e, "uuid", None) for e in messages if hasattr(e, "uuid")]
+        assert uuids == ["x", "y", "z"]
+
+        # Also verify template generation works (reuse pre-built tree)
+        root_messages, session_nav, context = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+        assert len(root_messages) > 0
+
+
+# =============================================================================
+# Test: Progress chain repair
+# =============================================================================
+
+# Path to real project test data with progress entries
+EXPERIMENTS_IDEAS_DIR = (
+    Path(__file__).parent / "test_data" / "real_projects" / "-experiments-ideas"
+)
+
+
+def _make_progress_entry(uuid: str, parent_uuid: str | None = None) -> dict[str, Any]:
+    """Helper to create a progress transcript entry dict."""
+    return {
+        "type": "progress",
+        "timestamp": "2025-07-01T10:00:00.000Z",
+        "uuid": uuid,
+        "parentUuid": parent_uuid,
+        "sessionId": "s1",
+        "content": {"type": "hook_progress"},
+    }
+
+
+class TestScanProgressChains:
+    """Unit tests for _scan_progress_chains helper."""
+
+    def test_scan_empty_directory(self, tmp_path: Path) -> None:
+        """Empty directory produces empty chain."""
+        chain = _scan_progress_chains(tmp_path)
+        assert chain == {}
+
+    def test_scan_file_with_no_progress(self, tmp_path: Path) -> None:
+        """File with no progress entries produces empty chain."""
+        entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        chain = _scan_progress_chains(tmp_path)
+        assert chain == {}
+
+    def test_scan_file_with_progress(self, tmp_path: Path) -> None:
+        """File with progress entries produces correct chain."""
+        entries = [
+            _make_progress_entry("p1", None),
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", "p1"),
+            _make_progress_entry("p2", "a"),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        chain = _scan_progress_chains(tmp_path)
+        assert chain == {"p1": None, "p2": "a"}
+
+    def test_scan_single_file_path(self, tmp_path: Path) -> None:
+        """Can scan a single file (not just a directory)."""
+        entries = [_make_progress_entry("p1", "parent1")]
+        path = tmp_path / "session.jsonl"
+        _write_jsonl(path, entries)
+        chain = _scan_progress_chains(path)
+        assert chain == {"p1": "parent1"}
+
+    def test_scan_real_data(self) -> None:
+        """Scan real test data with 11 progress entries."""
+        chain = _scan_progress_chains(EXPERIMENTS_IDEAS_DIR)
+        assert len(chain) == 11
+
+
+class TestRepairParentChains:
+    """Unit tests for _repair_parent_chains helper."""
+
+    def test_no_progress_noop(self, tmp_path: Path) -> None:
+        """No progress entries means no repairs needed."""
+        entries = [
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", None),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        from claude_code_log.converter import load_transcript
+
+        messages = load_transcript(tmp_path / "session.jsonl", silent=True)
+        _repair_parent_chains(messages, {})
+        assert isinstance(messages[0], BaseTranscriptEntry)
+        assert isinstance(messages[1], BaseTranscriptEntry)
+        assert messages[0].parentUuid is None
+        assert messages[1].parentUuid == "a"
+
+    def test_single_progress_gap(self, tmp_path: Path) -> None:
+        """Progress entry with uuid+sessionId becomes PassthroughTranscriptEntry.
+
+        With passthrough entries in the DAG, the chain is intact —
+        no repair needed for progress entries that have uuid+sessionId.
+        """
+        from claude_code_log.models import PassthroughTranscriptEntry
+
+        entries = [
+            _make_progress_entry("p1", None),
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", "p1"),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        from claude_code_log.converter import load_transcript
+
+        messages = load_transcript(tmp_path / "session.jsonl", silent=True)
+        progress_chain = {"p1": None}
+        _repair_parent_chains(messages, progress_chain)
+        # p1 is now a PassthroughTranscriptEntry (not dropped)
+        assert isinstance(messages[0], PassthroughTranscriptEntry)
+        assert messages[0].uuid == "p1"
+        # user(a).parentUuid remains "p1" — chain intact via passthrough
+        user_a = [m for m in messages if getattr(m, "uuid", None) == "a"][0]
+        assert isinstance(user_a, BaseTranscriptEntry)
+        assert user_a.parentUuid == "p1"
+
+    def test_chained_progress_gap(self, tmp_path: Path) -> None:
+        """Chain of passthrough progress entries preserves DAG links."""
+        # real_parent → progress(p1) → progress(p2) → user(a)
+        entries = [
+            _make_user_entry("real_parent", "s1", "2025-07-01T10:00:00.000Z", None),
+            _make_progress_entry("p1", "real_parent"),
+            _make_progress_entry("p2", "p1"),
+            _make_user_entry("a", "s1", "2025-07-01T10:01:00.000Z", "p2"),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+        from claude_code_log.converter import load_transcript
+
+        messages = load_transcript(tmp_path / "session.jsonl", silent=True)
+        progress_chain = {"p1": "real_parent", "p2": "p1"}
+        _repair_parent_chains(messages, progress_chain)
+        # With passthrough entries, chain is intact: a → p2 → p1 → real_parent
+        user_a = [m for m in messages if getattr(m, "uuid", None) == "a"][0]
+        assert isinstance(user_a, BaseTranscriptEntry)
+        assert user_a.parentUuid == "p2"  # NOT repaired — p2 is in the DAG
+
+
+class TestProgressChainRepairIntegration:
+    """Integration tests for progress chain repair in load_directory_transcripts."""
+
+    def test_progress_chain_repair_directory(self, caplog: Any) -> None:
+        """Progress entries are bridged: no orphan warnings from DAG build."""
+        with caplog.at_level(logging.WARNING):
+            result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+
+        # Should have loaded entries (41 non-progress, non-file-history entries)
+        assert len(result) > 0
+
+        # No orphan warnings should appear in logs
+        orphan_warnings = [
+            r.message for r in caplog.records if "Orphan node" in r.message
+        ]
+        assert orphan_warnings == [], (
+            f"Expected no orphan warnings, got: {orphan_warnings}"
+        )
+
+    def test_progress_chain_repair_single_file(self) -> None:
+        """Single-file mode: progress entries are PassthroughTranscriptEntry nodes.
+
+        With passthrough entries, progress entries are in the DAG and don't
+        need repair. Entries pointing to them have valid parents.
+        """
+        from claude_code_log.converter import (
+            load_transcript,
+            _scan_progress_chains,
+            _repair_parent_chains,
+        )
+        from claude_code_log.models import PassthroughTranscriptEntry
+
+        single_file = (
+            EXPERIMENTS_IDEAS_DIR / "03eb5929-52b3-4b13-ada3-b93ae35806b8.jsonl"
+        )
+        messages = load_transcript(single_file, silent=True)
+
+        # Progress entries are now PassthroughTranscriptEntry in messages
+        progress_chain = _scan_progress_chains(single_file)
+        assert len(progress_chain) == 11
+
+        # Progress entries should be in the messages list
+        passthrough_uuids = {
+            m.uuid
+            for m in messages
+            if isinstance(m, PassthroughTranscriptEntry) and m.type == "progress"
+        }
+        assert len(passthrough_uuids) > 0
+
+        # Repair should be a no-op since all progress entries are present
+        _repair_parent_chains(messages, progress_chain)
+
+        # Entries still point to progress UUIDs (which is correct —
+        # those are valid PassthroughTranscriptEntry nodes in the DAG)
+        entries_with_progress_parents = sum(
+            1 for m in messages if getattr(m, "parentUuid", None) in progress_chain
+        )
+        assert entries_with_progress_parents > 0  # Chain intact through passthrough
+
+    def test_progress_chain_preserves_entry_count(self) -> None:
+        """Repair doesn't add or remove entries, only mutates parentUuid."""
+        from claude_code_log.converter import load_transcript
+
+        single_file = (
+            EXPERIMENTS_IDEAS_DIR / "03eb5929-52b3-4b13-ada3-b93ae35806b8.jsonl"
+        )
+        messages = load_transcript(single_file, silent=True)
+        count_before = len(messages)
+
+        progress_chain = _scan_progress_chains(single_file)
+        _repair_parent_chains(messages, progress_chain)
+
+        assert len(messages) == count_before
+
+    def test_dag_chain_fully_connected(self) -> None:
+        """After repair, DAG build produces a single connected chain."""
+        from claude_code_log.dag import build_dag_from_entries
+
+        result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+
+        # Filter to DAG-eligible entries (those with uuid)
+        dag_entries = [e for e in result if hasattr(e, "uuid")]
+
+        # Build DAG to verify connectivity
+        tree = build_dag_from_entries(dag_entries)
+
+        # Should have sessions in the tree
+        assert len(tree.sessions) >= 1
+
+        # All DAG-eligible entries should be accounted for in the tree nodes
+        assert len(tree.nodes) > 0
+
+    def test_synthetic_progress_in_directory_mode(self, tmp_path: Path) -> None:
+        """Progress entries become passthrough nodes in directory mode."""
+        from claude_code_log.models import PassthroughTranscriptEntry
+
+        entries: list[dict[str, Any]] = [
+            _make_progress_entry("p1", None),
+            _make_user_entry("a", "s1", "2025-07-01T10:00:00.000Z", "p1", "Start"),
+            _make_assistant_entry("b", "s1", "2025-07-01T10:01:00.000Z", "a"),
+            _make_progress_entry("p2", "b"),
+            _make_user_entry("c", "s1", "2025-07-01T10:02:00.000Z", "p2", "Continue"),
+            _make_assistant_entry("d", "s1", "2025-07-01T10:03:00.000Z", "c"),
+        ]
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        result, _ = load_directory_transcripts(tmp_path, silent=True)
+        uuids = [getattr(e, "uuid", None) for e in result]
+
+        # All 6 entries in DAG order (including passthrough progress entries)
+        assert uuids == ["p1", "a", "b", "p2", "c", "d"]
+
+        # Progress entries are PassthroughTranscriptEntry
+        passthrough = [e for e in result if isinstance(e, PassthroughTranscriptEntry)]
+        assert len(passthrough) == 2
+        assert {p.uuid for p in passthrough} == {"p1", "p2"}
+
+
+# =============================================================================
+# Test: Within-session fork detection in real data
+# =============================================================================
+
+
+class TestWithinSessionForkRealData:
+    """Test fork detection using real session 03eb5929 which has a fork at eb84."""
+
+    def test_fork_detected_at_eb84(self) -> None:
+        """The real data has a fork at eb84 with two children (5270, 9edc)."""
+        from claude_code_log.dag import build_dag_from_entries
+
+        result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+        dag_entries = [e for e in result if hasattr(e, "uuid")]
+        tree = build_dag_from_entries(dag_entries)
+
+        # Find the fork junction at eb84
+        fork_jps = [
+            (uuid, jp)
+            for uuid, jp in tree.junction_points.items()
+            if uuid.startswith("eb84") and any("@" in t for t in jp.target_sessions)
+        ]
+        assert len(fork_jps) == 1, (
+            f"Expected 1 fork junction at eb84, got {len(fork_jps)}"
+        )
+        uuid, jp = fork_jps[0]
+        assert len(jp.target_sessions) == 2
+
+    def test_no_linearity_warnings(self, caplog: Any) -> None:
+        """Fork handling should produce no linearity violation warnings."""
+        import logging
+        from claude_code_log.dag import build_dag_from_entries
+
+        with caplog.at_level(logging.WARNING, logger="claude_code_log.dag"):
+            result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+            dag_entries = [e for e in result if hasattr(e, "uuid")]
+            build_dag_from_entries(dag_entries)
+
+        linearity_warnings = [
+            r.message for r in caplog.records if "linearity" in r.message
+        ]
+        assert linearity_warnings == []
+
+    def test_branch_sessions_created(self) -> None:
+        """Branch pseudo-sessions are created for the fork."""
+        from claude_code_log.dag import build_dag_from_entries
+
+        result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+        dag_entries = [e for e in result if hasattr(e, "uuid")]
+        tree = build_dag_from_entries(dag_entries)
+
+        branch_sessions = [sid for sid in tree.sessions if "@" in sid]
+        assert len(branch_sessions) >= 2
+
+        for sid in branch_sessions:
+            dl = tree.sessions[sid]
+            assert dl.is_branch is True
+            assert dl.original_session_id is not None
+            assert len(dl.uuids) > 0
+
+    def test_end_to_end_rendering_with_fork(self) -> None:
+        """Full rendering pipeline produces branch headers for fork."""
+        from claude_code_log.renderer import generate_template_messages
+        from claude_code_log.models import SessionHeaderMessage
+
+        result, session_tree = load_directory_transcripts(
+            EXPERIMENTS_IDEAS_DIR, silent=True
+        )
+        root_messages, session_nav, ctx = generate_template_messages(
+            result, session_tree=session_tree
+        )
+
+        # Find branch headers
+        branch_headers = [
+            tm
+            for tm in root_messages
+            if isinstance(tm.content, SessionHeaderMessage) and tm.content.is_branch
+        ]
+        assert len(branch_headers) >= 2
+
+    def test_within_fork_coverage(self) -> None:
+        """All entries are covered by DAG-lines (trunk + branches)."""
+        from claude_code_log.dag import build_dag_from_entries
+
+        result, _ = load_directory_transcripts(EXPERIMENTS_IDEAS_DIR, silent=True)
+        dag_entries = [e for e in result if hasattr(e, "uuid")]
+        tree = build_dag_from_entries(dag_entries)
+
+        # Should have both trunk and branch pseudo-sessions
+        real_sessions = [sid for sid in tree.sessions if "@" not in sid]
+        branch_sessions = [sid for sid in tree.sessions if "@" in sid]
+        assert len(real_sessions) >= 1
+        assert len(branch_sessions) >= 2
+
+        # All entries should be covered
+        total_in_daglines = sum(len(dl.uuids) for dl in tree.sessions.values())
+        assert total_in_daglines == len(tree.nodes)
+
+
+# =============================================================================
+# Test: Agent transcript DAG integration
+# =============================================================================
+
+
+class TestAgentDagIntegration:
+    """Test that agent (sidechain) transcripts are integrated into the DAG."""
+
+    def test_agent_entries_parented_to_anchor(self, tmp_path: Path) -> None:
+        """Agent root entry gets parentUuid pointing to the anchor tool_result."""
+        # Main session: user → assistant(tool_use Agent) → user(tool_result, agentId)
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("a1", "s1", "2025-07-01T10:01:00.000Z", "u1"),
+            # User entry carrying tool_result with agentId reference
+            _make_user_entry(
+                "u2",
+                "s1",
+                "2025-07-01T10:02:00.000Z",
+                "a1",
+                "tool result",
+                agent_id="agent-abc",
+            ),
+            _make_assistant_entry("a2", "s1", "2025-07-01T10:03:00.000Z", "u2"),
+        ]
+        # Agent file entries (all sidechain)
+        agent_entries = [
+            _make_user_entry(
+                "ag1",
+                "s1",
+                "2025-07-01T10:01:30.000Z",
+                None,
+                "Agent prompt",
+                is_sidechain=True,
+                agent_id="agent-abc",
+            ),
+            _make_assistant_entry(
+                "ag2",
+                "s1",
+                "2025-07-01T10:01:40.000Z",
+                "ag1",
+                "Agent reply",
+                is_sidechain=True,
+                agent_id="agent-abc",
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + agent_entries)
+
+        result, tree = load_directory_transcripts(tmp_path, silent=True)
+        uuids = [getattr(e, "uuid", None) for e in result]
+
+        # Agent entries should be in the DAG, placed at the junction point
+        assert "ag1" in uuids
+        assert "ag2" in uuids
+        # Main session entries should be in order
+        assert uuids.index("u1") < uuids.index("a1")
+        assert uuids.index("a1") < uuids.index("u2")
+        assert uuids.index("u2") < uuids.index("a2")
+        # Agent entries should appear between the anchor (u2) and
+        # continuation (a2) — the agent DAG-line is a child session
+        # traversed at the junction point
+        assert uuids.index("u2") < uuids.index("ag1")
+        assert uuids.index("ag2") < uuids.index("a2")
+
+    def test_agent_session_in_tree(self, tmp_path: Path) -> None:
+        """Agent transcript creates a synthetic child session in the tree."""
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_user_entry(
+                "u2",
+                "s1",
+                "2025-07-01T10:02:00.000Z",
+                "u1",
+                "tool result",
+                agent_id="agent-xyz",
+            ),
+        ]
+        agent_entries = [
+            _make_user_entry(
+                "ag1",
+                "s1",
+                "2025-07-01T10:01:00.000Z",
+                None,
+                "Agent prompt",
+                is_sidechain=True,
+                agent_id="agent-xyz",
+            ),
+            _make_assistant_entry(
+                "ag2",
+                "s1",
+                "2025-07-01T10:01:10.000Z",
+                "ag1",
+                "Agent reply",
+                is_sidechain=True,
+                agent_id="agent-xyz",
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + agent_entries)
+
+        _, tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # Should have synthetic agent session
+        agent_sids = [sid for sid in tree.sessions if "#agent-" in sid]
+        assert len(agent_sids) == 1
+        assert agent_sids[0] == "s1#agent-agent-xyz"
+
+        # Agent session should be a child of the main session
+        agent_dag_line = tree.sessions[agent_sids[0]]
+        assert agent_dag_line.parent_session_id == "s1"
+        assert agent_dag_line.attachment_uuid == "u2"
+
+        # Main session should be a root
+        assert "s1" in tree.roots
+        assert agent_sids[0] not in tree.roots
+
+    def test_agent_no_session_header(self, tmp_path: Path) -> None:
+        """Agent sessions don't generate session headers in rendering."""
+        from claude_code_log.renderer import generate_template_messages
+        from claude_code_log.models import SessionHeaderMessage
+
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_user_entry(
+                "u2",
+                "s1",
+                "2025-07-01T10:02:00.000Z",
+                "u1",
+                "tool result",
+                agent_id="agent-xyz",
+            ),
+        ]
+        agent_entries = [
+            _make_user_entry(
+                "ag1",
+                "s1",
+                "2025-07-01T10:01:00.000Z",
+                None,
+                "Agent prompt",
+                is_sidechain=True,
+                agent_id="agent-xyz",
+            ),
+            _make_assistant_entry(
+                "ag2",
+                "s1",
+                "2025-07-01T10:01:10.000Z",
+                "ag1",
+                "Agent reply",
+                is_sidechain=True,
+                agent_id="agent-xyz",
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + agent_entries)
+
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        root_messages, session_nav, context = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        # Only one session header (for the main session), not for the agent
+        headers = [
+            m for m in context.messages if isinstance(m.content, SessionHeaderMessage)
+        ]
+        assert len(headers) == 1
+        header_content = headers[0].content
+        assert isinstance(header_content, SessionHeaderMessage)
+        assert header_content.session_id == "s1"
+
+    def test_multiple_agents_ordered(self, tmp_path: Path) -> None:
+        """Multiple agents are each placed at their respective anchor points."""
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("a1", "s1", "2025-07-01T10:01:00.000Z", "u1"),
+            # First agent anchor
+            _make_user_entry(
+                "u2",
+                "s1",
+                "2025-07-01T10:02:00.000Z",
+                "a1",
+                "result1",
+                agent_id="agent-1",
+            ),
+            _make_assistant_entry("a2", "s1", "2025-07-01T10:03:00.000Z", "u2"),
+            # Second agent anchor
+            _make_user_entry(
+                "u3",
+                "s1",
+                "2025-07-01T10:04:00.000Z",
+                "a2",
+                "result2",
+                agent_id="agent-2",
+            ),
+            _make_assistant_entry("a3", "s1", "2025-07-01T10:05:00.000Z", "u3"),
+        ]
+        agent1_entries = [
+            _make_user_entry(
+                "ag1-1",
+                "s1",
+                "2025-07-01T10:01:30.000Z",
+                None,
+                "Agent1 prompt",
+                is_sidechain=True,
+                agent_id="agent-1",
+            ),
+            _make_assistant_entry(
+                "ag1-2",
+                "s1",
+                "2025-07-01T10:01:40.000Z",
+                "ag1-1",
+                "Agent1 reply",
+                is_sidechain=True,
+                agent_id="agent-1",
+            ),
+        ]
+        agent2_entries = [
+            _make_user_entry(
+                "ag2-1",
+                "s1",
+                "2025-07-01T10:03:30.000Z",
+                None,
+                "Agent2 prompt",
+                is_sidechain=True,
+                agent_id="agent-2",
+            ),
+            _make_assistant_entry(
+                "ag2-2",
+                "s1",
+                "2025-07-01T10:03:40.000Z",
+                "ag2-1",
+                "Agent2 reply",
+                is_sidechain=True,
+                agent_id="agent-2",
+            ),
+        ]
+
+        _write_jsonl(
+            tmp_path / "session.jsonl",
+            main_entries + agent1_entries + agent2_entries,
+        )
+
+        result, tree = load_directory_transcripts(tmp_path, silent=True)
+        uuids = [getattr(e, "uuid", None) for e in result]
+
+        # Each agent should appear after its anchor and before the next main entry
+        assert uuids.index("ag1-1") > uuids.index("u2")
+        assert uuids.index("ag1-2") < uuids.index("a2")
+        assert uuids.index("ag2-1") > uuids.index("u3")
+        assert uuids.index("ag2-2") < uuids.index("a3")
+
+        # Two synthetic agent sessions
+        agent_sids = [sid for sid in tree.sessions if "#agent-" in sid]
+        assert len(agent_sids) == 2
+
+    def test_agent_in_branch(self, tmp_path: Path) -> None:
+        """Agent anchored inside a within-session fork attaches to the branch."""
+        from claude_code_log.renderer import generate_template_messages
+
+        # Trunk: u1 → a1 (fork point)
+        # Branch 1: b1_u (rewind from a1, different timestamp) → b1_a
+        #   with agent anchored at b1_u
+        # Branch 2: b2_u (rewind from a1, different timestamp)
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("a1", "s1", "2025-07-01T10:01:00.000Z", "u1"),
+            # Branch 1: user rewind from a1
+            _make_user_entry(
+                "b1_u",
+                "s1",
+                "2025-07-01T10:02:00.000Z",
+                "a1",
+                "Branch 1",
+                agent_id="agent-b1",
+            ),
+            _make_assistant_entry(
+                "b1_a",
+                "s1",
+                "2025-07-01T10:03:00.000Z",
+                "b1_u",
+            ),
+            # Branch 2: user rewind from a1 (different timestamp = real fork)
+            _make_user_entry(
+                "b2_u",
+                "s1",
+                "2025-07-01T10:04:00.000Z",
+                "a1",
+                "Branch 2",
+            ),
+        ]
+        agent_entries = [
+            _make_user_entry(
+                "ag1",
+                "s1",
+                "2025-07-01T10:02:30.000Z",
+                None,
+                "Agent in branch",
+                is_sidechain=True,
+                agent_id="agent-b1",
+            ),
+            _make_assistant_entry(
+                "ag2",
+                "s1",
+                "2025-07-01T10:02:40.000Z",
+                "ag1",
+                "Agent reply",
+                is_sidechain=True,
+                agent_id="agent-b1",
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + agent_entries)
+
+        result, tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # Agent session's parent should be the branch pseudo-session, not trunk
+        agent_sids = [sid for sid in tree.sessions if "#agent-" in sid]
+        assert len(agent_sids) == 1
+        agent_dl = tree.sessions[agent_sids[0]]
+        # The branch pseudo-session has format "s1@{child_uuid[:12]}"
+        assert agent_dl.parent_session_id is not None
+        assert "@" in agent_dl.parent_session_id, (
+            f"Agent should be child of branch, got parent={agent_dl.parent_session_id}"
+        )
+        assert agent_dl.attachment_uuid == "b1_u"
+
+        # End-to-end rendering: agent messages should appear in the branch,
+        # not get regrouped under the trunk
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        root_messages, session_nav, context = generate_template_messages(
+            messages, session_tree=session_tree
+        )
+
+        # Verify message ordering: agent messages should be in the branch
+        # block (after b1_u anchor, before branch 2's b2_u)
+        msg_uuids = {m.meta.uuid: m.message_index for m in context.messages}
+        assert "ag1" in msg_uuids
+        assert "b1_u" in msg_uuids
+        assert "b2_u" in msg_uuids
+        assert msg_uuids["b1_u"] < msg_uuids["ag1"] < msg_uuids["b2_u"]  # type: ignore[operator]
+
+    def test_agent_messages_coalesced_into_parent_session(self, tmp_path: Path) -> None:
+        """Agent message counts and tokens fold into parent session aggregates.
+
+        Regression test: agent messages must not be dropped from session
+        metadata used for pagination and cache. They should be counted under
+        the parent session.
+        """
+        # Main session: user → assistant(anchor, agentId) → user(next)
+        main_entries = [
+            _make_user_entry("u1", "s1", "2025-01-01T00:00:00Z", text="Hello"),
+            _make_assistant_entry(
+                "a1",
+                "s1",
+                "2025-01-01T00:00:01Z",
+                parent_uuid="u1",
+                agent_id="ag1",
+            ),
+            _make_user_entry(
+                "u2",
+                "s1",
+                "2025-01-01T00:00:05Z",
+                parent_uuid="a1",
+                text="Continue",
+            ),
+        ]
+        # Agent sidechain: 2 entries (user + assistant)
+        agent_entries = [
+            _make_user_entry(
+                "ag_u1",
+                "s1",
+                "2025-01-01T00:00:02Z",
+                is_sidechain=True,
+                agent_id="ag1",
+                text="agent task",
+            ),
+            _make_assistant_entry(
+                "ag_a1",
+                "s1",
+                "2025-01-01T00:00:03Z",
+                parent_uuid="ag_u1",
+                is_sidechain=True,
+                agent_id="ag1",
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", main_entries + agent_entries)
+
+        messages, _tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # Build session data (used for pagination page assignment)
+        session_data = _build_session_data_from_messages(messages)
+
+        # Only the parent session should exist — no agent-synthetic session
+        assert "s1" in session_data
+        assert not any("#agent-" in sid for sid in session_data)
+
+        s1 = session_data["s1"]
+        # message_count should include both main (3) and agent (2) entries
+        assert s1.message_count == 5
+
+        # Token totals should include agent assistant entry (10 input, 5 output)
+        # Main has 1 assistant (a1: 10 input, 5 output)
+        # Agent has 1 assistant (ag_a1: 10 input, 5 output)
+        assert s1.total_input_tokens == 20
+        assert s1.total_output_tokens == 10
+
+
+# =============================================================================
+# Test: current_render_session reset across sessions
+# =============================================================================
+
+
+class TestRenderSessionResetAcrossSessions:
+    """Test that current_render_session is reset when entering a new session.
+
+    Bug: _render_messages() sets current_render_session when entering a
+    within-session fork branch but never clears it on new sessions,
+    causing subsequent session messages to inherit a stale branch ID.
+    """
+
+    def test_second_session_not_polluted_by_first_session_branch(
+        self, tmp_path: Path
+    ) -> None:
+        """Messages in session 2 should not inherit session 1's branch render_session_id."""
+        from claude_code_log.renderer import generate_template_messages
+
+        # Session s1 with a fork: u1 → a1, then both u2a and u2b branch from a1
+        s1_entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_assistant_entry("a1", "s1", "2025-07-01T10:01:00.000Z", "u1"),
+            # Fork: two children of a1
+            _make_user_entry("u2a", "s1", "2025-07-01T10:02:00.000Z", "a1", "Branch A"),
+            _make_assistant_entry("a2a", "s1", "2025-07-01T10:03:00.000Z", "u2a"),
+            _make_user_entry("u2b", "s1", "2025-07-01T10:02:01.000Z", "a1", "Branch B"),
+            _make_assistant_entry("a2b", "s1", "2025-07-01T10:03:01.000Z", "u2b"),
+        ]
+
+        # Session s2: separate session, should NOT inherit s1's branch state
+        s2_entries = [
+            _make_user_entry(
+                "u3", "s2", "2025-07-01T11:00:00.000Z", None, "New session"
+            ),
+            _make_assistant_entry("a3", "s2", "2025-07-01T11:01:00.000Z", "u3"),
+        ]
+
+        _write_jsonl(tmp_path / "s1.jsonl", s1_entries)
+        _write_jsonl(tmp_path / "s2.jsonl", s2_entries)
+
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        _, _, ctx = generate_template_messages(messages, session_tree=session_tree)
+
+        # Find messages from session s2 by UUID
+        s2_msgs = [m for m in ctx.messages if m.meta.uuid in ("u3", "a3")]
+        assert len(s2_msgs) == 2, f"Expected 2 s2 messages, got {len(s2_msgs)}"
+
+        for msg in s2_msgs:
+            assert msg.render_session_id == "s2", (
+                f"Message {msg.meta.uuid} has render_session_id={msg.render_session_id!r}, "
+                f"expected 's2' — branch tracking from s1 leaked into s2"
+            )
+
+
+# =============================================================================
+# Test: PassthroughTranscriptEntry for DAG chain continuity
+# =============================================================================
+
+
+def _make_passthrough_entry(
+    uuid: str,
+    session_id: str,
+    timestamp: str,
+    parent_uuid: str | None = None,
+    entry_type: str = "attachment",
+) -> dict[str, Any]:
+    """Helper to create a passthrough (non-rendered) entry dict."""
+    return {
+        "type": entry_type,
+        "timestamp": timestamp,
+        "parentUuid": parent_uuid,
+        "isSidechain": False,
+        "userType": "external",
+        "cwd": "/tmp",
+        "sessionId": session_id,
+        "version": "1.0.0",
+        "uuid": uuid,
+        # No "message" field — this is not a user/assistant entry
+    }
+
+
+class TestPassthroughDagChain:
+    """Test that passthrough entries (attachment, etc.) preserve DAG chain."""
+
+    def test_attachment_preserves_parent_chain(self, tmp_path: Path) -> None:
+        """Assistant whose parentUuid points to an attachment should not be a false root."""
+        entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_passthrough_entry(
+                "att1", "s1", "2025-07-01T10:00:30.000Z", "u1", "attachment"
+            ),
+            _make_assistant_entry(
+                "a1", "s1", "2025-07-01T10:01:00.000Z", "att1", "Reply"
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        messages, tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # All three entries should be in the DAG
+        assert "u1" in tree.nodes
+        assert "att1" in tree.nodes
+        assert "a1" in tree.nodes
+
+        # a1's parent should be att1, att1's parent should be u1
+        assert tree.nodes["a1"].parent_uuid == "att1"
+        assert tree.nodes["att1"].parent_uuid == "u1"
+
+        # a1 should NOT be a false root — the session should have only 1 root (u1)
+        s1 = tree.sessions.get("s1")
+        assert s1 is not None
+        assert s1.uuids[0] == "u1", "u1 should be the first entry in the session"
+
+    def test_attachment_not_rendered(self, tmp_path: Path) -> None:
+        """Passthrough entries should not appear in rendered output."""
+        from claude_code_log.renderer import generate_template_messages
+
+        entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Hello"),
+            _make_passthrough_entry(
+                "att1", "s1", "2025-07-01T10:00:30.000Z", "u1", "attachment"
+            ),
+            _make_assistant_entry(
+                "a1", "s1", "2025-07-01T10:01:00.000Z", "att1", "World"
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        messages, session_tree = load_directory_transcripts(tmp_path, silent=True)
+        _, _, ctx = generate_template_messages(messages, session_tree=session_tree)
+
+        # No message should have uuid "att1"
+        rendered_uuids = [m.meta.uuid for m in ctx.messages if m.meta.uuid]
+        assert "att1" not in rendered_uuids
+        # But user and assistant should be rendered
+        assert "u1" in rendered_uuids
+        assert "a1" in rendered_uuids
+
+    def test_multiple_passthrough_types(self, tmp_path: Path) -> None:
+        """Various unknown types with uuid should all become passthrough entries."""
+        entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_passthrough_entry(
+                "p1", "s1", "2025-07-01T10:00:10.000Z", "u1", "attachment"
+            ),
+            _make_passthrough_entry(
+                "p2", "s1", "2025-07-01T10:00:20.000Z", "p1", "permission-mode"
+            ),
+            _make_passthrough_entry(
+                "p3", "s1", "2025-07-01T10:00:30.000Z", "p2", "file-history-snapshot"
+            ),
+            _make_assistant_entry(
+                "a1", "s1", "2025-07-01T10:01:00.000Z", "p3", "Reply"
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        messages, tree = load_directory_transcripts(tmp_path, silent=True)
+
+        # All should be in DAG
+        for uid in ["u1", "p1", "p2", "p3", "a1"]:
+            assert uid in tree.nodes, f"{uid} should be in DAG"
+
+        # Chain should be intact: u1 → p1 → p2 → p3 → a1
+        assert tree.nodes["a1"].parent_uuid == "p3"
+        assert tree.nodes["p3"].parent_uuid == "p2"
+        assert tree.nodes["p2"].parent_uuid == "p1"
+        assert tree.nodes["p1"].parent_uuid == "u1"
+
+    def test_passthrough_excluded_from_session_data(self, tmp_path: Path) -> None:
+        """Passthrough entries should not inflate session message counts."""
+        entries = [
+            _make_user_entry("u1", "s1", "2025-07-01T10:00:00.000Z", None, "Start"),
+            _make_passthrough_entry(
+                "att1", "s1", "2025-07-01T10:00:30.000Z", "u1", "attachment"
+            ),
+            _make_assistant_entry(
+                "a1", "s1", "2025-07-01T10:01:00.000Z", "att1", "Reply"
+            ),
+        ]
+
+        _write_jsonl(tmp_path / "session.jsonl", entries)
+
+        messages, _ = load_directory_transcripts(tmp_path, silent=True)
+        session_data = _build_session_data_from_messages(messages)
+
+        # Only user + assistant should be counted (not the attachment)
+        assert session_data["s1"].message_count == 2
diff --git a/test/test_data/dag_fork.jsonl b/test/test_data/dag_fork.jsonl
new file mode 100644
index 00000000..11475211
--- /dev/null
+++ b/test/test_data/dag_fork.jsonl
@@ -0,0 +1,11 @@
+{"type":"user","timestamp":"2025-07-01T10:00:00.000Z","parentUuid":null,"isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"a","message":{"role":"user","content":[{"type":"text","text":"Start"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:01:00.000Z","parentUuid":"a","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"b","requestId":"req_1","message":{"id":"b","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Reply 1"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"output_tokens":5}}}
+{"type":"user","timestamp":"2025-07-01T10:02:00.000Z","parentUuid":"b","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"c","message":{"role":"user","content":[{"type":"text","text":"Middle"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:03:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"d","requestId":"req_2","message":{"id":"d","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Reply 2"}],"stop_reason":"end_turn","usage":{"input_tokens":15,"output_tokens":8}}}
+{"type":"user","timestamp":"2025-07-01T10:04:00.000Z","parentUuid":"d","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"e","message":{"role":"user","content":[{"type":"text","text":"Last in s1"}]}}
+{"type":"user","timestamp":"2025-07-01T11:00:00.000Z","parentUuid":"e","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"f","message":{"role":"user","content":[{"type":"text","text":"Continue from e"}]}}
+{"type":"assistant","timestamp":"2025-07-01T11:01:00.000Z","parentUuid":"f","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"g","requestId":"req_3","message":{"id":"g","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Continued reply"}],"stop_reason":"end_turn","usage":{"input_tokens":20,"output_tokens":10}}}
+{"type":"user","timestamp":"2025-07-01T11:02:00.000Z","parentUuid":"g","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"h","message":{"role":"user","content":[{"type":"text","text":"End of s2"}]}}
+{"type":"user","timestamp":"2025-07-01T12:00:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s3","version":"1.0.0","uuid":"i","message":{"role":"user","content":[{"type":"text","text":"Fork from c"}]}}
+{"type":"assistant","timestamp":"2025-07-01T12:01:00.000Z","parentUuid":"i","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s3","version":"1.0.0","uuid":"j","requestId":"req_4","message":{"id":"j","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Forked reply"}],"stop_reason":"end_turn","usage":{"input_tokens":25,"output_tokens":12}}}
+{"type":"user","timestamp":"2025-07-01T12:02:00.000Z","parentUuid":"j","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s3","version":"1.0.0","uuid":"k","message":{"role":"user","content":[{"type":"text","text":"End of s3"}]}}
diff --git a/test/test_data/dag_resume.jsonl b/test/test_data/dag_resume.jsonl
new file mode 100644
index 00000000..fc6203cf
--- /dev/null
+++ b/test/test_data/dag_resume.jsonl
@@ -0,0 +1,8 @@
+{"type":"user","timestamp":"2025-07-01T10:00:00.000Z","parentUuid":null,"isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"a","message":{"role":"user","content":[{"type":"text","text":"Start"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:01:00.000Z","parentUuid":"a","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"b","requestId":"req_1","message":{"id":"b","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Reply 1"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"output_tokens":5}}}
+{"type":"user","timestamp":"2025-07-01T10:02:00.000Z","parentUuid":"b","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"c","message":{"role":"user","content":[{"type":"text","text":"Continue"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:03:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"d","requestId":"req_2","message":{"id":"d","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Reply 2"}],"stop_reason":"end_turn","usage":{"input_tokens":15,"output_tokens":8}}}
+{"type":"user","timestamp":"2025-07-01T10:04:00.000Z","parentUuid":"d","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"e","message":{"role":"user","content":[{"type":"text","text":"Last in s1"}]}}
+{"type":"user","timestamp":"2025-07-01T11:00:00.000Z","parentUuid":"e","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"f","message":{"role":"user","content":[{"type":"text","text":"Resume here"}]}}
+{"type":"assistant","timestamp":"2025-07-01T11:01:00.000Z","parentUuid":"f","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"g","requestId":"req_3","message":{"id":"g","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Resumed reply"}],"stop_reason":"end_turn","usage":{"input_tokens":20,"output_tokens":10}}}
+{"type":"user","timestamp":"2025-07-01T11:02:00.000Z","parentUuid":"g","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s2","version":"1.0.0","uuid":"h","message":{"role":"user","content":[{"type":"text","text":"End of s2"}]}}
diff --git a/test/test_data/dag_simple.jsonl b/test/test_data/dag_simple.jsonl
new file mode 100644
index 00000000..5b5152d6
--- /dev/null
+++ b/test/test_data/dag_simple.jsonl
@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2025-07-01T10:00:00.000Z","parentUuid":null,"isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"a","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:01:00.000Z","parentUuid":"a","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"b","requestId":"req_1","message":{"id":"b","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Hi there"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"output_tokens":5}}}
+{"type":"user","timestamp":"2025-07-01T10:02:00.000Z","parentUuid":"b","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"c","message":{"role":"user","content":[{"type":"text","text":"How are you?"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:03:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"d","requestId":"req_2","message":{"id":"d","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"I'm doing well"}],"stop_reason":"end_turn","usage":{"input_tokens":15,"output_tokens":8}}}
+{"type":"user","timestamp":"2025-07-01T10:04:00.000Z","parentUuid":"d","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"e","message":{"role":"user","content":[{"type":"text","text":"Goodbye"}]}}
diff --git a/test/test_data/dag_within_fork.jsonl b/test/test_data/dag_within_fork.jsonl
new file mode 100644
index 00000000..c6faf28e
--- /dev/null
+++ b/test/test_data/dag_within_fork.jsonl
@@ -0,0 +1,8 @@
+{"type":"user","timestamp":"2025-07-01T10:00:00.000Z","parentUuid":null,"isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"a","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:01:00.000Z","parentUuid":"a","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"b","requestId":"req_1","message":{"id":"b","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Hi there"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"output_tokens":5}}}
+{"type":"user","timestamp":"2025-07-01T10:02:00.000Z","parentUuid":"b","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"c","message":{"role":"user","content":[{"type":"text","text":"Fork point"}]}}
+{"type":"user","timestamp":"2025-07-01T10:03:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"d","message":{"role":"user","content":[{"type":"text","text":"Branch 1 start"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:04:00.000Z","parentUuid":"d","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"e","requestId":"req_2","message":{"id":"e","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Branch 1 reply"}],"stop_reason":"end_turn","usage":{"input_tokens":15,"output_tokens":8}}}
+{"type":"user","timestamp":"2025-07-01T10:05:00.000Z","parentUuid":"e","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"f","message":{"role":"user","content":[{"type":"text","text":"Branch 1 end"}]}}
+{"type":"user","timestamp":"2025-07-01T10:10:00.000Z","parentUuid":"c","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"d_prime","message":{"role":"user","content":[{"type":"text","text":"Branch 2 start"}]}}
+{"type":"assistant","timestamp":"2025-07-01T10:11:00.000Z","parentUuid":"d_prime","isSidechain":false,"userType":"human","cwd":"/tmp","sessionId":"s1","version":"1.0.0","uuid":"e_prime","requestId":"req_3","message":{"id":"e_prime","type":"message","role":"assistant","model":"claude-3-sonnet","content":[{"type":"text","text":"Branch 2 reply"}],"stop_reason":"end_turn","usage":{"input_tokens":15,"output_tokens":8}}}
diff --git a/test/test_data/real_projects/-experiments-ideas/03eb5929-52b3-4b13-ada3-b93ae35806b8.jsonl b/test/test_data/real_projects/-experiments-ideas/03eb5929-52b3-4b13-ada3-b93ae35806b8.jsonl
new file mode 100644
index 00000000..a28c0ffd
--- /dev/null
+++ b/test/test_data/real_projects/-experiments-ideas/03eb5929-52b3-4b13-ada3-b93ae35806b8.jsonl
@@ -0,0 +1,61 @@
+{"type":"file-history-snapshot","messageId":"13f97369-4175-446a-bac8-0b7e2981d649","snapshot":{"messageId":"13f97369-4175-446a-bac8-0b7e2981d649","trackedFileBackups":{},"timestamp":"2026-02-16T18:47:50.736Z"},"isSnapshotUpdate":false}
+{"parentUuid":null,"isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","type":"progress","data":{"type":"hook_progress","hookEvent":"SessionStart","hookName":"SessionStart:startup","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor started"},"parentToolUseID":"47c43ea7-0408-4ce4-8ebf-7ee2693ad459","toolUseID":"47c43ea7-0408-4ce4-8ebf-7ee2693ad459","timestamp":"2026-02-16T18:46:55.028Z","uuid":"a2c5ddf6-b5bf-4ed9-96d5-6302976cd948"}
+{"parentUuid":"a2c5ddf6-b5bf-4ed9-96d5-6302976cd948","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","type":"user","message":{"role":"user","content":"Ok, so there's isn't much to see here, mostly one idea about how to organize the work Markdown documents generated during a Claude Code session."},"uuid":"13f97369-4175-446a-bac8-0b7e2981d649","timestamp":"2026-02-16T18:47:50.590Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"13f97369-4175-446a-bac8-0b7e2981d649","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","message":{"model":"claude-opus-4-6","id":"msg_01UHi2Lt3JY6hKT2YohPo25U","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":5376,"cache_read_input_tokens":21440,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":5376},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFGaJeJwUa1Y2S4C9WU","type":"assistant","uuid":"b5c90882-1e0a-493a-859c-2af606f624a1","timestamp":"2026-02-16T18:47:53.122Z"}
+{"parentUuid":"b5c90882-1e0a-493a-859c-2af606f624a1","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","message":{"model":"claude-opus-4-6","id":"msg_01UHi2Lt3JY6hKT2YohPo25U","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user is talking about the current directory (`experiments/ideas`) and mentioning there's one idea about organizing work Markdown documents generated during a Claude Code session. Let me look at what's in this directory to understand what they're referring to.","signature":"ErADCkYICxgCKkCs4awX2Vpb/coi/geSoM4hvM4cP6bS0IrYVqoF3M76OpXWT+r0pOBksyKm2HfX3hnEU3UzkwTCjc84sXUrZYWbEgxdBPP6El2kTixd/7YaDL5TYOpkwWnmrHWUvCIwxYx3OEpjl9Itm+abBReBf/3HgvGJ44T5HiZiPShYyVxFpkagbNOmAgMThLnGqRSWKpcCnHogamn9qy8mAQtbEisrmBeyWe617qgVQlxk9TDXhzQy6fV38nKxhtc8k9Vp2SWLIQ3wMNs2QYlYdEC9MhVNj97HSLhVn5t6qIN9ZXiQ237nNsXmadizcE1B+S8QCgKinid89Kpmxq2D1cSifhy4Q3HCHOUDCVQnhRfj+YWI+wn/CeOFPqvhA8ghToqkabVzlE3C5nh7vjjTNYpA5Ir6u97xYJuM25VodQvRuZ8oTmCsPJmAGxMuuSddRx1F+OCWNrKr30sbXF48mWI8gI6zuK7Jfr4/fCJJ1JT/GTQ7ECpyrqNUx3Nz2VliSomEf0gFaVpZ0E54+xoaUsjb1p0Gkd1IjrGYed4msjZ3q5474jdj3UHKqQJmGAE="}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":5376,"cache_read_input_tokens":21440,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":5376},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFGaJeJwUa1Y2S4C9WU","type":"assistant","uuid":"788d2450-b82d-402b-8d85-995b28f2548c","timestamp":"2026-02-16T18:47:54.006Z"}
+{"parentUuid":"788d2450-b82d-402b-8d85-995b28f2548c","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","message":{"model":"claude-opus-4-6","id":"msg_01UHi2Lt3JY6hKT2YohPo25U","type":"message","role":"assistant","content":[{"type":"text","text":"Let me take a look at what's here."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":5376,"cache_read_input_tokens":21440,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":5376},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFGaJeJwUa1Y2S4C9WU","type":"assistant","uuid":"f2ad6242-f4e1-4589-bdb9-99af55017d54","timestamp":"2026-02-16T18:47:54.478Z"}
+{"parentUuid":"f2ad6242-f4e1-4589-bdb9-99af55017d54","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","message":{"model":"claude-opus-4-6","id":"msg_01UHi2Lt3JY6hKT2YohPo25U","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01R8fKGi2tkSE4siHWmS8j1f","name":"Bash","input":{"command":"ls -la /home/user/project/","description":"List contents of the ideas directory"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":5376,"cache_read_input_tokens":21440,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":5376},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFGaJeJwUa1Y2S4C9WU","type":"assistant","uuid":"bba9b15d-5384-4c34-ab75-1d92033e1a6e","timestamp":"2026-02-16T18:47:55.190Z"}
+{"parentUuid":"bba9b15d-5384-4c34-ab75-1d92033e1a6e","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","type":"progress","data":{"type":"hook_progress","hookEvent":"PostToolUse","hookName":"PostToolUse:Bash","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor busy"},"parentToolUseID":"toolu_01R8fKGi2tkSE4siHWmS8j1f","toolUseID":"toolu_01R8fKGi2tkSE4siHWmS8j1f","timestamp":"2026-02-16T18:47:55.327Z","uuid":"9bad499b-b108-49a1-9a69-f5d7e984d63a"}
+{"parentUuid":"bba9b15d-5384-4c34-ab75-1d92033e1a6e","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01R8fKGi2tkSE4siHWmS8j1f","type":"tool_result","content":"total 12\ndrwxrwxr-x 2 cboos cboos 4096 févr. 16 19:46 .\ndrwxrwxr-x 3 cboos cboos 4096 févr. 16 19:46 ..\n-rw-rw-r-- 1 cboos cboos  345 févr. 16 19:46 work-and-dev-docs.md","is_error":false}]},"uuid":"ddaea810-9825-40b6-9003-b2094061cca7","timestamp":"2026-02-16T18:47:55.323Z","toolUseResult":{"stdout":"total 12\ndrwxrwxr-x 2 cboos cboos 4096 févr. 16 19:46 .\ndrwxrwxr-x 3 cboos cboos 4096 févr. 16 19:46 ..\n-rw-rw-r-- 1 cboos cboos  345 févr. 16 19:46 work-and-dev-docs.md","stderr":"","interrupted":false,"isImage":false,"noOutputExpected":false},"sourceToolAssistantUUID":"bba9b15d-5384-4c34-ab75-1d92033e1a6e"}
+{"parentUuid":"ddaea810-9825-40b6-9003-b2094061cca7","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_016dvKLUUWxWYT4YKotNcLfH","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_016hTGfKRpRvGvUEjFmijpZV","name":"Read","input":{"file_path":"/home/user/project/work-and-dev-docs.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":1,"cache_creation_input_tokens":298,"cache_read_input_tokens":26816,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":298},"output_tokens":25,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFGvPPPWr46ShCw6VcF","type":"assistant","uuid":"9598e2ef-4606-49cd-986e-9415253c4a79","timestamp":"2026-02-16T18:47:58.573Z"}
+{"parentUuid":"9598e2ef-4606-49cd-986e-9415253c4a79","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"PostToolUse","hookName":"PostToolUse:Read","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor busy"},"parentToolUseID":"toolu_016hTGfKRpRvGvUEjFmijpZV","toolUseID":"toolu_016hTGfKRpRvGvUEjFmijpZV","timestamp":"2026-02-16T18:47:58.595Z","uuid":"a2e57ef3-28a8-40b3-9e97-8c42d4f388bb"}
+{"parentUuid":"a2e57ef3-28a8-40b3-9e97-8c42d4f388bb","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"PostToolUse","hookName":"PostToolUse:Read","command":"callback"},"parentToolUseID":"toolu_016hTGfKRpRvGvUEjFmijpZV","toolUseID":"toolu_016hTGfKRpRvGvUEjFmijpZV","timestamp":"2026-02-16T18:47:58.595Z","uuid":"fa6c70ea-e46b-4864-867a-ea8f5acc53c9"}
+{"parentUuid":"9598e2ef-4606-49cd-986e-9415253c4a79","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_016hTGfKRpRvGvUEjFmijpZV","type":"tool_result","content":"     1→# dev-docs/ vs work/ Directory Convention\n     2→\n     3→- `dev-docs/` = technical reference (architecture, API, data model)\n     4→- `work/` = work items:\n     5→  - `archive/` = completed plans and proposals\n     6→  - `backlog/` = known issues, unfinished work\n     7→  - `future/` = planned features, proposals not yet started\n     8→  - Top-level `work/*.md` = currently active work items\n     9→"}]},"uuid":"678beeff-0788-4a6e-a711-3802bffba8eb","timestamp":"2026-02-16T18:47:58.594Z","toolUseResult":{"type":"text","file":{"filePath":"/home/user/project/work-and-dev-docs.md","content":"# dev-docs/ vs work/ Directory Convention\n\n- `dev-docs/` = technical reference (architecture, API, data model)\n- `work/` = work items:\n  - `archive/` = completed plans and proposals\n  - `backlog/` = known issues, unfinished work\n  - `future/` = planned features, proposals not yet started\n  - Top-level `work/*.md` = currently active work items\n","numLines":9,"startLine":1,"totalLines":9}},"sourceToolAssistantUUID":"9598e2ef-4606-49cd-986e-9415253c4a79"}
+{"parentUuid":"678beeff-0788-4a6e-a711-3802bffba8eb","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_017zBSoLmTCZWWh3ARsjYcpf","type":"message","role":"assistant","content":[{"type":"text","text":"Got it. One idea file — a convention for separating technical reference docs (`dev-docs/`) from work-tracking documents (`work/`) generated during Claude Code sessions. I notice you also have this captured as a guideline already at `~/.claude/guidelines/work-and-dev-docs.md`.\n\nIs there something you'd like to do with this — flesh it out further, try applying it to a project, or something else?"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":1,"cache_creation_input_tokens":224,"cache_read_input_tokens":27114,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":224},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFHAJJEK19ECuCBzwY8","type":"assistant","uuid":"3220c04b-b0dc-48b5-845b-3c1c10f6a684","timestamp":"2026-02-16T18:48:03.229Z"}
+{"parentUuid":"3220c04b-b0dc-48b5-845b-3c1c10f6a684","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"12cfda0b-113a-446d-86d8-a90bf2a03c43","toolUseID":"12cfda0b-113a-446d-86d8-a90bf2a03c43","timestamp":"2026-02-16T18:48:03.266Z","uuid":"2ceae58c-1a09-4e84-bafa-d08ab9c31a98"}
+{"parentUuid":"2ceae58c-1a09-4e84-bafa-d08ab9c31a98","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T18:48:03.384Z","uuid":"eb84e3ee-fc54-4fe4-ad76-badc5ebb4671","toolUseID":"12cfda0b-113a-446d-86d8-a90bf2a03c43"}
+{"type":"file-history-snapshot","messageId":"5270777a-1975-4e8a-9cad-b36280ae0ec5","snapshot":{"messageId":"5270777a-1975-4e8a-9cad-b36280ae0ec5","trackedFileBackups":{},"timestamp":"2026-02-16T18:49:30.598Z"},"isSnapshotUpdate":false}
+{"parentUuid":"eb84e3ee-fc54-4fe4-ad76-badc5ebb4671","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"I very much like this idea, and I used it already with some success in the clmail project. Can you list, in 5 bullet points, what are the strengths of this proposal?"},"uuid":"5270777a-1975-4e8a-9cad-b36280ae0ec5","timestamp":"2026-02-16T18:49:30.468Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"5270777a-1975-4e8a-9cad-b36280ae0ec5","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01Ed6t7MQDew7A8RnvCXfoQx","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":92,"cache_read_input_tokens":27433,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":92},"output_tokens":14,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFPwhhfPQiWyfNxFoMd","type":"assistant","uuid":"d94c9c9b-9e26-4cfe-a21d-d993784adc8b","timestamp":"2026-02-16T18:49:33.473Z"}
+{"parentUuid":"d94c9c9b-9e26-4cfe-a21d-d993784adc8b","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01Ed6t7MQDew7A8RnvCXfoQx","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user wants me to articulate the strengths of the dev-docs/ vs work/ directory convention. Let me think about this based on the content and my understanding of how Claude Code sessions generate markdown documents.","signature":"EoEDCkYICxgCKkBR8IMN1Ju63dzPbvou2lEf0kFZjiX8um4ZW+aP2b/C8dXsI0v3ytTrZzDMfIjXaVQVnjSpSWt4ON5eLnJXdW93EgyJC8a0bHsmd4flgKUaDAGRw6+bXvdqWJnJHiIw/H8xErRsRZOkLSboApw95IxU69nGQqny/KiFfpHuEbS0JzhOyBf6Nfwni16kq6HTKugBc4PztHoihwTRlKdeq3JQOIkag+DNdntwFsafms8UJxWffPbLd0/9UA67G0nBuLccFEOUhdRKlzxUra8zi0xOOPDslz8W+0ff0k8Gpj7mU/kx4/kPDwGJRS9vI3p8DY2FDZujBdsIs2BySL2LM8fBl+7e371bC6cpi9PKzOVQ0fywVkNBMhkdiFFCytRho5ctaNLMFhFRmhYgbZY+HdOl/uQZs2hZWCPKgt8Pvn3EvQNGmblUMe/eqnTO/VldO+4Rcm2Crni6wp4PnZ1nAewIEJUpQlWO2OZS8cjT11G0HWBACVR6QQ0NMhgB"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":92,"cache_read_input_tokens":27433,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":92},"output_tokens":14,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFPwhhfPQiWyfNxFoMd","type":"assistant","uuid":"ff14c7f7-a74e-4e29-a713-735009d15c04","timestamp":"2026-02-16T18:49:34.397Z"}
+{"parentUuid":"ff14c7f7-a74e-4e29-a713-735009d15c04","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01Ed6t7MQDew7A8RnvCXfoQx","type":"message","role":"assistant","content":[{"type":"text","text":"- **Clear separation of concerns** — Technical reference (how things work) never gets mixed up with operational artifacts (what needs doing), making both easier to find and maintain.\n\n- **Natural lifecycle management** — The `work/` subdirectories (`archive/`, `backlog/`, top-level active) map directly to a task's lifecycle, so moving a file between folders is a lightweight status update that's visible in the file tree.\n\n- **Reduced context pollution** — When Claude Code loads project context, it can target `dev-docs/` for understanding architecture or `work/` for picking up tasks, rather than sifting through a flat pile of mixed-purpose markdown.\n\n- **Scales without clutter** — Projects accumulate many work documents over time; the convention keeps the root clean and avoids the common pattern of a single `docs/` folder that becomes an unsorted dumping ground.\n\n- **Low adoption cost** — It's just directories and a naming convention, no tooling required. Any project can adopt it incrementally, and it's intuitive enough that both humans and AI agents understand the intent immediately."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":92,"cache_read_input_tokens":27433,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":92},"output_tokens":14,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFPwhhfPQiWyfNxFoMd","type":"assistant","uuid":"7bb81bd8-ec67-4ed5-b9c1-19f2d2117f1d","timestamp":"2026-02-16T18:49:42.439Z"}
+{"parentUuid":"7bb81bd8-ec67-4ed5-b9c1-19f2d2117f1d","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"c9fab21a-2604-4f78-9e5e-a0127b99e65c","toolUseID":"c9fab21a-2604-4f78-9e5e-a0127b99e65c","timestamp":"2026-02-16T18:49:42.494Z","uuid":"d4335cb6-30a0-413d-b389-760f4892fa57"}
+{"parentUuid":"d4335cb6-30a0-413d-b389-760f4892fa57","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T18:49:42.608Z","uuid":"2679083d-ddd4-4452-995e-7a19aa2317d8","toolUseID":"c9fab21a-2604-4f78-9e5e-a0127b99e65c"}
+{"type":"file-history-snapshot","messageId":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","snapshot":{"messageId":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","trackedFileBackups":{},"timestamp":"2026-02-16T18:51:05.354Z"},"isSnapshotUpdate":false}
+{"parentUuid":"2679083d-ddd4-4452-995e-7a19aa2317d8","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"OK, so, to be fair, maybe also list 5 weak points, risks, or caveats."},"uuid":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","timestamp":"2026-02-16T18:51:05.217Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01CAgUXyPMrcZLbyeRW4W25K","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":27828,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFWvSFXTYH5aDVj9nxw","type":"assistant","uuid":"c4b71b36-5d0c-44c0-be6f-6d70ae2a961d","timestamp":"2026-02-16T18:51:08.316Z"}
+{"parentUuid":"c4b71b36-5d0c-44c0-be6f-6d70ae2a961d","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01CAgUXyPMrcZLbyeRW4W25K","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user wants a balanced view - let me think critically about the weaknesses, risks, and caveats of this convention.","signature":"Ep4CCkYICxgCKkAw1rYNUsyvBcNWUTXb8kn+rjqQPaRtitvrRxP2zQxl8v6P/3gzu9DpRyO0w0TdmAyn84jhUNkakgx58k3GWPJvEgwXCftxzWYCbp5j5ZUaDCakTff8HkK2O+O/RSIw42dw9ktrqWUUkhI3/IIZQjM6vjJS5PRh6iREPmBmcKbtAc/hSMBUL3zk3yHA2PHzKoUBc0POGxMc4yqK3kAn/C+5CPBm6dgDCKQlUM/a1oe8Xmv5dL2bxIFdgEAZhyi+eYNnaMzlIOmRwJ1JJjQq8SeQ5XHm6m6rxuecp/38FDqfTjtTIL7epMJRaNTaq2pafR3zX5L5NyDCIr+VU7MVhatFNZJQH698x8oy1e36rfHM2xuT0mISRBgB"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":27828,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFWvSFXTYH5aDVj9nxw","type":"assistant","uuid":"bce6d847-8f80-406e-953a-413a065ea941","timestamp":"2026-02-16T18:51:08.810Z"}
+{"parentUuid":"bce6d847-8f80-406e-953a-413a065ea941","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01CAgUXyPMrcZLbyeRW4W25K","type":"message","role":"assistant","content":[{"type":"text","text":"- **Boundary is often blurry** — Some documents are both reference and work artifact (e.g. an ADR, a design doc that becomes permanent architecture documentation). Deciding where they live requires judgment calls that the convention doesn't resolve.\n\n- **Drift without discipline** — Nothing enforces the convention. Active work items can linger at `work/` top-level long after they're done, `backlog/` can become a graveyard nobody reviews, and `archive/` can accumulate indefinitely without cleanup.\n\n- **Assumes a single workflow** — The `backlog/future/archive` structure bakes in one way of tracking work. Teams already using issue trackers, project boards, or other systems may find it redundant or conflicting — two sources of truth for task status.\n\n- **AI agent discoverability isn't free** — Claude Code won't automatically know that `dev-docs/` is for context and `work/` is for tasks unless told via CLAUDE.md or similar instructions. The convention only reduces context pollution if it's explicitly wired into the agent's workflow.\n\n- **Overhead for small projects** — For a project with three markdown files total, splitting them across a directory hierarchy adds structure without proportional benefit. The convention pays off at scale but can feel like premature organization early on."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":27828,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFWvSFXTYH5aDVj9nxw","type":"assistant","uuid":"f4dbd8f0-5b95-47ce-bfd7-44d7fa838e60","timestamp":"2026-02-16T18:51:17.406Z"}
+{"parentUuid":"f4dbd8f0-5b95-47ce-bfd7-44d7fa838e60","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"d65a641c-8317-453e-80ce-9eac26faa597","toolUseID":"d65a641c-8317-453e-80ce-9eac26faa597","timestamp":"2026-02-16T18:51:17.542Z","uuid":"db0d804c-4f4b-43e7-b6d9-d9bf151cef34"}
+{"parentUuid":"db0d804c-4f4b-43e7-b6d9-d9bf151cef34","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T18:51:17.655Z","uuid":"75f4bb33-40d3-435e-85f3-4856c673d8c0","toolUseID":"d65a641c-8317-453e-80ce-9eac26faa597"}
+{"type":"file-history-snapshot","messageId":"a17b2091-fd44-4c3e-aaeb-69196456ab73","snapshot":{"messageId":"a17b2091-fd44-4c3e-aaeb-69196456ab73","trackedFileBackups":{},"timestamp":"2026-02-16T18:53:15.963Z"},"isSnapshotUpdate":false}
+{"parentUuid":"75f4bb33-40d3-435e-85f3-4856c673d8c0","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"Fair enough. Can you write a balanced opinion on this approach? Keep it same overall length as the pros or cons."},"uuid":"a17b2091-fd44-4c3e-aaeb-69196456ab73","timestamp":"2026-02-16T18:53:15.830Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"a17b2091-fd44-4c3e-aaeb-69196456ab73","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01CQrPP8F6qBuymMP8Xxhnrm","type":"message","role":"assistant","content":[{"type":"text","text":"\n\nThe convention's real value is that it introduces **intentionality** about where generated documents end up. Without it, Claude Code sessions naturally produce a mix of plans, analyses, and reference docs that all land in the same place — and entropy wins fast. Having two top-level buckets forces a minimal but meaningful classification at creation time.\n\nThat said, it's best understood as a **starting point, not a system**. It works well when one person (or one agent) is both the author and consumer of these documents. The moment you need shared task tracking or formal documentation, purpose-built tools will outgrow the convention — and that's fine. The directory structure should be a lightweight scaffold you're willing to reshape, not a process to defend.\n\nThe strongest argument for it may be pragmatic: **it's better than nothing, and it costs almost nothing to try.** If it stops being useful, you just move files around."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":28236,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCFgYj4bmq8CMrHKHDHZ","type":"assistant","uuid":"95b483e6-74a7-4c50-b3c8-705944edf7ae","timestamp":"2026-02-16T18:53:24.117Z"}
+{"parentUuid":"95b483e6-74a7-4c50-b3c8-705944edf7ae","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"154eda8c-0e51-4d0b-b3b5-f4f46c86df5c","toolUseID":"154eda8c-0e51-4d0b-b3b5-f4f46c86df5c","timestamp":"2026-02-16T18:53:24.178Z","uuid":"31128ff1-2e5c-4254-8aae-c1b499d5d6b7"}
+{"parentUuid":"31128ff1-2e5c-4254-8aae-c1b499d5d6b7","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T18:53:24.295Z","uuid":"2f4668dd-c177-455f-81c1-caa947d43e73","toolUseID":"154eda8c-0e51-4d0b-b3b5-f4f46c86df5c"}
+{"type":"file-history-snapshot","messageId":"c5464fba-3497-4db8-926a-870e58d47f53","snapshot":{"messageId":"c5464fba-3497-4db8-926a-870e58d47f53","trackedFileBackups":{},"timestamp":"2026-02-16T18:55:26.977Z"},"isSnapshotUpdate":false}
+{"type":"file-history-snapshot","messageId":"9edc38e6-0ac0-42c0-b911-e24611af2a5b","snapshot":{"messageId":"9edc38e6-0ac0-42c0-b911-e24611af2a5b","trackedFileBackups":{},"timestamp":"2026-02-16T19:24:30.882Z"},"isSnapshotUpdate":false}
+{"parentUuid":"eb84e3ee-fc54-4fe4-ad76-badc5ebb4671","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"I actually don't like much this idea, and I somewhat struggled with it in the clmail project. Can you list, in 5 bullet points, what are the weak points, risks, or caveats of this proposal?"},"uuid":"9edc38e6-0ac0-42c0-b911-e24611af2a5b","timestamp":"2026-02-16T19:24:30.747Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"9edc38e6-0ac0-42c0-b911-e24611af2a5b","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01F9RwXxPTymSnjvME4X7w8K","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":2750,"cache_read_input_tokens":24675,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":2750},"output_tokens":9,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJ4kzMHiqbRgiFGuZQh","type":"assistant","uuid":"251d3443-8595-4aa6-af60-fce5b87206d7","timestamp":"2026-02-16T19:24:33.074Z"}
+{"parentUuid":"251d3443-8595-4aa6-af60-fce5b87206d7","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01F9RwXxPTymSnjvME4X7w8K","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user wants me to critique the `dev-docs/` vs `work/` convention. Let me think about the genuine weaknesses of this approach.","signature":"EqkCCkYICxgCKkDVERi7ZM2ho+dkojPTq7lFrSsHEtlxUZ5VxpvKyxbkiDy+qPD76AGPC9ehwMK5frPOjxFWRn7x0jljTdLbSM/tEgzegfL9wOZjkg6NRnwaDMPBg8xmLuXd7XYTDiIwFCH3A2cr9digHxdB8JpvNQgQKgKCremsI5jbLkks67ls4NQ4OoWXETAobz1IfuA1KpABQXEzlukJEcDklTJIc18G9gUm5aUDGFmAuVQH8ewNiJGoqmlLEurCw6C2cNoBDndXQm+o+8Po5epiziywnGuRRO0IyZfmUcOt/beFqjCOhNTKVqiub1ERw8Kl+YR/XhibkbE6UVrMFUrBSzgRbkwzjcksPBbxgznOaFqxYp3rKr84qAA2SPTN6w/eTx4N78khGAE="}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":2750,"cache_read_input_tokens":24675,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":2750},"output_tokens":9,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJ4kzMHiqbRgiFGuZQh","type":"assistant","uuid":"e240c16e-c51b-4923-a649-7d3f14ab10ca","timestamp":"2026-02-16T19:24:33.901Z"}
+{"parentUuid":"e240c16e-c51b-4923-a649-7d3f14ab10ca","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01F9RwXxPTymSnjvME4X7w8K","type":"message","role":"assistant","content":[{"type":"text","text":"Here are 5 weak points of the `dev-docs/` vs `work/` convention:\n\n- **Blurry boundary between \"reference\" and \"work\"**: A design doc starts as a proposal (`work/future/`), becomes active work (`work/`), then after implementation it's really technical reference (`dev-docs/`). The same document migrates across categories over its lifetime, creating churn and broken links.\n\n- **Overhead of constant triage**: Deciding where a document belongs — and when to move it — adds friction. In practice, files end up in the wrong folder or never get moved, making the structure misleading rather than helpful.\n\n- **Fragmented context**: Understanding a feature often requires both its technical reference *and* its work history (decisions made, alternatives rejected). Splitting them across two trees forces you to cross-reference constantly instead of having everything about a topic in one place.\n\n- **Doesn't match how Claude Code sessions actually produce docs**: A session generates a mix of notes, plans, and technical writeups organically. Forcing them into a rigid two-tree structure mid-session interrupts flow, and retroactively sorting them is tedious busywork.\n\n- **Scales poorly with multiple contributors/actors**: When several actors (alice, bob, monk) generate documents concurrently, the `work/` subdirectory hierarchy (`archive/`, `backlog/`, `future/`, active) becomes a coordination bottleneck — everyone needs to agree on status transitions, and conflicts arise over what's \"active\" vs \"backlog\" vs \"done.\""}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":2750,"cache_read_input_tokens":24675,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":2750},"output_tokens":9,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJ4kzMHiqbRgiFGuZQh","type":"assistant","uuid":"469c1506-89fc-47ae-934a-b6f569fd575e","timestamp":"2026-02-16T19:24:43.794Z"}
+{"parentUuid":"469c1506-89fc-47ae-934a-b6f569fd575e","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"d515dc57-67c8-43e0-b7aa-f04605a73404","toolUseID":"d515dc57-67c8-43e0-b7aa-f04605a73404","timestamp":"2026-02-16T19:24:43.860Z","uuid":"3a876c2c-2b70-41bf-87c4-5964f7018bc5"}
+{"parentUuid":"3a876c2c-2b70-41bf-87c4-5964f7018bc5","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T19:24:43.997Z","uuid":"052223b6-f8d1-473c-bff0-f58c5a7688ff","toolUseID":"d515dc57-67c8-43e0-b7aa-f04605a73404"}
+{"type":"file-history-snapshot","messageId":"ad1515d0-c65d-45df-bfde-32d931b446c1","snapshot":{"messageId":"ad1515d0-c65d-45df-bfde-32d931b446c1","trackedFileBackups":{},"timestamp":"2026-02-16T19:25:46.307Z"},"isSnapshotUpdate":false}
+{"parentUuid":"052223b6-f8d1-473c-bff0-f58c5a7688ff","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"Ok, so, to be fair, maybe also list 5 strengths of this proposal."},"uuid":"ad1515d0-c65d-45df-bfde-32d931b446c1","timestamp":"2026-02-16T19:25:46.151Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"ad1515d0-c65d-45df-bfde-32d931b446c1","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01S5L7Tj3zt7QYuhzqtQj2qJ","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":71,"cache_read_input_tokens":27822,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":71},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJAKV6mtqnWmS6AGbxk","type":"assistant","uuid":"dc365667-a9d3-4a77-9920-8d32c633fa45","timestamp":"2026-02-16T19:25:48.673Z"}
+{"parentUuid":"dc365667-a9d3-4a77-9920-8d32c633fa45","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01S5L7Tj3zt7QYuhzqtQj2qJ","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user wants a balanced view - 5 strengths of the dev-docs/ vs work/ convention.","signature":"EvoBCkYICxgCKkBeUlcoKurASKiMGRmAlMb4pxjWiWln/68cSxd87BpsmhKc6x2s1Ny1W/Nhbp+oScx6m/QtK7wpgQSMqAfjDuFHEgwoPiHvGgnReerXPyQaDC15z1Bd/peDgFv9GyIwo3Q534dfNXxJRM0FQ/L12EQSSRTexTkRLiq5IBApnd1anvFUGoUdiUFeb2Kp8czeKmIJdtMYjjKJVcOZdYJh7/3Ohk22XuS46ErPnpKqqruI2EBRaLbtoEhxabzrNu1H2y7j7ZQ9fk0WX8GsR6JkzfZ0eQfCzKsLz2Ce4M8Y5v1crrM7m+JtFVtNzyiBwJq3phwW1RgB"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":71,"cache_read_input_tokens":27822,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":71},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJAKV6mtqnWmS6AGbxk","type":"assistant","uuid":"f8d26873-0e14-4c9e-b970-0e33fa2a0914","timestamp":"2026-02-16T19:25:49.097Z"}
+{"parentUuid":"f8d26873-0e14-4c9e-b970-0e33fa2a0914","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01S5L7Tj3zt7QYuhzqtQj2qJ","type":"message","role":"assistant","content":[{"type":"text","text":"- **Clear intent signal**: The split immediately tells you whether a document is meant to be durable knowledge (`dev-docs/`) or transient/evolving (`work/`). You know at a glance what to trust as current truth vs. what's in flux.\n\n- **Keeps reference docs clean**: Without separation, technical reference gets buried under plans, drafts, and abandoned proposals. A dedicated `dev-docs/` stays focused and navigable — you don't wade through old work items to find the architecture overview.\n\n- **Natural archival path**: The `work/` subdirectories (`backlog/`, `archive/`, `future/`) give completed or deferred items a place to go rather than cluttering the project root or getting deleted. Nothing is lost, but nothing is in the way either.\n\n- **Supports selective `.gitignore` or access control**: You might want `work/` to be gitignored (personal scratch space) while `dev-docs/` is committed. Or vice versa — commit work items for team visibility but keep dev-docs generated locally. The two-tree split makes this trivial.\n\n- **Reduces cognitive load for newcomers**: Someone joining the project can ignore `work/` entirely and focus on `dev-docs/` to understand the system. The convention acts as a filter — \"read this, skip that\" — without needing a README to explain which files matter."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":71,"cache_read_input_tokens":27822,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":71},"output_tokens":12,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJAKV6mtqnWmS6AGbxk","type":"assistant","uuid":"1691f02e-4cc2-432c-945b-855027323e8f","timestamp":"2026-02-16T19:25:58.443Z"}
+{"parentUuid":"1691f02e-4cc2-432c-945b-855027323e8f","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"a0e1e62c-2a4f-462d-a0b4-7266be4bc00d","toolUseID":"a0e1e62c-2a4f-462d-a0b4-7266be4bc00d","timestamp":"2026-02-16T19:25:58.497Z","uuid":"6e1cea3c-b5b2-4cac-9e18-4a636e980b62"}
+{"parentUuid":"6e1cea3c-b5b2-4cac-9e18-4a636e980b62","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T19:25:58.633Z","uuid":"817c0a12-f667-4933-aa2d-c242772ea450","toolUseID":"a0e1e62c-2a4f-462d-a0b4-7266be4bc00d"}
+{"type":"file-history-snapshot","messageId":"d3658335-ec7f-42ce-9d87-747cda79e881","snapshot":{"messageId":"d3658335-ec7f-42ce-9d87-747cda79e881","trackedFileBackups":{},"timestamp":"2026-02-16T19:27:07.768Z"},"isSnapshotUpdate":false}
+{"parentUuid":"817c0a12-f667-4933-aa2d-c242772ea450","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"Fair enough. Can you write a balanced opinion on this approach? Keep it same overall length as the pros or cons."},"uuid":"d3658335-ec7f-42ce-9d87-747cda79e881","timestamp":"2026-02-16T19:27:07.599Z","thinkingMetadata":{"maxThinkingTokens":31999},"todos":[],"permissionMode":"default"}
+{"parentUuid":"d3658335-ec7f-42ce-9d87-747cda79e881","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01EfSS5axx8kM8Dm5gmuojYA","type":"message","role":"assistant","content":[{"type":"text","text":"\n\n"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":28242,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJGKiA9jhxgYime6865","type":"assistant","uuid":"18037c5a-b000-42c9-a689-06fa14b1300d","timestamp":"2026-02-16T19:27:10.014Z"}
+{"parentUuid":"18037c5a-b000-42c9-a689-06fa14b1300d","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01EfSS5axx8kM8Dm5gmuojYA","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"The user wants a balanced opinion, roughly the same length as the 5-bullet lists I gave before.","signature":"EocCCkYICxgCKkD2KAZnGRpSMriYO/XMg46krEGj/4P9wsgWcYNaSdwQu+MJiBZl1IQbXAboBnOJslWKNy/nFv21O/6GO7ZntnPjEgywgmlHojpEQRiyHUgaDEdnZuktHHjniLPQvyIwDaAJ8gcGK0NHIoopbCMuFqpAP4aYWPaY/jjMVMKlAE2lGTLKHcdrGGtFqj3uP+VMKm9A9ARVN/cg51mj8X5jhwljkm344vNxTslAsBOyxGQQGfFHqpRwMsDYmWr9LAFu9ARpMgLoZc9f2k2RuE10lN04LWcys6/YQv9IWhdGVHkQPjSU5pWl38Pk9wnpGNJUGxlc3+Ipx4lVweF6xGqtIgcYAQ=="}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":28242,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJGKiA9jhxgYime6865","type":"assistant","uuid":"5ce6fa4b-0530-4d85-af03-ba2c70445306","timestamp":"2026-02-16T19:27:10.579Z"}
+{"parentUuid":"5ce6fa4b-0530-4d85-af03-ba2c70445306","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","message":{"model":"claude-opus-4-6","id":"msg_01EfSS5axx8kM8Dm5gmuojYA","type":"message","role":"assistant","content":[{"type":"text","text":"The `dev-docs/` vs `work/` split works best when a project has stabilized enough that the distinction between \"reference\" and \"in-progress\" is genuine. In that context, it reduces noise and gives newcomers a clear entry point.\n\nHowever, the convention fights against the natural lifecycle of documents, which tend to start as work items and graduate into reference. The more actively a project evolves — especially with AI-assisted sessions generating docs organically — the more the boundary feels artificial and the maintenance cost outweighs the clarity gained.\n\nA pragmatic middle ground: use the split lightly as a *naming convention* (e.g. prefix or tag) rather than a *directory structure*. This preserves the intent signal without forcing files to physically move between folders as their status changes. The rigid subdirectory hierarchy (`archive/`, `backlog/`, `future/`) is where the approach most often breaks down in practice — it demands discipline that rarely survives contact with real workflows.\n\nIn short: the *idea* is sound, but the *implementation as a directory tree* over-commits to a structure that real projects tend to outgrow or ignore."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":3,"cache_creation_input_tokens":75,"cache_read_input_tokens":28242,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":75},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYCJGKiA9jhxgYime6865","type":"assistant","uuid":"8cb01e66-3ee6-4912-9e07-bd0d98771d4d","timestamp":"2026-02-16T19:27:18.808Z"}
+{"parentUuid":"8cb01e66-3ee6-4912-9e07-bd0d98771d4d","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"progress","data":{"type":"hook_progress","hookEvent":"Stop","hookName":"Stop","command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"},"parentToolUseID":"07ed7399-e055-4260-a8e3-c0e6299b29cb","toolUseID":"07ed7399-e055-4260-a8e3-c0e6299b29cb","timestamp":"2026-02-16T19:27:18.848Z","uuid":"a2a708f7-fdab-40a9-97a2-bee0b30e16fe"}
+{"parentUuid":"a2a708f7-fdab-40a9-97a2-bee0b30e16fe","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"system","subtype":"stop_hook_summary","hookCount":1,"hookInfos":[{"command":"\"${CLAUDE_PLUGIN_ROOT}/scripts/clmail.cmd\" actor idle"}],"hookErrors":[],"preventedContinuation":false,"stopReason":"","hasOutput":true,"level":"suggestion","timestamp":"2026-02-16T19:27:18.988Z","uuid":"6d6613f0-b642-40f2-ae08-694c8f822957","toolUseID":"07ed7399-e055-4260-a8e3-c0e6299b29cb"}
+{"type":"file-history-snapshot","messageId":"cba5bd18-a49a-46a6-9b1d-81491229c2c2","snapshot":{"messageId":"cba5bd18-a49a-46a6-9b1d-81491229c2c2","trackedFileBackups":{},"timestamp":"2026-02-17T00:13:55.285Z"},"isSnapshotUpdate":false}
+{"parentUuid":"6d6613f0-b642-40f2-ae08-694c8f822957","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>"},"isMeta":true,"uuid":"d008e68d-eb7f-42d3-8ed1-137c9eb25eb3","timestamp":"2026-02-17T00:13:55.281Z"}
+{"parentUuid":"d008e68d-eb7f-42d3-8ed1-137c9eb25eb3","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"<command-name>/exit</command-name>\n            <command-message>exit</command-message>\n            <command-args></command-args>"},"uuid":"cba5bd18-a49a-46a6-9b1d-81491229c2c2","timestamp":"2026-02-17T00:13:55.281Z"}
+{"parentUuid":"cba5bd18-a49a-46a6-9b1d-81491229c2c2","isSidechain":false,"userType":"external","cwd":"/home/user/project","sessionId":"03eb5929-52b3-4b13-ada3-b93ae35806b8","version":"2.1.42","gitBranch":"HEAD","slug":"zippy-wondering-wadler","type":"user","message":{"role":"user","content":"<local-command-stdout>See ya!</local-command-stdout>"},"uuid":"d107d4c0-ae71-4d3d-af3a-cf7a370bd21f","timestamp":"2026-02-17T00:13:55.281Z"}
diff --git a/test/test_data/real_projects/-experiments-ideas/a95fea4a-b88a-4e49-ac07-4cc323d8700c.jsonl b/test/test_data/real_projects/-experiments-ideas/a95fea4a-b88a-4e49-ac07-4cc323d8700c.jsonl
new file mode 100644
index 00000000..be1ff170
--- /dev/null
+++ b/test/test_data/real_projects/-experiments-ideas/a95fea4a-b88a-4e49-ac07-4cc323d8700c.jsonl
@@ -0,0 +1,4 @@
+{"type":"file-history-snapshot","messageId":"13f97369-4175-446a-bac8-0b7e2981d649","snapshot":{"messageId":"13f97369-4175-446a-bac8-0b7e2981d649","trackedFileBackups":{},"timestamp":"2026-02-16T18:47:50.736Z"},"isSnapshotUpdate":false}
+{"type":"file-history-snapshot","messageId":"5270777a-1975-4e8a-9cad-b36280ae0ec5","snapshot":{"messageId":"5270777a-1975-4e8a-9cad-b36280ae0ec5","trackedFileBackups":{},"timestamp":"2026-02-16T18:49:30.598Z"},"isSnapshotUpdate":false}
+{"type":"file-history-snapshot","messageId":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","snapshot":{"messageId":"12f81cce-ffa9-40d4-929e-0c2c6ad7c6c9","trackedFileBackups":{},"timestamp":"2026-02-16T18:51:05.354Z"},"isSnapshotUpdate":false}
+{"type":"file-history-snapshot","messageId":"a17b2091-fd44-4c3e-aaeb-69196456ab73","snapshot":{"messageId":"a17b2091-fd44-4c3e-aaeb-69196456ab73","trackedFileBackups":{},"timestamp":"2026-02-16T18:53:15.963Z"},"isSnapshotUpdate":false}
diff --git a/test/test_shallow_mode.py b/test/test_shallow_mode.py
new file mode 100644
index 00000000..485ea413
--- /dev/null
+++ b/test/test_shallow_mode.py
@@ -0,0 +1,824 @@
+#!/usr/bin/env python3
+"""Tests for --shallow rendering mode.
+
+Shallow mode filters out everything except user and assistant text messages:
+no tools, no thinking, no system messages.
+"""
+
+import json
+import shutil
+import uuid
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from claude_code_log.cli import main
+from claude_code_log.converter import convert_jsonl_to, load_transcript
+from claude_code_log.html.renderer import HtmlRenderer
+from claude_code_log.markdown.renderer import MarkdownRenderer
+from claude_code_log.models import (
+    AssistantTranscriptEntry,
+    SystemTranscriptEntry,
+    ThinkingContent,
+    ToolResultContent,
+    ToolUseContent,
+    UserTranscriptEntry,
+)
+from claude_code_log.renderer import _filter_shallow, generate_template_messages
+
+
+# -- Test data helpers --------------------------------------------------------
+
+
+def _user_entry(
+    text: str,
+    session_id: str = "sess-001",
+    timestamp: str = "2025-01-01T10:00:00Z",
+    extra_content: list | None = None,
+) -> dict:
+    content: list = [{"type": "text", "text": text}]
+    if extra_content:
+        content.extend(extra_content)
+    return {
+        "type": "user",
+        "timestamp": timestamp,
+        "sessionId": session_id,
+        "uuid": f"u-{uuid.uuid4().hex[:8]}",
+        "parentUuid": None,
+        "isSidechain": False,
+        "userType": "external",
+        "cwd": "/tmp",
+        "version": "1.0.0",
+        "message": {"role": "user", "content": content},
+    }
+
+
+def _assistant_entry(
+    text: str,
+    session_id: str = "sess-001",
+    timestamp: str = "2025-01-01T10:00:01Z",
+    extra_content: list | None = None,
+) -> dict:
+    content: list = [{"type": "text", "text": text}]
+    if extra_content:
+        content.extend(extra_content)
+    return {
+        "type": "assistant",
+        "timestamp": timestamp,
+        "sessionId": session_id,
+        "uuid": f"a-{uuid.uuid4().hex[:8]}",
+        "parentUuid": None,
+        "isSidechain": False,
+        "userType": "external",
+        "cwd": "/tmp",
+        "version": "1.0.0",
+        "message": {
+            "id": f"msg_{uuid.uuid4().hex[:16]}",
+            "type": "message",
+            "role": "assistant",
+            "model": "claude-sonnet-4-20250514",
+            "content": content,
+        },
+    }
+
+
+def _system_entry(
+    text: str,
+    session_id: str = "sess-001",
+    timestamp: str = "2025-01-01T10:00:02Z",
+) -> dict:
+    return {
+        "type": "system",
+        "timestamp": timestamp,
+        "sessionId": session_id,
+        "message": text,
+    }
+
+
+def _tool_use_item(name: str = "Bash", tool_id: str = "tool_001") -> dict:
+    return {
+        "type": "tool_use",
+        "id": tool_id,
+        "name": name,
+        "input": {"command": "echo hello"},
+    }
+
+
+def _tool_result_item(tool_id: str = "tool_001") -> dict:
+    return {
+        "type": "tool_result",
+        "tool_use_id": tool_id,
+        "content": "hello",
+        "is_error": False,
+    }
+
+
+def _thinking_item(text: str = "Let me think...") -> dict:
+    return {"type": "thinking", "thinking": text}
+
+
+def _write_jsonl(entries: list[dict], path: Path) -> Path:
+    path.write_text("\n".join(json.dumps(e) for e in entries) + "\n", encoding="utf-8")
+    return path
+
+
+# -- Unit tests for _filter_compact ------------------------------------------
+
+
+class TestFilterShallow:
+    """Test the _filter_compact function directly on parsed TranscriptEntry lists."""
+
+    def test_keeps_user_and_assistant_text(self, tmp_path):
+        """Plain user and assistant messages pass through."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry("Hi there!"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 2
+        assert isinstance(result[0], UserTranscriptEntry)
+        assert isinstance(result[1], AssistantTranscriptEntry)
+
+    def test_removes_system_entries(self, tmp_path):
+        """System entries are dropped entirely."""
+        entries = [
+            _user_entry("Hello"),
+            _system_entry("model changed"),
+            _assistant_entry("Hi"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 2
+        assert all(not isinstance(m, SystemTranscriptEntry) for m in result)
+
+    def test_strips_tool_use_from_assistant(self, tmp_path):
+        """Tool use items within assistant entries are stripped."""
+        entries = [
+            _user_entry("Do something"),
+            _assistant_entry(
+                "I'll run a command.",
+                extra_content=[_tool_use_item()],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 2
+        # Assistant entry should have text but no tool_use
+        assistant = result[1]
+        assert isinstance(assistant, AssistantTranscriptEntry)
+        for item in assistant.message.content:
+            assert not isinstance(item, ToolUseContent)
+
+    def test_strips_tool_result_from_user(self, tmp_path):
+        """Tool result items within user entries are stripped."""
+        entries = [
+            _user_entry(
+                "Here's the result",
+                extra_content=[_tool_result_item()],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 1
+        user = result[0]
+        assert isinstance(user, UserTranscriptEntry)
+        for item in user.message.content:
+            assert not isinstance(item, ToolResultContent)
+
+    def test_strips_thinking_from_assistant(self, tmp_path):
+        """Thinking items within assistant entries are stripped."""
+        entries = [
+            _assistant_entry(
+                "Here's my answer.",
+                extra_content=[_thinking_item()],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 1
+        assistant = result[0]
+        assert isinstance(assistant, AssistantTranscriptEntry)
+        for item in assistant.message.content:
+            assert not isinstance(item, ThinkingContent)
+
+    def test_drops_assistant_with_only_tool_use(self, tmp_path):
+        """Assistant entries with only tool_use (no text) are dropped entirely."""
+        # Build an entry where the only content is a tool_use (no text at all)
+        entry = _assistant_entry("placeholder", extra_content=[_tool_use_item()])
+        # Remove the text item, keeping only tool_use
+        entry["message"]["content"] = [_tool_use_item()]
+        messages = load_transcript(_write_jsonl([entry], tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 0
+
+    def test_removes_sidechain_entries(self, tmp_path):
+        """Sidechain (subagent) entries are dropped."""
+        sidechain_user = _user_entry("Subagent prompt")
+        sidechain_user["isSidechain"] = True
+        sidechain_assistant = _assistant_entry("Subagent reply")
+        sidechain_assistant["isSidechain"] = True
+        entries = [
+            _user_entry("Main prompt"),
+            sidechain_user,
+            sidechain_assistant,
+            _assistant_entry("Main reply"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        result = _filter_shallow(messages)
+        assert len(result) == 2
+        for m in result:
+            assert isinstance(m, (UserTranscriptEntry, AssistantTranscriptEntry))
+            assert not m.isSidechain
+
+    def test_does_not_mutate_original(self, tmp_path):
+        """Filtering creates copies, not mutations of the original."""
+        entries = [
+            _assistant_entry(
+                "Some text",
+                extra_content=[_tool_use_item()],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+        first = messages[0]
+        assert isinstance(first, AssistantTranscriptEntry)
+        original_content_count = len(first.message.content)
+        _filter_shallow(messages)
+        assert len(first.message.content) == original_content_count
+
+
+# -- Integration tests: generate_template_messages with shallow ---------------
+
+
+class TestShallowTemplateMessages:
+    """Test shallow mode through the full generate_template_messages pipeline."""
+
+    def test_shallow_removes_tool_messages(self, tmp_path):
+        """Shallow mode should not produce tool_use or tool_result TemplateMessages."""
+        entries = [
+            _user_entry("Run something"),
+            _assistant_entry(
+                "Running it.",
+                extra_content=[_tool_use_item()],
+                timestamp="2025-01-01T10:00:01Z",
+            ),
+            _user_entry(
+                "",
+                extra_content=[_tool_result_item()],
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("Done!", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, _, _ = generate_template_messages(messages, shallow=True)
+        # Flatten tree
+        all_types = set()
+        _collect_types(root_messages, all_types)
+        assert "tool_use" not in all_types
+        assert "tool_result" not in all_types
+        assert "user" in all_types
+        assert "assistant" in all_types
+
+    def test_shallow_removes_thinking_messages(self, tmp_path):
+        """Shallow mode should not produce thinking TemplateMessages."""
+        entries = [
+            _user_entry("Think about this"),
+            _assistant_entry(
+                "Here's my answer.",
+                extra_content=[_thinking_item("deep thoughts")],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, _, _ = generate_template_messages(messages, shallow=True)
+        all_types = set()
+        _collect_types(root_messages, all_types)
+        assert "thinking" not in all_types
+        assert "assistant" in all_types
+
+    def test_shallow_preserves_session_headers(self, tmp_path):
+        """Session headers are still generated in shallow mode."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry("Hi"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, session_nav, _ = generate_template_messages(
+            messages, shallow=True
+        )
+        assert len(root_messages) >= 1
+        assert root_messages[0].is_session_header
+        assert len(session_nav) >= 1
+
+    def test_shallow_removes_bash_messages(self, tmp_path):
+        """Shallow mode removes bash-input and bash-output messages."""
+        entries = [
+            _user_entry("Check the directory"),
+            # bash-input is parsed from user text containing <bash-input> tags
+            _user_entry(
+                "<bash-input>ls -la</bash-input>", timestamp="2025-01-01T10:00:01Z"
+            ),
+            _user_entry(
+                "<bash-stdout>total 42\ndrwxr-xr-x</bash-stdout>",
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("Here are the files.", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, _, _ = generate_template_messages(messages, shallow=True)
+        all_types = set()
+        _collect_types(root_messages, all_types)
+        assert "bash-input" not in all_types
+        assert "bash-output" not in all_types
+
+    def test_shallow_removes_slash_command_messages(self, tmp_path):
+        """Shallow mode removes slash command messages (e.g. /exit)."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry("Hi", timestamp="2025-01-01T10:00:01Z"),
+            # Slash command entries are user entries whose text matches /command
+            _user_entry("/exit", timestamp="2025-01-01T10:00:02Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, _, ctx = generate_template_messages(messages, shallow=True)
+        all_types = set()
+        _collect_types(root_messages, all_types)
+        # /exit should not appear as any type
+        for msg in ctx.messages:
+            assert "/exit" not in getattr(msg.content, "text", ""), (
+                f"Slash command '/exit' found in shallow output as {msg.type}"
+            )
+
+    def test_shallow_removes_sidechain_messages(self, tmp_path):
+        """Shallow mode removes sidechain (subagent) messages entirely."""
+        sidechain_user = _user_entry("Subagent task", timestamp="2025-01-01T10:00:01Z")
+        sidechain_user["isSidechain"] = True
+        sidechain_assistant = _assistant_entry(
+            "Subagent result", timestamp="2025-01-01T10:00:02Z"
+        )
+        sidechain_assistant["isSidechain"] = True
+        entries = [
+            _user_entry("Do a task"),
+            sidechain_user,
+            sidechain_assistant,
+            _assistant_entry("Task done.", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        root_messages, _, ctx = generate_template_messages(messages, shallow=True)
+        # No sidechain messages should remain
+        for msg in ctx.messages:
+            assert not msg.is_sidechain, f"Sidechain message found: {msg.type}"
+
+    def test_shallow_vs_normal_fewer_messages(self, tmp_path):
+        """Shallow mode produces fewer messages than normal mode."""
+        entries = [
+            _user_entry("Do something"),
+            _assistant_entry(
+                "OK, running bash.",
+                extra_content=[_tool_use_item()],
+                timestamp="2025-01-01T10:00:01Z",
+            ),
+            _user_entry(
+                "",
+                extra_content=[_tool_result_item()],
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("All done!", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        normal_roots, _, normal_ctx = generate_template_messages(
+            messages, shallow=False
+        )
+        shallow_roots, _, shallow_ctx = generate_template_messages(
+            messages, shallow=True
+        )
+
+        normal_count = len(normal_ctx.messages)
+        shallow_count = len(shallow_ctx.messages)
+        assert shallow_count < normal_count
+
+
+# -- HTML rendering tests -----------------------------------------------------
+
+
+class TestShallowHtmlRendering:
+    """Test shallow mode through the HTML renderer."""
+
+    def test_shallow_html_no_tool_divs(self, tmp_path):
+        """Shallow HTML should not contain tool_use or tool_result message divs."""
+        entries = [
+            _user_entry("Write a file"),
+            _assistant_entry(
+                "Creating the file.",
+                extra_content=[_tool_use_item("Write", "tool_w01")],
+                timestamp="2025-01-01T10:00:01Z",
+            ),
+            _user_entry(
+                "",
+                extra_content=[_tool_result_item("tool_w01")],
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("File created!", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        renderer = HtmlRenderer()
+        renderer.shallow = True
+        html = renderer.generate(messages, "Shallow Test")
+
+        assert "class='message tool_use" not in html
+        assert "class='message tool_result" not in html
+        assert "Write a file" in html
+        assert "Creating the file" in html
+        assert "File created!" in html
+
+    def test_shallow_html_no_thinking(self, tmp_path):
+        """Shallow HTML should not contain thinking message divs."""
+        entries = [
+            _user_entry("Explain something"),
+            _assistant_entry(
+                "Here's the explanation.",
+                extra_content=[_thinking_item("I need to consider...")],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        renderer = HtmlRenderer()
+        renderer.shallow = True
+        html = renderer.generate(messages, "Shallow Test")
+
+        assert "class='message thinking" not in html
+        assert "I need to consider" not in html
+        assert "Here's the explanation" in html
+
+
+# -- Markdown rendering tests --------------------------------------------------
+
+
+class TestShallowMarkdownRendering:
+    """Test shallow mode through the Markdown renderer."""
+
+    def test_shallow_markdown_no_tool_content(self, tmp_path):
+        """Shallow Markdown should not contain tool names or tool output."""
+        entries = [
+            _user_entry("Write a file"),
+            _assistant_entry(
+                "Creating the file.",
+                extra_content=[_tool_use_item("Write", "tool_w01")],
+                timestamp="2025-01-01T10:00:01Z",
+            ),
+            _user_entry(
+                "",
+                extra_content=[_tool_result_item("tool_w01")],
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("File created!", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        renderer = MarkdownRenderer()
+        renderer.shallow = True
+        md = renderer.generate(messages, "Shallow Test")
+
+        assert "Write a file" in md
+        assert "Creating the file" in md
+        assert "File created!" in md
+        # Tool-specific content should be absent
+        assert (
+            "Write" not in md.split("File created!")[0].split("Creating the file.")[1]
+        )
+
+    def test_shallow_markdown_no_thinking(self, tmp_path):
+        """Shallow Markdown should not contain thinking blocks."""
+        entries = [
+            _user_entry("Explain this"),
+            _assistant_entry(
+                "Here's the explanation.",
+                extra_content=[_thinking_item("Let me reason about this...")],
+            ),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        renderer = MarkdownRenderer()
+        renderer.shallow = True
+        md = renderer.generate(messages, "Shallow Test")
+
+        assert "Here's the explanation" in md
+        assert "Let me reason about this" not in md
+        assert "Thinking" not in md
+
+    def test_shallow_markdown_preserves_session_structure(self, tmp_path):
+        """Shallow Markdown preserves session headers."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry("Hi there"),
+        ]
+        messages = load_transcript(_write_jsonl(entries, tmp_path / "t.jsonl"))
+
+        renderer = MarkdownRenderer()
+        renderer.shallow = True
+        md = renderer.generate(messages, "Shallow Test")
+
+        assert "# Shallow Test" in md
+        assert "Hello" in md
+        assert "Hi there" in md
+
+    def test_shallow_markdown_on_real_projects(self, tmp_path):
+        """Shallow Markdown works on real project data."""
+        real_projects = Path(__file__).parent / "test_data" / "real_projects"
+        if not real_projects.exists():
+            pytest.skip("Real test projects not available")
+
+        # Pick first JSONL file
+        jsonl_files = []
+        for project_dir in real_projects.iterdir():
+            if project_dir.is_dir():
+                jsonl_files.extend(project_dir.glob("*.jsonl"))
+        if not jsonl_files:
+            pytest.skip("No JSONL files in real_projects")
+
+        renderer = MarkdownRenderer()
+        renderer.shallow = True
+        messages = load_transcript(jsonl_files[0])
+        md = renderer.generate(messages, "Shallow MD Test")
+        assert md
+        assert "# Shallow MD Test" in md
+
+
+# -- CLI tests ----------------------------------------------------------------
+
+
+class TestShallowCLI:
+    """Test the --shallow CLI flag."""
+
+    def test_shallow_flag_accepted(self, tmp_path):
+        """CLI accepts --shallow without error."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry("Hi there"),
+        ]
+        _write_jsonl(entries, tmp_path / "test.jsonl")
+        output_file = tmp_path / "output.html"
+
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [str(tmp_path / "test.jsonl"), "-o", str(output_file), "--shallow"],
+        )
+        assert result.exit_code == 0, f"CLI failed: {result.output}"
+        assert output_file.exists()
+
+    def test_shallow_flag_filters_tools(self, tmp_path):
+        """CLI --shallow produces HTML without tool messages."""
+        entries = [
+            _user_entry("Run a command"),
+            _assistant_entry(
+                "Running it.",
+                extra_content=[_tool_use_item("Bash", "tool_b01")],
+                timestamp="2025-01-01T10:00:01Z",
+            ),
+            _user_entry(
+                "",
+                extra_content=[_tool_result_item("tool_b01")],
+                timestamp="2025-01-01T10:00:02Z",
+            ),
+            _assistant_entry("Here's the output.", timestamp="2025-01-01T10:00:03Z"),
+        ]
+        _write_jsonl(entries, tmp_path / "test.jsonl")
+        output_file = tmp_path / "output.html"
+
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [str(tmp_path / "test.jsonl"), "-o", str(output_file), "--shallow"],
+        )
+        assert result.exit_code == 0, f"CLI failed: {result.output}"
+
+        html = output_file.read_text(encoding="utf-8")
+        assert "class='message tool_use" not in html
+        assert "class='message tool_result" not in html
+        assert "Run a command" in html
+        assert "Here's the output" in html
+
+    def test_shallow_with_markdown_format(self, tmp_path):
+        """CLI --shallow works with --format md too."""
+        entries = [
+            _user_entry("Hello"),
+            _assistant_entry(
+                "Hi",
+                extra_content=[_tool_use_item()],
+            ),
+        ]
+        _write_jsonl(entries, tmp_path / "test.jsonl")
+        output_file = tmp_path / "output.md"
+
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [
+                str(tmp_path / "test.jsonl"),
+                "-o",
+                str(output_file),
+                "--shallow",
+                "--format",
+                "md",
+            ],
+        )
+        assert result.exit_code == 0, f"CLI failed: {result.output}"
+        assert output_file.exists()
+        md = output_file.read_text(encoding="utf-8")
+        assert "Hello" in md
+        assert "Bash" not in md  # Tool name should not appear
+
+
+# -- Real project data tests --------------------------------------------------
+
+REAL_PROJECTS_DIR = Path(__file__).parent / "test_data" / "real_projects"
+
+
+@pytest.fixture(scope="module")
+def real_projects_path() -> Path:
+    if not REAL_PROJECTS_DIR.exists():
+        pytest.skip("Real test projects not available")
+    return REAL_PROJECTS_DIR
+
+
+class TestShallowRealProjects:
+    """Test shallow mode against real project data from test_data/real_projects/."""
+
+    def _get_project_jsonl_files(self, projects_path: Path) -> list[Path]:
+        """Get all JSONL files from real projects (top-level only, no subagents)."""
+        files = []
+        for project_dir in sorted(projects_path.iterdir()):
+            if project_dir.is_dir():
+                for f in project_dir.glob("*.jsonl"):
+                    files.append(f)
+        return files
+
+    def test_shallow_produces_valid_html(self, real_projects_path):
+        """Shallow mode generates valid HTML for every real project file."""
+        files = self._get_project_jsonl_files(real_projects_path)
+        assert files, "No JSONL files found in real_projects"
+
+        renderer = HtmlRenderer()
+        renderer.shallow = True
+
+        for jsonl_file in files:
+            messages = load_transcript(jsonl_file)
+            html = renderer.generate(messages, f"Shallow: {jsonl_file.name}")
+            assert html, f"Empty HTML for {jsonl_file.name}"
+            assert "<!DOCTYPE html>" in html
+
+    def test_shallow_has_no_excluded_messages(self, real_projects_path):
+        """Shallow HTML from real projects contains no tool, thinking, bash, or sidechain divs."""
+        files = self._get_project_jsonl_files(real_projects_path)
+
+        renderer = HtmlRenderer()
+        renderer.shallow = True
+
+        excluded_patterns = [
+            "class='message tool_use",
+            "class='message tool_result",
+            "class='message thinking",
+            "class='message bash-input",
+            "class='message bash-output",
+            "class='message user-slash-command",
+            "class='message command-output",
+            "class='message compacted-summary",
+        ]
+
+        for jsonl_file in files:
+            messages = load_transcript(jsonl_file)
+            html = renderer.generate(messages, "Shallow Test")
+            for pattern in excluded_patterns:
+                count = html.count(pattern)
+                msg_type = pattern.split("class='message ")[1]
+                assert count == 0, (
+                    f"{jsonl_file.name}: found {count} {msg_type} messages"
+                )
+
+    def test_shallow_fewer_messages_than_normal(self, real_projects_path):
+        """Shallow mode produces strictly fewer messages for projects with tools."""
+        files = self._get_project_jsonl_files(real_projects_path)
+
+        for jsonl_file in files:
+            messages = load_transcript(jsonl_file)
+            _, _, normal_ctx = generate_template_messages(messages, shallow=False)
+            _, _, shallow_ctx = generate_template_messages(messages, shallow=True)
+
+            normal_count = len(normal_ctx.messages)
+            shallow_count = len(shallow_ctx.messages)
+
+            # Real projects typically have many tool calls, so shallow should
+            # have fewer messages. Some tiny projects might only have text.
+            assert shallow_count <= normal_count, (
+                f"{jsonl_file.name}: shallow ({shallow_count}) > normal ({normal_count})"
+            )
+
+    def test_shallow_preserves_user_and_assistant(self, real_projects_path):
+        """Shallow mode keeps user and assistant messages from real projects."""
+        files = self._get_project_jsonl_files(real_projects_path)
+
+        for jsonl_file in files:
+            messages = load_transcript(jsonl_file)
+            root_messages, _, _ = generate_template_messages(messages, shallow=True)
+            all_types = set()
+            _collect_types(root_messages, all_types)
+
+            # Should only have user/assistant text types (plus session headers)
+            non_header_types = all_types - {
+                "session-header",
+                "session_header",
+            }
+            allowed = {
+                "user",
+                "assistant",
+                "user-steering",
+                "user-memory",
+            }
+            unexpected = non_header_types - allowed
+            assert not unexpected, (
+                f"{jsonl_file.name}: unexpected types in shallow: {unexpected}"
+            )
+
+    def test_shallow_directory_mode(self, real_projects_path, tmp_path):
+        """Shallow mode works on a directory of JSONL files."""
+        # Copy a project to tmp for isolated testing
+        project_dirs = [d for d in real_projects_path.iterdir() if d.is_dir()]
+        if not project_dirs:
+            pytest.skip("No project dirs in real_projects")
+
+        source = project_dirs[0]
+        dest = tmp_path / source.name
+        shutil.copytree(source, dest)
+
+        output = convert_jsonl_to(
+            "html",
+            dest,
+            use_cache=False,
+            generate_individual_sessions=False,
+            silent=True,
+            shallow=True,
+        )
+        html = output.read_text(encoding="utf-8")
+        assert "<!DOCTYPE html>" in html
+        assert "class='message tool_use" not in html
+        assert "class='message tool_result" not in html
+
+
+# -- Test data file tests (representative_messages.jsonl) ----------------------
+
+
+class TestShallowTestData:
+    """Test shallow mode on the bundled test data files."""
+
+    @pytest.fixture
+    def test_data_dir(self) -> Path:
+        return Path(__file__).parent / "test_data"
+
+    def test_shallow_representative_messages(self, test_data_dir):
+        """Shallow mode on representative_messages.jsonl removes tools."""
+        test_file = test_data_dir / "representative_messages.jsonl"
+        messages = load_transcript(test_file)
+
+        renderer = HtmlRenderer()
+        renderer.shallow = True
+        html = renderer.generate(messages, "Shallow Representative")
+
+        # Should have user and assistant content
+        assert "class='message user" in html
+        assert "class='message assistant" in html
+        # Should not have tool content
+        assert "class='message tool_use" not in html
+        assert "class='message tool_result" not in html
+
+    def test_shallow_sidechain(self, test_data_dir):
+        """Shallow mode on sidechain data removes tool messages."""
+        test_file = test_data_dir / "sidechain.jsonl"
+        if not test_file.exists():
+            pytest.skip("sidechain.jsonl not available")
+        messages = load_transcript(test_file)
+
+        root_messages, _, _ = generate_template_messages(messages, shallow=True)
+        all_types = set()
+        _collect_types(root_messages, all_types)
+        assert "tool_use" not in all_types
+        assert "tool_result" not in all_types
+
+
+# -- Helpers ------------------------------------------------------------------
+
+
+def _collect_types(messages: list, types: set[str]) -> None:
+    """Recursively collect all message types from a tree of TemplateMessages."""
+    for msg in messages:
+        types.add(msg.type)
+        if hasattr(msg, "children"):
+            _collect_types(msg.children, types)
diff --git a/test/test_template_data.py b/test/test_template_data.py
index c748fe8c..0f41d980 100644
--- a/test/test_template_data.py
+++ b/test/test_template_data.py
@@ -260,7 +260,7 @@ def test_multi_session_data_structure(self):
         test_data_dir = Path(__file__).parent / "test_data"
 
         # Load from directory to get multiple sessions
-        messages = load_directory_transcripts(test_data_dir)
+        messages, _ = load_directory_transcripts(test_data_dir)
         html = generate_html(messages, "Multi Session Test")
 
         # Verify session dividers are present
@@ -282,7 +282,7 @@ def test_empty_directory_handling(self):
             temp_path = Path(temp_dir)
 
             # Should return empty list for directory with no JSONL files
-            messages = load_directory_transcripts(temp_path)
+            messages, _ = load_directory_transcripts(temp_path)
             assert messages == []
 
             # Should generate minimal HTML for empty message list
diff --git a/test/test_version_deduplication.py b/test/test_version_deduplication.py
index 6888683e..11840ec5 100644
--- a/test/test_version_deduplication.py
+++ b/test/test_version_deduplication.py
@@ -271,17 +271,16 @@ def test_full_stutter_pair(self):
         content_count = html.count("Data content")
         assert content_count == 1, f"Expected 1 data content, got {content_count}"
 
-    def test_user_text_message_deduplication(self):
-        """Test deduplication of user text messages with same timestamp but different UUIDs.
+    def test_user_text_messages_with_different_uuids_not_deduped(self):
+        """User text messages with different UUIDs are distinct DAG nodes.
 
-        This can happen during git branch switches where Claude Code logs the same
-        user input multiple times with content split across entries.
+        Even at the same timestamp, user text messages with different UUIDs
+        must be preserved to maintain DAG parent references.
         """
         from claude_code_log.models import TextContent
 
         timestamp = "2025-11-13T11:44:08.771Z"
 
-        # Message 1: Has both IDE tag and actual text (2 content items) - this is the "best"
         msg1 = UserTranscriptEntry(
             type="user",
             uuid="uuid-msg1",
@@ -295,46 +294,16 @@ def test_user_text_message_deduplication(self):
             message=UserMessageModel(
                 role="user",
                 content=[
-                    TextContent(
-                        type="text",
-                        text="<ide_opened_file>User opened test.md</ide_opened_file>",
-                    ),
-                    TextContent(
-                        type="text",
-                        text="This is the actual user message content.",
-                    ),
+                    TextContent(type="text", text="First message"),
                 ],
             ),
         )
 
-        # Message 2: Only has the actual text (1 content item)
         msg2 = UserTranscriptEntry(
             type="user",
             uuid="uuid-msg2",
             parentUuid="parent-002",
-            timestamp=timestamp,  # Same timestamp
-            version="2.0.37",
-            isSidechain=False,
-            userType="external",
-            cwd="/test",
-            sessionId="session-test",
-            message=UserMessageModel(
-                role="user",
-                content=[
-                    TextContent(
-                        type="text",
-                        text="This is the actual user message content.",
-                    ),
-                ],
-            ),
-        )
-
-        # Message 3: Only has IDE tag (1 content item)
-        msg3 = UserTranscriptEntry(
-            type="user",
-            uuid="uuid-msg3",
-            parentUuid="parent-003",
-            timestamp=timestamp,  # Same timestamp
+            timestamp=timestamp,
             version="2.0.37",
             isSidechain=False,
             userType="external",
@@ -343,28 +312,10 @@ def test_user_text_message_deduplication(self):
             message=UserMessageModel(
                 role="user",
                 content=[
-                    TextContent(
-                        type="text",
-                        text="<ide_opened_file>User opened test.md</ide_opened_file>",
-                    ),
+                    TextContent(type="text", text="Second message"),
                 ],
             ),
         )
 
-        # Test all orderings - should always keep msg1 (most content items)
-        for messages in [
-            [msg1, msg2, msg3],
-            [msg2, msg1, msg3],
-            [msg3, msg2, msg1],
-        ]:
-            deduped = deduplicate_messages(messages)
-            html = generate_html(deduped, "User Text Dedup Test")
-
-            # The actual message should appear only once
-            content_count = html.count("This is the actual user message content.")
-            assert content_count == 1, (
-                f"Expected 1 message content, got {content_count}"
-            )
-
-            # Should have kept msg1 which has the IDE notification
-            assert "test.md" in html, "Expected IDE notification to be present"
+        deduped = deduplicate_messages([msg1, msg2])
+        assert len(deduped) == 2, "Different UUIDs should not be deduped"
diff --git a/work/phase-c-agent-transcripts.md b/work/phase-c-agent-transcripts.md
new file mode 100644
index 00000000..47ef30e6
--- /dev/null
+++ b/work/phase-c-agent-transcripts.md
@@ -0,0 +1,87 @@
+# Phase C: Agent Transcript Rework
+
+## Status: Steps 1-2 Complete (DAG Integration)
+
+## What Changed
+
+### Step 1: Agent Data Shapes (Analysis Complete)
+
+Key findings from real data analysis:
+
+- **Agent entries share `sessionId`** with their parent session
+- All agent entries have `isSidechain: true` and `agentId`
+- First entry always has `parentUuid: null` (top-level agents)
+- Internal `parentUuid` chains form the same fork patterns as main sessions
+  (tool-result side-branches)
+- `agentId` reference in main session: either entry-level `agentId` (old Task
+  tool) or `toolUseResult.agentId` (new Agent tool, copied to entry level by
+  converter.py parsing code)
+
+### Step 2: DAG-Level Agent Integration (Implemented)
+
+**`converter.py` — `_integrate_agent_entries()`**:
+1. Builds `agentId -> anchor_uuid` map from main-session entries with `agentId`
+2. For each sidechain entry: assigns synthetic `sessionId`
+   (`{sessionId}#agent-{agentId}`) so agents form separate DAG-lines
+3. Parents root entries (`parentUuid=None`) to the anchor UUID
+
+**Effect**: Agent entries are included in the DAG. The existing DAG machinery
+(build_dag, extract_session_dag_lines, build_session_tree, traverse_session_tree)
+handles them as child sessions of the main session, spliced at the anchor point.
+
+**Key constraint**: `entry.sessionId` on disk / in cache is NEVER mutated.
+The synthetic ID is only assigned in-memory during `load_directory_transcripts()`.
+
+### Renderer Changes
+
+- Agent sessions (`#agent-` in session_id) **don't get session headers**
+- Agent messages use parent session's `render_session_id` for correct grouping
+  in `_reorder_session_template_messages()`
+- Agent sessions excluded from session navigation and individual file generation
+
+### What Was Kept
+
+- `_cleanup_sidechain_duplicates()` — still needed for Task tool dedup
+  (first user message = Task input, last assistant = Task output).
+  This is content-level dedup that can't be handled at the DAG level.
+- `sidechain_uuids` parameter in `build_dag()` — still needed for unloaded
+  subagent files (e.g. aprompt_suggestion agents never referenced via agentId)
+
+### What Was Removed (Step 4)
+
+- `_reorder_sidechain_template_messages()` — removed. With DAG integration,
+  agent messages are already in correct order via DAG traversal. Single-file
+  mode now also calls `_integrate_agent_entries()` so both paths use DAG-based
+  ordering.
+
+## Remaining Steps
+
+### Step 3: Session Tree Integration (Partially Done)
+
+Agent DAG-lines already appear as child sessions in the tree. The
+`traverse_session_tree()` naturally visits them at the junction point.
+What's left:
+- Verify rendering hierarchy (levels 4/5) works correctly for all cases
+- Test with projects that have nested agents (agent spawning sub-agents)
+
+### Step 4: Rendering Cleanup (Done)
+
+- Removed `_reorder_sidechain_template_messages()` — no longer needed with
+  DAG-based ordering. Added `_integrate_agent_entries()` to single-file mode
+  in `converter.py` so both code paths use consistent DAG integration.
+- `_cleanup_sidechain_duplicates()` — kept as-is. Content-level dedup
+  (Task input/output duplicated in sidechain) cannot be handled at the DAG
+  level since it requires text comparison, not structural ordering.
+
+### Step 5: Agent Tool Renderer (separate PR, `dev/user-sidechain`)
+
+- Specialized rendering for Agent tool_use/tool_result (like old Task tool had)
+- Sidechain user messages rendered as markdown (already on `dev/user-sidechain`)
+
+## Test Coverage
+
+4 new integration tests in `TestAgentDagIntegration`:
+- `test_agent_entries_parented_to_anchor` — agent root gets parentUuid to anchor
+- `test_agent_session_in_tree` — synthetic session created, tree structure correct
+- `test_agent_no_session_header` — no session header generated for agents
+- `test_multiple_agents_ordered` — multiple agents placed at respective anchors