davinci-resolve-mcp 2.37.2 → 2.38.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.38.0
+
+Busy gate for long DaVinci Resolve operations — the first piece of the
+concurrency design for the stdio + networked two-instance setup.
+
+- **Added** cross-process registration for long synchronous Resolve calls
+  (timeline export/import, scene-cut detection, subtitle generation,
+  Dolby Vision analysis, folder/clip audio transcription). A tool call that
+  arrives while one is running now waits up to 5 seconds and then returns a
+  structured `RESOLVE_BUSY` error (new `busy` category, retryable, with
+  `state.busy_with` and `state.age_seconds`) instead of hanging silently
+  inside the scripting bridge. Stale registrations from crashed operations
+  are ignored automatically; an operation never gates its own thread.
+- Design decisions recorded: single-editor/multi-client is the supported
+  concurrency target; confirm tokens stay per-instance; actor identity is
+  deferred to the governance phase.
+
+## What's New in v2.37.3
+
+Deep-audit fixes, rounds two and three: agent-facing action discovery,
+crash-safe user-state persistence, and resource hygiene.
+
+- **Fixed** three tools' unknown-action error lists drifting from their real
+  dispatch: `timeline` omitted `clip_where` and `action_help`;
+  `timeline_item_color` and `graph` omitted `action_help`. Agents recovering
+  from a typo now see the full action set. A static AST test keeps every
+  tool's advertised list in both-way sync with its dispatch (and verifies
+  docstring-advertised actions are real).
+- **Fixed** user-state files being vulnerable to truncation by a crash
+  mid-write. Affected files all reset to `{}` on corruption, so the next
+  save would silently wipe remaining user data. Writers now use atomic
+  temp-file + `os.replace`: `media-analysis-preferences.json` (all
+  analysis/caps/governance/update defaults — including the
+  `set_resolution_tier` and `set_caps_preset` paths, now routed through the
+  shared writer), `update-check.json`, the dashboard's `analysis.json`
+  transcription patch, and `transcript-corrections.json`.
+- **Fixed** `_safe_project_delete` discarding `SaveProject()`'s result when
+  closing the current project before deletion; a failed save now surfaces
+  as a warning in the response.
+- **Fixed** a file-descriptor leak: the parent kept its copy of the control
+  panel's log handle open after spawning the detached child.
+- Audit classes verified clean: bare excepts, mutable default arguments,
+  `asyncio.run` inside running loops, subprocess timeouts, docstring phantom
+  actions, silent-success swallows in metadata/marker/archive write paths.
+
 ## What's New in v2.37.2
 
 Static-audit fixes — four undefined-name references that silently fell back

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.37.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.38.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-33%20(341%20full)-blue.svg)](#server-modes)

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.37.2"
+VERSION = "2.38.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.37.2",
+  "version": "2.38.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -21,6 +21,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from urllib.parse import parse_qs, unquote, urlparse
 
 from src.utils.media_analysis import (
+    _write_json as _atomic_write_json,
     analysis_index_status,
     analysis_root_coverage,
     build_analysis_index,
@@ -12605,9 +12606,7 @@ def regenerate_clip_transcript(
     if payload.get("words"):
         updated_report["transcription"]["words"] = payload["words"]
     try:
-        with open(artifacts["analysis_json"], "w", encoding="utf-8") as handle:
-            json.dump(updated_report, handle, indent=2)
-            handle.write("\n")
+        _atomic_write_json(artifacts["analysis_json"], updated_report)
     except Exception as exc:
         return {"success": False, "error": f"transcript written but analysis.json patch failed: {exc}"}
     word_segment_count = sum(1 for seg in (payload.get("segments") or []) if isinstance(seg, dict) and seg.get("words"))
@@ -12779,9 +12778,7 @@ def save_clip_transcript_corrections(project_root: str, clip_id: str, body: Dict
         },
     }
     try:
-        with open(path, "w", encoding="utf-8") as handle:
-            json.dump(payload, handle, indent=2)
-            handle.write("\n")
+        _atomic_write_json(path, payload)
     except Exception as exc:
         return {"success": False, "error": str(exc)}
     return {

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.37.2"
+VERSION = "2.38.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/resolve_control.py

@@ -534,5 +534,5 @@ def quit_resolve() -> Dict[str, Any]:
     resolve = get_resolve()
     if resolve is None:
         return {"error": "Not connected to DaVinci Resolve"}
-    result = resolve.Quit()
+    resolve.Quit()
     return {"success": True, "message": "DaVinci Resolve is quitting"}

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.37.2"
+VERSION = "2.38.0"
 
 import base64
 import os
@@ -84,6 +84,8 @@ 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 resolve_busy
+from src.utils.resolve_busy import long_resolve_op
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
     batch_job_status as media_analysis_batch_job_status,
@@ -830,6 +832,7 @@ ERROR_CATEGORIES = (
     "wrong_page",            # action requires a specific page (Color, Edit, Fairlight…)
     "invalid_input",         # caller-side fixable (bad param shape, unknown enum)
     "resolve_api_failed",    # Resolve returned None/False for unclear reasons
+    "busy",                  # another long Resolve op holds the bridge; retry later
     "destructive_blocked",   # strict-mode/confirm-token refusal
     "pending_user_decision", # confirm_token required
     "unsupported",           # feature/version/method not available
@@ -846,6 +849,7 @@ _CATEGORY_RETRYABLE_DEFAULT: Dict[str, bool] = {
     "wrong_page":            True,   # trivial caller fix; retry after page switch
     "invalid_input":         False,  # caller fix required
     "resolve_api_failed":    True,   # often transient; retry once
+    "busy":                  True,   # another long Resolve op holds the bridge
     "destructive_blocked":   False,  # user decision required
     "pending_user_decision": False,  # confirm_token required
     "unsupported":           False,  # API/version mismatch
@@ -1671,6 +1675,19 @@ def _annotation_boundary_report(tl, p: Dict[str, Any]):
     }
 
 def _check():
+    busy = resolve_busy.wait_until_free()
+    if busy:
+        return None, None, _err(
+            f"Resolve is busy with a long operation: {busy['label']} "
+            f"(running for {busy['age_seconds']}s). Retry after it completes.",
+            code="RESOLVE_BUSY", category="busy",
+            remediation="Wait for the named operation to finish, then retry this call.",
+            state={
+                "busy_with": busy["label"],
+                "age_seconds": busy["age_seconds"],
+                "same_process": busy["same_process"],
+            },
+        )
     resolve = get_resolve()
     if resolve is None:
         return None, None, _err(
@@ -4916,7 +4933,8 @@ def _export_timeline_checked(tl, p: Dict[str, Any]):
     spec = _timeline_export_spec(p, 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"})
-    success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
+    with long_resolve_op("timeline.export_timeline_checked"):
+        success = bool(tl.Export(path, spec["export_type"], spec["export_subtype"]))
     files = []
     primary_file = path
     if success and os.path.isdir(path):
@@ -4969,7 +4987,8 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
         tl_existing = proj.GetTimelineByIndex(index)
         if tl_existing:
             before_ids.add(str(tl_existing.GetUniqueId()))
-    imported = mp.ImportTimelineFromFile(path, options)
+    with long_resolve_op("timeline.import_timeline_checked"):
+        imported = mp.ImportTimelineFromFile(path, options)
     if not imported:
         return _err("Failed to import timeline")
     imported_id = str(imported.GetUniqueId())
@@ -5937,7 +5956,8 @@ def _subtitle_generation_probe(tl, p: Dict[str, Any]):
         return _ok(would_generate=True, settings=settings, note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
     if not _has_method(tl, "CreateSubtitlesFromAudio"):
         return _err("CreateSubtitlesFromAudio unavailable")
-    return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
+    with long_resolve_op("timeline.create_subtitles_from_audio"):
+        return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
 
 
 def _fairlight_boundary_report(proj, mp, tl, p: Dict[str, Any]):
@@ -6944,11 +6964,22 @@ def _read_media_analysis_preferences() -> Dict[str, Any]:
 
 
 def _write_media_analysis_preferences(preferences: Dict[str, Any]) -> None:
+    # Atomic replace: a crash mid-write must not truncate the file, because the
+    # reader resets to {} on corruption and the next save would then wipe every
+    # remaining user preference.
     path = _media_analysis_preferences_path()
     os.makedirs(os.path.dirname(path), exist_ok=True)
-    with open(path, "w", encoding="utf-8") as handle:
-        json.dump(preferences, handle, indent=2, sort_keys=True)
-        handle.write("\n")
+    tmp_path = f"{path}.tmp-{os.getpid()}-{threading.get_ident()}-{time.time_ns()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(preferences, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(tmp_path, path)
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
 
 
 def _setup_text_key(value: Any) -> str:
@@ -11553,6 +11584,11 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
         )
     except (OSError, FileNotFoundError) as exc:
         return _err(f"Failed to launch control panel: {type(exc).__name__}: {exc}")
+    finally:
+        # The child holds its own copy of the fd; keeping ours open would leak
+        # one descriptor per panel launch.
+        if log_handle is not subprocess.DEVNULL:
+            log_handle.close()
 
     # Verify the child actually came up. Bind errors (port in use), import
     # failures, etc. would otherwise leave us reporting "launched" while the
@@ -12270,11 +12306,14 @@ def _safe_project_delete(pm, p: Dict[str, Any]) -> Dict[str, Any]:
     if current_name == name:
         if not p.get("close_current", False):
             return _err("Refusing to delete the currently open project; pass close_current=True")
-        if p.get("save_current", True):
-            pm.SaveProject()
+        saved = bool(pm.SaveProject()) if p.get("save_current", True) else None
         closed = bool(pm.CloseProject(current))
         if not closed:
             return _err(f"Failed to close current project '{name}' before delete")
+        result = {"success": bool(pm.DeleteProject(name))}
+        if saved is False:
+            result["warning"] = "SaveProject returned False before close; unsaved changes may have been discarded"
+        return result
     return {"success": bool(pm.DeleteProject(name))}
 
 
@@ -13792,7 +13831,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "setup_multicam_timeline":
         return _setup_multicam_timeline(proj, mp, p)
     elif action == "import_timeline":
-        tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
+        with long_resolve_op("media_pool.import_timeline"):
+            tl = mp.ImportTimelineFromFile(p["path"], p.get("options", {}))
         return _ok(name=tl.GetName()) if tl else _err("Failed to import timeline")
     elif action == "delete_timelines":
         count = proj.GetTimelineCount()
@@ -14002,8 +14042,10 @@ 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:
-            return {"success": bool(f.TranscribeAudio())}
-        return {"success": bool(f.TranscribeAudio(bool(usd)))}
+            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)))}
     elif action == "clear_transcription":
         return {"success": bool(f.ClearTranscription())}
     elif action == "perform_audio_classification":
@@ -14319,8 +14361,10 @@ 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:
-            return {"success": bool(clip.TranscribeAudio())}
-        return {"success": bool(clip.TranscribeAudio(bool(usd)))}
+            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)))}
     elif action == "clear_transcription":
         return {"success": bool(clip.ClearTranscription())}
     elif action == "get_transcription":
