davinci-resolve-mcp 2.61.0 → 2.62.0

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.61.0"
+VERSION = "2.62.0"
 
 import base64
 import os
@@ -85,7 +85,7 @@ from src.utils.media_analysis import (
     summarize_reports as summarize_media_analysis_reports,
 )
 from src.utils.sync_detection import detect_sync_events_for_records as detect_media_sync_events
-from src.utils import actor_identity, resolve_busy
+from src.utils import actor_identity, background_jobs, resolve_busy
 from src.utils.resolve_busy import long_resolve_op
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
@@ -744,6 +744,13 @@ sys.path.insert(0, RESOLVE_MODULES_PATH)
 resolve = None
 dvr_script = None
 _resolve_lock = threading.RLock()
+# Serializes synchronous tool bodies once they run off the event loop (see
+# _install_threaded_tool_dispatch): the Resolve scripting bridge executes one
+# call at a time, so two sync tool bodies must never enter it concurrently. No
+# body re-acquires it, so a plain Lock (not RLock) states the invariant. The
+# async media_analysis tool is not wrapped and does not take this lock; it is
+# assumed not to run concurrently with another tool (true for a serial client).
+_bridge_lock = threading.Lock()
 
 # On Windows the fusionscript native bridge DLL must be locatable before the
 # Python import machinery attempts to load it.  Setting PYTHONHOME, prepending
@@ -1214,6 +1221,26 @@ def _ok(**kw):
     return {"success": True, **kw}
 
 
+def _run_maybe_background(label: str, params: Dict[str, Any], fn):
+    """Run a long Resolve operation synchronously, or off-thread when requested.
+
+    When params carries a truthy `background` (alias `async_job`), start a polled
+    job and return its id at once; otherwise run fn inside long_resolve_op and
+    return its result, preserving the synchronous contract.
+    """
+    if params.get("background") or params.get("async_job"):
+        job_id = background_jobs.start_job(label, fn)
+        return {
+            "success": True,
+            "job_id": job_id,
+            "status": "running",
+            "label": label,
+            "note": "poll with resolve_control(action='job_status', params={'job_id': ...})",
+        }
+    with long_resolve_op(label):
+        return fn()
+
+
 def _record_action_outcome(scope_key: Optional[str], action_name: str,
                             response: Dict[str, Any]) -> Dict[str, Any]:
     """E2 — record the (scope, action) outcome with the failure tracker and
@@ -2418,11 +2445,13 @@ def _build_append_clip_info_dict(
     ci: Dict[str, Any],
     index: int,
     timeline_start_frame: Optional[int] = None,
+    pack: bool = False,
 ):
     """Build one MediaPool.AppendToTimeline clipInfo map (Python API uses camelCase keys).
 
     See docs/reference/resolve_scripting_api.txt: mediaPoolItem, startFrame, endFrame,
