zoom_engine.py

#!/usr/bin/env python3
"""
zoom_engine.py — Headless WAL poller for Zoom Notes.

Replaces zoom_menu_bar.py. No rumps, no UI — designed to run as a child process
of the Swift ZoomNotesApp. Emits newline-delimited JSON events to stdout and
accepts JSON commands on stdin (for future extensibility).

State machine: idle → active → generating → idle

JSON events emitted to stdout:
  {"event": "state", "value": "idle"}
  {"event": "state", "value": "active", "meeting_id": "<id>"}
  {"event": "state", "value": "generating"}
  {"event": "done", "title": "...", "path": "...", "transcript_path": "...", "attendees": [...], "meeting_id": "..."}
  {"event": "recovery_available", "meeting_id": "...", "entry_count": N, "last_updated": "...", "slug_hint": "...", "location": "root|failed", "title": "...?", "failed_at": "...?", "last_error": "...?"}
  {"event": "error", "message": "..."}

stdin commands accepted (one JSON object per line):
  {"cmd": "generate"}                       — manual trigger
  {"cmd": "reload"}                         — reload settings (also triggered by SIGHUP)
  {"cmd": "retry", "meeting_id": "..."}     — retry a meeting whose LLM call just failed
  {"cmd": "recover", "meeting_id": "..."}   — recover a meeting from a prior crash
"""

import concurrent.futures
import json
import re
import signal
import sys
import threading
import time
from datetime import datetime
from pathlib import Path


def _friendly_error(exc: Exception) -> str:
    """Convert a raw exception into a short, human-readable menu bar message."""
    msg = str(exc)
    # HTTP status codes from LLM providers
    for code, label in [
        ("429", "LLM quota exceeded — try again later"),
        ("401", "LLM authentication failed — check your API key in Settings"),
        ("403", "LLM access denied — check your API key in Settings"),
        ("500", "LLM server error — try again later"),
        ("503", "LLM service unavailable — try again later"),
    ]:
        if code in msg:
            return label
    # Truncate anything else to a reasonable length
    first_line = msg.splitlines()[0] if msg else "Unknown error"
    return first_line[:80] + ("…" if len(first_line) > 80 else "")


from zoom_config import (
    get_config,
    invalidate_config_cache,
    get_api_key,
    resolve_subfolder,
    resolve_filename,
)
from zoom_notes import (
    CancelledError,
    find_origin_dir,
    find_wal,
    parse_transcript,
    parse_meeting_title,
    read_calendar_title,
    format_transcript,
    summarize,
    generate_title,
    build_note_content,
    build_placeholder_note,
    build_transcript_content,
    save_transcript_only,
    save_note_only,
    overwrite_note,
    slugify_title,
    detect_active_meeting_id,
    persist_accumulator,
    load_persisted_accumulator,
    load_failed_sidecar,
    _persisted_paths,
    delete_persisted_accumulator,
    purge_stale_accumulators,
    list_recoverable_meetings,
    mark_meeting_failed,
    _path_to_vault_link,
    _atomic_write_text,
    _CACHE_DIR,
    _safe_meeting_id_slug,
)


# ── Event emission ────────────────────────────────────────────────────────────

_emit_lock = threading.Lock()


def emit(payload: dict) -> None:
    """Write a JSON event to stdout, thread-safe."""
    with _emit_lock:
        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
        sys.stdout.flush()


# ── WAL watcher ───────────────────────────────────────────────────────────────

class EngineState:
    IDLE = "idle"
    ACTIVE = "active"
    GENERATING = "generating"


# Hard ceiling for one note-generation pass (parse + LLM + write).
# urllib's per-call timeout is 180s and _http_retry sleeps 15+30+60 between
# attempts, so the worst-case for one summarize() call is ~13 minutes. We cap
# the whole pipeline at 5 minutes — anything longer is almost certainly stuck.
_GENERATE_TIMEOUT_SECS = 5 * 60

# Force a fresh on-disk snapshot every N ACTIVE ticks regardless of whether
# the in-memory accumulator changed. Belt-and-suspenders against a SQLite WAL
# checkpoint that resets the file without the parser yielding new entries —
# the in-RAM accumulator stays correct, but the on-disk copy could otherwise
# go stale right when a crash would leave it as the only surviving copy.
# At the default 5s poll interval, 6 ticks ≈ 30s.
_PERIODIC_PERSIST_TICKS = 6

# A WAL "shrink" is suspicious only when the new size is well below the
# previous size — normal frame rotation can drop a few bytes between ticks
# without truncating the log. Treat <50% of last_size as a truncate signal.
_TRUNCATE_RATIO = 0.5