@@ -14759,10 +14803,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         prefs["resolve_ai_governance_preset"] = preset
         if isinstance(p.get("overrides"), dict):
             prefs["resolve_ai_governance_overrides"] = p["overrides"]
-        path = _media_analysis_preferences_path()
-        os.makedirs(os.path.dirname(path), exist_ok=True)
-        with open(path, "w", encoding="utf-8") as fh:
-            json.dump(prefs, fh, indent=2)
+        _write_media_analysis_preferences(prefs)
         return {"success": True, "tier": preset, "overrides": prefs.get("resolve_ai_governance_overrides") or {}}
     if action == "set_caps_preset":
         preset = (p.get("preset") or "").strip().lower()
@@ -14774,10 +14815,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         prefs["analysis_caps_preset"] = preset
         if isinstance(p.get("overrides"), dict):
             prefs["analysis_caps_overrides"] = p["overrides"]
-        path = _media_analysis_preferences_path()
-        os.makedirs(os.path.dirname(path), exist_ok=True)
-        with open(path, "w", encoding="utf-8") as fh:
-            json.dump(prefs, fh, indent=2)
+        _write_media_analysis_preferences(prefs)
         return {"success": True, "preset": preset, "overrides": prefs.get("analysis_caps_overrides") or {}}
     if action == "get_usage":
         from src.utils import analysis_caps as _ac