-    optional mediaType, trackIndex, recordFrame.
+    optional mediaType, trackIndex, recordFrame. With pack=True, recordFrame is omitted
+    so Resolve appends each clip contiguously at the end of its track.
     """
     if not isinstance(ci, dict):
         return None, _err(f"clip_infos[{index}] must be an object")
@@ -2439,14 +2468,15 @@ def _build_append_clip_info_dict(
             f"clip_infos[{index}] requires start_frame/startFrame and end_frame/endFrame "
             "(source range on the MediaPoolItem)"
         )
-    rf = ci.get("recordFrame", ci.get("record_frame"))
-    if rf is None:
-        return None, _err(
-            f"clip_infos[{index}] requires record_frame/recordFrame (timeline record frame)"
-        )
-    rf, rf_err = _normalize_record_frame(ci, index, timeline_start_frame)
-    if rf_err:
-        return None, rf_err
+    if not pack:
+        rf = ci.get("recordFrame", ci.get("record_frame"))
+        if rf is None:
+            return None, _err(
+                f"clip_infos[{index}] requires record_frame/recordFrame (timeline record frame)"
+            )
+        rf, rf_err = _normalize_record_frame(ci, index, timeline_start_frame)
+        if rf_err:
+            return None, rf_err
     ti = ci.get("trackIndex", ci.get("track_index"))
     if ti is None:
         return None, _err(
@@ -2456,9 +2486,10 @@ def _build_append_clip_info_dict(
         "mediaPoolItem": mp_item,
         "startFrame": sf,
         "endFrame": ef,
-        "recordFrame": rf,
         "trackIndex": ti,
     }
+    if not pack:
+        out["recordFrame"] = rf
     mt = ci.get("mediaType", ci.get("media_type"))
     if mt is not None:
         out["mediaType"] = mt
@@ -3472,6 +3503,27 @@ def _timeline_media_type(track_type: str):
     return None
 
 
+def _track_selector(p: Dict[str, Any]):
+    """(track_type, track_index, err) from a params dict.
+
+    Accepts the 1-based track index as either ``index`` or ``track_index``. err
+    is a validation message (None on success) so a missing or malformed selector
+    returns a structured error.
+    """
+    normalized = dict(p)
+    if normalized.get("index") is None and normalized.get("track_index") is not None:
+        normalized["index"] = normalized["track_index"]
+    err, clean = _validate_params(normalized, {
+        "track_type": {"type": str, "required": True, "enum": ["video", "audio", "subtitle"]},
+        "index": {"type": int, "required": True, "min": 1},
+    })
+    if err:
+        if err.startswith("'index' is required"):
+            err = "requires a 1-based track index ('index' or 'track_index')"
+        return None, None, err
+    return clean["track_type"], clean["index"], None
+
+
 def _timeline_track_count(tl, track_type: str):
     try:
         return int(tl.GetTrackCount(track_type) or 0)
@@ -4025,6 +4077,20 @@ def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool =
     return out
 
 
+def _apply_cuts_skip_reason(cut):
+    """Why a CutList entry is not applicable by apply_cuts, or None if it is."""
+    if not isinstance(cut, dict):
+        return "not an object"
+    if cut.get("action") not in ("lift", "ripple_delete"):
+        return f"action {cut.get('action')!r} is not lift or ripple_delete"
+    span = cut.get("span")
+    if not isinstance(span, dict):
+        return "missing span"
+    if span.get("start") is None or span.get("end") is None:
+        return "span missing start/end"
+    return None
+
+
 def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
     start, end, items, err = _collect_timeline_items_in_range(tl, p)
     if err:
@@ -4837,6 +4903,43 @@ def _timeline_apply_look_to_items(tl, p: Dict[str, Any]) -> Dict[str, Any]:
     return out
 
 
+def _variant_item_placement(item) -> Dict[str, Any]:
+    """Report an appended item's placed frame positions in both frame spaces.
+    record_* are TIMELINE frames (GetStart/GetEnd/GetDuration); source_start is
+    a SOURCE frame."""
+    def _read(method):
+        fn = getattr(item, method, None)
+        if not callable(fn):
+            return None
+        try:
+            return _frame_int(fn())
+        except Exception:
+            return None
+    record_start = _read("GetStart")
+    record_end = _read("GetEnd")
+    duration = _read("GetDuration")
+    if duration is None and record_start is not None and record_end is not None:
+        duration = record_end - record_start
+    return {
+        "record_start": record_start,
+        "record_end": record_end,
+        "duration": duration,
+        "source_start": _timeline_item_source_start(item),
+    }
+
+
+def _variant_audio_summary(built):
+    """Video/audio range counts for an assembled variant, warning when it carries
+    no audio. create_variant_from_ranges places exactly the ranges given, so a
+    video-only range list yields a silent timeline."""
+    video = sum(1 for row in built if row.get("media_type") == 1)
+    audio = sum(1 for row in built if row.get("media_type") == 2)
+    summary = {"video_ranges": video, "audio_ranges": audio}
+    if audio == 0:
+        summary["warning"] = "video-only (no audio): add ranges with track_type='audio' to carry sound"
+    return summary
+
+
 def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) -> Dict[str, Any]:
     ranges = p.get("ranges") or p.get("clip_infos")
     if not isinstance(ranges, list) or not ranges:
@@ -4854,6 +4957,10 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
             start_frame = int(source_tl.GetStartFrame())
         except Exception:
             start_frame = 0
+    # pack=True butts clips together at the end of each track (record_frame is
+    # ignored); Resolve packs by actual placed duration, so the result is gap-free
+    # even when source and timeline frame rates differ.
+    pack = bool(p.get("pack", False))
     built = []
     cursor_by_track: Dict[Tuple[int, int], int] = {}
     max_tracks = {"video": 1, "audio": 1}
@@ -4877,9 +4984,12 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
             return _err(f"ranges[{index}] requires valid start_frame/end_frame")
         record_frame = _frame_int(row.get("record_frame", row.get("recordFrame")))
         key = (int(media_type), track_index)
-        if record_frame is None:
-            record_frame = cursor_by_track.get(key, start_frame)
-        cursor_by_track[key] = record_frame + (end - start)
+        if pack:
+            record_frame = None  # Resolve packs at the end of the track
+        else:
+            if record_frame is None:
+                record_frame = cursor_by_track.get(key, start_frame)
+            cursor_by_track[key] = record_frame + (end - start)
         built.append({
             "clip_id": row.get("clip_id") or row.get("media_pool_item_id"),
             "start_frame": start,
@@ -4890,6 +5000,14 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
             "_source_row": row,
             "_index": index,
         })
+    # Resolve every clip (media-pool id + frame range) before choosing dry-run
+    # vs commit, so a dry run fails on the same id/frame errors as the commit.
+    append_infos = []
+    for row in built:
+        clip_info, clip_err = _build_append_clip_info_dict(root, row, row["_index"], pack=pack)
+        if clip_err:
+            return clip_err
+        append_infos.append(clip_info)
     if p.get("dry_run", False):
         return {
             "success": True,
@@ -4900,6 +5018,7 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
                 for row in built
             ],
             "markers": p.get("markers") or [],
+            "audio": _variant_audio_summary(built),
             "would_create_timeline": True,
         }
     new_tl = mp.CreateEmptyTimeline(name)
@@ -4915,21 +5034,23 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
         while int(new_tl.GetTrackCount(track_type) or 0) < needed:
             if not new_tl.AddTrack(track_type):
                 break
-    append_infos = []
-    for row in built:
-        clip_info, clip_err = _build_append_clip_info_dict(root, row, row["_index"])
-        if clip_err:
-            return clip_err
-        append_infos.append(clip_info)
     appended = mp.AppendToTimeline(append_infos)
     if not appended:
         return _err("AppendToTimeline returned no items for variant")
     items_out = []
+    placement_mismatches = 0
     for index, item in enumerate(appended):
         item_out, item_err = _serialize_appended_timeline_item(item, index, allow_empty_timeline_item_id=True)
         if item_err:
             return item_err
-        item_out["range"] = {key: value for key, value in built[index].items() if not key.startswith("_")}
+        requested = {key: value for key, value in built[index].items() if not key.startswith("_")}
+        item_out["range"] = requested  # the requested range (still carries media_type/track_index)
+        placed = _variant_item_placement(item)  # the frame positions Resolve placed it at
+        item_out["placed"] = placed
+        requested_duration = requested["end_frame"] - requested["start_frame"]
+        if placed["duration"] is not None and placed["duration"] != requested_duration:
+            item_out["duration_delta"] = placed["duration"] - requested_duration
+            placement_mismatches += 1
         transform = built[index]["_source_row"].get("transform")
         if isinstance(transform, dict):
             item_out["transform"] = {}
@@ -4958,6 +5079,8 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
         "name": new_tl.GetName(),
         "id": new_tl.GetUniqueId(),
         "items": items_out,
+        "placement_mismatches": placement_mismatches,
+        "audio": _variant_audio_summary(built),
         "markers": marker_results,
         "look": look_result,
         "gaps_overlaps": _detect_gaps_overlaps_from_snapshot(_timeline_conform_snapshot(new_tl, {}), {}),
@@ -5313,38 +5436,41 @@ def _export_timeline_checked(tl, p: Dict[str, Any]):
     spec = _timeline_export_spec(p, get_resolve())
     if p.get("dry_run"):
         return _ok(path=path, would_export=True, spec={k: v for k, v in spec.items() if k != "export_type"})
-    with long_resolve_op("timeline.export_timeline_checked"):
+
+    def _work():
         success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
-    files = []
-    primary_file = path
-    if success and os.path.isdir(path):
-        for dirpath, _, filenames in os.walk(path):
-            for filename in filenames:
-                file_path = os.path.join(dirpath, filename)
-                files.append({"path": file_path, "size": os.path.getsize(file_path)})
-        preferred_exts = (".fcpxml", ".xml", ".edl", ".drt", ".aaf", ".otio")
-        for ext in preferred_exts:
-            match = next((row["path"] for row in files if row["path"].lower().endswith(ext)), None)
-            if match:
-                primary_file = match
-                break
-    size = 0
-    if success and os.path.exists(path):
-        if os.path.isdir(path):
-            size = sum(row["size"] for row in files)
-        else:
-            size = os.path.getsize(path)
-    return {
-        "success": success,
-        "path": path,
-        "primary_file": primary_file,
-        "is_directory": bool(success and os.path.isdir(path)),
-        "files": files,
-        "size": size,
-        "format": spec["requested"],
-        "export_type": spec["export_type_name"],
-        "export_subtype": spec["export_subtype_name"],
-    }
+        files = []
+        primary_file = path
+        if success and os.path.isdir(path):
+            for dirpath, _, filenames in os.walk(path):
+                for filename in filenames:
+                    file_path = os.path.join(dirpath, filename)
+                    files.append({"path": file_path, "size": os.path.getsize(file_path)})
+            preferred_exts = (".fcpxml", ".xml", ".edl", ".drt", ".aaf", ".otio")
+            for ext in preferred_exts:
+                match = next((row["path"] for row in files if row["path"].lower().endswith(ext)), None)
+                if match:
+                    primary_file = match
+                    break
+        size = 0
+        if success and os.path.exists(path):
+            if os.path.isdir(path):
+                size = sum(row["size"] for row in files)
+            else:
+                size = os.path.getsize(path)
+        return {
+            "success": success,
+            "path": path,
+            "primary_file": primary_file,
+            "is_directory": bool(success and os.path.isdir(path)),
+            "files": files,
+            "size": size,
+            "format": spec["requested"],
+            "export_type": spec["export_type_name"],
+            "export_subtype": spec["export_subtype_name"],
+        }
+
+    return _run_maybe_background("timeline.export_timeline_checked", p, _work)
 
 
 def _timeline_media_coverage(tl) -> Dict[str, Any]:
@@ -5533,74 +5659,76 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             out["note"] = binary_relink_note
         return out
 
-    before_ids = set()
-    for index in range(1, int(proj.GetTimelineCount() or 0) + 1):
-        tl_existing = proj.GetTimelineByIndex(index)
-        if tl_existing:
-            before_ids.add(str(tl_existing.GetUniqueId()))
-    with long_resolve_op("timeline.import_timeline_checked"):
+    def _work():
+        before_ids = set()
+        for index in range(1, int(proj.GetTimelineCount() or 0) + 1):
+            tl_existing = proj.GetTimelineByIndex(index)
+            if tl_existing:
+                before_ids.add(str(tl_existing.GetUniqueId()))
         imported = mp.ImportTimelineFromFile(import_path, options)
 
-    # Resolve's API returns None even when it created an (offline) timeline. Detect
-    # the newly-created timeline via the before/after id diff so we never report a
-    # false "Failed to import" for what is really a partial success.
-    api_returned_object = bool(imported)
-    if not imported:
-        for index in range(1, int(proj.GetTimelineCount() or 0) + 1):
-            t = proj.GetTimelineByIndex(index)
-            if t and str(t.GetUniqueId()) not in before_ids:
-                imported = t
-    if not imported:
-        if is_binary:
-            remediation = (
-                f"Resolve created no timeline from this {ext}. Verify it exports/opens in "
-                "Resolve directly, or convert to FCP7 XML / FCPXML upstream and import that."
-            )
-        elif sanitize:
-            remediation = None
-        else:
-            remediation = (
-                "This XML may reference missing media or contain generator clips, which "
-                "abort the scripting-API import. Retry with sanitize_media=True."
+        # Resolve's API returns None even when it created an (offline) timeline. Detect
+        # the newly-created timeline via the before/after id diff so we never report a
+        # false "Failed to import" for what is really a partial success.
+        api_returned_object = bool(imported)
+        if not imported:
+            for index in range(1, int(proj.GetTimelineCount() or 0) + 1):
+                t = proj.GetTimelineByIndex(index)
+                if t and str(t.GetUniqueId()) not in before_ids:
+                    imported = t
+        if not imported:
+            if is_binary:
+                remediation = (
+                    f"Resolve created no timeline from this {ext}. Verify it exports/opens in "
+                    "Resolve directly, or convert to FCP7 XML / FCPXML upstream and import that."
+                )
+            elif sanitize:
+                remediation = None
+            else:
+                remediation = (
+                    "This XML may reference missing media or contain generator clips, which "
+                    "abort the scripting-API import. Retry with sanitize_media=True."
+                )
+            return _err(
+                "Failed to import timeline (Resolve created no timeline)",
+                remediation=remediation,
             )
-        return _err(
-            "Failed to import timeline (Resolve created no timeline)",
-            remediation=remediation,
+
+        imported_id = str(imported.GetUniqueId())
+        media = _timeline_media_coverage(imported)
+        # AAF fuzzy-relink parity: when search roots are given for a binary import, relink through
+        # the media pool after import (the XML path-rewrite relink can't run on a binary file).
+        relink_result = None
+        if is_binary and search_roots:
+            relink_result = _binary_post_import_relink(imported, mp, search_roots)
+            if relink_result.get("after"):
+                media = relink_result["after"]
+        out = _ok(
+            name=imported.GetName(),
+            id=imported_id,
+            created_new=imported_id not in before_ids,
+            timeline_count=proj.GetTimelineCount(),
+            api_returned_object=api_returned_object,
+            media=media,
         )
+        if sanitize_report is not None:
+            out["sanitize"] = sanitize_report
+        if relink_result is not None:
+            out["relink"] = relink_result
+        if binary_relink_note:
+            out["note"] = binary_relink_note
+        if media["total"] and media["offline"]:
+            msg = f"{media['offline']} of {media['total']} timeline items are offline (no linked media)."
+            if is_binary:
+                msg += (" Relink via the media pool (right-click → Relink Clips) or point Resolve "
+                        "at the media roots — AAF media links there, not by rewriting the file.")
+            elif not sanitize:
+                msg += (" Retry with sanitize_media=True to drop missing-media/generator "
+                        "clips so the remaining media links automatically.")
+            out["warning"] = msg
+        return out
 
-    imported_id = str(imported.GetUniqueId())
-    media = _timeline_media_coverage(imported)
-    # AAF fuzzy-relink parity: when search roots are given for a binary import, relink through
-    # the media pool after import (the XML path-rewrite relink can't run on a binary file).
-    relink_result = None
-    if is_binary and search_roots:
-        relink_result = _binary_post_import_relink(imported, mp, search_roots)
-        if relink_result.get("after"):
-            media = relink_result["after"]
-    out = _ok(
-        name=imported.GetName(),
-        id=imported_id,
-        created_new=imported_id not in before_ids,
-        timeline_count=proj.GetTimelineCount(),
-        api_returned_object=api_returned_object,
-        media=media,
-    )
-    if sanitize_report is not None:
-        out["sanitize"] = sanitize_report
-    if relink_result is not None:
-        out["relink"] = relink_result
-    if binary_relink_note:
-        out["note"] = binary_relink_note
-    if media["total"] and media["offline"]:
-        msg = f"{media['offline']} of {media['total']} timeline items are offline (no linked media)."
-        if is_binary:
-            msg += (" Relink via the media pool (right-click → Relink Clips) or point Resolve "
-                    "at the media roots — AAF media links there, not by rewriting the file.")
-        elif not sanitize:
-            msg += (" Retry with sanitize_media=True to drop missing-media/generator "
-                    "clips so the remaining media links automatically.")
-        out["warning"] = msg
-    return out
+    return _run_maybe_background("timeline.import_timeline_checked", p, _work)
 
 
 # A .drp/.drt is a zip of SeqContainer*.xml entries. Two on-disk naming conventions,
@@ -5703,11 +5831,13 @@ def _import_from_drp(proj, mp, p: Dict[str, Any]):
     else:
         selected = list(containers)
 
-    # Per-timeline options passthrough (importSourceClips etc.) minus selection keys.
+    # Per-timeline options passthrough (importSourceClips etc.) minus selection
+    # keys; background is a top-level option, so each sub-step import runs
+    # synchronously and the loop can verify it.
     base = {
         k: v
         for k, v in p.items()
-        if k not in ("drpPath", "drp_path", "path", "timelineNames", "timeline_names", "timelineIndexes", "timeline_indexes", "dry_run")
+        if k not in ("drpPath", "drp_path", "path", "timelineNames", "timeline_names", "timelineIndexes", "timeline_indexes", "dry_run", "background", "async_job")
     }
 
     tmp_dir = tempfile.mkdtemp(prefix="drp_import_")
@@ -5786,6 +5916,15 @@ def _find_timeline_by_name(proj, name: Any):
     return None, None
 
 
+def _find_timeline_by_id(proj, timeline_id: Any):
+    want = str(timeline_id or "")
+    for index in range(1, int(proj.GetTimelineCount() or 0) + 1):
+        tl = proj.GetTimelineByIndex(index)
+        if tl and str(tl.GetUniqueId()) == want:
+            return tl, index
+    return None, None
+
+
 def _unique_timeline_name(proj, requested_name: Any) -> str:
     base = str(requested_name or "Untitled Timeline").strip() or "Untitled Timeline"
     existing_names = set()
@@ -5913,7 +6052,8 @@ def _probe_interchange_roundtrip(proj, mp, tl, p: Dict[str, Any]):
     spec = _timeline_export_spec(p, resolve)
     base_name = p.get("name") or f"roundtrip_{str(spec['requested']).lower()}"
     path = p.get("path") or os.path.join(output_dir, base_name + spec["extension"])
-    export_result = _export_timeline_checked(tl, {**p, "path": path, "require_temp_path": p.get("require_temp_path", True)})
+    # background is a top-level option; a sub-step export must run synchronously.
+    export_result = _export_timeline_checked(tl, {**p, "path": path, "require_temp_path": p.get("require_temp_path", True), "background": False, "async_job": False})
     if export_result.get("error") or not export_result.get("success"):
         return {"success": False, "stage": "export", "export": export_result}
     import_path = export_result.get("primary_file") or export_result.get("path") or path
@@ -6907,8 +7047,9 @@ def _subtitle_generation_probe(tl, p: Dict[str, Any]):
                    note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
     if not _has_method(tl, "CreateSubtitlesFromAudio"):
         return _err("CreateSubtitlesFromAudio unavailable")
-    with long_resolve_op("timeline.create_subtitles_from_audio"):
-        return _safe_create_subtitles(tl, p)
+    return _run_maybe_background(
+        "timeline.create_subtitles_from_audio", p, lambda: _safe_create_subtitles(tl, p)
+    )
 
 
 def _fairlight_boundary_report(proj, mp, tl, p: Dict[str, Any]):
@@ -12667,6 +12808,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         facts about quirky/unreliable Resolve API behavior (no connection needed).
       verification_stats() -> {stats}  — readback-verification tally
         (verified/contradicted/unverified) since server start (no connection needed).
+      job_status(job_id) -> {id, label, status, result?, error?, started_at, ended_at}
+        — poll a background job started by a long op run with background=True
+          (no connection needed). status is running, done, or error.
+      list_jobs() -> {jobs}  — compact status of every known background job
+        (no connection needed).
       get_page() -> {page}
       open_page(page) -> {success}  — page: edit, cut, color, fusion, fairlight, deliver
       get_keyframe_mode() -> {mode}
@@ -12697,6 +12843,18 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"stats": stats, "note": "Counts since server start. A rising "
                 "'contradicted' count means the API reported success but a readback disagreed."}
 
+    # Background-job polling is a registry read — no Resolve connection needed.
+    if action == "job_status":
+        job_id = p.get("job_id")
+        if not job_id:
+            return _err("job_status requires job_id", category="invalid_input")
+        status = background_jobs.job_status(job_id)
+        if status is None:
+            return _err(f"Unknown job_id: {job_id}", category="invalid_input")
+        return status
+    if action == "list_jobs":
+        return {"jobs": background_jobs.list_jobs()}
+
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
         return _open_control_panel(p)
@@ -12789,7 +12947,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","get_version","api_truth","verification_stats","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","get_version","api_truth","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -15651,7 +15809,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       setup_multicam_timeline(name, clip_ids|angles, sync_mode?, include_audio?, dry_run?) -> {success}
         — creates a stacked multicam prep timeline: one angle per video track, optional
           matching audio tracks. Native multicam clip conversion remains a Resolve UI step.
-      import_timeline(path, options?) -> {success, name}
+      import_timeline(path, options?, background?) -> {success, name | job_id}
         UNSAFE. No path sandboxing. Prefer timeline.import_timeline_checked.
       delete_timelines(timeline_ids) -> {success}
         CATASTROPHIC. Deletes timelines outright.
@@ -15836,14 +15994,17 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         # Whitelist options to the documented keys; Resolve silently ignores
         # unknown keys, so a typo would be dropped with no signal (P1 #4).
         options, ignored_opts = _filter_to_keys(p.get("options", {}), _IMPORT_TIMELINE_OPTION_KEYS)
-        with long_resolve_op("media_pool.import_timeline"):
+
+        def _work():
             tl = mp.ImportTimelineFromFile(p["path"], options)
-        if not tl:
-            return _err("Failed to import timeline")
-        result = _ok(name=tl.GetName())
-        if ignored_opts:
-            result["ignored_options"] = ignored_opts
-        return result
+            if not tl:
+                return _err("Failed to import timeline")
+            result = _ok(name=tl.GetName())
+            if ignored_opts:
+                result["ignored_options"] = ignored_opts
+            return result
+
+        return _run_maybe_background("media_pool.import_timeline", p, _work)
     elif action == "delete_timelines":
         count = proj.GetTimelineCount()
         timelines = []
@@ -16094,7 +16255,7 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
       is_stale(path?) -> {stale}
       get_unique_id(path?) -> {id}
       export(path?, export_path) -> {success}
-      transcribe_audio(path?, use_speaker_detection?) -> {success}  — use_speaker_detection is Resolve 21+
+      transcribe_audio(path?, use_speaker_detection?, background?) -> {success | job_id}  — use_speaker_detection is Resolve 21+; background=true returns a job_id (poll resolve_control job_status)
       clear_transcription(path?) -> {success}
       perform_audio_classification(path?) -> {success}  — Resolve 21+
       clear_audio_classification(path?) -> {success}  — Resolve 21+
@@ -16129,10 +16290,12 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            with long_resolve_op("folder.transcribe_audio"):
-                return {"success": bool(f.TranscribeAudio())}
-        with long_resolve_op("folder.transcribe_audio"):
-            return {"success": bool(f.TranscribeAudio(bool(usd)))}
+            return _run_maybe_background(
+                "folder.transcribe_audio", p, lambda: {"success": bool(f.TranscribeAudio())}
+            )
+        return _run_maybe_background(
+            "folder.transcribe_audio", p, lambda: {"success": bool(f.TranscribeAudio(bool(usd)))}
+        )
     elif action == "clear_transcription":
         return {"success": bool(f.ClearTranscription())}
     elif action == "perform_audio_classification":
@@ -16246,11 +16409,13 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       monitor_growing_file(clip_id) -> {success}
       replace_clip_preserve_sub_clip(clip_id, path) -> {success}
       get_unique_id(clip_id) -> {id}
-      transcribe_audio(clip_id, use_speaker_detection?) -> {success}  — use_speaker_detection is Resolve 21+
+      transcribe_audio(clip_id, use_speaker_detection?, background?) -> {success | job_id}  — use_speaker_detection is Resolve 21+; background=true returns a job_id (poll resolve_control job_status)
       clear_transcription(clip_id) -> {success}
       get_transcription(clip_id) -> {text, truncated, status, has_transcription}
         Read a clip's transcription. `truncated` flags when Resolve's preview
-        property cut the text off (the full transcript is longer).
+        property cut the text off (the full transcript is longer). Clip-level and
+        separate from the timeline subtitle transcript (timeline.get_transcript)
+        that propose_cuts uses.
       extract_frames(clip_id, timestamps, output_dir?) -> {frame_paths, output_dir, count, errors}
         Extract still JPEGs from the clip's source at the given timestamps (seconds)
         via ffmpeg. Source-safe: reads source, writes only to a scratch dir.
@@ -16466,10 +16631,12 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "transcribe_audio":
         usd = _first_param(p, "use_speaker_detection", "useSpeakerDetection")
         if usd is None:
-            with long_resolve_op("media_pool_item.transcribe_audio"):
-                return {"success": bool(clip.TranscribeAudio())}
-        with long_resolve_op("media_pool_item.transcribe_audio"):
-            return {"success": bool(clip.TranscribeAudio(bool(usd)))}
+            return _run_maybe_background(
+                "media_pool_item.transcribe_audio", p, lambda: {"success": bool(clip.TranscribeAudio())}
+            )
+        return _run_maybe_background(
+            "media_pool_item.transcribe_audio", p, lambda: {"success": bool(clip.TranscribeAudio(bool(usd)))}
+        )
     elif action == "clear_transcription":
         return {"success": bool(clip.ClearTranscription())}
     elif action == "get_transcription":
@@ -18582,6 +18749,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 "audio_accounting": {
                     "planned_audio_ranges": audio_keep_ranges,
                     "planned_video_ranges": video_keep_ranges,
+                    # variant_* count placed items; variant["audio"] counts requested ranges.
                     "variant_audio_items": sum(
                         1 for it in (variant.get("items") or [])
                         if (it.get("range") or {}).get("media_type") == 2
@@ -18768,6 +18936,28 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
     ])
 
 
+_TIMELINE_ACTIONS = [
+    "list", "get_current", "set_current", "get_name", "set_name", "get_start_frame",
+    "get_end_frame", "get_start_timecode", "set_start_timecode", "get_track_count",
+    "add_track", "delete_track", "get_track_sub_type", "set_track_enable",
+    "get_track_enabled", "set_track_lock", "get_track_locked", "get_track_name",
+    "set_track_name", "get_items", "delete_clips", "set_clips_linked", "duplicate",
+    "duplicate_clips", "copy_clips", "move_clips", "copy_range", "duplicate_range",
+    "overwrite_range", "lift_range", "story_spine_report", "create_variant_from_ranges",
+    "bulk_set_item_properties", "apply_look_to_items", "thumbnail_contact_sheet",
+    "marker_thumbnail_review", "edit_kernel_capabilities", "probe_edit_kernel_item",
+    "title_property_scan", "set_title_text", "bulk_set_title_text", "create_compound_clip",
+    "create_fusion_clip", "import_into_timeline", "export", "get_setting", "set_setting",
+    "insert_generator", "insert_fusion_generator", "insert_fusion_composition",
+    "insert_ofx_generator", "insert_title", "insert_fusion_title", "get_unique_id",
+    "get_node_graph", "get_media_pool_item", "get_transcript", "propose_cuts", "apply_cuts",
+    "get_mark_in_out", "set_mark_in_out", "clear_mark_in_out", "convert_to_stereo",
+    "get_items_in_track", "get_voice_isolation_state", "set_voice_isolation_state",
+    "extract_source_frame_ranges", "audio_mix_capability_report", "clip_where", "action_help",
+    *_TIMELINE_CONFORM_KERNEL_ACTIONS, *_TIMELINE_AUDIO_KERNEL_ACTIONS,
+]
+
+
 @mcp.tool()
 @_destructive_op("timeline")
 def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -18776,12 +18966,19 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     PREFER probe_* / *_capabilities / *_boundary_report / *_checked / dry_run variants
     where they exist. Raw mutators are kept for advanced callers but bypass guardrails.
     DESTRUCTIVE actions auto-archive the current timeline (C6); pass strict=true for
-    refuse-on-archive-failure behavior on the catastrophic ops.
+    refuse-on-archive-failure behavior on the catastrophic ops. To thread several
+    destructive calls into ONE archived predecessor instead of N, wrap them in
+    timeline_versioning begin_run/end_run.
+
+    Frame numbers are TIMELINE/record frames (position on the timeline) unless an action
+    says SOURCE. Source frames are positions within a media-pool clip's own media:
+    create_variant_from_ranges takes SOURCE start_frame/end_frame; extract_source_frame_ranges
+    and source_range_report return SOURCE ranges.
 
     Actions:
       list() -> {timelines}
       get_current() -> {name, id, start_frame, end_frame, start_timecode}
-      set_current(index) -> {success}  — 1-based index
+      set_current(index|id|name) -> {success}  — id/name are stable across archives; index is 1-based
       get_name() -> {name}
       set_name(name) -> {success}
       get_start_frame() -> {frame}
@@ -18802,7 +18999,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       get_track_locked(track_type, index) -> {locked}
       get_track_name(track_type, index) -> {name}
       set_track_name(track_type, index, name) -> {success}
-      get_items(track_type, index) -> {items}
+      get_items(track_type, index|track_index) -> {items}  — track_type: video|audio|subtitle
       clip_where(filters|track_type?, track_index?, name_contains?, duration_lt?, duration_gt?) -> {clips, match_count, total_clips}
         Find clips on the current timeline matching named filters (AND). Pass filters
         inline or as a `filters` dict. Live filters: track_type, track_index,
@@ -18826,7 +19023,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       copy_range/duplicate_range(start_frame, end_frame, record_frame, ...) -> {results, count}
       overwrite_range(start_frame, end_frame, record_frame, ...) -> {results, count}
       lift_range(start_frame, end_frame, allow_partial_item_delete?, ripple?) -> {success, deleted}
-        DESTRUCTIVE. Removes items in a record-frame range. ripple=True closes the gap.
+        DESTRUCTIVE. Deletes timeline items whose record-frame range overlaps [start,end].
+        ripple=True closes the gap left by those deleted items (shifts later clips left). It
+        does NOT close a pre-existing empty gap: if no item overlaps the range, deleted=0 and
+        nothing moves. (frames here are TIMELINE/record frames.)
       story_spine_report() -> {beats, track_summaries, source_ranges, audio_spine}
       create_variant_from_ranges(name, ranges, markers?, cdl?, dry_run?) -> {success, id, items}
         # example: action_help(name='<action_name>')
@@ -18849,7 +19049,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       create_fusion_clip(clip_ids) -> {success}
       import_into_timeline(path, options?) -> {success}
         UNSAFE. No path sandboxing. Prefer import_timeline_checked.
-      export(path, type, subtype?) -> {success}  — type: AAF, EDL, FCPXML, etc.
+      export(path, type, subtype?, background?) -> {success | job_id}  — type: AAF, EDL, FCPXML, etc.
         UNSAFE. No path sandboxing. Prefer export_timeline_checked.
       get_setting(name?) -> {settings}
       set_setting(name, value) -> {success}
@@ -18863,11 +19063,16 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       get_node_graph() -> {available}
       get_media_pool_item() -> {name, id}
       get_transcript(with_timecodes?) -> {text, cue_count, has_subtitles, cues}
-        Read the timeline's subtitle track(s) as transcript text.
+        Read the timeline's subtitle track(s) as transcript text. This is the
+        TIMELINE subtitle transcript that propose_cuts consumes; it is separate
+        from clip-level transcription (produced by transcribe_audio on a
+        folder/clip, read via media_pool_item get_transcription), which does not
+        drive timeline cuts.
       propose_cuts(cues?, long_pause_frames?) -> {cuts, cut_count, basis_cue_count, pass, note}
         DRY-RUN. Mechanically detect candidate cuts (filler words, long pauses,
         repeated lines) from the subtitle transcript. Proposes only; applies nothing.
-      apply_cuts(cuts, dry_run?, confirm_token?, allow_partial_item_delete?) -> {applied, total, results}
+      apply_cuts(cuts, dry_run?, confirm_token?, allow_partial_item_delete?) -> {applied, total, skipped, results}
+        skipped lists cuts that were not applicable, each with a reason.
         Apply a CutList (from propose_cuts) as lift/ripple deletes. DRY-RUN by
         default; applying is DESTRUCTIVE — confirm-token gated and a timeline
         version is archived first. Cuts apply latest-first.
@@ -18875,7 +19080,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       set_mark_in_out(mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(type?) -> {success}
       convert_to_stereo() -> {success}
-      get_items_in_track(track_type, track_index) -> {items}
+      get_items_in_track(track_type, track_index|index) -> {items}  — full serialization of each item
       get_voice_isolation_state(track_index) -> {isEnabled, amount}
       set_voice_isolation_state(track_index, state) -> {success}
       extract_source_frame_ranges(handles?, gap_max?, skip_extensions?) -> {timeline_name, frame_ranges, occurrences, ...}
@@ -18887,8 +19092,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       probe_timeline_structure(track_types?, include_markers?, include_clip_properties?) -> {tracks, markers}
       detect_gaps_overlaps(track_types?, min_gap?) -> {gaps, overlaps}
       source_range_report(handles?, merge?) -> {ranges, occurrences}
-      export_timeline_checked(path, format?|type?, subtype?, require_temp_path?, dry_run?) -> {success, path, size}
-      import_timeline_checked(path, options?, timeline_name?, import_source_clips?, sanitize_media?, require_temp_path?, dry_run?) -> {success, name, id, media, sanitize?, warning?}
+      export_timeline_checked(path, format?|type?, subtype?, require_temp_path?, dry_run?, background?) -> {success, path, size | job_id}
+      import_timeline_checked(path, options?, timeline_name?, import_source_clips?, sanitize_media?, require_temp_path?, dry_run?, background?) -> {success, name, id, media, sanitize?, warning? | job_id}
         Imports an FCP7 xmeml / FCPXML / AAF timeline. AAF (.aaf) is read natively by
         Resolve — the XML sanitize pass is SKIPPED for it (media relinks via the media
         pool, not by rewriting the file); a `note` says so. For AAF, passing
@@ -18957,6 +19162,16 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
                 timelines.append({"name": tl.GetName(), "id": tl.GetUniqueId(), "index": i})
         return {"timelines": timelines}
     elif action == "set_current":
+        # id/name take precedence over index.
+        selector_id = p.get("id") or p.get("timeline_id")
+        selector_name = p.get("name")
+        if selector_id or selector_name:
+            tl = _find_timeline_by_id(proj, selector_id)[0] if selector_id else None
+            if tl is None and selector_name:
+                tl = _find_timeline_by_name(proj, selector_name)[0]
+            if tl is None:
+                return _err(f"No timeline matching {selector_id or selector_name!r}")
+            return {"success": bool(proj.SetCurrentTimeline(tl))}
         err, clean = _validate_params(p, {"index": {"type": int, "required": True, "min": 1}})
         if err:
             return _err(err)
@@ -19071,7 +19286,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "set_track_name":
         return {"success": bool(tl.SetTrackName(p["track_type"], p["index"], p["name"]))}
     elif action == "get_items":
-        items = tl.GetItemListInTrack(p["track_type"], p["index"])
+        track_type, track_index, err = _track_selector(p)
+        if err:
+            return _err(err)
+        items = tl.GetItemListInTrack(track_type, track_index)
         return {"items": [{"name": it.GetName(), "id": it.GetUniqueId(), "start": it.GetStart(), "end": it.GetEnd(), "duration": it.GetDuration()} for it in (items or [])]}
     elif action == "delete_clips":
         # Find timeline items by unique IDs
@@ -19181,13 +19399,16 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         # friendly type/subtype names (or EXPORT_* constant names) the same way
         # export_timeline_checked does. This raw action keeps no path sandbox.
         spec = _timeline_export_spec(p, get_resolve())
-        with long_resolve_op("timeline.export"):
+
+        def _work():
             success = bool(tl.Export(p["path"], spec["export_type"], spec["export_subtype"]))
-        return {
-            "success": success,
-            "export_type": spec["export_type_name"],
-            "export_subtype": spec["export_subtype_name"],
-        }
+            return {
+                "success": success,
+                "export_type": spec["export_type_name"],
+                "export_subtype": spec["export_subtype_name"],
+            }
+
+        return _run_maybe_background("timeline.export", p, _work)
     elif action == "get_setting":
         return {"settings": _ser(tl.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
@@ -19235,12 +19456,14 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         cuts = p.get("cuts")
         if not isinstance(cuts, list):
             return _err("apply_cuts requires 'cuts' (a list, e.g. from propose_cuts)")
-        applicable = [
-            c for c in cuts
-            if isinstance(c, dict) and c.get("action") in ("lift", "ripple_delete")
-            and isinstance(c.get("span"), dict)
-            and c["span"].get("start") is not None and c["span"].get("end") is not None
-        ]
+        applicable = []
+        skipped = []
+        for index, c in enumerate(cuts):
+            reason = _apply_cuts_skip_reason(c)
+            if reason:
+                skipped.append({"index": index, "cut": c, "reason": reason})
+            else:
+                applicable.append(c)
         applicable.sort(key=lambda c: c["span"]["start"], reverse=True)
         plan = [{"action": c["action"], "span": c["span"], "kind": c.get("kind")} for c in applicable]
 
@@ -19249,6 +19472,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
                 "dry_run": True,
                 "would_apply": len(applicable),
                 "plan": plan,
+                "skipped": skipped,
                 "note": "No edits made. Re-run with dry_run=false (and a confirm_token) to apply.",
             }
 
@@ -19262,6 +19486,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
                                "archived first.",
                     "would_apply": len(applicable),
                     "plan": plan,
+                    "skipped": skipped,
                 },
             )
         blocked = _consume_confirm_token(action="timeline.apply_cuts", params=p)
@@ -19281,7 +19506,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             results.append({"action": c["action"], "span": sp, "result": res})
         applied = sum(1 for r in results
                       if isinstance(r["result"], dict) and r["result"].get("success"))
-        return {"success": True, "applied": applied, "total": len(applicable), "results": results}
+        return {"success": True, "applied": applied, "total": len(applicable),
+                "skipped": skipped, "results": results}
     elif action == "get_mark_in_out":
         return _ser(tl.GetMarkInOut())
     elif action == "set_mark_in_out":
@@ -19299,7 +19525,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "convert_to_stereo":
         return {"success": bool(tl.ConvertTimelineToStereo())}
     elif action == "get_items_in_track":
-        return {"items": _ser(tl.GetItemListInTrack(p["track_type"], p["track_index"]))}
+        track_type, track_index, err = _track_selector(p)
+        if err:
+            return _err(err)
+        return {"items": _ser(tl.GetItemListInTrack(track_type, track_index))}
     elif action == "get_voice_isolation_state":
         missing = _requires_method(tl, "GetVoiceIsolationState", "20.1")
         if missing:
@@ -19495,7 +19724,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         if mp_err:
             return mp_err
         return _fairlight_boundary_report(proj, mp, tl, p)
-    return _unknown(action, ["list","get_current","set_current","get_name","set_name","get_start_frame","get_end_frame","get_start_timecode","set_start_timecode","get_track_count","add_track","delete_track","get_track_sub_type","set_track_enable","get_track_enabled","set_track_lock","get_track_locked","get_track_name","set_track_name","get_items","delete_clips","set_clips_linked","duplicate","duplicate_clips","copy_clips","move_clips","copy_range","duplicate_range","overwrite_range","lift_range","story_spine_report","create_variant_from_ranges","bulk_set_item_properties","apply_look_to_items","thumbnail_contact_sheet","marker_thumbnail_review","edit_kernel_capabilities","probe_edit_kernel_item","title_property_scan","set_title_text","bulk_set_title_text","create_compound_clip","create_fusion_clip","import_into_timeline","export","get_setting","set_setting","insert_generator","insert_fusion_generator","insert_fusion_composition","insert_ofx_generator","insert_title","insert_fusion_title","get_unique_id","get_node_graph","get_media_pool_item","get_transcript","propose_cuts","apply_cuts","get_mark_in_out","set_mark_in_out","clear_mark_in_out","convert_to_stereo","get_items_in_track","get_voice_isolation_state","set_voice_isolation_state","extract_source_frame_ranges","audio_mix_capability_report","clip_where","action_help",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
+    return _unknown(action, _TIMELINE_ACTIONS)
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -19628,9 +19857,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
     """AI and analysis operations on the current timeline.
 
     Actions:
