feat: add --branches main to drop rewound-and-abandoned forks

claude_code_log/cli.py

@@ -101,6 +101,7 @@ def _render_provider_input_file(
     compact: bool,
     no_timestamps: bool,
     no_recaps: bool,
+    branches: str,
     open_browser: bool,
 ) -> None:
     """Render a single provider session file handed in as an INPUT_PATH.
@@ -204,6 +205,7 @@ def _run_provider_wholesale(
     compact: bool,
     no_timestamps: bool,
     no_recaps: bool,
+    branches: str,
     write_combined: bool,
     write_individual: bool,
     from_date: "Optional[str]",
@@ -1033,6 +1035,20 @@ def _validate_git_link_template(template: str) -> None:
         "redundancy at --depth assistant."
     ),
 )
+@click.option(
+    "--branches",
+    type=click.Choice(["all", "main"]),
+    default="all",
+    show_default=True,
+    help=(
+        "Which conversation branches to render. Rewinding (/rewind, or "
+        "editing an earlier prompt) forks the transcript instead of "
+        "deleting anything, so abandoned attempts stay in the JSONL and "
+        "are rendered as extra 'Branch' sections. 'main' keeps only the "
+        "longest root-to-leaf path per trunk, dropping the attempts that "
+        "were rewound away."
+    ),
+)
 @click.option(
     "--debug",
     is_flag=True,
@@ -1069,6 +1085,7 @@ def main(
     git_link: Optional[str],
     no_timestamps: bool,
     no_recaps: bool,
+    branches: str,
     debug: bool,
 ) -> None:
     """Convert Claude transcript JSONL files to HTML or Markdown.
@@ -1384,6 +1401,7 @@ def main(
                     compact,
                     no_timestamps,
                     no_recaps,
+                    branches,
                     write_combined,
                     write_individual,
                     from_date,
@@ -1411,6 +1429,7 @@ def main(
                     compact,
                     no_timestamps,
                     no_recaps,
+                    branches,
                     open_browser,
                 )
                 return
@@ -1659,6 +1678,7 @@ def render_provider(destination: Path) -> Path:
                         compact=compact,
                         no_timestamps=no_timestamps,
                         no_recaps=no_recaps,
+                        branches=branches,
                     ),
                 )
                 return
@@ -1674,6 +1694,7 @@ def render_provider(destination: Path) -> Path:
                 compact=compact,
                 no_timestamps=no_timestamps,
                 no_recaps=no_recaps,
+                branches=branches,
             )
             click.echo(f"Successfully exported session to {output_path}")
             if open_browser:
@@ -1735,6 +1756,7 @@ def render_provider(destination: Path) -> Path:
                 write_combined=write_combined,
                 no_timestamps=no_timestamps,
                 no_recaps=no_recaps,
+                branches=branches,
                 jobs=jobs,
             )
 
@@ -1775,6 +1797,7 @@ def render_provider(destination: Path) -> Path:
                         compact,
                         no_timestamps,
                         no_recaps,
+                        branches,
                         write_combined,
                         write_individual,
                         from_date,
@@ -1797,6 +1820,7 @@ def render_provider(destination: Path) -> Path:
                     compact,
                     no_timestamps,
                     no_recaps,
+                    branches,
                     open_browser,
                 )
                 return
@@ -1854,6 +1878,7 @@ def render_provider(destination: Path) -> Path:
                     write_combined=True,
                     no_timestamps=no_timestamps,
                     no_recaps=no_recaps,
+                    branches=branches,
                     force_regenerate=True,
                 ),
             )
@@ -1883,6 +1908,7 @@ def render_provider(destination: Path) -> Path:
             write_combined=write_combined,
             no_timestamps=no_timestamps,
             no_recaps=no_recaps,
+            branches=branches,
             # An explicit `-o` *file* always regenerates: the version-marker
             # skip only knows the embedded version, not which source produced
             # the file, so it would keep stale content at a user-chosen path

claude_code_log/converter.py

@@ -60,7 +60,12 @@
     ToolResultContent,
     ToolUseContent,
 )
