teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/services/downloader.py

@@ -0,0 +1,1283 @@
+"""Main transcript download orchestration.
+
+Coordinates the full pipeline: CDP target discovery, meeting navigation,
+transcript extraction, VTT post-processing, and output emission.
+
+This module is the composition root -- it depends on adapters (CDP helpers,
+Vertex agent), service functions (navigation, extraction), and domain
+functions (VTT processing, summary building).  It also performs all file
+I/O.
+
+Extracted from ``transcript_download.py`` ``main()`` (lines 3635-3967).
+
+Schema version: 2.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import datetime as dt_module
+import json
+import sys
+import typing
+from dataclasses import dataclass, field
+
+import websockets.exceptions
+
+from teams_transcripts.adapters.cdp.browser import CdpBrowserAdapter
+from teams_transcripts.adapters.cdp.helpers import (
+    find_iframe_target,
+    find_search_target,
+    find_teams_targets,
+    find_xplatplugins_targets_io,
+    verify_cdp,
+)
+from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+from teams_transcripts.adapters.vertex import VertexAgentAdapter, create_agent_client
+from teams_transcripts.domain.chat import build_chat_note_block, insert_chat_block
+from teams_transcripts.domain.models import ChatMessage, MeetingParticipants, RosterMember
+from teams_transcripts.domain.participants import (
+    build_meeting_participants,
+    parse_partlist_xml,
+    parse_tracking_entries,
+)
+from teams_transcripts.domain.speakers import (
+    apply_speaker_mapping,
+    build_speaker_map_from_roster,
+)
+from teams_transcripts.domain.summary import build_result_summary, verify_vtt_content
+from teams_transcripts.domain.timestamps import parse_meeting_times
+from teams_transcripts.domain.vtt import (
+    ensure_trailing_newline,
+    merge_parts,
+    prepend_metadata,
+)
+from teams_transcripts.infrastructure.errors import (
+    EXIT_CDP_UNAVAILABLE,
+    EXIT_DOWNLOAD_FAILED,
+    EXIT_MEETING_NOT_FOUND,
+    EXIT_OK,
+    EXIT_VERIFICATION_FAILED,
+    exit_error,
+)
+from teams_transcripts.services.extraction import (
+    check_permission,
+    click_part_and_transcript,
+    detect_part_tabs,
+    download_native_vtt,
+    extract_chat_messages,
+    extract_dom_vtt,
+    extract_roster_members,
+    extract_tracking_data,
+    extract_via_react_props,
+    retry_click_transcript,
+)
+from teams_transcripts.services.navigation import (
+    navigate_to_meeting,
+    navigate_to_thread_direct,
+    navigate_to_transcript,
+    verify_meeting_thread_id,
+)
+from teams_transcripts.services.output import (
+    _build_config_dict,
+    _emit_output,
+)
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.domain.models import MeetingConfig
+    from teams_transcripts.infrastructure.logging import Logger
+    from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MAX_SEARCH_RETRIES: int = 4
+"""Maximum number of search result indices to try before giving up."""
+
+_MONTH_NAMES: tuple[str, ...] = (
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_date_from_meeting_time(meeting_time_text: str) -> str:
+    """Extract ISO date from meeting time text.
+
+    Teams Recap headers use the format ``"5 January 2026 09:00 - 09:30"``.
+    Parses the day/month/year and returns an ISO ``YYYY-MM-DD`` string.
+
+    Returns an empty string if parsing fails.
+    """
+    import re
+
+    match = re.match(r"(\d{1,2})\s+(\w+)\s+(\d{4})", meeting_time_text.strip())
+    if not match:
+        return ""
+    day, month_name, year = match.groups()
+    try:
+        parsed = dt_module.datetime.strptime(f"{day} {month_name} {year}", "%d %B %Y").replace(
+            tzinfo=dt_module.timezone.utc,
+        )
+        return parsed.date().isoformat()
+    except ValueError:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Internal data: navigation result threading
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _NavMetadata:
+    """Metadata returned from the Step 4+5 retry loop.
+
+    Avoids stashing temporary data on the browser adapter.
+    """
+
+    search_target_id: str = ""
+    speaker_map: dict[str, str] = field(default_factory=dict)
+    meeting_time_text: str = ""
+    pre_nav_iframe_ids: set[str] = field(default_factory=set)
+
+
+# ---------------------------------------------------------------------------
+# Main orchestration
+# ---------------------------------------------------------------------------
+
+
+async def run_download(
+    config: MeetingConfig,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> None:
+    """Execute the full transcript download pipeline.
+
+    Steps:
+        1. Ensure Teams is running with CDP enabled.
+        2. Verify CDP is responding.
+        3. Discover Teams page targets.
+        4-5. Navigate to meeting and transcript (with retry loop).
+        6. Find the transcript iframe target.
+        7. Download VTT (native blob or DOM extraction).
+        8. Verify the output.
+
+    Output is emitted according to the ``--output`` / ``--format``
+    combination on the config.
+
+    Args:
+        config: Resolved meeting configuration.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+    """
+    # Log configuration
+    datetime_label = config.date
+    if config.time:
+        datetime_label += f"T{config.time}"
+    if config.meeting_id:
+        logger.log("main", f"Meeting ID: {config.meeting_id}")
+    else:
+        logger.log("main", f"Meeting: {config.meeting}")
+    logger.log("main", f"Date: {datetime_label}")
+    logger.log("main", f"Output: {config.output}")
+    logger.log("main", f"CDP port: {config.port}")
+    logger.log("main", f"Model: {config.model}")
+    logger.log("main", f"GCP project: {config.gcp_project}")
+    logger.log("main", f"GCP region: {config.gcp_region}")
+
+    # Step 1: Ensure Teams is running
+    ensure_teams_running(
+        config.port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=config.format_json,
+        force=config.force_restart,
+    )
+
+    # Step 2: Verify CDP
+    verify_cdp(
+        config.port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=config.format_json,
+    )
+
+    # Step 3: Find main Teams targets
+    targets = find_teams_targets(
+        config.port,
+        logger=logger,
+        format_json=config.format_json,
+    )
+    if not targets:
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "NO_TARGETS",
+            "No Teams page targets found via CDP.",
+            step="step3",
+            format_json=config.format_json,
+        )
+    logger.log("step3", f"Found {len(targets)} Teams page target(s)")
+    for t in targets:
+        logger.log("step3", f"  {t['id'][:20]}... {t.get('title', '')[:60]}")
+
+    # Create agent client and adapter
+    agent_client = create_agent_client(config)
+    agent = VertexAgentAdapter(client=agent_client, model=config.model, logger=logger)
+    browser = CdpBrowserAdapter(port=config.port)
+
+    # Step 3b: Verify tenant (when --tenant is specified)
+    tenant_domain: str | None = None
+    tenant_id: str | None = None
+    if config.tenant:
+        from teams_transcripts.adapters.cdp.teams import relaunch_teams_on_tenant
+        from teams_transcripts.services.tenant import (
+            TenantSwitchNeededError,
+            TenantVerification,
+            ensure_tenant,
+            pick_detection_target,
+        )
+
+        # Pick the best target for tenant detection.  Prefer a target with
+        # a descriptive title (e.g. "Chat | ... | TenantName | ...") over
+        # a generic "Microsoft Teams" shell page.
+        detection_target_id = pick_detection_target(targets)
+
+        await browser.connect(detection_target_id)
+        try:
+            verified_tenant = await ensure_tenant(browser, config, logger)
+        except TenantSwitchNeededError as switch:
+            await browser.disconnect()
+            # Kill Teams and relaunch on the correct tenant
+            relaunch_teams_on_tenant(
+                config.port,
+                switch.tenant_id,
+                logger=logger,
+                shutdown=shutdown,
+                format_json=config.format_json,
+                force=config.force_restart,
+            )
+            # Re-verify CDP after relaunch
+            verify_cdp(
+                config.port,
+                logger=logger,
+                shutdown=shutdown,
+                format_json=config.format_json,
+            )
+            # Re-discover targets on the new tenant
+            targets = find_teams_targets(
+                config.port,
+                logger=logger,
+                format_json=config.format_json,
+            )
+            if not targets:
+                exit_error(
+                    EXIT_CDP_UNAVAILABLE,
+                    "NO_TARGETS",
+                    "No Teams page targets found after tenant switch.",
+                    step="step3b",
+                    format_json=config.format_json,
+                )
+            logger.log("step3b", f"Found {len(targets)} target(s) after switch")
+            for t in targets:
+                logger.log("step3b", f"  {t['id'][:20]}... {t.get('title', '')[:60]}")
+
+            # Re-create browser adapter (old websocket is dead)
+            browser = CdpBrowserAdapter(port=config.port)
+
+            # Re-verify tenant on the new targets
+            detection_target_id = pick_detection_target(targets)
+            await browser.connect(detection_target_id)
+            try:
+                verified_tenant = await ensure_tenant(browser, config, logger)
+            except TenantSwitchNeededError as retry_switch:
+                # Switch failed -- the relaunch didn't land on the right tenant.
+                exit_error(
+                    EXIT_CDP_UNAVAILABLE,
+                    "TENANT_SWITCH_FAILED",
+                    f"Tenant switch failed: Teams opened on the wrong tenant "
+                    f"after relaunch. Expected '{config.tenant}', "
+                    f"got a different tenant. Target was "
+                    f"'{retry_switch.domain}' ({retry_switch.tenant_id[:8]}...).",
+                    step="step3b",
+                    format_json=config.format_json,
+                )
+            finally:
+                await browser.disconnect()
+        else:
+            await browser.disconnect()
+        if isinstance(verified_tenant, TenantVerification):
+            tenant_domain = verified_tenant.domain
+            tenant_id = verified_tenant.tenant_id
+
+    # Steps 4+5: Navigate to meeting and Recap > Transcript (with retries)
+    # When --call-id is used, always resolve via MCPS (string match required).
+    # When --meeting-id is used, try direct navigation first (skips the MCPS
+    # scan entirely for non-recurring meetings).  Only fall back to MCPS if
+    # direct navigation fails or the meeting is recurring.
+    resolved_thread_id: str | None = None
+    nav_meta: _NavMetadata | None = None
+    if config.call_id and not config.meeting:
+        from teams_transcripts.services.listing import resolve_call_id
+
+        resolved_subject, resolved_date, resolved_thread_id = await resolve_call_id(
+            config.port,
+            config.call_id,
+            logger=logger,
+            shutdown=shutdown,
+            format_json=config.format_json,
+            tenant_id=tenant_id,
+            force_restart=config.force_restart,
+        )
+        config = config.model_copy(
+            update={"meeting": resolved_subject, "date": resolved_date},
+        )
+        logger.log("main", f"Resolved call ID to: {config.meeting}")
+        logger.log("main", f"Meeting date: {config.date}")
+
+    elif config.meeting_id and not config.meeting:
+        # OPTIMISATION: Attempt direct navigation without MCPS scan.
+        # For non-recurring meetings (the common case), this saves 10-20s
+        # by building thread_id from the UUID and navigating directly.
+        from teams_transcripts.domain.mcps import build_thread_id
+
+        speculative_thread_id = build_thread_id(config.meeting_id)
+        logger.log(
+            "main",
+            f"Attempting direct navigation for meeting ID {config.meeting_id[:12]}...",
+        )
+
+        # Discover search target for navigation
+        search_target_id_spec = await find_search_target(
+            config.port,
+            targets,
+            logger=logger,
+        )
+        speculative_nav_title: str | None = None
+        if search_target_id_spec:
+            speculative_nav_title = await navigate_to_thread_direct(
+                browser,
+                search_target_id_spec,
+                speculative_thread_id,
+                logger,
+                shutdown,
+            )
+
+        if speculative_nav_title and search_target_id_spec:
+            # Sidebar found the chat.  Now try Recap/Transcript.
+            # config.date is "" here — _select_correct_occurrence handles
+            # empty date by returning False for recurring meetings (dropdown
+            # present).  Non-recurring meetings have no dropdown → success.
+            logger.log("main", "Direct thread navigation succeeded (speculative).")
+            pre_nav_iframe_ids = {t["id"] for t in find_xplatplugins_targets_io(config.port)}
+
+            nav_result = await navigate_to_transcript(
+                browser,
+                agent,
+                search_target_id_spec,
+                config.date,  # "" for speculative path
+                config.time,
+                config.model,
+                logger,
+                shutdown,
+                format_json=config.format_json,
+                require_recap=config.include_transcript or config.include_metadata,
+                require_transcript=config.include_transcript,
+            )
+            if nav_result.success:
+                # Non-recurring meeting — speculative path succeeded!
+                # Derive subject from sidebar title, date from meeting time.
+                resolved_thread_id = speculative_thread_id
+                derived_date = _parse_date_from_meeting_time(nav_result.meeting_time_text)
+                config = config.model_copy(
+                    update={
+                        "meeting": speculative_nav_title,
+                        "date": derived_date or config.date,
+                    },
+                )
+                logger.log(
+                    "main",
+                    f"Speculative navigation succeeded: '{config.meeting}' on {config.date}",
+                )
+                nav_meta = _NavMetadata(
+                    search_target_id=search_target_id_spec,
+                    speaker_map=nav_result.speaker_map,
+                    meeting_time_text=nav_result.meeting_time_text,
+                    pre_nav_iframe_ids=pre_nav_iframe_ids,
+                )
+            else:
+                # Recurring meeting — occurrence selection failed (no date).
+                # Fall back to MCPS to get the date, then retry navigation.
+                logger.log(
+                    "main",
+                    "Speculative navigation failed (recurring meeting likely). "
+                    "Falling back to MCPS resolution.",
+                )
+                nav_meta = None
+                # Resolve via MCPS (the slow path)
+                from teams_transcripts.services.listing import resolve_meeting_id
+
+                resolved_subject, resolved_date, resolved_thread_id = await resolve_meeting_id(
+                    config.port,
+                    config.meeting_id,
+                    logger=logger,
+                    shutdown=shutdown,
+                    format_json=config.format_json,
+                    tenant_id=tenant_id,
+                    force_restart=config.force_restart,
+                )
+                config = config.model_copy(
+                    update={"meeting": resolved_subject, "date": resolved_date},
+                )
+                logger.log("main", f"Resolved meeting ID to: {config.meeting}")
+                logger.log("main", f"Meeting date: {config.date}")
+        else:
+            # Sidebar miss — fall back to MCPS for full resolution
+            logger.log(
+                "main",
+                "Speculative sidebar navigation failed. Falling back to MCPS resolution.",
+            )
+            from teams_transcripts.services.listing import resolve_meeting_id
+
+            resolved_subject, resolved_date, resolved_thread_id = await resolve_meeting_id(
+                config.port,
+                config.meeting_id,
+                logger=logger,
+                shutdown=shutdown,
+                format_json=config.format_json,
+                tenant_id=tenant_id,
+                force_restart=config.force_restart,
+            )
+            config = config.model_copy(
+                update={"meeting": resolved_subject, "date": resolved_date},
+            )
+            logger.log("main", f"Resolved meeting ID to: {config.meeting}")
+            logger.log("main", f"Meeting date: {config.date}")
+
+    # When we have a thread_id from resolution (MCPS or speculative) and
+    # nav_meta hasn't been set yet, attempt direct navigation via the
+    # sidebar fibre walk.
+    direct_nav_ok = False
+    search_target_id: str | None = None
+    if nav_meta is None and resolved_thread_id:
+        # We need a search target for Step 5 (navigate_to_transcript).
+        # Discover it first so we can use it regardless of nav path.
+        search_target_id = await find_search_target(
+            config.port,
+            targets,
+            logger=logger,
+        )
+        if search_target_id:
+            direct_nav_title = await navigate_to_thread_direct(
+                browser,
+                search_target_id,
+                resolved_thread_id,
+                logger,
+                shutdown,
+            )
+            direct_nav_ok = direct_nav_title is not None
+            if direct_nav_ok:
+                logger.log("main", "Direct thread navigation succeeded.")
+
+    if direct_nav_ok and search_target_id:
+        # Direct navigation landed on the correct chat.
+        # Record pre-navigation iframe IDs, then proceed to Step 5
+        # (Recap > Transcript).
+        pre_nav_iframe_ids = {t["id"] for t in find_xplatplugins_targets_io(config.port)}
+
+        nav_result = await navigate_to_transcript(
+            browser,
+            agent,
+            search_target_id,
+            config.date,
+            config.time,
+            config.model,
+            logger,
+            shutdown,
+            format_json=config.format_json,
+            require_recap=config.include_transcript or config.include_metadata,
+            require_transcript=config.include_transcript,
+        )
+        if nav_result.success:
+            nav_message = (
+                "Correct occurrence found and transcript tab loaded."
+                if config.include_transcript
+                else "Correct occurrence found. Transcript tab was not required."
+            )
+            logger.log("main", nav_message)
+            nav_meta = _NavMetadata(
+                search_target_id=search_target_id,
+                speaker_map=nav_result.speaker_map,
+                meeting_time_text=nav_result.meeting_time_text,
+                pre_nav_iframe_ids=pre_nav_iframe_ids,
+            )
+        else:
+            # Occurrence not found via direct nav — fall back to full retry loop
+            logger.log(
+                "main",
+                "Direct navigation reached a chat but occurrence mismatch. "
+                "Falling back to search-based navigation.",
+            )
+            nav_meta = None
+
+    if nav_meta is None:
+        nav_meta = await _navigate_with_retries(
+            browser,
+            agent,
+            targets,
+            config,
+            logger,
+            shutdown,
+        )
+    search_target_id = nav_meta.search_target_id
+    speaker_map = nav_meta.speaker_map
+
+    # Detect multi-part meetings (quick DOM check, no navigation).
+    # Always runs (even for dry-run) so the summary can report the
+    # actual part count.  Navigation to the Transcript tab has already
+    # completed by this point.
+    num_parts = await detect_part_tabs(browser, search_target_id)
+    logger.log("main", f"Meeting parts detected: {num_parts}")
+
+    # --- Dry-run exit ---
+    # Must happen before download (matching legacy behaviour).  Dry-run
+    # should be non-destructive: no iframe discovery, no chat tab
+    # navigation, no Details tab navigation.  Roster extraction is kept
+    # because it only opens the participant popover and is part of the
+    # documented dry-run metadata contract.
+    if config.dry_run:
+        roster_members_raw: list[dict] = []
+        organizer_id = ""
+        if config.include_metadata or config.include_chat:
+            (
+                roster_members_raw,
+                speaker_map,
+                _member_map,
+                organizer_id,
+            ) = await _extract_roster_and_maps(
+                browser, search_target_id, nav_meta.speaker_map, logger, shutdown
+            )
+
+        participants: MeetingParticipants | None = None
+        if config.include_metadata:
+            roster_as_members = [
+                RosterMember(
+                    name=m["name"],
+                    email=m.get("email", ""),
+                    object_id=m.get("objectId", ""),
+                    role=m.get("role", "member"),
+                )
+                for m in roster_members_raw
+            ]
+            participants = build_meeting_participants(
+                all_members=roster_as_members,
+                speaker_map=speaker_map,
+                attendance=[],
+                organizer_id=organizer_id,
+            )
+
+        config_dict = _build_config_dict(
+            config,
+            speaker_map,
+            roster_members_raw,
+            nav_meta.meeting_time_text,
+            tenant_domain=tenant_domain,
+        )
+        summary = build_result_summary(
+            config_dict,
+            num_parts=num_parts,
+            chat_count=0,
+            participants=participants,
+            chat_messages=None,
+            include_transcript=config.include_transcript,
+            include_chat=config.include_chat,
+            include_metadata=config.include_metadata,
+        )
+        summary["dry_run"] = True
+        if config.format_json:
+            print(
+                json.dumps(summary, ensure_ascii=False, indent=2),
+                flush=True,
+            )
+        else:
+            logger.log(
+                "main",
+                f"Dry-run summary: {json.dumps(summary, ensure_ascii=False)}",
+            )
+        sys.exit(EXIT_OK)
+
+    # --- Transcript download (time-critical: iframe is ephemeral) ---
+    # The xplatplugins iframe target only exists for ~8 seconds after
+    # the Recap/Transcript tab loads.  Download MUST happen immediately
+    # before any roster/chat/metadata extraction that might navigate
+    # away or cause the SPA to unmount the Recap panel.
+    part_vtt_contents: list[str] = []
+    if config.include_transcript:
+        part_vtt_contents = await _download_parts(
+            browser,
+            agent,
+            search_target_id,
+            config,
+            logger,
+            shutdown,
+            num_parts=num_parts,
+            speaker_map=speaker_map,
+            pre_nav_iframe_ids=nav_meta.pre_nav_iframe_ids,
+        )
+
+        if not part_vtt_contents:
+            exit_error(
+                EXIT_DOWNLOAD_FAILED,
+                "DOWNLOAD_FAILED",
+                "No transcript parts were downloaded.",
+                step="step7",
+                format_json=config.format_json,
+            )
+
+    # --- Metadata extraction (safe to navigate away now) ---
+    # Roster extraction (after steps 4+5 so speaker_map is available)
+    # Run roster extraction when metadata or chat is needed (chat uses member_map
+    # for author name resolution).
+    roster_members_raw: list[dict] = []
+    member_map: dict[str, str] | None = None
+    organizer_id = ""
+    if config.include_metadata or config.include_chat:
+        roster_members_raw, speaker_map, member_map, organizer_id = await _extract_roster_and_maps(
+            browser,
+            search_target_id,
+            nav_meta.speaker_map,
+            logger,
+            shutdown,
+        )
+
+    # Build config dict for domain functions (they expect plain dicts)
+    config_dict = _build_config_dict(
+        config,
+        speaker_map,
+        roster_members_raw,
+        nav_meta.meeting_time_text,
+        tenant_domain=tenant_domain,
+    )
+
+    # --- Extract non-transcript components (chat + metadata) ---
+    # These are extracted regardless of --dry-run when requested.
+    chat_messages: list[ChatMessage] = []
+    event_call_contents: list[str] = []
+    participants: MeetingParticipants | None = None
+    chat_count = 0
+
+    # Chat extraction: needed when include_chat OR include_metadata (for attendance data)
+    if config.include_chat or config.include_metadata:
+        chat_messages, event_call_contents = await extract_chat_messages(
+            browser,
+            search_target_id,
+            config.date,
+            logger,
+            shutdown,
+            meeting_time_text=config_dict.get("meeting_time_text", ""),
+            member_map=member_map,
+            speaker_map=speaker_map,
+        )
+        if config.include_chat:
+            chat_count = len(chat_messages)
+
+    # Build categorised participant lists
+    if config.include_metadata:
+        roster_as_members = [
+            RosterMember(
+                name=m["name"],
+                email=m.get("email", ""),
+                object_id=m.get("objectId", ""),
+                role=m.get("role", "member"),
+            )
+            for m in roster_members_raw
+        ]
+
+        attendance: list[dict] = []
+        for ec_content in event_call_contents:
+            attendance.extend(parse_partlist_xml(ec_content))
+        if attendance:
+            logger.log("main", f"Parsed {len(attendance)} attendance record(s) from partlists")
+
+        # Extract tracking/RSVP data from the Details tab
+        shutdown.check_shutdown()
+        tracking_labels = await extract_tracking_data(
+            browser,
+            search_target_id,
+            logger,
+            shutdown,
+        )
+        tracking_entries = parse_tracking_entries(tracking_labels) if tracking_labels else []
+        if tracking_entries:
+            logger.log("main", f"Parsed {len(tracking_entries)} tracking/RSVP entries")
+
+        participants = build_meeting_participants(
+            all_members=roster_as_members,
+            speaker_map=speaker_map,
+            attendance=attendance,
+            organizer_id=organizer_id,
+            tracking=tracking_entries or None,
+        )
+        rsvp_count = sum(1 for m in participants.invited if m.rsvp_status)
+        logger.log(
+            "main",
+            f"Participants: organiser={len(participants.organiser)}, "
+            f"invited={len(participants.invited)}, "
+            f"speakers={len(participants.speakers)}, "
+            f"attendees={len(participants.attendees)}"
+            + (f", rsvp_enriched={rsvp_count}" if rsvp_count else ""),
+        )
+
+    # --- Transcript excluded: JSON-only output path ---
+    if not config.include_transcript:
+        summary = build_result_summary(
+            config_dict,
+            num_parts=num_parts,
+            chat_count=chat_count,
+            participants=participants,
+            chat_messages=chat_messages if config.include_chat else None,
+            include_transcript=False,
+            include_chat=config.include_chat,
+            include_metadata=config.include_metadata,
+        )
+        if config.output:
+            # Write JSON to file
+            with open(config.output, "w") as f:
+                json.dump(summary, f, ensure_ascii=False, indent=2)
+                f.write("\n")
+            logger.log("main", f"JSON output written to {config.output}")
+        else:
+            # JSON to stdout
+            print(
+                json.dumps(summary, ensure_ascii=False, indent=2),
+                flush=True,
+            )
+        sys.exit(EXIT_OK)
+
+    # --- Transcript included: full download path ---
+
+    # Assemble final VTT content
+    if num_parts > 1:
+        logger.log("main", f"Merging {len(part_vtt_contents)} parts...")
+        content = merge_parts(part_vtt_contents)
+    else:
+        content = part_vtt_contents[0]
+
+    shutdown.check_shutdown()
+
+    # If we haven't done chat extraction yet (e.g. include_chat=True but
+    # extraction was deferred), it's already done above.  The extraction
+    # now happens BEFORE the transcript download for the component-flag flow.
+
+    # Insert metadata (when metadata is included)
+    if config.include_metadata and participants is not None:
+        content = prepend_metadata(content, config_dict, participants=participants)
+    elif config.include_metadata:
+        # Fallback: legacy metadata from roster (no MeetingParticipants)
+        content = prepend_metadata(content, config_dict)
+
+    # Append chat messages (when chat is included)
+    if config.include_chat and chat_messages:
+        time_text = config_dict.get("meeting_time_text", "")
+        if time_text:
+            meeting_start, _ = parse_meeting_times(time_text, config.date)
+        elif config.time:
+            meeting_start = f"{config.date}T{config.time}"
+        else:
+            meeting_start = config.date
+
+        chat_dicts = [
+            {
+                "timestamp": m.timestamp,
+                "author": m.author,
+                "text": m.text,
+                "reactions": (
+                    [{"type": r.type, "users": r.users} for r in m.reactions]
+                    if m.reactions
+                    else None
+                ),
+            }
+            for m in chat_messages
+        ]
+        chat_block = build_chat_note_block(chat_dicts, meeting_start)
+        content = insert_chat_block(content, chat_block)
+    elif not config.include_chat:
+        logger.log("main", "Chat excluded by --chat no.")
+    else:
+        logger.log("main", "No chat messages found for this meeting occurrence.")
+
+    # Ensure trailing newline
+    content = ensure_trailing_newline(content)
+
+    # Write VTT to output file (only when format is VTT;
+    # JSON format writes structured JSON later in _emit_output)
+    if not config.format_json:
+        assert config.output is not None
+        with open(config.output, "w") as f:
+            f.write(content)
+
+    # Step 8: Verify
+    verification = verify_vtt_content(content, require_cues=config.include_transcript)
+    if verification["valid"]:
+        logger.log("step8", f"Cue count: {verification['cue_count']}")
+        for sp, cnt in sorted(verification["speakers"].items()):
+            logger.log("step8", f"  {sp}: {cnt}")
+        logger.log("main", "Transcript download complete.")
+    else:
+        exit_error(
+            EXIT_VERIFICATION_FAILED,
+            "VERIFICATION_FAILED",
+            f"Output file verification failed: {verification.get('error')}",
+            step="step8",
+            format_json=config.format_json,
+        )
+
+    # Emit final output
+    _emit_output(
+        config,
+        config_dict,
+        content,
+        num_parts,
+        verification,
+        chat_count,
+        participants,
+        chat_messages=chat_messages if config.include_chat else None,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal: navigation retry loop (Steps 4+5)
+# ---------------------------------------------------------------------------
+
+
+async def _navigate_with_retries(
+    browser: CdpBrowserAdapter,
+    agent: VertexAgentAdapter,
+    targets: list[dict],
+    config: MeetingConfig,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> _NavMetadata:
+    """Run the Step 4+5 retry loop, returning navigation metadata.
+
+    Exits the process with ``EXIT_MEETING_NOT_FOUND`` if all retries
+    are exhausted.
+    """
+    port = config.port
+    result_index_override: int | None = None
+    search_target_id: str | None = None
+
+    datetime_label = config.date
+    if config.time:
+        datetime_label += f"T{config.time}"
+
+    for attempt in range(MAX_SEARCH_RETRIES):
+        shutdown.check_shutdown()
+
+        # Record existing iframe targets before navigation
+        pre_nav_iframe_ids = {t["id"] for t in find_xplatplugins_targets_io(port)}
+        if pre_nav_iframe_ids:
+            logger.log("main", f"Pre-existing iframe targets: {len(pre_nav_iframe_ids)}")
+
+        try:
+            # Step 4: Find search target and navigate to meeting.
+            # After a fresh relaunch, Teams may take time to load content
+            # targets -- the shell target appears first but the page
+            # targets with the search input load later.  Retry with
+            # target re-discovery to handle this.
+            search_target_id = await find_search_target(
+                port,
+                targets,
+                logger=logger,
+            )
+            if not search_target_id:
+                for search_wait in range(3):
+                    wait_secs = 5 + search_wait * 5
+                    logger.log(
+                        "step4",
+                        f"Search input not found. Waiting {wait_secs}s "
+                        f"for Teams to finish loading "
+                        f"(attempt {search_wait + 1}/3)...",
+                    )
+                    await shutdown.interruptible_sleep(wait_secs)
+                    # Re-discover targets -- new ones may have appeared
+                    targets = find_teams_targets(
+                        port,
+                        logger=logger,
+                        format_json=config.format_json,
+                    )
+                    if targets:
+                        search_target_id = await find_search_target(
+                            port,
+                            targets,
+                            logger=logger,
+                        )
+                        if search_target_id:
+                            break
+
+            if not search_target_id:
+                exit_error(
+                    EXIT_CDP_UNAVAILABLE,
+                    "NO_TARGETS",
+                    "Could not find Teams search input on any CDP target.",
+                    step="step4",
+                    format_json=config.format_json,
+                )
+
+            nav_ok = await navigate_to_meeting(
+                browser,
+                agent,
+                search_target_id,
+                config.meeting,
+                config.date,
+                logger,
+                shutdown,
+                format_json=config.format_json,
+                result_index_override=result_index_override,
+            )
+
+            if not nav_ok:
+                if result_index_override is None:
+                    result_index_override = 1
+                else:
+                    result_index_override += 1
+                logger.log(
+                    "main",
+                    f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} failed "
+                    f"(navigation). Retrying with index {result_index_override}...",
+                )
+                continue
+
+            # Step 4b: Verify thread_id when --meeting-id was used
+            if config.meeting_id:
+                from teams_transcripts.domain.mcps import build_thread_id
+
+                expected_tid = build_thread_id(config.meeting_id)
+                tid_ok = await verify_meeting_thread_id(
+                    browser,
+                    search_target_id,
+                    expected_tid,
+                    logger,
+                )
+                if not tid_ok:
+                    if result_index_override is None:
+                        result_index_override = 1
+                    else:
+                        result_index_override += 1
+                    logger.log(
+                        "main",
+                        f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} failed "
+                        f"(thread_id mismatch). "
+                        f"Retrying with index {result_index_override}...",
+                    )
+                    continue
+
+            # Step 5: Navigate to Recap > Transcript
+            nav_result = await navigate_to_transcript(
+                browser,
+                agent,
+                search_target_id,
+                config.date,
+                config.time,
+                config.model,
+                logger,
+                shutdown,
+                format_json=config.format_json,
+                require_recap=config.include_transcript or config.include_metadata,
+                require_transcript=config.include_transcript,
+            )
+
+            if nav_result.success:
+                nav_message = (
+                    "Correct occurrence found and transcript tab loaded."
+                    if config.include_transcript
+                    else "Correct occurrence found. Transcript tab was not required."
+                )
+                logger.log("main", nav_message)
+                return _NavMetadata(
+                    search_target_id=search_target_id,
+                    speaker_map=nav_result.speaker_map,
+                    meeting_time_text=nav_result.meeting_time_text,
+                    pre_nav_iframe_ids=pre_nav_iframe_ids,
+                )
+
+            # Occurrence not found -- try the next search result
+            if result_index_override is None:
+                result_index_override = 1
+            else:
+                result_index_override += 1
+            logger.log(
+                "main",
+                f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} failed. "
+                f"Retrying with search result index {result_index_override}...",
+            )
+
+        except websockets.exceptions.ConnectionClosed as exc:
+            # The CDP WebSocket was dropped -- typically because Teams
+            # navigated away or the target was destroyed.  Treat as a
+            # retriable failure: re-discover targets on the next attempt.
+            logger.log(
+                "main",
+                f"Attempt {attempt + 1}/{MAX_SEARCH_RETRIES} lost "
+                f"WebSocket connection: {exc}.  Re-discovering targets...",
+            )
+            targets = find_teams_targets(
+                port,
+                logger=logger,
+                format_json=config.format_json,
+            )
+            search_target_id = None
+    else:
+        # Exhausted all retries
+        exit_error(
+            EXIT_MEETING_NOT_FOUND,
+            "MEETING_NOT_FOUND",
+            f"Could not find the target {datetime_label} in any "
+            f"of the first {MAX_SEARCH_RETRIES} search results.",
+            step="step5",
+            format_json=config.format_json,
+        )
+
+    # Unreachable: either the loop returned above or exit_error terminated.
+    # Required by ruff RET503 since exit_error's NoReturn isn't visible
+    # through the for/else structure.
+    msg = "Unreachable: retry loop exhausted without exit"
+    raise AssertionError(msg)
+
+
+# ---------------------------------------------------------------------------
+# Internal: roster and member map extraction
+# ---------------------------------------------------------------------------
+
+
+async def _extract_roster_and_maps(
+    browser: CdpBrowserAdapter,
+    search_target_id: str,
+    speaker_map: dict[str, str],
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+) -> tuple[list[dict], dict[str, str], dict[str, str], str]:
+    """Extract roster members and build speaker/member maps.
+
+    Returns a tuple of ``(roster_members_raw, speaker_map, member_map, organizer_id)``.
+    """
+    # Extract roster
+    roster_members, organizer_id = await extract_roster_members(
+        browser,
+        search_target_id,
+        logger,
+        shutdown,
+        speaker_map=speaker_map or None,
+    )
+
+    # Convert to plain dicts for domain functions
+    roster_members_raw = [
+        {
+            "name": m.name,
+            "email": m.email,
+            "objectId": m.object_id,
+            "role": m.role,
+        }
+        for m in roster_members
+    ]
+
+    # Build combined member map
+    member_map = build_speaker_map_from_roster(roster_members_raw, speaker_map or None)
+
+    return roster_members_raw, speaker_map, member_map, organizer_id
+
+
+# ---------------------------------------------------------------------------
+# Internal: per-part download loop
+# ---------------------------------------------------------------------------
+
+
+async def _download_parts(
+    browser: CdpBrowserAdapter,
+    agent: VertexAgentAdapter,
+    search_target_id: str,
+    config: MeetingConfig,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    *,
+    num_parts: int,
+    speaker_map: dict[str, str],
+    pre_nav_iframe_ids: set[str] | None = None,
+) -> list[str]:
+    """Download all transcript parts and return their VTT contents.
+
+    For multi-part meetings, clicks each Part tab and downloads
+    separately.
+
+    Args:
+        pre_nav_iframe_ids: Set of iframe target IDs that existed
+            *before* the Step 4+5 navigation.  For part 1, using this
+            set lets us detect the xplatplugins target that appeared
+            during Recap/Transcript tab load (which may be ephemeral).
+            If not supplied, the current state is captured instead.
+    """
+    port = config.port
+    part_vtt_contents: list[str] = []
+    # For part 1: use the pre-navigation set captured before step 5,
+    # so the xplatplugins target that appeared during Recap/Transcript
+    # load is detected as "new".  Falls back to current state if not
+    # provided (backward compatibility).
+    if pre_nav_iframe_ids is None:
+        pre_nav_iframe_ids = {t["id"] for t in find_xplatplugins_targets_io(port)}
+
+    for part_num in range(1, num_parts + 1):
+        shutdown.check_shutdown()
+        part_label = f"Part {part_num}/{num_parts}"
+
+        if part_num > 1:
+            logger.log("main", f"Navigating to {part_label}...")
+            pre_part_iframe_ids = {t["id"] for t in find_xplatplugins_targets_io(port)}
+            ok = await click_part_and_transcript(
+                browser,
+                search_target_id,
+                part_num,
+                logger,
+                shutdown,
+            )
+            if not ok:
+                logger.log("main", f"WARNING: Could not navigate to {part_label}. Skipping.")
+                continue
+            pre_nav_iframe_ids = pre_part_iframe_ids
+
+        logger.log("main", f"Downloading transcript for {part_label}...")
+
+        # Step 6: Find iframe target.  For parts > 1, use allow_missing
+        # so that we can retry by re-clicking the Transcript tab rather
+        # than hard-exiting.
+        is_subsequent_part = part_num > 1
+        iframe_target_id = find_iframe_target(
+            port,
+            config=config,
+            agent_client=agent.client,
+            logger=logger,
+            shutdown=shutdown,
+            pre_nav_iframe_ids=pre_nav_iframe_ids,
+            allow_missing=is_subsequent_part,
+        )
+
+        # Retry once for subsequent parts: re-click Transcript and poll
+        # again.  The initial click may have been a no-op if the tab was
+        # already selected.
+        if iframe_target_id is None and is_subsequent_part:
+            logger.log("step6", "Retrying: re-clicking Transcript tab...")
+            pre_retry_ids = {t["id"] for t in find_xplatplugins_targets_io(port)}
+            ok = await retry_click_transcript(browser, search_target_id, logger, shutdown)
+            if ok:
+                iframe_target_id = find_iframe_target(
+                    port,
+                    config=config,
+                    agent_client=agent.client,
+                    logger=logger,
+                    shutdown=shutdown,
+                    pre_nav_iframe_ids=pre_retry_ids,
+                    allow_missing=True,
+                )
+
+        if iframe_target_id is None:
+            if num_parts == 1:
+                exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "IFRAME_NOT_FOUND",
+                    "No xplatplugins iframe target found. "
+                    "Check that Step 5 completed and the Transcript tab loaded.",
+                    step="step6",
+                    format_json=config.format_json,
+                )
+            logger.log("main", f"WARNING: No iframe target for {part_label}. Skipping.")
+            continue
+
+        # Step 7: Check permission.
+        permission_state = await check_permission(
+            browser,
+            iframe_target_id,
+            logger,
+            shutdown,
+        )
+
+        if permission_state == "no_button":
+            if num_parts == 1:
+                exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "DOWNLOAD_FAILED",
+                    "Download button not found. The transcript may not have loaded.",
+                    step="step7",
+                    format_json=config.format_json,
+                )
+            logger.log("main", f"WARNING: No download button for {part_label}. Skipping.")
+            continue
+
+        # Step 7A or 7B based on permission
+        vtt_content: str | None = None
+        if permission_state == "has_permission":
+            logger.log("main", f"{part_label}: Using Approach A (native blob interception)")
+            vtt_content = await download_native_vtt(
+                browser,
+                iframe_target_id,
+                logger,
+                shutdown,
+            )
+        else:
+            logger.log("main", f"{part_label}: Using Approach B (DOM extraction)")
+            vtt_content = await extract_via_react_props(
+                browser,
+                iframe_target_id,
+                logger,
+                speaker_map=speaker_map or None,
+            )
+            if vtt_content is None:
+                logger.log(
+                    "main",
+                    f"{part_label}: React props unavailable, falling back to scroll",
+                )
+                vtt_content = await extract_dom_vtt(
+                    browser,
+                    iframe_target_id,
+                    logger,
+                )
+
+        if not vtt_content:
+            if num_parts == 1:
+                exit_error(
+                    EXIT_DOWNLOAD_FAILED,
+                    "DOWNLOAD_FAILED",
+                    "Transcript download failed.",
+                    step="step7",
+                    format_json=config.format_json,
+                )
+            logger.log("main", f"WARNING: Download failed for {part_label}. Skipping.")
+            continue
+
+        # Normalise line endings: Teams blob downloads use CRLF (\r\n).
+        # Domain functions and the VTT spec expect LF (\n).  The old
+        # monolith normalised this implicitly via file I/O round-trips
+        # (Python's universal newlines mode).
+        vtt_content = vtt_content.replace("\r\n", "\n")
+
+        # Apply speaker mapping
+        if speaker_map:
+            vtt_content = apply_speaker_mapping(vtt_content, speaker_map)
+
+        part_vtt_contents.append(vtt_content)
+        logger.log("main", f"{part_label}: downloaded successfully")
+
+    return part_vtt_contents