-      create_subtitles(settings?) -> {success}  — auto-caption from audio
-      detect_scene_cuts() -> {success}
-      analyze_dolby_vision(clip_ids?, analysis_type?) -> {success}
+      create_subtitles(settings?, background?) -> {success | job_id}  — auto-caption from audio.
+        These are long ops: background=true returns a job_id immediately; poll
+        resolve_control(action="job_status", params={"job_id": ...}).
+      detect_scene_cuts(background?) -> {success | job_id}
+      analyze_dolby_vision(clip_ids?, analysis_type?, background?) -> {success | job_id}
       grab_still() -> {success}
       grab_all_stills(source?) -> {count}
     """
@@ -19640,11 +19871,13 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         return err
 
     if action == "create_subtitles":
-        with long_resolve_op("timeline_ai.create_subtitles"):
-            return _safe_create_subtitles(tl, p)
+        return _run_maybe_background(
+            "timeline_ai.create_subtitles", p, lambda: _safe_create_subtitles(tl, p)
+        )
     elif action == "detect_scene_cuts":
-        with long_resolve_op("timeline_ai.detect_scene_cuts"):
-            return {"success": bool(tl.DetectSceneCuts())}
+        return _run_maybe_background(
+            "timeline_ai.detect_scene_cuts", p, lambda: {"success": bool(tl.DetectSceneCuts())}
+        )
     elif action == "analyze_dolby_vision":
         clip_ids = p.get("clip_ids", [])
         items = []
@@ -19655,8 +19888,10 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                         if it.GetUniqueId() in clip_ids:
                             items.append(it)
         analysis_type = p.get("analysis_type")
-        with long_resolve_op("timeline_ai.analyze_dolby_vision"):
-            return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
+        return _run_maybe_background(
+            "timeline_ai.analyze_dolby_vision", p,
+            lambda: {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))},
+        )
     elif action == "grab_still":
         still = tl.GrabStill()
         return _ok() if still else _err("Failed to grab still")
@@ -20628,6 +20863,18 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
         },
     },
     "timeline": {
+        "get_items": {
+            "summary": "List items on one track as a summary (name/id/start/end/duration).",
+            "params": "track_type (video|audio|subtitle), index|track_index (1-based)",
+            "returns": "{items: [{name, id, start, end, duration}]}",
+            "example": 'timeline(action="get_items", params={"track_type": "video", "index": 1})',
+        },
+        "get_items_in_track": {
+            "summary": "List items on one track with full per-item serialization.",
+            "params": "track_type (video|audio|subtitle), track_index|index (1-based)",
+            "returns": "{items}",
+            "example": 'timeline(action="get_items_in_track", params={"track_type": "audio", "track_index": 1})',
+        },
         "duplicate_clips": {
             "summary": "Re-place the same MediaPool media with the same source trim. Video clips only.",
             "params": "clip_ids?|selected?, target_track_index?|track_offset?, placement? (same_time|offset|at_playhead|track_above|after_source|next_gap), record_frame?, record_frame_offset?, copy_properties?, include_linked?",
@@ -20643,17 +20890,22 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
             ),
         },
         "create_variant_from_ranges": {
-            "summary": "Build a variant timeline from N source ranges. Source-safe; supports dry_run.",
-            "params": "name, ranges: [{source_clip_id|clip_id, start_frame, end_frame, record_frame?, track_type?}], markers?, cdl?, dry_run?",
-            "returns": "{success, id, items}",
+            "summary": "Build a variant timeline from N source ranges. Video-only unless ranges include track_type='audio'. Source-safe; dry_run validates clip ids and frame ranges.",
+            "params": (
+                "name, ranges: [{clip_id|media_pool_item_id, start_frame, end_frame, "
+                "record_frame?, track_type?}], pack?, markers?, cdl?, dry_run?  — clip_id is a "
+                "media-pool item id (not a timeline-item id); start_frame/end_frame are SOURCE "
+                "frames, end_frame exclusive (source duration = end_frame - start_frame). "
+                "pack=true butts clips together at the end of each track (gap-free, ignores record_frame)"
+            ),
+            "returns": "{success, id, items}  — items[].placed = placed frames; items[].range = the requested range",
             "example": (
                 'timeline(action="create_variant_from_ranges", params={\n'
                 '  "name": "v02_tighter_act1",\n'
                 '  "ranges": [\n'
-                '    {"source_clip_id": "TimelineItem-abc", "start_frame": 108000, "end_frame": 108120},\n'
-                '    {"source_clip_id": "TimelineItem-def", "start_frame": 108300, "end_frame": 108400}\n'
+                '    {"clip_id": "<media-pool-item-id>", "start_frame": 1200, "end_frame": 1320},\n'
+                '    {"clip_id": "<media-pool-item-id>", "start_frame": 1500, "end_frame": 1600}\n'
                 '  ],\n'
-                '  "markers": [{"frame": 0, "color": "Blue", "name": "Act1 turn"}],\n'
                 '  "dry_run": True\n'
                 '})'
             ),
@@ -21074,22 +21326,46 @@ def _propose_grade(proj, p: Dict[str, Any]) -> Dict[str, Any]:
     return payload
 
 
+# Full valid-action list per tool, for tools that expose one. Lets action_help
+# report every action (not only the documented subset) and tell an unknown
+# action apart from a valid-but-undocumented one.
+_TOOL_ACTIONS: Dict[str, List[str]] = {
+    "timeline": _TIMELINE_ACTIONS,
+}
+
+
 def _action_help(tool_name: str, p: Dict[str, Any]) -> Dict[str, Any]:
     """Return long-form guidance + example for a named action on tool_name."""
     name = (p or {}).get("name") or (p or {}).get("action_name")
     catalog = _ACTION_HELP.get(tool_name, {})
+    valid = _TOOL_ACTIONS.get(tool_name)
     if not name:
-        return _ok(tool=tool_name, available=sorted(catalog.keys()),
-                   note="Call action_help with params.name to retrieve guidance for a specific action.")
+        payload = {
+            "tool": tool_name,
+            "available": sorted(catalog.keys()),
+            "note": "Call action_help with params.name to retrieve guidance for a specific action.",
+        }
+        if valid is not None:
+            payload["actions"] = sorted(valid)
+            payload["note"] = ("'available' lists actions with detailed help; 'actions' lists all "
+                               "valid actions. Call action_help with params.name for one action.")
+        return _ok(**payload)
     entry = catalog.get(name)
-    if not entry:
+    if entry:
+        return _ok(tool=tool_name, action=name, **entry)
+    if valid is not None and name not in valid:
         return _err(
-            f"No help registered for {tool_name}.{name}.",
-            code="HELP_NOT_REGISTERED",
+            f"Unknown action {tool_name}.{name}.",
+            code="UNKNOWN_ACTION",
             category="invalid_input",
-            remediation=f"Call action_help() with no name for the list of actions with detailed help.",
+            remediation=f"Valid actions: {', '.join(sorted(valid))}",
         )
-    return _ok(tool=tool_name, action=name, **entry)
+    return _err(
+        f"No help registered for {tool_name}.{name}.",
+        code="HELP_NOT_REGISTERED",
+        category="invalid_input",
+        remediation="Call action_help() with no name for the list of actions with detailed help.",
+    )
 
 
 def _grade_evidence_line(*, item_name, version_label, num_nodes, has_lut, group_name,
@@ -24975,8 +25251,58 @@ def _resource_install_guidance() -> Dict[str, Any]:
 # Server Startup
 # ═══════════════════════════════════════════════════════════════════════════════
 
+def _install_threaded_tool_dispatch(fastmcp) -> int:
+    """Run synchronous tool bodies in a worker thread instead of inline on the
+    event loop.
+
+    The MCP SDK invokes a sync tool function directly on the single asyncio
+    event-loop thread, so a blocking Resolve call (or subprocess, or the up-to-
+    60s launch wait) freezes the whole server — including the stdio read loop —
+    until it returns. Wrapping each sync tool as an async function that offloads
+    to a worker thread keeps the event loop servicing the transport. Bodies are
+    serialized on _bridge_lock so the single-threaded Resolve bridge is never
+    entered concurrently. A body that outlives a client cancellation runs to
+    completion (the bridge is never left half-mutated) still holding the lock.
+
+    Couples to mcp SDK private attrs (ToolManager._tools, Tool.fn /
+    Tool.is_async; verified on mcp 1.27). Best-effort: if that shape changes,
+    leave the tools as-is, falling back to the current inline behavior.
+    """
+    import functools
+    import anyio
+
+    manager = getattr(fastmcp, "_tool_manager", None)
+    tools = getattr(manager, "_tools", None)
+    if not isinstance(tools, dict) or not tools:
+        return 0
+
+    def _offloaded(fn):
+        @functools.wraps(fn)
+        async def run_off_thread(**kwargs):
+            def call():
+                with _bridge_lock:
+                    return fn(**kwargs)
+            return await anyio.to_thread.run_sync(call)
+        return run_off_thread
+
+    wrapped = 0
+    for tool in tools.values():
+        if getattr(tool, "is_async", False):
+            continue
+        try:
+            tool.fn = _offloaded(tool.fn)
+            tool.is_async = True
+        except Exception as exc:  # unexpected SDK shape — keep the original tool
+            logger.warning(f"threaded tool dispatch skipped for {getattr(tool, 'name', '?')}: {exc}")
+            continue
+        wrapped += 1
+    logger.info(f"Threaded tool dispatch installed for {wrapped} tools")
+    return wrapped
+
+
 if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
+    _install_threaded_tool_dispatch(mcp)
 
     # Support --full flag to run the 341-tool granular server instead
     if "--full" in sys.argv:
@@ -24984,6 +25310,7 @@ if __name__ == "__main__":
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 
+        _install_threaded_tool_dispatch(granular_mcp)
         run_fastmcp_stdio(granular_mcp)
         sys.exit(0)