@@ -15795,7 +15833,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "import_into_timeline":
         return {"success": bool(tl.ImportIntoTimeline(p["path"], p.get("options", {})))}
     elif action == "export":
-        return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
+        with long_resolve_op("timeline.export"):
+            return {"success": bool(tl.Export(p["path"], p["type"], p.get("subtype", "")))}
     elif action == "get_setting":
         return {"settings": _ser(tl.GetSetting(p.get("name", "")))}
     elif action == "set_setting":
@@ -16099,7 +16138,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",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
+    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])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -16236,9 +16275,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         return err
 
     if action == "create_subtitles":
-        return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
+        with long_resolve_op("timeline_ai.create_subtitles"):
+            return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
     elif action == "detect_scene_cuts":
-        return {"success": bool(tl.DetectSceneCuts())}
+        with long_resolve_op("timeline_ai.detect_scene_cuts"):
+            return {"success": bool(tl.DetectSceneCuts())}
     elif action == "analyze_dolby_vision":
         clip_ids = p.get("clip_ids", [])
         items = []
@@ -16249,7 +16290,8 @@ 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")
-        return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
+        with long_resolve_op("timeline_ai.analyze_dolby_vision"):
+            return {"success": bool(tl.AnalyzeDolbyVision(items, analysis_type))}
     elif action == "grab_still":
         still = tl.GrabStill()
         return _ok() if still else _err("Failed to grab still")