-from .dag import SessionTree, build_dag_from_entries, traverse_session_tree
+from .dag import (
+    SessionTree,
+    build_dag_from_entries,
+    filter_to_main_line,
+    traverse_session_tree,
+)
 from .renderer import (
     get_renderer,
     prepare_session_ai_titles,
@@ -1877,6 +1882,7 @@ def convert_jsonl_to(
     write_combined: bool = True,
     no_timestamps: bool = False,
     no_recaps: bool = False,
+    branches: str = "all",
     force_regenerate: bool = False,
     report: Optional["RegenerationReport"] = None,
 ) -> Path:
@@ -1895,6 +1901,9 @@ def convert_jsonl_to(
         page_size: Maximum messages per page for combined transcript pagination.
             If None, uses format default (embedded for HTML, referenced for Markdown).
         depth: Output depth level (full, high, low, minimal).
+        branches: Which conversation branches to render. "all" (default)
+            keeps every rewound fork; "main" keeps only the longest
+            root→leaf path per trunk, dropping abandoned rewind attempts.
         force_regenerate: Always (re)generate, bypassing the version-marker
             staleness skip. The CLI sets this for an explicit ``--output``
             (issue #221): the staleness heuristic only knows the embedded
@@ -2044,6 +2053,18 @@ def convert_jsonl_to(
     # Deduplicate messages (removes version stutters while preserving concurrent tool results)
     messages = deduplicate_messages(messages)
 
+    # Drop rewound-and-abandoned fork branches (--branches main). Runs after
+    # dedup so the DAG sees the same entries the renderer will. A prebuilt
+    # tree describes the unfiltered graph, so rebuild it from the survivors
+    # while carrying the workflow links across.
+    if branches == "main":
+        messages = filter_to_main_line(messages)
+        if session_tree is not None:
+            _pruned_tree = build_dag_from_entries(messages)
+            _pruned_tree.workflow_runs = session_tree.workflow_runs
+            _pruned_tree.workflow_links = session_tree.workflow_links
+            session_tree = _pruned_tree
+
     # Update title to include date range if specified
     if from_date or to_date:
         date_range_parts: list[str] = []
@@ -2609,6 +2630,7 @@ def generate_single_session_file(
     compact: bool = False,
     no_timestamps: bool = False,
     no_recaps: bool = False,
+    branches: str = "all",
 ) -> Path:
     """Generate a single session output file for the given session ID.
 
@@ -2646,6 +2668,11 @@ def generate_single_session_file(
     # Load messages from JSONL files
     messages, _session_tree = load_directory_transcripts(input_path, cache_manager)
 
+    # Mirror ``convert_jsonl_to``: drop rewound-and-abandoned fork branches
+    # so a per-session file matches the combined transcript (--branches main).
+    if branches == "main":
+        messages = filter_to_main_line(messages)
+
     # Collect all known session IDs: from loaded messages + cache metadata
     all_session_ids: set[str] = {
         getattr(msg, "sessionId")
@@ -3435,6 +3462,7 @@ def process_projects_hierarchy(
     write_combined: bool = True,
     no_timestamps: bool = False,
     no_recaps: bool = False,
+    branches: str = "all",
     jobs: Optional[int] = None,
 ) -> Path:
     """Process the entire ~/.claude/projects/ hierarchy and create linked output files.
@@ -3649,6 +3677,7 @@ def _convert_plan_inline(plan: _ProjectPlan) -> None:
                 write_combined=write_combined,
                 no_timestamps=no_timestamps,
                 no_recaps=no_recaps,
+                branches=branches,
             )
         except Exception:
             _print_project_failed(plan, traceback.format_exc())

claude_code_log/dag.py

@@ -1144,3 +1144,170 @@ def build_dag_from_entries(
     build_dag(nodes, sidechain_uuids=sidechain_uuids)
     sessions = extract_session_dag_lines(nodes)
     return build_session_tree(nodes, sessions)
+
+
+# =============================================================================
+# Step 6: Abandoned-branch pruning (--branches main)
+# =============================================================================
+
+
+def _line_group_key(dag_line: SessionDAGLine) -> str:
+    """Group a DAG-line with the trunk it forked from.
+
+    Within-session forks get synthetic ids (``s1@abcd1234``) and carry the
+    trunk id in ``original_session_id``; the trunk itself carries none.
+    """
+    return dag_line.original_session_id or dag_line.session_id
+
+
+def _path_length(
+    line_id: str,
+    sessions: dict[str, SessionDAGLine],
+    memo: dict[str, int],
+) -> int:
+    """Messages from the conversation root through the end of ``line_id``.
+
+    A fork does not restate the history it grew from, so a branch's true
+    length is its parent's length *up to the fork point* plus its own.
+    """
+    if line_id in memo:
+        return memo[line_id]
+    memo[line_id] = 0  # cycle guard
+    dag_line = sessions[line_id]
+    prefix = 0
+    parent_id = dag_line.parent_session_id
+    if dag_line.is_branch and parent_id is not None and parent_id in sessions:
+        parent = sessions[parent_id]
+        if dag_line.attachment_uuid in parent.uuids:
+            prefix = parent.uuids.index(dag_line.attachment_uuid) + 1
+            # The fork point's own history counts, but only once.
+            prefix += _path_length(parent_id, sessions, memo) - len(parent.uuids)
+    total = prefix + len(dag_line.uuids)
+    memo[line_id] = total
+    return total
+
+
+def select_main_lines(
+    sessions: dict[str, SessionDAGLine],
+) -> dict[str, SessionDAGLine]:
+    """Drop within-session fork branches that were rewound and abandoned.
+
+    Claude Code's ``/rewind`` (and editing an earlier prompt) does not delete
+    anything: it appends a new message whose ``parentUuid`` points at an
+    *earlier* message, so the transcript becomes a tree and the abandoned
+    attempt stays in the file. Anthropic never marks those dead branches —
+    ``isSidechain`` stays ``False`` on every node (anthropics/claude-code#24471)
+    — so they cannot be filtered by flag; the shape of the graph is the only
+    signal available.
+
+    This keeps, per trunk, the single root→leaf path carrying the most
+    messages, and truncates each ancestor at the fork point it was left at.
+    Sidechains (subagent transcripts) never compete: they are real work
+    branching off the trunk, and are kept whenever their anchor survives.
+
+    Longest path — not latest timestamp — is deliberate. The newest leaf in a
+    real transcript is routinely a stray ``attachment`` or a one-line prompt
+    typed after a rewind, so "most recent" selects a stub. Longest path picks
+    the thread the session actually spent its time on.
+    """
+    groups: dict[str, list[str]] = {}
+    for line_id, dag_line in sessions.items():
+        if dag_line.is_sidechain:
+            continue
+        groups.setdefault(_line_group_key(dag_line), []).append(line_id)
+
+    memo: dict[str, int] = {}
+    kept: dict[str, SessionDAGLine] = {}
+
+    for group_lines in groups.values():
+        if len(group_lines) == 1:
+            kept[group_lines[0]] = sessions[group_lines[0]]
+            continue
+        winner = max(
+            group_lines,
+            key=lambda lid: (
+                _path_length(lid, sessions, memo),
+                sessions[lid].first_timestamp,
+            ),
+        )
+        # Walk the winner back to the trunk, truncating each ancestor at
+        # the fork point its surviving child grew from.
+        chain: list[str] = []
+        cursor: Optional[str] = winner
+        guard: set[str] = set()
+        while cursor is not None and cursor not in guard:
+            guard.add(cursor)
+            chain.append(cursor)
+            current = sessions[cursor]
+            if not current.is_branch:
+                break
+            cursor = current.parent_session_id
+            if cursor is not None and cursor not in sessions:
+                cursor = None
+        chain.reverse()
+
+        for index, line_id in enumerate(chain):
+            dag_line = sessions[line_id]
+            child_id = chain[index + 1] if index + 1 < len(chain) else None
+            if child_id is None:
+                kept[line_id] = dag_line
+                continue
+            fork_uuid = sessions[child_id].attachment_uuid
+            if fork_uuid is None or fork_uuid not in dag_line.uuids:
+                kept[line_id] = dag_line
+                continue
+            cut = dag_line.uuids.index(fork_uuid) + 1
+            kept[line_id] = SessionDAGLine(
+                session_id=dag_line.session_id,
+                uuids=dag_line.uuids[:cut],
+                first_timestamp=dag_line.first_timestamp,
+                parent_session_id=dag_line.parent_session_id,
+                attachment_uuid=dag_line.attachment_uuid,
+                is_branch=dag_line.is_branch,
+                original_session_id=dag_line.original_session_id,
+                is_sidechain=dag_line.is_sidechain,
+            )
+
+    # Re-admit sidechains whose anchor message survived the prune.
+    surviving_uuids = {uuid for dl in kept.values() for uuid in dl.uuids}
+    for line_id, dag_line in sessions.items():
+        if not dag_line.is_sidechain:
+            continue
+        anchor = dag_line.attachment_uuid
+        if anchor is None or anchor in surviving_uuids:
+            kept[line_id] = dag_line
+
+    dropped = len(sessions) - len(kept)
+    if dropped:
+        logger.debug("Pruned %d abandoned fork branch(es)", dropped)
+    return kept
+
+
+def main_line_uuids(
+    entries: list[TranscriptEntry],
+    sidechain_uuids: set[str] | None = None,
+) -> set[str]:
+    """UUIDs surviving :func:`select_main_lines` for ``entries``."""
+    nodes = build_message_index(entries)
+    build_dag(nodes, sidechain_uuids=sidechain_uuids)
+    sessions = extract_session_dag_lines(nodes)
+    kept = select_main_lines(sessions)
+    return {uuid for dag_line in kept.values() for uuid in dag_line.uuids}
+
+
+def filter_to_main_line(
+    entries: list[TranscriptEntry],
+    sidechain_uuids: set[str] | None = None,
+) -> list[TranscriptEntry]:
+    """Return ``entries`` with abandoned rewind branches removed.
+
+    Entries without a ``uuid`` (summaries, ai-titles, queue operations) do
+    not participate in the DAG and are passed through untouched.
+    """
+    keep = main_line_uuids(entries, sidechain_uuids=sidechain_uuids)
+    result: list[TranscriptEntry] = []
+    for entry in entries:
+        uuid = getattr(entry, "uuid", None)
+        if uuid is None or uuid in keep:
+            result.append(entry)
+    return result