class ZoomEngine:
    def __init__(self):
        self._state = EngineState.IDLE
        self._state_lock = threading.Lock()
        self._generating_lock = threading.Lock()

        # All WAL-tracking variables share a single lock. Read and write only
        # via the helpers below; never touch the underscored fields directly
        # from outside the lock.
        self._tracking_lock = threading.Lock()
        self._last_mtime: float | None = None
        self._last_size: int | None = None
        self._last_active_ts: float | None = None
        self._active_meeting_id: str | None = None
        # WAL mtime captured when the current ACTIVE session first started
        # (the IDLE→ACTIVE transition tick). Combined with `_active_meeting_id`
        # it forms a session fingerprint that distinguishes recurring Zoom
        # meetings (same meeting_id, different start time) from a checkpoint
        # mutation of the same meeting we just generated for.
        self._active_session_mtime: float | None = None

        # Fingerprint of the last successfully-generated meeting session.
        # Tuple of (meeting_id, session_start_mtime). Guards against:
        #   1. Zoom's post-meeting WAL checkpoint replaying the same meeting.
        #   2. False suppression of recurring meetings that reuse the same
        #      Zoom meeting_id — a new IDLE→ACTIVE produces a different
        #      session_start_mtime so the guard correctly lets it through.
        self._last_generated_session: tuple[str, float] | None = None

        # `(meeting_id, latest_ts_secs)` for the session we most recently
        # generated notes for, where `latest_ts_secs` is the wall-clock
        # seconds-since-midnight of the last transcript entry we wrote.
        # Passed to `detect_active_meeting_id` on the next IDLE -> ACTIVE
        # transition so the just-completed meeting can't trap detection
        # while its data is still resident in the WAL (the 2026-04-30
        # back-to-back-meeting overwrite scenario). Distinct from
        # `_last_generated_session`: the fingerprint there guards against
        # re-summarizing the same checkpoint, this guards against picking
        # up the wrong meeting when a NEW one starts immediately after.
        self._last_completed_boundary: tuple[str, int] | None = None

        # Set by _generate_notes when it writes a placeholder note instead of
        # a final note. Read by the worker so it knows to keep the persisted
        # accumulator (for retry) rather than deleting it.
        self._last_run_note_failed: bool = False

        # Cooperative cancellation signal for in-flight note generation.
        # Cleared at the start of every _trigger_generate / _trigger_retry
        # and set when the outer 5-min wall-clock timeout fires (so the
        # still-running summarize() thread can abort at its next checkpoint
        # instead of zombie-running until the urllib per-call timeout).
        self._cancel_event = threading.Event()

        # Most recent failed-note metadata, used to drive a retry without
        # asking the user to remember the meeting ID. Cleared on retry success.
        self._last_failed_meeting: dict | None = None

        # Accumulated transcript entries keyed by msg_id. Populated on every
        # poll tick so a WAL checkpoint can't lose data already read.
        self._accumulated: dict[str, dict] = {}
        self._accumulated_lock = threading.Lock()

        # Monotonic timestamp of when the WAL was last seen while ACTIVE.
        # Set when the WAL disappears mid-meeting (Zoom checkpoint) so we can
        # fire generation after idle_threshold even without the WAL present.
        self._wal_gone_since: float | None = None

        # Counter of ACTIVE ticks since the last accumulator persist call. Used
        # to force a fresh disk snapshot every _PERIODIC_PERSIST_TICKS even when
        # nothing changed in the parser output — guards against the gap where a
        # SQLite WAL checkpoint truncates the file without producing parser
        # output that flips `changed_in_acc` true.
        self._ticks_since_persist: int = 0

        # Streak counter for change-ticks while ACTIVE that yielded zero
        # new accumulator entries. A growing streak strongly suggests a
        # parser regression vs. a Zoom WAL format change — the WAL is
        # being written (mtime/size moved) but our parser sees nothing.
        # Emitted via diag at threshold so a degraded session is visible
        # in logs without re-creating the issue.
        self._empty_parse_streak: int = 0

        # Monotonic timestamp of the last tick that added new entries to
        # the accumulator. Used by the secondary idle trigger to detect
        # meetings where Zoom's post-meeting WAL checkpoint writes keep
        # the WAL "alive" (resetting the normal idle clock) even after
        # the last speech was captured — causing the meeting to never
        # trigger generation until the app is restarted.
        self._last_acc_changed_wall_time: float | None = None

        # Purge stale in-progress cache files left over from prior crashes.
        # Order matters: purge first so the recovery scan that follows only
        # surfaces snapshots inside the live retention window.
        purge_stale_accumulators()

        # Snapshot any in-progress accumulators that survived purge so run()
        # can emit `recovery_available` events on startup. We capture this in
        # __init__ rather than at run() time so a crash between those two
        # phases doesn't lose the list. The Swift menu bar uses these events
        # to surface a "Recover unfinished meeting" item — without this,
        # cached transcripts from a prior crash are unreachable through the
        # UI even though they're sitting on disk.
        try:
            self._recoverable_at_startup: list[dict] = list_recoverable_meetings()
        except Exception:
            self._recoverable_at_startup = []

        # Config (reloaded on SIGHUP or "reload" command)
        self._cfg_lock = threading.Lock()
        self._reload_requested = False
        # Cleared together with config so a settings change picks up new WAL
        # prefixes / a Zoom install relocation on the next tick.
        self._origin_invalidated = False

        # Resolved WAL paths, keyed by (origin_str, kind). Populated lazily on
        # first successful resolution and reused on every subsequent poll —
        # the underlying IndexedDB folder structure is stable for the life of
        # an engine session. Cleared whenever origin is invalidated (settings
        # reload, Zoom relocation) so a config change picks up fresh paths.
        # Only positive results are cached — `None` is intentionally NOT
        # cached so we keep retrying when the user enables Notetaker / starts
        # their first meeting after launching the app.
        self._wal_cache: dict[tuple[str, str], Path] = {}

        # One-shot guard for the "Zoom installed but no transcript WAL"
        # setup error. Without this, a misconfigured Zoom would re-emit the
        # error every 5-second poll and spam the user. Reset on origin
        # invalidation so settings changes give us a fresh chance to retry.
        self._setup_error_emitted = False

        signal.signal(signal.SIGHUP, self._on_sighup)
        signal.signal(signal.SIGTERM, self._on_sigterm)

    def _on_sighup(self, signum, frame):
        """SIGHUP triggers a config reload on the next poll tick."""
        self._reload_requested = True

    def _on_sigterm(self, signum, frame):
        """SIGTERM: finish any in-flight generation before exiting.

        Without this, app termination mid-generation kills the background
        thread before it can call delete_persisted_accumulator(), leaving
        an orphaned snapshot that surfaces as a spurious "recover unfinished
        meeting" item on the next launch. Cancelling the LLM call and waiting
        up to 10 seconds gives the worker a clean exit path.
        """
        self._cancel_event.set()
        acquired = self._generating_lock.acquire(timeout=10)
        if acquired:
            self._generating_lock.release()
        sys.exit(0)

    # ── Tracking helpers (always held under _tracking_lock) ─────────────────

    def _read_tracking(self):
        with self._tracking_lock:
            return (
                self._last_mtime,
                self._last_size,
                self._last_active_ts,
                self._active_meeting_id,
            )

    def _read_session_mtime(self) -> float | None:
        with self._tracking_lock:
            return self._active_session_mtime

    def _latest_acc_ts_secs_for(self, meeting_id: str) -> int | None:
        """Latest accumulator timestamp for `meeting_id`, in seconds-since-midnight.

        Used to stamp `_last_completed_boundary` after generation. Returns
        None if the accumulator has no entries for that meeting (we won't
        block detection on a non-existent boundary).
        """
        latest = -1
        with self._accumulated_lock:
            for e in self._accumulated.values():
                if e.get("meeting_id") != meeting_id:
                    continue
                ts = e.get("timestamp")
                if not ts:
                    continue
                try:
                    parts = [int(x) for x in ts.split(":")]
                except ValueError:
                    continue
                if len(parts) != 3:
                    continue
                secs = parts[0] * 3600 + parts[1] * 60 + parts[2]
                if secs > latest:
                    latest = secs
        return latest if latest >= 0 else None

    def _write_tracking(self, *, mtime=..., size=..., active_ts=..., meeting_id=..., session_mtime=...):
        with self._tracking_lock:
            if mtime is not ...:
                self._last_mtime = mtime
            if size is not ...:
                self._last_size = size
            if active_ts is not ...:
                self._last_active_ts = active_ts
            if meeting_id is not ...:
                self._active_meeting_id = meeting_id
            if session_mtime is not ...:
                self._active_session_mtime = session_mtime

    def _reset_tracking(self) -> None:
        with self._tracking_lock:
            self._last_mtime = None
            self._last_size = None
            self._last_active_ts = None
            self._active_meeting_id = None
            self._active_session_mtime = None
        # Reset the periodic-persist counter alongside tracking — its meaning
        # is "ticks since last persist while ACTIVE", and a tracking reset
        # always implies we're leaving ACTIVE. Same reasoning for the
        # empty-parse streak and accumulator-change timestamp.
        self._ticks_since_persist = 0
        self._empty_parse_streak = 0
        self._last_acc_changed_wall_time = None

    # ── State helpers ───────────────────────────────────────────────────────

    def _set_state(self, new_state: str, **extra) -> None:
        with self._state_lock:
            self._state = new_state
        payload: dict = {"event": "state", "value": new_state}
        payload.update(extra)
        emit(payload)

    def _get_state(self) -> str:
        with self._state_lock:
            return self._state

    # ── Diagnostics ─────────────────────────────────────────────────────────

    def _emit_diag(self, kind: str, **fields) -> None:
        """Emit a structured diagnostic event when diagnostics is enabled.

        These show up in the engine's stdout JSON stream and are mirrored to
        the Swift app's log file by EngineManager. Useful for post-mortem
        investigation of "why was my meeting skipped" without code reading.
        """
        try:
            if not self._diagnostics_enabled():
                return
        except Exception:
            return
        payload = {"event": "diag", "kind": kind}
        payload.update(fields)
        emit(payload)

    def _diagnostics_enabled(self) -> bool:
        try:
            cfg = self._get_cfg()
            return bool(getattr(cfg, "diagnostics", False))
        except Exception:
            return False

    # ── Config ─────────────────────────────────────────────────────────────

    def _get_cfg(self):
        with self._cfg_lock:
            if self._reload_requested:
                invalidate_config_cache()
                self._reload_requested = False
                self._origin_invalidated = True
        return get_config()

    def _consume_origin_invalidated(self) -> bool:
        with self._cfg_lock:
            was = self._origin_invalidated
            self._origin_invalidated = False
        if was:
            # Drop cached WAL paths and re-arm the one-shot setup error so a
            # settings change (or a Zoom reinstall mid-session) gets a fresh
            # resolution and a fresh chance to surface a real diagnostic.
            self._wal_cache.clear()
            self._setup_error_emitted = False
        return was

    # ── WAL resolution (with cache and setup-error fallback) ────────────────

    def _resolve_wal(self, origin, cfg, kind: str) -> Path | None:
        """Resolve the transcript or blocks WAL, caching positive results.

        `kind` is `"transcript"` or `"blocks"`. Calls into `find_wal()` —
        which tries the configured prefix first and falls back to scanning
        WAL contents — and caches the resolved Path in memory. Subsequent
        polls re-use the cached path until the file disappears or origin is
        invalidated. Negative results (None) are NOT cached: that's the
        common cold-start state for users who haven't yet run a meeting
        with AI Notetaker, and we want every poll to keep trying until the
        WAL appears.
        """
        if origin is None:
            return None
        cache_key = (str(origin), kind)
        cached = self._wal_cache.get(cache_key)
        if cached is not None:
            try:
                if cached.exists() and cached.stat().st_size > 256:
                    return cached
            except OSError:
                pass
            # Stale cache — Zoom rotated the WAL or the user reinstalled.
            self._wal_cache.pop(cache_key, None)

        prefix = (
            cfg.transcript_db_prefix
            if kind == "transcript"
            else cfg.blocks_db_prefix
        )
        wal = find_wal(origin, prefix, kind=kind)
        if wal is not None:
            self._wal_cache[cache_key] = wal
            via = "prefix" if wal.parent.name.startswith(prefix) else "content"
            self._emit_diag(
                "wal_resolved",
                wal_kind=kind,
                path=str(wal),
                via=via,
            )
        return wal

    def _maybe_emit_setup_error(self, origin) -> None:
        """Emit a one-shot UI error when origin is found but no transcript
        WAL exists.

        This is the failure mode that previously left the engine silently
        stuck in IDLE forever: Zoom is installed (we have an origin), but
        none of its IndexedDB stores contain transcript data — typically
        because AI Companion / Notetaker is disabled or has never been
        used on this account. Surfacing this in the UI tells the user
        what to fix instead of leaving them staring at "Waiting for
        meeting..." through an entire call.
        """
        if origin is None or self._setup_error_emitted:
            return
        self._setup_error_emitted = True
        emit({
            "event": "error",
            "message": (
                "Couldn't find Zoom's transcript database. Make sure "
                "AI Companion / Notetaker is enabled in your Zoom client "
                "and has been used at least once on this account."
            ),
        })

    # ── Persistence helpers ─────────────────────────────────────────────────

    def _persist_accumulator_now(self, meeting_id: str, reason: str) -> None:
        """Snapshot and write the in-memory accumulator to disk, atomically.

        Resets the periodic-persist tick counter so a same-tick persist can't
        be immediately followed by another forced one. `reason` is included in
        the diag event for post-mortem analysis ("changed", "truncated",
        "periodic"). Safe to call even with an empty accumulator — it just
        writes an empty snapshot, which is a valid resume state.
        """
        if not meeting_id:
            return
        with self._accumulated_lock:
            snapshot = dict(self._accumulated)
        try:
            persist_accumulator(meeting_id, snapshot)
        except Exception:
            return
        self._ticks_since_persist = 0
        self._emit_diag(
            "accumulator_persisted",
            count=len(snapshot),
            meeting_id=meeting_id,
            reason=reason,
        )

    # ── Polling loop ────────────────────────────────────────────────────────

    def run(self) -> None:
        # Emit a one-shot readiness event with Zoom-detection status before
        # the regular state stream, so the UI can show a setup error if
        # Zoom isn't installed / WAL paths don't resolve.
        initial_origin = find_origin_dir()
        emit({
            "event": "ready",
            "zoom_installed": initial_origin is not None,
            "wal_path": str(initial_origin) if initial_origin else None,
        })

        # Surface any in-progress accumulators left over from a prior crash.
        # Emitted between `ready` and the first `state` event so the UI can
        # render a "Recover unfinished meeting" menu before the engine starts
        # actively polling. The UI is responsible for suppressing recovery
        # entries whose meeting_id later matches an `active` state event —
        # those will be auto-resumed via the existing IDLE→ACTIVE seed path.
        for rec in self._recoverable_at_startup:
            evt = {
                "event": "recovery_available",
                "meeting_id": rec["meeting_id"],
                "entry_count": rec["entry_count"],
                "last_updated": rec["last_updated"],
                "slug_hint": rec["slug_hint"],
                "location": rec.get("location", "root"),
            }
            # Confirmed-failed snapshots (in `failed/`) carry sidecar metadata
            # — pass through what we have so the menu bar can render a richer
            # label like "Sales Sync — failed 3 days ago" instead of the
            # speaker-name slug hint.
            if rec.get("title"):
                evt["title"] = rec["title"]
            if rec.get("failed_at"):
                evt["failed_at"] = rec["failed_at"]
            if rec.get("last_error"):
                evt["last_error"] = rec["last_error"]
            emit(evt)

        emit({"event": "state", "value": EngineState.IDLE})

        threading.Thread(target=self._stdin_reader, daemon=True).start()

        origin = initial_origin
        while True:
            try:
                cfg = self._get_cfg()
                poll_interval = cfg.poll_interval_secs
                idle_threshold = cfg.idle_threshold_secs

                # Reset cached origin whenever config was reloaded OR we never
                # found one — a re-poll is cheap (single directory iter) and
                # lets us recover when Zoom is installed/relocated mid-session.
                if origin is None or self._consume_origin_invalidated():
                    origin = find_origin_dir()

                self._poll_once(origin, cfg, idle_threshold)

            except Exception as exc:
                emit({"event": "error", "message": f"Poll error: {exc}"})

            time.sleep(poll_interval)

    def _poll_once(self, origin, cfg, idle_threshold: int) -> None:
        if origin is None:
            return

        wal = self._resolve_wal(origin, cfg, "transcript")
        if not wal:
            # Zoom is installed but we can't find a transcript-shaped WAL.
            # Surface the diagnostic the first time we hit this so the user
            # sees a real error instead of silently sitting in IDLE. We
            # only emit when we've never been ACTIVE — once a meeting has
            # been seen, a transient WAL-gone window is the existing
            # "checkpoint mid-meeting" path below and shouldn't trigger a
            # setup-error message.
            if self._get_state() == EngineState.IDLE:
                self._maybe_emit_setup_error(origin)
            state = self._get_state()
            if state == EngineState.ACTIVE:
                with self._accumulated_lock:
                    has_entries = bool(self._accumulated)
                if has_entries:
                    # WAL disappeared mid-meeting (Zoom checkpoint). Keep ACTIVE
                    # and fire generation once the idle threshold elapses.
                    if self._wal_gone_since is None:
                        self._wal_gone_since = time.monotonic()
                    idle_secs = time.monotonic() - self._wal_gone_since
                    if idle_secs >= idle_threshold:
                        self._wal_gone_since = None
                        self._trigger_generate(origin, cfg)
                    return
                # No entries yet — WAL gone before we accumulated anything
                self._wal_gone_since = None
                self._set_state(EngineState.IDLE)
                self._reset_tracking()
            return
        # WAL present — reset the gone timer
        self._wal_gone_since = None

        try:
            stat = wal.stat()
        except OSError:
            return

        mtime = stat.st_mtime
        size = stat.st_size
        now = time.time()

        last_mtime, last_size, last_active_ts, _ = self._read_tracking()

        # First poll after startup (or after _reset_tracking): we don't know
        # whether the WAL is currently changing or just has stale state from a
        # past meeting. Anchor to the observed values WITHOUT marking it as
        # "changed" — otherwise a stale WAL from a meeting that ended hours
        # ago would immediately flip us to ACTIVE on engine restart and
        # re-trigger generation 90 seconds later.
        if last_mtime is None or last_size is None:
            self._write_tracking(mtime=mtime, size=size)
            return

        changed = (mtime != last_mtime) or (size != last_size)

        # Truncate detection: the WAL shrunk well below its previous size,
        # which on SQLite means a checkpoint truncated the journal. The new
        # entries we already accumulated are still valid in RAM, but the
        # parser will yield nothing new from this point until fresh writes
        # land — so this is a critical moment to force a persist.
        truncated = (
            last_size is not None
            and size < last_size
            and size < last_size * _TRUNCATE_RATIO
        )

        self._write_tracking(mtime=mtime, size=size)

        state = self._get_state()

        # Force a fresh disk snapshot when the WAL just got truncated (a
        # SQLite checkpoint cleared the journal) or when we've gone too many
        # ACTIVE ticks without persisting. Run this BEFORE the change-handling
        # branch so a tick that sees a truncate ALSO benefits from the regular
        # accumulator-update logic below if there happens to be fresh data.
        if state == EngineState.ACTIVE:
            self._ticks_since_persist += 1
            _, _, _, current_meeting_id = self._read_tracking()
            if current_meeting_id and (
                truncated or self._ticks_since_persist >= _PERIODIC_PERSIST_TICKS
            ):
                if truncated:
                    self._emit_diag(
                        "wal_truncated",
                        meeting_id=current_meeting_id,
                        old_size=last_size, new_size=size,
                    )
                self._persist_accumulator_now(
                    current_meeting_id,
                    reason="truncated" if truncated else "periodic",
                )

        if changed:
            self._write_tracking(active_ts=now)
            # On IDLE -> ACTIVE we ask detection to ignore the meeting we
            # just finished generating notes for. Without this the still-
            # resident WAL data from that meeting (huge entry count + still
            # within the recency window) outscores the one or two entries
            # the freshly-starting meeting has produced, and tracking locks
            # onto the wrong id for the rest of the session — the 2026-04-30
            # back-to-back-meeting failure mode.
            #
            # Boundary filter applies in TWO cases (the 2026-04-30 PM lesson):
            #   1. The IDLE -> ACTIVE transition tick (original case).
            #   2. While ACTIVE but with no tracked meeting_id yet — i.e. we
            #      went ACTIVE on a tick where Zoom hadn't written its
            #      `meetingId` token yet, so detection returned None. On
            #      subsequent ticks, while tracking is still empty, the
            #      boundary filter must STILL apply or the just-ended
            #      meeting (whose data is still resident in the WAL) gets
            #      promoted to active and contaminates the new session.
            _, _, _, current_tracking_id = self._read_tracking()
            tracking_is_empty = not current_tracking_id
            apply_boundary = (
                state == EngineState.IDLE
                or (state == EngineState.ACTIVE and tracking_is_empty)
            )
            exclude_id = None
            freshness_floor = None
            if apply_boundary and self._last_completed_boundary is not None:
                exclude_id, freshness_floor = self._last_completed_boundary
            try:
                meeting_id = detect_active_meeting_id(
                    wal,
                    exclude_meeting_id=exclude_id,
                    freshness_floor_secs=freshness_floor,
                )
            except Exception:
                meeting_id = None

            # Blocked-meeting guard: if the detected meeting_id is in the
            # user's block list, refuse the transition entirely and stay IDLE.
            # Normalize by stripping whitespace so copy-pasted IDs with a
            # trailing space or newline still match.
            if meeting_id:
                blocked = [b.strip() for b in getattr(cfg, "blocked_meeting_ids", [])]
                if meeting_id.strip() in blocked:
                    self._emit_diag(
                        "meeting_blocked",
                        meeting_id=meeting_id,
                    )
                    return

            if state == EngineState.IDLE:
                # Stamp the session fingerprint as we enter ACTIVE. `mtime`
                # is the current WAL mtime; combined with meeting_id it lets
                # the post-success dedupe distinguish a recurring meeting's
                # new session from a checkpoint of the one we just finished.
                self._write_tracking(meeting_id=meeting_id, session_mtime=mtime)
                # Only clear the boundary anchor once we've successfully
                # tracked the new meeting. If meeting_id is None here (Zoom
                # hadn't written meetingId yet), keep the boundary in place
                # so subsequent ACTIVE-with-empty-tracking ticks can still
                # apply it.
                if meeting_id:
                    self._last_completed_boundary = None
                # Fresh ACTIVE period — restart the periodic-persist clock so
                # we don't immediately force a snapshot on the very first
                # change tick before the accumulator has any new content.
                self._ticks_since_persist = 0
                with self._accumulated_lock:
                    # Seed from any persisted snapshot so a mid-meeting engine
                    # restart doesn't lose entries collected before the restart.
                    # Validate every entry's meeting_id matches — guards against
                    # a mismatched snapshot ever poisoning the accumulator.
                    self._accumulated = {}
                    if meeting_id:
                        persisted = load_persisted_accumulator(meeting_id)
                        if persisted:
                            # Only seed from a snapshot written today — a prior-day
                            # snapshot is kept for manual recovery but must not
                            # auto-load into a fresh live session.  Loading it would
                            # cause Case-B abandoned-meeting logic to fire with stale
                            # data and generate notes for the wrong (yesterday's)
                            # meeting instead of the one that just started.
                            slug = _safe_meeting_id_slug(meeting_id)
                            snap_path = _CACHE_DIR / f"in-progress-{slug}.json"
                            try:
                                snap_mtime = datetime.fromtimestamp(snap_path.stat().st_mtime)
                                age_hours = (datetime.now() - snap_mtime).total_seconds() / 3600
                                is_recent = age_hours < 4
                            except OSError:
                                is_recent = True  # no stat → treat as safe to load
                            if is_recent:
                                self._accumulated = {
                                    k: v for k, v in persisted.items()
                                    if not v.get("meeting_id") or v.get("meeting_id") == meeting_id
                                }
                            else:
                                # Snapshot is stale (>4 h old) — a prior-day or
                                # earlier same-day occurrence of a recurring meeting.
                                # Delete it so the failed/ recovery item (if any) is
                                # also cleaned up, and start with an empty accumulator.
                                delete_persisted_accumulator(meeting_id)
                    acc_size = len(self._accumulated)
                self._emit_diag(
                    "meeting_id_changed",
                    from_id=None, to_id=meeting_id or "",
                    reason="idle_to_active", seeded_from_snapshot=acc_size > 0,
                )
                self._set_state(
                    EngineState.ACTIVE,
                    meeting_id=meeting_id or "",
                    accumulator_size=acc_size,
                )
            elif state == EngineState.ACTIVE and meeting_id:
                # Re-evaluate the active meeting ID on every tick. Two distinct
                # cases to handle:
                #
                # (A) Upgrade-from-empty: tracking is currently empty (because
                #     IDLE -> ACTIVE happened before Zoom wrote `meetingId`),
                #     and detection has now produced a real id. Adopt it
                #     WITHOUT clearing the accumulator — the entries we
                #     captured during the empty-tracking window are real
                #     for this same meeting; their `meeting_id` field was
                #     just None at parse time. The generation-time filter
                #     keeps no-id entries alongside matching-id entries.
                #     This is the 2026-04-30 PM Brand Team Meeting fix.
                #
                # (B) Meeting actually changed: tracking has a real id but
                #     the WAL now scores a different one as best. A new
                #     meeting started while the old one's data was still
                #     in the WAL — switch and clear the accumulator so the
                #     two don't mix.
                if tracking_is_empty:
                    # Case A: upgrade without clearing.
                    self._write_tracking(meeting_id=meeting_id, session_mtime=mtime)
                    self._last_completed_boundary = None
                    with self._accumulated_lock:
                        # Stamp the late-arriving meeting_id onto any entries
                        # that lacked one so they survive the strict filter
                        # at generation time even if anything later changes
                        # the inclusion rules.
                        for entry in self._accumulated.values():
                            if not entry.get("meeting_id"):
                                entry["meeting_id"] = meeting_id
                        acc_size = len(self._accumulated)
                    self._emit_diag(
                        "meeting_id_changed",
                        from_id="", to_id=meeting_id,
                        reason="upgrade_from_empty",
                        accumulator_preserved=True,
                    )
                    self._set_state(
                        EngineState.ACTIVE,
                        meeting_id=meeting_id,
                        accumulator_size=acc_size,
                    )
                elif meeting_id != current_tracking_id:
                    # If the newly detected meeting_id is blocked, don't
                    # perform the Case B transition — stay on the current
                    # tracked meeting (or let idle detection handle it).
                    _blocked_ids = [b.strip() for b in getattr(cfg, "blocked_meeting_ids", [])]
                    if meeting_id.strip() in _blocked_ids:
                        self._emit_diag(
                            "meeting_blocked",
                            meeting_id=meeting_id,
                            context="case_b",
                        )
                    else:
                        # Case B: real meeting change. Two sub-scenarios:
                        #
                        #   1) BACK-TO-BACK MEETINGS: the previous meeting really
                        #      happened, has a real accumulator with real
                        #      conversation. Auto-generate its note now (the
                        #      2026-05-04 AEO GA fix) before clearing local
                        #      state. Runs in a background thread so the new
                        #      meeting's tracking proceeds without delay.
                        #
                        #   2) MISIDENTIFICATION: scoring just corrected itself
                        #      after briefly tracking the wrong meeting (the
                        #      original 2026-04-30 reason this branch existed).
                        #      Accumulator is small / has no real speakers.
                        #      Discard as before — generating a note from
                        #      misidentified noise wastes an LLM call and
                        #      produces a confusing artifact.
                        #
                        # `_abandoned_looks_real` is the gate between the two.
                        with self._accumulated_lock:
                            abandoned_snapshot = dict(self._accumulated)
                        # Gate on entries that *explicitly* belong to the
                        # abandoned meeting_id. The full snapshot may contain
                        # early utterances from the new meeting whose WAL pages
                        # haven't established a meeting_id context yet
                        # (meeting_id=None). Including them inflates the count
                        # and causes false-positives where a stale meeting +
                        # 3 new-meeting utterances triggers abandoned generation.
                        strict_snapshot = {
                            k: v for k, v in abandoned_snapshot.items()
                            if v.get("meeting_id") == current_tracking_id
                        }
                        if self._abandoned_looks_real(strict_snapshot):
                            self._trigger_abandoned_generation(
                                current_tracking_id, abandoned_snapshot,
                            )
                            # Note: do NOT delete_persisted_accumulator here —
                            # _trigger_abandoned_generation persists a fresh
                            # snapshot synchronously and cleans up after itself
                            # on success.
                        else:
                            try:
                                delete_persisted_accumulator(current_tracking_id)
                            except Exception:
                                pass
                        self._write_tracking(meeting_id=meeting_id, session_mtime=mtime)
                        with self._accumulated_lock:
                            self._accumulated = {}
                        self._emit_diag(
                            "meeting_id_changed",
                            from_id=current_tracking_id, to_id=meeting_id,
                            reason="active_reevaluation",
                            abandoned_snapshot_size=len(abandoned_snapshot),
                            strict_snapshot_size=len(strict_snapshot),
                            abandoned_auto_generated=self._abandoned_looks_real(strict_snapshot),
                        )
                        self._set_state(
                            EngineState.ACTIVE,
                            meeting_id=meeting_id,
                            accumulator_size=0,
                        )

            # Snapshot new entries into the accumulator on every change tick.
            # No meeting_id_filter here — we accumulate everything and filter
            # at generation time. This prevents a stale meeting ID (detected
            # at IDLE→ACTIVE when old data was still in the WAL) from causing
            # new utterances to be silently dropped.
            try:
                _, _, _, current_meeting_id = self._read_tracking()
                fresh = parse_transcript(wal)
                changed_in_acc = False
                with self._accumulated_lock:
                    _today_str = datetime.now().strftime("%Y-%m-%d")
                    for entry in fresh:
                        mid_key = entry["msg_id"]
                        if mid_key not in self._accumulated:
                            entry["_session_date"] = _today_str
                            self._accumulated[mid_key] = entry
                            changed_in_acc = True
                        else:
                            existing = self._accumulated[mid_key]
                            # Cross-meeting guard (the 2026-05-04 Quick Chat
                            # incident): if the fresh parse claims this msg_id
                            # belongs to a different meeting than the one we
                            # already have stamped on the accumulated entry,
                            # treat the fresh metadata as untrustworthy and
                            # skip the speaker/timestamp overwrites. The
                            # `meeting_id` field is already protected by the
                            # `not existing.get("meeting_id")` clause below;
                            # without this guard, a parse_transcript run that
                            # leaked metadata from an adjacent corrupted-
                            # boundary entry could rewrite the speaker and
                            # timestamp of an entry already stamped to the
                            # active session via Case A upgrade-from-empty.
                            fresh_mid = entry.get("meeting_id")
                            existing_mid = existing.get("meeting_id")
                            mid_conflict = bool(fresh_mid) and bool(existing_mid) \
                                and fresh_mid != existing_mid

                            if len(entry.get("text", "")) > len(existing.get("text", "")):
                                existing["text"] = entry["text"]
                                changed_in_acc = True
                            if not mid_conflict:
                                if entry.get("speaker") and entry["speaker"] != "Unknown" \
                                   and existing.get("speaker") != entry["speaker"]:
                                    existing["speaker"] = entry["speaker"]
                                    changed_in_acc = True
                                if entry.get("timestamp") and existing.get("timestamp") != entry["timestamp"]:
                                    existing["timestamp"] = entry["timestamp"]
                                    changed_in_acc = True
                            if entry.get("meeting_id") and not existing.get("meeting_id"):
                                existing["meeting_id"] = entry["meeting_id"]
                                changed_in_acc = True
                # Persist on any change (new entry, longer text, speaker fix,
                # timestamp update). Speaker corrections and timestamp fills
                # matter for retry just as much as new utterances.
                if changed_in_acc and current_meeting_id:
                    self._persist_accumulator_now(current_meeting_id, reason="changed")
                if changed_in_acc:
                    self._last_acc_changed_wall_time = time.monotonic()

                # Empty-parse streak: WAL moved (mtime/size) but the parser
                # found nothing new. Reset on real changes; emit a diag at
                # threshold so a degraded session shows up in logs.
                if changed_in_acc:
                    self._empty_parse_streak = 0
                else:
                    self._empty_parse_streak += 1
                    if self._empty_parse_streak in (5, 20, 60):
                        self._emit_diag(
                            "empty_parse_streak",
                            count=self._empty_parse_streak,
                            meeting_id=current_meeting_id or "",
                        )
            except Exception as exc:
                # Previously a silent `pass`. Surface as a diag event so
                # parser regressions are visible in logs without users
                # having to recreate the issue.
                self._emit_diag(
                    "parse_error",
                    error=str(exc)[:200],
                    meeting_id=(self._read_tracking()[3] or ""),
                )

            # Secondary idle trigger: fire generation when the accumulator
            # has been frozen for a long time even though the WAL file is
            # still being updated by Zoom checkpoint writes. This is the
            # "Jose Ocando" failure mode — meeting ends, Zoom keeps the WAL
            # alive overnight with periodic checkpoint writes, the normal
            # idle clock never elapses because `changed` stays True.
            # Threshold is max(3× idle_threshold, 5 min) so a brief
            # mid-meeting Notetaker pause doesn't trigger prematurely.
            if (
                state == EngineState.ACTIVE
                and self._last_acc_changed_wall_time is not None
            ):
                acc_stale_secs = time.monotonic() - self._last_acc_changed_wall_time
                acc_stale_threshold = max(idle_threshold * 3, 5 * 60)
                if acc_stale_secs >= acc_stale_threshold:
                    _, _, _, _stale_mid = self._read_tracking()
                    if _stale_mid:
                        with self._accumulated_lock:
                            _has_content = any(
                                e.get("meeting_id") == _stale_mid
                                for e in self._accumulated.values()
                            )
                        if _has_content:
                            _provider = cfg.llm_provider
                            if _provider != "ollama":
                                from zoom_config import get_api_key as _ak
                                if not _ak(_provider):
                                    return
                            self._emit_diag(
                                "acc_stale_trigger",
                                meeting_id=_stale_mid,
                                acc_stale_secs=int(acc_stale_secs),
                                threshold=acc_stale_threshold,
                            )
                            self._trigger_generate(origin, cfg)
                            return

        else:
            if state == EngineState.ACTIVE and last_active_ts is not None:
                idle_secs = now - last_active_ts
                if idle_secs >= idle_threshold:
                    # Belt-and-suspenders: don't re-summarize a meeting we
                    # already finished. Zoom checkpoints the WAL after the
                    # meeting ends, which mutates mtime/size and would
                    # otherwise look like a new active period.
                    #
                    # The fingerprint is (meeting_id, session_start_mtime).
                    # Using just meeting_id wrongly suppresses recurring
                    # meetings that reuse the same Zoom ID across days —
                    # those re-enter IDLE→ACTIVE with a new mtime and so
                    # produce a different fingerprint. A checkpoint-only
                    # mutation keeps the same session_start_mtime (which
                    # was captured at IDLE→ACTIVE, not on every tick) and
                    # so still matches.
                    _, _, _, current_meeting_id = self._read_tracking()
                    current_session_mtime = self._read_session_mtime()
                    if current_meeting_id is not None and \
                       current_session_mtime is not None and \
                       self._last_generated_session is not None and \
                       (current_meeting_id, current_session_mtime) == self._last_generated_session:
                        self._write_tracking(active_ts=None)
                        self._set_state(EngineState.IDLE)
                        return

                    # Late-joiner / WAL-noise gate. WAL filesystem activity
                    # alone (you joining the room, Notetaker initializing,
                    # Zoom checkpoints, presence updates) can elapse the
                    # idle threshold without producing any real transcript
                    # entries for the active meeting. Triggering generation
                    # in that state would either:
                    #   - hand the LLM whatever stale cross-meeting data
                    #     the WAL still has (the 2026-04-29 contamination
                    #     where an Anna Punihaole [13:07:23] fragment from
                    #     a meeting hours earlier ended up as an entire
                    #     "Mike Nick" note), or
                    #   - fail with "No transcript entries found." now
                    #     that we've removed the unfiltered fallback in
                    #     _collect_entries_for_generation.
                    # Either way: don't trigger. Disarm and return to IDLE;
                    # the next genuine WAL change will re-arm us, and as
                    # soon as the late participant speaks, the accumulator
                    # will hold a real entry for the active meeting and the
                    # gate will open on the following idle elapse.
                    if current_meeting_id:
                        with self._accumulated_lock:
                            has_real_content = any(
                                e.get("meeting_id") == current_meeting_id
                                for e in self._accumulated.values()
                            )
                        if not has_real_content:
                            self._emit_diag(
                                "idle_trigger_skipped_no_content",
                                meeting_id=current_meeting_id,
                                idle_secs=int(idle_secs),
                                accumulator_size=len(self._accumulated),
                            )
                            self._write_tracking(active_ts=None)
                            self._set_state(EngineState.IDLE)
                            return

                    provider = cfg.llm_provider
                    if provider != "ollama":
                        from zoom_config import get_api_key as _get_key
                        if not _get_key(provider):
                            emit({"event": "error", "message": f"No API key set for {provider}. Open Settings to configure."})
                            self._write_tracking(active_ts=None)  # disarm until WAL changes again
                            return
                    self._trigger_generate(origin, cfg)

    # ── Note generation ─────────────────────────────────────────────────────

    def _trigger_generate(self, origin, cfg) -> None:
        """Start note generation in a background thread (non-blocking).

        Wraps the work in a ThreadPoolExecutor so we can cap wall-clock time at
        _GENERATE_TIMEOUT_SECS — a stuck LLM call must not pin the engine to
        the GENERATING state forever.
        """
        if not self._generating_lock.acquire(blocking=False):
            return

        self._set_state(EngineState.GENERATING)

        # Snapshot tracking state under-lock so a restore-on-error can put us
        # back in a coherent ACTIVE-but-disarmed state.
        saved_mtime, saved_size, _, _ = self._read_tracking()

        # Snapshot the meeting_id and session-start mtime we're processing
        # so the worker can stamp the success fingerprint even after
        # _reset_tracking has cleared the live tracking state.
        _, _, _, processing_meeting_id = self._read_tracking()
        processing_session_mtime = self._read_session_mtime()

        # Reset the per-run note_failed flag so the worker can detect whether
        # _generate_notes wrote a placeholder (LLM failure) or a final note.
        self._last_run_note_failed = False

        # Reset cancellation so this run starts clean. Any cancel signal
        # raised below targets THIS generation only.
        self._cancel_event.clear()

        def worker():
            executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
            future = executor.submit(self._generate_notes, origin, cfg)
            try:
                future.result(timeout=_GENERATE_TIMEOUT_SECS)
                # Remember which session we just processed so we don't
                # re-trigger if Zoom mutates the WAL on checkpoint. We do
                # this even on note_failed — the user retries via the menu
                # bar, not by waiting for another idle period.
                if processing_meeting_id and processing_session_mtime is not None:
                    self._last_generated_session = (
                        processing_meeting_id, processing_session_mtime
                    )
                # Stamp the boundary anchor: the latest transcript timestamp
                # we just summarized. The next IDLE -> ACTIVE will pass this
                # to `detect_active_meeting_id` so the just-completed
                # meeting (whose entries are still resident in the WAL)
                # cannot be re-detected as the new active meeting.
                if processing_meeting_id:
                    latest = self._latest_acc_ts_secs_for(processing_meeting_id)
                    if latest is not None:
                        self._last_completed_boundary = (processing_meeting_id, latest)
                # Clean up the in-memory accumulator. Keep the persisted
                # disk snapshot if note generation failed — it's the source
                # of truth for the retry flow.
                with self._accumulated_lock:
                    self._accumulated = {}
                if processing_meeting_id and not self._last_run_note_failed:
                    delete_persisted_accumulator(processing_meeting_id)
                self._wal_gone_since = None
                # Anchor tracking to the WAL state we just consumed. We must
                # NOT reset to None — that would make the next poll see the
                # unchanged WAL as "new", flip back to ACTIVE, idle out, and
                # regenerate the same notes in a loop.
                #
                # Re-stat now so we capture any final writes Zoom did during
                # the generation window; if the meeting really is over the
                # next poll's mtime/size will match these and `changed`
                # stays False until a NEW meeting starts.
                try:
                    wal = self._resolve_wal(origin, cfg, "transcript")
                    if wal is not None:
                        s = wal.stat()
                        self._write_tracking(
                            mtime=s.st_mtime, size=s.st_size,
                            active_ts=None, meeting_id=None,
                        )
                    else:
                        # WAL disappeared entirely — meeting fully checkpointed.
                        # Safe to reset; there's nothing to re-trigger on.
                        self._reset_tracking()
                except OSError:
                    self._reset_tracking()
            except concurrent.futures.TimeoutError:
                emit({"event": "error", "message": "Note generation timed out — try again"})
                # future.cancel() is a no-op once the work has started, so
                # signal cooperative cancellation. The summarize() thread
                # will observe this between retries / during backoff sleep
                # and bail out with CancelledError. Worst-case latency is
                # bounded by the urllib per-call timeout (_HTTP_TIMEOUT_SECS).
                self._cancel_event.set()
                future.cancel()
                self._write_tracking(
                    mtime=saved_mtime, size=saved_size,
                    active_ts=None, meeting_id=None,
                )
                self._wal_gone_since = None
            except Exception as exc:
                emit({"event": "error", "message": _friendly_error(exc)})
                self._write_tracking(
                    mtime=saved_mtime, size=saved_size,
                    active_ts=None, meeting_id=None,
                )
                self._wal_gone_since = None
            finally:
                executor.shutdown(wait=False)
                self._generating_lock.release()
                self._set_state(EngineState.IDLE)

        threading.Thread(target=worker, daemon=True).start()

    def _generate_notes(self, origin, cfg) -> None:
        """Three-stage finalization: build transcript, save transcript, generate note.

        Save-transcript is the durability boundary — once it succeeds, the
        meeting's content is safe on disk regardless of what happens to the
        LLM call. LLM failures produce a placeholder note (saved alongside
        the transcript) and a retryable `note_failed` event, NOT a hard error.
        """
        gen_start = time.monotonic()
        transcript_wal = self._resolve_wal(origin, cfg, "transcript")
        blocks_wal = self._resolve_wal(origin, cfg, "blocks")

        _, _, _, active_meeting_id = self._read_tracking()

        entries, recovered_meeting_id = self._collect_entries_for_generation(
            transcript_wal, active_meeting_id
        )
        # If self-heal recovered a different meeting_id, treat it as the
        # canonical id from here on. Update tracking so the post-success
        # boundary anchor + frontmatter + diag events all reflect what
        # actually got summarized — not the misidentified id we entered
        # generation with.
        if recovered_meeting_id and recovered_meeting_id != active_meeting_id:
            self._emit_diag(
                "active_id_self_healed",
                from_id=active_meeting_id or "",
                to_id=recovered_meeting_id,
                entry_count=len(entries),
            )
            self._write_tracking(meeting_id=recovered_meeting_id)
            active_meeting_id = recovered_meeting_id

        if not transcript_wal and not entries:
            raise RuntimeError("Transcript WAL not found during generation.")

        if not entries:
            raise RuntimeError("No transcript entries found.")

        # Refuse to generate a note from a near-empty transcript — this
        # catches recurring meetings (static meeting_id) whose Notetaker
        # only captured a brief opening monologue before the WAL went
        # quiet. Threshold matches _abandoned_looks_real for consistency.
        entries_by_id = {e.get("msg_id", str(i)): e for i, e in enumerate(entries)}
        if not self._abandoned_looks_real(entries_by_id):
            emit({
                "event": "error",
                "message": (
                    f"Skipped note generation — only {len(entries)} transcript "
                    f"entr{'y' if len(entries) == 1 else 'ies'} found "
                    f"(minimum 5 with at least one identified speaker required)."
                ),
            })
            return

        cfg = self._get_cfg()

        meeting_title = self._derive_meeting_title(blocks_wal, transcript_wal, entries)
        date_match = re.search(r"(\d{4}-\d{2}-\d{2})", meeting_title)
        date_str = date_match.group(1) if date_match else datetime.now().strftime("%Y-%m-%d")

        seen: dict[str, None] = {}
        for e in entries:
            s = e["speaker"]
            if s and s != "Unknown":
                seen[s] = None
        attendees = list(seen.keys())

        created_iso = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
        transcript_text = format_transcript(entries)

        # When neither Apple Calendar nor the blocks WAL could supply a title,
        # _derive_meeting_title falls back to "Zoom Meeting YYYY-MM-DD HH:MM".
        # Ask the LLM for a short descriptive title instead.
        if meeting_title.startswith("Zoom Meeting "):
            ai_title = generate_title(transcript_text, cfg)
            if ai_title:
                meeting_title = ai_title
                date_match = re.search(r"(\d{4}-\d{2}-\d{2})", meeting_title)
                if not date_match:
                    date_str = datetime.now().strftime("%Y-%m-%d")

        # ── Stage 1: save transcript (durability boundary) ─────────────────
        # Thread `active_meeting_id` through so a same-day same-title
        # collision (e.g. two unrelated Zoom calls that both slug to
        # "Daily Standup" because the second one had no AI Notetaker
        # title) lands as a `-2` sibling instead of clobbering the first
        # meeting's note. The 2026-04-30 incident was exactly this:
        # a follow-up 1:1 wiped the morning standup's saved note.
        #
        # The note_link in the transcript content will be corrected once we
        # know the actual note path (Stage 3). Write a best-guess link now
        # so the file is immediately useful even in the failure path.
        transcript_content = build_transcript_content(
            transcript_text, meeting_title, date_str, cfg,
            meeting_id=active_meeting_id,
        )
        transcript_path = save_transcript_only(
            transcript_content, meeting_title, date_str, cfg,
            meeting_id=active_meeting_id,
        )
        slug = slugify_title(meeting_title, fallback_date=date_str)

        # Actual transcript link derived from the file that was just saved.
        # This accounts for any -2/-3 suffix that _resolve_save_path assigned.
        actual_transcript_link = _path_to_vault_link(transcript_path, cfg, "transcript", date_str)

        # ── Stage 2: generate note via LLM ─────────────────────────────────
        try:
            summary = summarize(
                transcript_text, meeting_title, cfg, cancel_event=self._cancel_event
            )
        except CancelledError:
            # A cancelled run leaves the transcript on disk (Stage 1 already
            # ran) and the persisted accumulator intact for retry. We do NOT
            # write a placeholder — a cancellation note in the user's vault
            # would be confusing noise.
            #
            # We DO emit note_failed so the menu bar shows an in-session retry
            # item immediately (not just at the next launch). Guard against a
            # new meeting having started while the LLM was timing out — if the
            # engine is no longer IDLE, skip the emit to avoid flipping the
            # active meeting's displayed state to idle.
            self._last_run_note_failed = True
            _title_slug = slugify_title(meeting_title, fallback_date=date_str)
            failed_meta = {
                "meeting_id": active_meeting_id or "",
                "title": _title_slug,
                "note_path": "",
                "transcript_path": str(transcript_path),
                "message": "API call timed out — the LLM took too long to respond",
                "date_str": date_str,
                "attendees": attendees,
            }
            self._last_failed_meeting = failed_meta
            if active_meeting_id:
                mark_meeting_failed(active_meeting_id, metadata=failed_meta)
            if self._get_state() == EngineState.IDLE:
                emit({
                    "event": "note_failed",
                    "title": _title_slug,
                    "meeting_id": active_meeting_id or "",
                    "note_path": "",
                    "transcript_path": str(transcript_path),
                    "message": failed_meta["message"],
                    "attendees": attendees,
                })
            return
        except Exception as exc:
            error_msg = _friendly_error(exc)
            placeholder = build_placeholder_note(
                meeting_title=meeting_title,
                date_str=date_str,
                attendees=attendees,
                created_iso=created_iso,
                error_message=error_msg,
                meeting_id=active_meeting_id or "",
                cfg=cfg,
                transcript_link_override=actual_transcript_link,
            )
            placeholder_path = save_note_only(
                placeholder, meeting_title, date_str, cfg,
                meeting_id=active_meeting_id,
            )
            # Update transcript with the actual note link now that we know where it landed.
            actual_note_link = _path_to_vault_link(placeholder_path, cfg, "note", date_str)
            updated_transcript = build_transcript_content(
                transcript_text, meeting_title, date_str, cfg,
                meeting_id=active_meeting_id,
                note_link_override=actual_note_link,
            )
            _atomic_write_text(transcript_path, updated_transcript)
            self._last_run_note_failed = True
            failed_record = {
                "meeting_id": active_meeting_id or "",
                "title": slug,
                "note_path": str(placeholder_path),
                "transcript_path": str(transcript_path),
                "message": error_msg,
                "date_str": date_str,
                "attendees": attendees,
            }
            self._last_failed_meeting = failed_record
            # Promote the snapshot from root cache into `failed/` so the
            # 30-day purge applies (instead of 24h) and the menu bar can
            # surface a labeled recovery item even after a long delay.
            # This MUST run before the worker's post-_generate_notes
            # cleanup — that block keeps the root snapshot intact only
            # while `_last_run_note_failed` is True; promoting it here
            # means root is empty afterward and `failed/` owns the data.
            if active_meeting_id:
                mark_meeting_failed(active_meeting_id, metadata=failed_record)
            emit({
                "event": "note_failed",
                "title": slug,
                "note_path": str(placeholder_path),
                "transcript_path": str(transcript_path),
                "meeting_id": active_meeting_id or "",
                "attendees": attendees,
                "message": error_msg,
            })
            return

        # ── Stage 3: save the final note ───────────────────────────────────
        note_content = build_note_content(
            summary, meeting_title, date_str, attendees, created_iso, cfg,
            meeting_id=active_meeting_id,
            transcript_link_override=actual_transcript_link,
        )
        note_path = save_note_only(
            note_content, meeting_title, date_str, cfg,
            meeting_id=active_meeting_id,
        )

        # Update transcript with the actual note link now that we know where it landed.
        actual_note_link = _path_to_vault_link(note_path, cfg, "note", date_str)
        updated_transcript = build_transcript_content(
            transcript_text, meeting_title, date_str, cfg,
            meeting_id=active_meeting_id,
            note_link_override=actual_note_link,
        )
        _atomic_write_text(transcript_path, updated_transcript)

        emit({
            "event": "done",
            "title": slug,
            "path": str(note_path),
            "transcript_path": str(transcript_path),
            "attendees": attendees,
            "meeting_id": active_meeting_id or "",
        })

        # Diag: how long did this take, how big was the transcript, which
        # provider/model. Useful for spotting regressions ("LLM is slow this
        # week") without instrumenting the user's machine further.
        self._emit_diag(
            "generation_completed",
            duration_ms=int((time.monotonic() - gen_start) * 1000),
            entry_count=len(entries),
            attendee_count=len(attendees),
            provider=cfg.llm_provider,
            model=cfg.llm_model,
            meeting_id=active_meeting_id or "",
        )

    def _collect_entries_for_generation(self, transcript_wal, active_meeting_id):
        """Pick the best entries source: in-memory accumulator > WAL > disk snapshot.

        Filter by active_meeting_id at this stage (not at poll time) so a stale
        ID at IDLE→ACTIVE transition never silently drops new utterances.

        Three-way decision when the strict filter returns 0 entries (the
        2026-04-30 lesson):

          1) The accumulator contains real content for ANOTHER meeting whose
             entries are at least as recent as the active session window —
             this means tracking misidentified the active meeting (e.g. it
             locked onto the just-ended meeting because its data was still
             resident at IDLE -> ACTIVE). Recompute `active_meeting_id` from
             accumulator content (most-common meeting_id among entries
             whose timestamp is on or after the engine's session-start
             wall-clock), and use those entries. Returns
             `(entries, recovered_meeting_id)` so the caller can update
             tracking + frontmatter to match.

          2) The accumulator only holds stale entries (timestamps before
             session start, or no meeting_id matches) — the late-joiner gate
             upstream should have caught this, but be defensive: return
             `([], None)`.

          3) No accumulator at all — fall back to parse_transcript or the
             persisted snapshot, same as before.

        Entries with no meeting_id are kept: those are early WAL pages that
        haven't yet attached a meetingId field, and dropping them would lose
        real opening utterances from the active meeting. This mirrors the
        same rule `persist_accumulator` already applies at the disk boundary.
        """
        with self._accumulated_lock:
            acc_snapshot = dict(self._accumulated)

        if acc_snapshot:
            # Self-heal first when we have no tracked meeting_id (the
            # 2026-04-30 PM scenario: Zoom wrote `meetingId` so late that
            # both IDLE -> ACTIVE detection and the upgrade-from-empty
            # tick missed it). Without this branch, the `else` path below
            # used to return EVERY accumulator entry — including stale
            # cross-day fragments like Anna Punihaole's [13:07:23] from
            # yesterday — which then poisoned title parsing and the LLM
            # input. With this branch we recover the right id from
            # accumulator content (most-common id with a session-fresh
            # timestamp); if we can't, we return an empty list rather
            # than gambling on stale content.
            if not active_meeting_id:
                recovered = self._recover_active_meeting_id(acc_snapshot)
                if recovered:
                    recovered_entries = [
                        e for e in acc_snapshot.values()
                        if e.get("meeting_id") == recovered
                        or not e.get("meeting_id")
                    ]
                    recovered_entries.sort(key=lambda e: e.get("timestamp") or "")
                    return recovered_entries, recovered
                # No anchor or no fresh-enough id found. Better to fail
                # cleanly than to summarize yesterday's Anna fragment.
                return [], None

            # Compute the session-start floor for anonymous entries.
            # Entries with no meeting_id are early WAL pages whose meetingId
            # field hadn't been written yet. We keep them — but only if their
            # transcript timestamp falls at or after the session start (with a
            # 5-minute look-back for clock skew / late ACTIVE detection). This
            # evicts stale anonymous entries from a prior meeting that are still
            # resident in the WAL after an accumulator reset, without dropping
            # real opening utterances from the current session.
            session_mtime = self._read_session_mtime()
            if session_mtime is not None:
                session_floor_secs = self._wallclock_secs_from_mtime(session_mtime) - 5 * 60
                _now_local = datetime.now()
                _now_secs = _now_local.hour * 3600 + _now_local.minute * 60 + _now_local.second
                _today_date = _now_local.strftime("%Y-%m-%d")
                _ANON_FUTURE_BUF = 5 * 60  # 5-minute buffer for clock skew / batch writes

                def _anon_entry_is_fresh(e: dict) -> bool:
                    # Reject entries from a prior calendar day.
                    sd = e.get("_session_date")
                    if sd and sd != _today_date:
                        return False
                    ts = e.get("timestamp")
                    if not ts:
                        return True  # no timestamp → keep (can't reject safely)
                    try:
                        parts = [int(x) for x in ts.split(":")]
                        if len(parts) != 3:
                            return True
                        secs = parts[0] * 3600 + parts[1] * 60 + parts[2]
                        # Must be at or after session start (with look-back buffer)
                        # AND must not be suspiciously ahead of current wall time.
                        # Stale WAL entries from an earlier meeting (e.g. 14:55 in
                        # a session that started at 12:16) fail the upper bound.
                        return secs >= session_floor_secs and secs <= _now_secs + _ANON_FUTURE_BUF
                    except ValueError:
                        return True
            else:
                def _anon_entry_is_fresh(e: dict) -> bool:  # type: ignore[misc]
                    return True

            acc_entries = [
                e for e in acc_snapshot.values()
                if e.get("meeting_id") == active_meeting_id
                or (not e.get("meeting_id") and _anon_entry_is_fresh(e))
            ]
            if not acc_entries:
                # Self-heal path #2: tracking has the wrong meeting_id
                # (e.g. trapped on a just-ended meeting). Pick the
                # most-common meeting_id in the accumulator that has
                # at least one timestamp at or after session start,
                # and return THOSE entries. Caller is expected to
                # update tracking + frontmatter to the recovered id.
                recovered = self._recover_active_meeting_id(acc_snapshot)
                if recovered:
                    recovered_entries = [
                        e for e in acc_snapshot.values()
                        if e.get("meeting_id") == recovered
                        or (not e.get("meeting_id") and _anon_entry_is_fresh(e))
                    ]
                    recovered_entries.sort(key=lambda e: e.get("timestamp") or "")
                    return recovered_entries, recovered
                return [], None
            return sorted(acc_entries, key=lambda e: e.get("timestamp") or ""), active_meeting_id

        if transcript_wal:
            return parse_transcript(transcript_wal, meeting_id_filter=active_meeting_id), active_meeting_id

        if active_meeting_id:
            persisted = load_persisted_accumulator(active_meeting_id)
            if persisted:
                return sorted(
                    persisted.values(), key=lambda e: e.get("timestamp") or ""
                ), active_meeting_id

        return [], active_meeting_id

    def _recover_active_meeting_id(self, acc_snapshot: dict) -> str | None:
        """Pick the meeting_id most plausibly matching the active session.

        Strategy: count entries by meeting_id, restrict to ids whose latest
        timestamp is at or after the engine's session start mtime (HH:MM:SS
        wall-clock). Among those, return the one with the most entries.

        Returns None if (a) we have no session-start anchor (engine isn't
        ACTIVE), or (b) no meeting_id in the accumulator has a fresh-enough
        timestamp. Without an anchor we can't tell stale from fresh, so we
        refuse to "recover" — better to return no entries than to gamble.
        """
        session_mtime = self._read_session_mtime()
        if session_mtime is None:
            return None
        session_floor_secs = self._wallclock_secs_from_mtime(session_mtime)

        # Group entries by meeting_id, tracking max-ts per group.
        # Skip entries from prior calendar days (defence-in-depth alongside
        # the is_today check on persisted snapshot files at IDLE→ACTIVE seed).
        from collections import Counter
        _now_r = datetime.now()
        _today_r = _now_r.strftime("%Y-%m-%d")
        _now_secs_r = _now_r.hour * 3600 + _now_r.minute * 60 + _now_r.second
        counts: Counter[str] = Counter()
        max_ts: dict[str, int] = {}
        for e in acc_snapshot.values():
            mid = e.get("meeting_id")
            if not mid:
                continue
            # Entries tagged from a prior calendar day are stale WAL residue.
            sd = e.get("_session_date")
            if sd and sd != _today_r:
                continue
            counts[mid] += 1
            ts = e.get("timestamp")
            if ts:
                try:
                    parts = [int(x) for x in ts.split(":")]
                    if len(parts) == 3:
                        secs = parts[0] * 3600 + parts[1] * 60 + parts[2]
                        if secs > max_ts.get(mid, -1):
                            max_ts[mid] = secs
                except ValueError:
                    pass

        # Eligibility: entry must be at or after session start AND must not
        # be suspiciously far ahead of the current wall clock. The upper-bound
        # check is the core fix for the HH:MM:SS-without-date problem: stale
        # WAL entries from an earlier meeting today (e.g. Michael Huard [14:55]
        # parsed during a 12:16 session) have timestamps numerically > session
        # start but also numerically > now-by-hours. A real in-progress entry
        # can never be more than a few seconds ahead of the current time.
        # The boundary check mirrors detect_active_meeting_id: don't re-select
        # a meeting we just finished generating notes for.
        _FUTURE_BUF_R = 5 * 60
        boundary = self._last_completed_boundary  # (exc_id, freshness_floor) or None

        eligible = []
        for mid in counts:
            ts_secs = max_ts.get(mid, -1)
            if ts_secs < session_floor_secs:
                continue
            if ts_secs > _now_secs_r + _FUTURE_BUF_R:
                continue  # timestamp is impossibly far in the future → stale
            if boundary is not None:
                exc_id, exc_floor = boundary
                if mid == exc_id and ts_secs <= exc_floor:
                    continue  # stale WAL data from the session we just finished
            eligible.append(mid)

        if not eligible:
            return None
        # Of the eligible, pick the one with the most entries.
        eligible.sort(key=lambda m: counts[m], reverse=True)
        return eligible[0]

    @staticmethod
    def _wallclock_secs_from_mtime(mtime: float) -> int:
        """Convert a unix mtime to seconds-since-midnight in the local
        timezone. Used to compare WAL mtimes against transcript HH:MM:SS
        timestamps, which are themselves local-time.
        """
        d = datetime.fromtimestamp(mtime)
        return d.hour * 3600 + d.minute * 60 + d.second

    def _derive_meeting_title(self, blocks_wal, transcript_wal, entries) -> str:
        anchor_entries = [e for e in entries if e.get("meeting_id")] or entries

        # Apple Calendar is the most authoritative source — it has the actual
        # invite name. Try it first. Falls back to None if the sidecar is
        # absent, stale, or no event window overlaps the transcript.
        meeting_title = None
        try:
            meeting_title = read_calendar_title(anchor_entries)
        except Exception:
            pass

        # WAL title as fallback — Zoom's own title detection. Can produce
        # speaker names or "Google Calendar Meeting (not synced)" for meetings
        # where Zoom couldn't read the calendar, but is better than nothing
        # when no calendar event matched.
        if not meeting_title and blocks_wal:
            try:
                meeting_title = parse_meeting_title(blocks_wal, anchor_entries)
            except Exception:
                pass

        if not meeting_title:
            mtime = transcript_wal.stat().st_mtime if transcript_wal else time.time()
            meeting_title = f"Zoom Meeting {datetime.fromtimestamp(mtime).strftime('%Y-%m-%d %H:%M')}"
        return meeting_title

    # ── Stdin reader ────────────────────────────────────────────────────────

    def _stdin_reader(self) -> None:
        """Read JSON commands from stdin line by line."""
        for raw_line in sys.stdin:
            line = raw_line.strip()
            if not line:
                continue
            try:
                cmd = json.loads(line)
            except json.JSONDecodeError:
                continue
            self._handle_command(cmd)

    def _handle_command(self, cmd: dict) -> None:
        action = cmd.get("cmd")
        if action == "reload":
            self._reload_requested = True
        elif action == "generate":
            cfg = self._get_cfg()
            origin = find_origin_dir()
            if origin:
                self._trigger_generate(origin, cfg)
            else:
                emit({"event": "error", "message": "Zoom WAL directory not found."})
        elif action == "retry":
            meeting_id = cmd.get("meeting_id") or ""
            self._trigger_retry(meeting_id)
        elif action == "recover":
            # Recovery is mechanically identical to retry — load the persisted
            # accumulator, re-derive title from blocks WAL, run the LLM,
            # write the note. The distinction is purely intent-level: retry
            # operates on a meeting whose failure was just observed in this
            # engine session; recover operates on one whose failure happened
            # in a prior session and was found at startup.
            meeting_id = cmd.get("meeting_id") or ""
            if not meeting_id:
                emit({"event": "error", "message": "recover command requires meeting_id."})
                return
            self._trigger_retry(meeting_id)
        elif action == "dismiss":
            meeting_id = cmd.get("meeting_id") or ""
            if not meeting_id:
                emit({"event": "error", "message": "dismiss command requires meeting_id."})
                return
            delete_persisted_accumulator(meeting_id)
            emit({"event": "dismissed", "meeting_id": meeting_id})
        elif action == "dismiss_all":
            ids = [r["meeting_id"] for r in self._recoverable_at_startup]
            for mid in ids:
                delete_persisted_accumulator(mid)
                emit({"event": "dismissed", "meeting_id": mid})
        elif action == "clear_cache":
            # Delete every in-progress snapshot from the root cache dir.
            # Leaves failed/ intact — those are deliberate LLM-failure survivors
            # that the user must explicitly discard via the recovery menu.
            count = 0
            if _CACHE_DIR.exists():
                for p in list(_CACHE_DIR.glob("in-progress-*.json")) + list(_CACHE_DIR.glob("in-progress-*.md")):
                    try:
                        p.unlink(missing_ok=True)
                        count += 1
                    except OSError:
                        pass
            emit({"event": "cache_cleared", "count": count})

    # ── Abandoned-meeting auto-generation ───────────────────────────────────

    @staticmethod
    def _abandoned_looks_real(snapshot: dict) -> bool:
        """Decide whether an abandoned accumulator deserves a real note.

        Case B (mid-ACTIVE meeting_id change) fires for two distinct
        scenarios:

          1) BACK-TO-BACK MEETINGS: the previous meeting really happened,
             produced a real transcript, and a new meeting just started.
             We want to generate a note for it (the 2026-05-04 AEO GA bug).

          2) MISIDENTIFICATION: the engine briefly tracked the wrong
             meeting (e.g. stale WAL data still resident at IDLE -> ACTIVE),
             and detection has now corrected itself. The accumulator at
             this point is small and contains no real conversation.

        We only auto-generate when the snapshot looks like (1). Heuristic:
        at least 5 entries AND at least one non-Unknown speaker. Tuned
        conservatively — a 30-second exchange has more than 5 entries,
        and a misidentification typically captures 0-2 utterances before
        Case B fires.
        """
        if len(snapshot) < 5:
            return False
        for entry in snapshot.values():
            speaker = entry.get("speaker")
            if speaker and speaker != "Unknown":
                return True
        return False

    def _trigger_abandoned_generation(self, meeting_id: str, snapshot: dict) -> None:
        """Finalize an accumulator that Case B is about to abandon.

        Mirrors `_trigger_retry` but with three differences that matter for
        the back-to-back-meetings use case:

          - Saves the transcript file (Stage 1 of `_generate_notes`). Retry
            assumes the transcript is already on disk; abandoned generation
            is the FIRST chance to save it.
          - Acquires `_generating_lock` with `blocking=True` so it queues
            behind any in-flight generation instead of being rejected.
          - Does NOT call `self._set_state(EngineState.GENERATING)`. The
            engine is now ACTIVE for a different meeting; flipping to
            GENERATING would freeze polling and lose transcript content
            from the new meeting.

        The caller (Case B in `_poll_once`) is expected to clear the
        in-memory accumulator and switch tracking AFTER calling this — the
        snapshot is captured by-value here, so the caller is free to
        mutate live state immediately.
        """
        if not meeting_id or not snapshot:
            return

        # Persist a fresh snapshot to disk synchronously, BEFORE spawning
        # the worker. If the engine crashes or quits mid-generation, the
        # snapshot is what `find_orphaned_accumulators` will surface for
        # menu-bar recovery on next launch.
        try:
            persist_accumulator(meeting_id, snapshot)
        except Exception:
            pass

        cfg = self._get_cfg()
        snapshot_copy = dict(snapshot)

        def worker():
            # Block until any in-flight generation finishes so two boundary
            # events back-to-back (A -> B -> C in rapid succession) serialize
            # cleanly through one LLM at a time.
            self._generating_lock.acquire(blocking=True)
            try:
                # Filter snapshot to only entries for this meeting_id (or
                # entries with no meeting_id, which are early WAL pages that
                # predate the meetingId field). Without this filter, stale
                # entries from adjacent meetings in the WAL contaminate the
                # title timestamp anchor and produce wrong titles.
                raw_entries = [
                    e for e in snapshot_copy.values()
                    if e.get("meeting_id") == meeting_id or not e.get("meeting_id")
                ]
                entries = sorted(raw_entries, key=lambda e: e.get("timestamp") or "")
                if not entries:
                    return

                # Re-apply the _abandoned_looks_real gate using only entries
                # that *explicitly* carry this meeting_id. The broad
                # raw_entries filter (above) also admits meeting_id=None
                # entries for transcript completeness, but using those here
                # would re-introduce the same false-positive the strict
                # pre-flight check was meant to prevent.
                strict_entries = [e for e in raw_entries if e.get("meeting_id") == meeting_id]
                filtered_snapshot = {e["msg_id"]: e for e in strict_entries if "msg_id" in e}
                if not self._abandoned_looks_real(filtered_snapshot):
                    try:
                        delete_persisted_accumulator(meeting_id)
                    except Exception:
                        pass
                    return

                origin = find_origin_dir()
                blocks_wal = self._resolve_wal(origin, cfg, "blocks") if origin else None
                transcript_wal = self._resolve_wal(origin, cfg, "transcript") if origin else None
                meeting_title = self._derive_meeting_title(blocks_wal, transcript_wal, entries)
                m = re.search(r"(\d{4}-\d{2}-\d{2})", meeting_title)
                date_str = m.group(1) if m else datetime.now().strftime("%Y-%m-%d")

                seen: dict[str, None] = {}
                for e in entries:
                    s = e.get("speaker")
                    if s and s != "Unknown":
                        seen[s] = None
                attendees = list(seen.keys())

                created_iso = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
                transcript_text = format_transcript(entries)

                if meeting_title.startswith("Zoom Meeting "):
                    ai_title = generate_title(transcript_text, cfg)
                    if ai_title:
                        meeting_title = ai_title
                        m2 = re.search(r"(\d{4}-\d{2}-\d{2})", meeting_title)
                        if not m2:
                            date_str = datetime.now().strftime("%Y-%m-%d")

                slug = slugify_title(meeting_title, fallback_date=date_str)

                self._emit_diag(
                    "abandoned_generation_started",
                    meeting_id=meeting_id,
                    entry_count=len(entries),
                    attendee_count=len(attendees),
                )

                # Stage 1: save transcript (durability boundary). Threads
                # `meeting_id` through so a same-day same-title collision
                # lands as a `-2` sibling instead of clobbering an existing
                # note.
                transcript_content = build_transcript_content(
                    transcript_text, meeting_title, date_str, cfg,
                    meeting_id=meeting_id,
                )
                transcript_path = save_transcript_only(
                    transcript_content, meeting_title, date_str, cfg,
                    meeting_id=meeting_id,
                )
                actual_transcript_link = _path_to_vault_link(
                    transcript_path, cfg, "transcript", date_str
                )

                # Stage 2: LLM. Use a fresh cancel event so cancellation
                # signals targeted at the main-meeting generation don't
                # also kill this background one.
                local_cancel = threading.Event()
                try:
                    summary = summarize(
                        transcript_text, meeting_title, cfg,
                        cancel_event=local_cancel,
                    )
                except CancelledError:
                    return
                except Exception as exc:
                    error_msg = _friendly_error(exc)
                    placeholder = build_placeholder_note(
                        meeting_title=meeting_title,
                        date_str=date_str,
                        attendees=attendees,
                        created_iso=created_iso,
                        error_message=error_msg,
                        meeting_id=meeting_id,
                        cfg=cfg,
                        transcript_link_override=actual_transcript_link,
                    )
                    placeholder_path = save_note_only(
                        placeholder, meeting_title, date_str, cfg,
                        meeting_id=meeting_id,
                    )
                    actual_note_link = _path_to_vault_link(
                        placeholder_path, cfg, "note", date_str
                    )
                    updated_transcript = build_transcript_content(
                        transcript_text, meeting_title, date_str, cfg,
                        meeting_id=meeting_id,
                        note_link_override=actual_note_link,
                    )
                    _atomic_write_text(transcript_path, updated_transcript)
                    failed_record = {
                        "meeting_id": meeting_id,
                        "title": slug,
                        "note_path": str(placeholder_path),
                        "transcript_path": str(transcript_path),
                        "message": error_msg,
                        "date_str": date_str,
                        "attendees": attendees,
                    }
                    # Promote into failed/ so the menu bar surfaces a retry
                    # item — same recovery flow as a regular LLM failure.
                    mark_meeting_failed(meeting_id, metadata=failed_record)
                    emit({
                        "event": "note_failed",
                        "title": slug,
                        "note_path": str(placeholder_path),
                        "transcript_path": str(transcript_path),
                        "meeting_id": meeting_id,
                        "attendees": attendees,
                        "message": error_msg,
                    })
                    return

                # Stage 3: save final note.
                note_content = build_note_content(
                    summary, meeting_title, date_str, attendees, created_iso, cfg,
                    meeting_id=meeting_id,
                    transcript_link_override=actual_transcript_link,
                )
                note_path = save_note_only(
                    note_content, meeting_title, date_str, cfg,
                    meeting_id=meeting_id,
                )
                actual_note_link = _path_to_vault_link(note_path, cfg, "note", date_str)
                updated_transcript = build_transcript_content(
                    transcript_text, meeting_title, date_str, cfg,
                    meeting_id=meeting_id,
                    note_link_override=actual_note_link,
                )
                _atomic_write_text(transcript_path, updated_transcript)

                # Stamp boundary anchor so the next IDLE -> ACTIVE pass
                # cannot re-detect this meeting from leftover WAL data.
                latest_ts_secs = -1
                for e in entries:
                    ts = e.get("timestamp") or ""
                    try:
                        parts = [int(x) for x in ts.split(":")]
                        if len(parts) == 3:
                            secs = parts[0] * 3600 + parts[1] * 60 + parts[2]
                            if secs > latest_ts_secs:
                                latest_ts_secs = secs
                    except (ValueError, AttributeError):
                        continue
                if latest_ts_secs >= 0:
                    self._last_completed_boundary = (meeting_id, latest_ts_secs)

                # Cleanup persisted snapshot — the note is now safe on disk.
                delete_persisted_accumulator(meeting_id)

                emit({
                    "event": "done",
                    "title": slug,
                    "path": str(note_path),
                    "transcript_path": str(transcript_path),
                    "attendees": attendees,
                    "meeting_id": meeting_id,
                })
                self._emit_diag(
                    "abandoned_generation_completed",
                    meeting_id=meeting_id,
                    entry_count=len(entries),
                )
            except Exception as exc:
                # Don't lose the snapshot on unexpected error — leave it on
                # disk so menu-bar recovery can surface it next launch.
                emit({"event": "error", "message": _friendly_error(exc)})
            finally:
                self._generating_lock.release()

        threading.Thread(target=worker, daemon=True).start()

    # ── Retry flow ──────────────────────────────────────────────────────────

    def _trigger_retry(self, meeting_id: str) -> None:
        """Re-run note generation for a previously-failed meeting.

        Loads the persisted accumulator from disk, re-runs the LLM stage,
        and overwrites the placeholder note on success. The transcript on
        disk is left as-is. Emits `done` on success or `error` on failure.
        """
        if not self._generating_lock.acquire(blocking=False):
            emit({"event": "error", "message": "Generation already in progress."})
            return

        # Resolve which failed meeting to retry. If the caller didn't pass a
        # meeting_id, use the most recent failure (driven from the menu bar).
        failed = self._last_failed_meeting
        if not meeting_id and failed:
            meeting_id = failed.get("meeting_id") or ""
        if failed and failed.get("meeting_id") != meeting_id:
            failed = None  # caller is retrying a different meeting

        if not meeting_id:
            self._generating_lock.release()
            emit({"event": "error", "message": "No failed meeting to retry."})
            return

        # For cross-session recovery (the "recover" cmd sent from a prior engine
        # session), _last_failed_meeting is None because it lives only in memory.
        # Load the on-disk sidecar so the retry has the correct title, note_path,
        # transcript_path, date_str, and attendees from the original failure.
        # Only use the sidecar when it carries real generation metadata (title +
        # date_str). Demoted snapshots have only `demoted_at` / `message` —
        # for those, fall through to the re-derive path below so the worker
        # doesn't use today's date for a meeting from a prior day.
        if failed is None and meeting_id:
            sidecar = load_failed_sidecar(meeting_id)
            if sidecar and sidecar.get("title") and sidecar.get("date_str"):
                failed = sidecar

        cfg = self._get_cfg()
        # Reset cancellation for this retry — a prior cancelled run must
        # not cause the retry to abort instantly.
        self._cancel_event.clear()

        def worker():
            self._set_state(EngineState.GENERATING)
            try:
                persisted = load_persisted_accumulator(meeting_id)
                if not persisted:
                    emit({
                        "event": "error",
                        "message": "Cached transcript no longer available for retry.",
                    })
                    return
                entries = sorted(
                    persisted.values(), key=lambda e: e.get("timestamp") or ""
                )
                if not entries:
                    emit({"event": "error", "message": "No transcript entries to retry."})
                    return

                # Reuse failure metadata when available; otherwise re-derive.
                if failed:
                    meeting_title = failed.get("title") or ""
                    date_str = failed.get("date_str") or datetime.now().strftime("%Y-%m-%d")
                    attendees = list(failed.get("attendees") or [])
                    placeholder_path_str = failed.get("note_path") or ""
                else:
                    origin = find_origin_dir()
                    blocks_wal = self._resolve_wal(origin, cfg, "blocks") if origin else None
                    transcript_wal = self._resolve_wal(origin, cfg, "transcript") if origin else None
                    meeting_title = self._derive_meeting_title(blocks_wal, transcript_wal, entries)
                    m = re.search(r"(\d{4}-\d{2}-\d{2})", meeting_title)
                    if m:
                        date_str = m.group(1)
                    else:
                        # Use the snapshot file's mtime as the date — avoids stamping
                        # old recovered meetings with today's date when the blocks
                        # WAL no longer holds a title for them.
                        snap_path, _ = _persisted_paths(meeting_id)
                        try:
                            date_str = datetime.fromtimestamp(
                                snap_path.stat().st_mtime
                            ).strftime("%Y-%m-%d") if snap_path else datetime.now().strftime("%Y-%m-%d")
                        except OSError:
                            date_str = datetime.now().strftime("%Y-%m-%d")
                    seen: dict[str, None] = {}
                    for e in entries:
                        s = e.get("speaker")
                        if s and s != "Unknown":
                            seen[s] = None
                    attendees = list(seen.keys())
                    placeholder_path_str = ""

                created_iso = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
                transcript_text = format_transcript(entries)
                slug = slugify_title(meeting_title, fallback_date=date_str)

                try:
                    summary = summarize(
                        transcript_text, meeting_title, cfg,
                        cancel_event=self._cancel_event,
                    )
                except CancelledError:
                    # Retry was cancelled (e.g. user quit the app). Leave
                    # the failed/ snapshot intact so the next launch still
                    # surfaces the recovery item.
                    emit({"event": "error", "message": "Retry cancelled"})
                    return
                except Exception as exc:
                    err_msg = _friendly_error(exc)
                    # Refresh the failed/ sidecar so the menu bar shows the
                    # latest error and a fresh `failed_at` (the file's mtime
                    # also gets bumped, which keeps it inside the 30-day
                    # purge window for another month). The .json/.md moves
                    # are no-ops when already in failed/, so this is safe
                    # to call repeatedly.
                    mark_meeting_failed(meeting_id, metadata={
                        "meeting_id": meeting_id,
                        "title": slug,
                        "note_path": placeholder_path_str,
                        "transcript_path": (failed or {}).get("transcript_path", ""),
                        "message": err_msg,
                        "date_str": date_str,
                        "attendees": attendees,
                    })
                    emit({
                        "event": "note_failed",
                        "title": slug,
                        "note_path": placeholder_path_str,
                        "transcript_path": (failed or {}).get("transcript_path", ""),
                        "meeting_id": meeting_id,
                        "attendees": attendees,
                        "message": err_msg,
                    })
                    return

                # Derive the actual transcript link from the saved transcript path
                # so the note points to the right file (e.g. "…-2" suffix).
                from pathlib import Path as _Path
                transcript_path_str = (failed or {}).get("transcript_path", "")
                transcript_link_override = None
                if transcript_path_str and _Path(transcript_path_str).exists():
                    transcript_link_override = _path_to_vault_link(
                        _Path(transcript_path_str), cfg, "transcript", date_str
                    )

                note_content = build_note_content(
                    summary, meeting_title, date_str, attendees, created_iso, cfg,
                    meeting_id=meeting_id,
                    transcript_link_override=transcript_link_override,
                )

                # Overwrite the placeholder note in place if we know its path,
                # otherwise write a fresh note (which save_note_only will
                # disambiguate via _resolve_save_path using meeting_id).
                if placeholder_path_str and _Path(placeholder_path_str).exists():
                    overwrite_note(_Path(placeholder_path_str), note_content)
                    note_path = _Path(placeholder_path_str)
                else:
                    note_path = save_note_only(
                        note_content, meeting_title, date_str, cfg,
                        meeting_id=meeting_id,
                    )

                # Cleanup: drop the persisted accumulator and forget the
                # last-failed meeting so the menu bar Retry item disappears.
                delete_persisted_accumulator(meeting_id)
                self._last_failed_meeting = None
                self._last_run_note_failed = False

                emit({
                    "event": "done",
                    "title": slug,
                    "path": str(note_path),
                    "transcript_path": (failed or {}).get("transcript_path", ""),
                    "attendees": attendees,
                    "meeting_id": meeting_id,
                })
            except Exception as exc:
                emit({"event": "error", "message": _friendly_error(exc)})
            finally:
                self._generating_lock.release()
                self._set_state(EngineState.IDLE)

        threading.Thread(target=worker, daemon=True).start()

# ── Entry point ───────────────────────────────────────────────────────────────

if __name__ == "__main__":
    # Flush stdout immediately so the Swift parent reads events without buffering.
    sys.stdout.reconfigure(line_buffering=True)  # type: ignore[attr-defined]

    engine = ZoomEngine()
    try:
        engine.run()
    except KeyboardInterrupt:
        emit({"event": "state", "value": "idle"})
        sys.exit(0)