@@ -18018,7 +18060,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
         return {"success": bool(item.CreateMagicMask(p.get("mode", "F")))}
     elif action == "regenerate_magic_mask":
         return {"success": bool(item.RegenerateMagicMask())}
-    return _unknown(action, ["set_cdl","copy_grades","add_version","get_current_version","get_version_names","load_version","rename_version","delete_version","get_node_graph","get_color_group","assign_color_group","remove_from_color_group","export_lut","get_color_cache","set_color_cache","get_fusion_cache","set_fusion_cache","reset_all_node_colors","stabilize","smart_reframe","create_magic_mask","regenerate_magic_mask",*_COLOR_GRADE_KERNEL_ACTIONS])
+    return _unknown(action, ["set_cdl","copy_grades","add_version","get_current_version","get_version_names","load_version","rename_version","delete_version","get_node_graph","get_color_group","assign_color_group","remove_from_color_group","export_lut","get_color_cache","set_color_cache","get_fusion_cache","set_fusion_cache","reset_all_node_colors","stabilize","smart_reframe","create_magic_mask","regenerate_magic_mask","action_help",*_COLOR_GRADE_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -18402,7 +18444,7 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         if blocked:
             return blocked
         return {"success": bool(g.ResetAllGrades())}
-    return _unknown(action, ["get_num_nodes","get_lut","set_lut","get_node_cache","set_node_cache","get_node_label","get_tools_in_node","set_node_enabled","apply_grade_from_drx","apply_arri_cdl_lut","reset_all_grades"])
+    return _unknown(action, ["get_num_nodes","get_lut","set_lut","get_node_cache","set_node_cache","get_node_label","get_tools_in_node","set_node_enabled","apply_grade_from_drx","apply_arri_cdl_lut","reset_all_grades","action_help"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/resolve_busy.py

@@ -0,0 +1,171 @@
+"""Cross-process visibility for long synchronous DaVinci Resolve operations.
+
+The Resolve scripting bridge executes one call at a time. Most calls return in
+milliseconds, but a handful block for seconds-to-minutes (timeline export and
+import, scene-cut detection, subtitle generation, audio transcription). A
+second tool call issued during one of those — from another thread of this
+server, or from the other instance when stdio and networked servers share one
+Resolve — simply hangs inside fusionscript with no feedback.
+
+This module gives those long operations a name and a presence that every
+instance can see, so the Resolve preflight can wait briefly and then return a
+structured "busy" answer instead of hanging:
+
+    with long_resolve_op("timeline.export"):
+        tl.Export(...)
+
+    op = wait_until_free(timeout_seconds=5.0)   # None when free
+    if op:
+        ... return a RESOLVE_BUSY error naming op["label"] ...
+
+Registration is advisory and best-effort: a sidecar JSON file in the temp dir
+(same approach as page_lock) carries {label, pid, thread, started_at}. Records
+are ignored when their pid is dead or they exceed MAX_OP_AGE_SECONDS, so a
+crashed operation can never wedge the server. The registering thread is exempt
+from its own gate — long operations call Resolve helpers internally.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Optional
+
+_SIDECAR = os.path.join(tempfile.gettempdir(), "davinci_resolve_mcp_busy.json")
+# A long op that has run this long is presumed crashed/leaked and ignored.
+MAX_OP_AGE_SECONDS = 2 * 60 * 60
+# Default time a preflight will wait for the bridge to free up before
+# returning a busy error.
+DEFAULT_WAIT_SECONDS = 5.0
+_POLL_SECONDS = 0.25
+
+_lock = threading.Lock()
+_local_owner: Optional[int] = None  # thread ident of the in-process registrant
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def _read_record() -> Optional[Dict[str, Any]]:
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(record, dict) or not record.get("label"):
+        return None
+    started_at = record.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return None
+    if time.time() - started_at > MAX_OP_AGE_SECONDS:
+        return None
+    pid = record.get("pid")
+    if not isinstance(pid, int) or not _pid_alive(pid):
+        return None
+    return record
+
+
+def _write_record(record: Dict[str, Any]) -> None:
+    tmp_path = f"{_SIDECAR}.tmp-{os.getpid()}-{threading.get_ident()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(record, handle)
+        os.replace(tmp_path, _SIDECAR)
+    except OSError:
+        pass
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+
+def _clear_record() -> None:
+    record = None
+    try:
+        with open(_SIDECAR, "r", encoding="utf-8") as handle:
+            record = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        pass
+    # Only the owning process removes the sidecar; never clobber another
+    # instance's registration.
+    if isinstance(record, dict) and record.get("pid") == os.getpid():
+        try:
+            os.remove(_SIDECAR)
+        except OSError:
+            pass
+
+
+def current_long_op() -> Optional[Dict[str, Any]]:
+    """The active long operation visible across instances, or None."""
+    record = _read_record()
+    if record is None:
+        return None
+    return {
+        "label": record.get("label"),
+        "pid": record.get("pid"),
+        "same_process": record.get("pid") == os.getpid(),
+        "started_at": record.get("started_at"),
+        "age_seconds": round(max(0.0, time.time() - float(record.get("started_at", 0.0))), 1),
+    }
+
+
+@contextmanager
+def long_resolve_op(label: str):
+    """Register a long synchronous Resolve call for its duration."""
+    global _local_owner
+    ident = threading.get_ident()
+    with _lock:
+        nested = _local_owner is not None
+        if not nested:
+            _local_owner = ident
+    if not nested:
+        _write_record({
+            "label": str(label),
+            "pid": os.getpid(),
+            "thread": ident,
+            "started_at": time.time(),
+        })
+    try:
+        yield
+    finally:
+        if not nested:
+            with _lock:
+                _local_owner = None
+            _clear_record()
+
+
+def wait_until_free(timeout_seconds: Optional[float] = None) -> Optional[Dict[str, Any]]:
+    """Wait briefly for any long op to finish.
+
+    Returns None when the bridge is free (or becomes free within the timeout),
+    otherwise the still-running operation's info. The thread that registered
+    the current in-process op is never gated by it. timeout_seconds defaults
+    to DEFAULT_WAIT_SECONDS, read at call time so callers/tests can tune it.
+    """
+    if timeout_seconds is None:
+        timeout_seconds = DEFAULT_WAIT_SECONDS
+    deadline = time.monotonic() + max(0.0, float(timeout_seconds))
+    while True:
+        op = current_long_op()
+        if op is None:
+            return None
+        if op["same_process"]:
+            record = _read_record() or {}
+            if record.get("thread") == threading.get_ident():
+                return None
+        if time.monotonic() >= deadline:
+            return op
+        time.sleep(_POLL_SECONDS)

package/src/utils/update_check.py

@@ -631,13 +631,22 @@ def _read_state(path: Path) -> Dict[str, Any]:
 
 
 def _write_state(path: Path, result: Mapping[str, Any]) -> None:
+    # Atomic replace: _read_state resets to {} on a corrupt file, so a crash
+    # mid-write would silently drop snooze/ignore preferences.
+    tmp_path = path.with_name(f"{path.name}.tmp-{os.getpid()}")
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
-        with path.open("w", encoding="utf-8") as handle:
+        with tmp_path.open("w", encoding="utf-8") as handle:
             json.dump(result, handle, indent=2, sort_keys=True)
             handle.write("\n")
+        os.replace(tmp_path, path)
     except OSError:
         return
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
 
 
 def _set_cached_status(result: Mapping[str, Any]) -> None: