davinci-resolve-mcp 2.82.0 → 2.86.1

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.82.0"
+VERSION = "2.86.1"
 
 import base64
 import os
@@ -46,6 +46,8 @@ for p in [current_dir, project_dir]:
 from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
+from src.utils import clip_colors as _clip_colors
+from src.utils import resolve_versions as _resolve_versions
 from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
@@ -179,9 +181,10 @@ mcp = FastMCP(
         "if one is already running they never launch a second. "
         "On a connection error, read the error's own remediation field — it names the "
         "fix that applies. External scripting is Studio-only, but the free edition is "
-        "reachable via the in-app bridge (Workspace > Scripts > resolve_bridge, with "
-        "DAVINCI_RESOLVE_BRIDGE=1), so a connection error does NOT mean the free "
-        "edition is unsupported."
+        "reachable via the in-app bridge (Workspace > Scripts > resolve_bridge — it is "
+        "used automatically when external scripting is unavailable; "
+        "DAVINCI_RESOLVE_BRIDGE=1 only forces it), so a connection error does NOT mean "
+        "the free edition is unsupported."
     ),
 )
 
@@ -936,8 +939,8 @@ def get_resolve():
                 "DaVinci Resolve is already running but is not answering the scripting API, "
                 "so it will NOT be launched again. Either enable Preferences > General > "
                 "'External scripting using' = Local (Studio only), or, on the free edition, "
-                "use the in-app bridge: install it, run Workspace > Scripts > resolve_bridge, "
-                "and set DAVINCI_RESOLVE_BRIDGE=1."
+                "use the in-app bridge: install it and run Workspace > Scripts > resolve_bridge "
+                "— once running it is used automatically, no environment variable needed."
             )
             return None
         if already_running is None:
@@ -990,8 +993,10 @@ def _not_connected_error():
             reason="External scripting is a Studio feature; the free edition refuses it "
                    "regardless of the preference. Resolve was NOT launched again.",
             remediation="On Studio: Preferences > General > 'External scripting using' = Local. "
-                        "On the free edition: install the in-app bridge, run "
-                        "Workspace > Scripts > resolve_bridge, and set DAVINCI_RESOLVE_BRIDGE=1.",
+                        "On the free edition: install the in-app bridge and run "
+                        "Workspace > Scripts > resolve_bridge — once it is running it is used "
+                        "automatically, no environment variable needed "
+                        "(DAVINCI_RESOLVE_BRIDGE=1 only forces it and disables this fallback).",
             # Which Resolve is refusing matters to the reader: a headless render
             # worker and the editor the user is looking at warrant different
             # responses, and the in-app bridge is not an option for the former.
@@ -3541,7 +3546,9 @@ def _coerce_item_list(value):
 
 def _get_selected_timeline_items(tl):
     warnings = []
-    for method_name in ("GetSelectedTimelineItems", "GetSelectedItems", "GetSelectedClips"):
+    # GetSelectedClips is the documented name since Resolve 21.0.4; the other two
+    # are legacy speculative probes kept for older/renamed builds.
+    for method_name in ("GetSelectedClips", "GetSelectedTimelineItems", "GetSelectedItems"):
         method = getattr(tl, method_name, None)
         if not callable(method):
             continue
@@ -7731,6 +7738,7 @@ _MEDIA_POOL_ITEM_METHODS = [
     "GetMarkInOut",
     "SetMarkInOut",
     "ClearMarkInOut",
+    "GetTimeline",
 ]
 
 _MEDIA_POOL_METHODS = [
@@ -9006,6 +9014,66 @@ def _safe_int(value: Any, default: int, *, minimum: Optional[int] = None, maximu
     return parsed
 
 
+def _set_clip_color_checked(obj, color, *, kind: str):
+    """SetClipColor, with the bare bool turned into something a caller can act on.
+
+    Two measured failures hide behind that bool (issue #124, enumerated live on
+    Studio 19.1.3.7):
+
+    - A name outside the 16-name Edit-page palette is refused with `False` and
+      nothing else. The marker constants are the only colour vocabulary the
+      scripting reference enumerates, so they are what an agent reaches for, and
+      most of them are refused.
+    - On generator and title items the call returns `True` and the colour does
+      not persist — `GetClipColor` still reads empty afterwards. Media-backed
+      items on the same timeline persist correctly, so the bool is honest for
+      some items and a lie for others.
+
+    So the return value is never trusted on its own: the colour is read back and
+    the response reports what actually stuck.
+    """
+    returned = bool(obj.SetClipColor(color))
+    readback = None
+    if _has_method(obj, "GetClipColor"):
+        try:
+            readback = obj.GetClipColor()
+        except Exception:  # pragma: no cover - defensive; getter is documented
+            readback = None
+    persisted = (readback == color) if readback is not None else None
+
+    if not returned:
+        refusal = _clip_colors.clip_color_refusal(color)
+        return _err(
+            f"SetClipColor refused '{color}' on this {kind}",
+            code="CLIP_COLOR_REJECTED",
+            category="invalid_input",
+            reason=refusal["reason"],
+            remediation=refusal["remediation"],
+            state=refusal["state"],
+        )
+    if persisted is False:
+        # The generator/title case. Reporting success here is the silent lie.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "warnings": [{
+                "code": "CLIP_COLOR_NOT_PERSISTED",
+                "message": (
+                    f"SetClipColor returned True on this {kind} but the colour did "
+                    f"not persist — GetClipColor reads {readback!r}. Measured on "
+                    "generator and title items, which take the call and drop it; "
+                    "media-backed items on the same timeline persist correctly."
+                ),
+                "remediation": (
+                    "Colour a media-backed item, or mark the generator another way "
+                    "(a timeline marker at its start reads back reliably)."
+                ),
+            }],
+        }
+    return {"success": True, "color": color, "readback": readback}
+
+
 def _filter_to_keys(settings: Any, allowed) -> Tuple[Dict[str, Any], list]:
     """Whitelist a settings/options dict to the keys a Resolve API documents.
 
@@ -13486,8 +13554,18 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       ignore_mcp_update() -> {success, version, update, decision}
       snooze_mcp_update(hours?) -> {success, version, update, decision}
       clear_mcp_update_preferences() -> {success, version, update, decision}
-      api_truth(query?) -> {verified_on, count, facts}  — look up behaviorally-verified
-        facts about quirky/unreliable Resolve API behavior (no connection needed).
+      api_truth(query?, resolve_version?) -> {verified_on, count, facts, live_version?}
+        — look up behaviorally-verified facts about quirky/unreliable Resolve API
+        behavior (no connection needed; never connects). When a build is already
+        connected or resolve_version is passed, each fact carries a
+        version_context saying whether it was measured on an older, newer or
+        identical build — the API changes per PATCH release, so a fact from
+        another build is a prior, not a finding.
+      check_version_support(symbol?, resolve_version?) -> {live_version, support|unavailable_on_this_build}
+        — does THIS build have that method? Answers "unknown" unless a gate is
+        recorded, because most of the API has never been version-bisected and a
+        false "available" is how an agent insists a missing method exists.
+        Omit symbol for every recorded gate this build does not clear.
       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}
@@ -13515,10 +13593,72 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     """
     p = _params(params)
 
-    # api_truth is a static knowledge lookup — no Resolve connection needed.
+    # api_truth is a static knowledge lookup — no Resolve connection needed, and
+    # that property is worth keeping: it is the one call that still answers when
+    # Resolve is down or unreachable. So the live build is used only if one is
+    # ALREADY connected, or if the caller names it. Never connect for this.
     if action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
-        return {"verified_on": _API_TRUTH_VERIFIED_ON, "count": len(facts), "facts": facts}
+        live_version = p.get("resolve_version")
+        if not live_version and resolve is not None:
+            try:
+                live_version = resolve.GetVersionString()
+            except Exception:
+                live_version = None
+        result = {
+            "verified_on": _API_TRUTH_VERIFIED_ON,
+            "count": len(facts),
+            "facts": _resolve_versions.annotate_facts(
+                facts, live_version, ledger_verified_on=_API_TRUTH_VERIFIED_ON
+            ),
+        }
+        if live_version:
+            result["live_version"] = str(live_version)
+            unavailable = _resolve_versions.gates_unavailable_on(live_version)
+            if unavailable:
+                result["unavailable_on_this_build"] = unavailable
+        else:
+            result["version_context"] = (
+                "No live build known, so facts are unannotated. The scripting API "
+                "changes per PATCH release, so a fact measured on another build is a "
+                "prior rather than a finding. Pass resolve_version, or call "
+                "get_version first."
+            )
+        return result
+    if action == "check_version_support":
+        # "Does THIS build have it?" asked directly, instead of inferred from
+        # prose. Answers `unknown` unless a gate is recorded — see
+        # utils/resolve_versions.py for why that default is the load-bearing one.
+        live_version = p.get("resolve_version")
+        if not live_version and resolve is not None:
+            try:
+                live_version = resolve.GetVersionString()
+            except Exception:
+                live_version = None
+        if not live_version:
+            return _err(
+                "No Resolve version available",
+                code="VERSION_UNKNOWN",
+                category="invalid_input",
+                reason="Nothing is connected and no resolve_version was passed.",
+                remediation="Call get_version first, or pass resolve_version='21.0.4.5'.",
+            )
+        symbol = p.get("symbol")
+        if symbol:
+            return {
+                "live_version": str(live_version),
+                "support": _resolve_versions.availability(symbol, live_version),
+            }
+        return {
+            "live_version": str(live_version),
+            "unavailable_on_this_build": _resolve_versions.gates_unavailable_on(live_version),
+            "known_gates": len(_resolve_versions.VERSION_GATES),
+            "note": (
+                "Only surfaces with recorded evidence appear here. Most of the "
+                "scripting API has never been version-bisected, so an absence from "
+                "this list is not a promise that a method exists."
+            ),
+        }
     if action == "verification_stats":
         # Process-level readback-verification tally — no connection needed.
         stats = _verification_stats()
@@ -13676,7 +13816,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","runtime_mode","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"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","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 ────────────────
@@ -15967,6 +16107,9 @@ _RENDER_SETTING_KEYS = [
     "ReplaceExistingFilesInPlace",
     "ExportSubtitle",
     "SubtitleFormat",
+    "UseFullExtents",
+    "AddFrameHandles",
+    "DataBurnIn",
 ]
 
 _RENDER_KERNEL_ACTIONS = [
@@ -16186,6 +16329,24 @@ def _render_preset_pin(proj, preset_name: str):
     return {"preset": preset_name, "loaded": True}, None
 
 
+def _render_settings_warnings(settings: Dict[str, Any]):
+    """Inter-key combinations Resolve accepts and then silently ignores.
+
+    SetRenderSettings returns True for these, so nothing downstream would ever
+    tell the caller the key did nothing — the same silent-no-op class as the
+    unknown-key drop that `_filter_to_keys` covers on the set path.
+    """
+    warnings = []
+    if not isinstance(settings, dict):
+        return warnings
+    if settings.get("UseFullExtents") is True and isinstance(settings.get("AddFrameHandles"), int) and settings["AddFrameHandles"] > 0:
+        warnings.append(
+            "AddFrameHandles is ignored while UseFullExtents is true: Resolve renders the "
+            "clip's full extents and the handle count silently does nothing. Drop one of the two."
+        )
+    return warnings
+
+
 def _validate_render_settings_payload(settings: Dict[str, Any], *, require_temp_target: bool = False):
     if not isinstance(settings, dict) or not settings:
         return None, _err("settings must be a non-empty object")
@@ -16201,15 +16362,20 @@ def _validate_render_settings_payload(settings: Dict[str, Any], *, require_temp_
             errors.append("TargetDir must be under the system temp directory for this safe operation")
     elif require_temp_target:
         errors.append("TargetDir is required for this safe operation")
-    for key in ("FormatWidth", "FormatHeight", "MarkIn", "MarkOut", "AudioBitDepth", "AudioSampleRate"):
+    for key in ("FormatWidth", "FormatHeight", "MarkIn", "MarkOut", "AudioBitDepth", "AudioSampleRate", "AddFrameHandles"):
         if key in settings and not isinstance(settings[key], int):
             errors.append(f"{key} must be an integer")
-    for key in ("SelectAllFrames", "ExportVideo", "ExportAudio", "ExportAlpha", "MultiPassEncode", "NetworkOptimization", "ReplaceExistingFilesInPlace", "ExportSubtitle"):
+    for key in ("SelectAllFrames", "ExportVideo", "ExportAudio", "ExportAlpha", "MultiPassEncode", "NetworkOptimization", "ReplaceExistingFilesInPlace", "ExportSubtitle", "UseFullExtents"):
         if key in settings and not isinstance(settings[key], bool):
             errors.append(f"{key} must be a boolean")
+    if "AddFrameHandles" in settings and isinstance(settings["AddFrameHandles"], int) and settings["AddFrameHandles"] < 0:
+        errors.append("AddFrameHandles must be >= 0")
+    if "DataBurnIn" in settings and not isinstance(settings["DataBurnIn"], str):
+        errors.append("DataBurnIn must be a string (a burn-in preset name, 'Same as project', or 'None')")
     if "MarkIn" in settings and "MarkOut" in settings and settings["MarkOut"] < settings["MarkIn"]:
         errors.append("MarkOut must be greater than or equal to MarkIn")
-    result = {"valid": not errors, "unknown_keys": unknown, "errors": errors, "settings": dict(settings)}
+    result = {"valid": not errors, "unknown_keys": unknown, "errors": errors,
+              "warnings": _render_settings_warnings(settings), "settings": dict(settings)}
     return result, None
 
 
@@ -16660,7 +16826,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
       set_mode(mode) -> {success}
       get_resolutions(format, codec) -> {resolutions}
       get_settings() -> {settings}  (alias for set_render_settings with get)
-      set_settings(settings) -> {success}
+      set_settings(settings) -> {success, ignored_settings?, warnings?}
+        Resolve 21.0.4+ settings keys: UseFullExtents (bool),
+        AddFrameHandles (int >= 0), DataBurnIn (burn-in preset name,
+        "Same as project", or "None"). AddFrameHandles is ignored while
+        UseFullExtents is true — the call still succeeds, so that pairing
+        comes back in warnings rather than silently doing nothing.
       list_presets() -> {presets}
       load_preset(name) -> {success}
       save_preset(name) -> {success}
@@ -16784,6 +16955,11 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         result = {"success": bool(proj.SetRenderSettings(settings))}
         if ignored_settings:
             result["ignored_settings"] = ignored_settings
+        # Accepted-then-ignored key combinations (21.0.4 AddFrameHandles under
+        # UseFullExtents) read as a clean success without this.
+        warnings = _render_settings_warnings(settings)
+        if warnings:
+            result["warnings"] = warnings
         return result
     elif action == "list_presets":
         return {"presets": proj.GetRenderPresetList()}
@@ -17611,6 +17787,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       get_mark_in_out(clip_id) -> {mark}
       set_mark_in_out(clip_id, mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(clip_id, type?) -> {success}
+      get_timeline(clip_id) -> {is_timeline, timeline: {name, unique_id?, start_frame?, end_frame?}}
+        — Resolve 21.0.4+. Resolves a Media Pool timeline entry to its timeline
+          object summary; is_timeline=false for ordinary clips.
       open_in_viewer(clip_id, page?, mark_in_seconds?, mark_out_seconds?, clear_marks?) -> {success, clip_id, clip_name, folder_name, page, mark_set}
         — Switches to Media page (default) and selects the clip in the bin.
           Resolve auto-loads the selected clip into the source viewer on Media page.
@@ -17783,7 +17962,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_clip_color":
         return {"color": clip.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(clip.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(clip, p["color"], kind="media pool item")
     elif action == "clear_clip_color":
         return {"success": bool(clip.ClearClipColor())}
     elif action == "link_proxy":
@@ -17939,7 +18118,28 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"success": bool(clip.SetMarkInOut(clean["mark_in"], clean["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(clip.ClearMarkInOut(p.get("type", "all")))}
-    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","extract_frames","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
+    elif action == "get_timeline":
+        missing = _requires_method(clip, "GetTimeline", "21.0.4")
+        if missing:
+            return missing
+        try:
+            tl_obj = clip.GetTimeline()
+        except Exception as exc:
+            return _err(f"GetTimeline failed: {exc}")
+        if not tl_obj:
+            return {"is_timeline": False, "timeline": None,
+                    "note": "This media pool item is not a timeline entry."}
+        summary = {}
+        for getter, key in (("GetName", "name"), ("GetUniqueId", "unique_id"),
+                            ("GetStartFrame", "start_frame"), ("GetEndFrame", "end_frame")):
+            if _has_method(tl_obj, getter):
+                try:
+                    summary[key] = getattr(tl_obj, getter)()
+                except Exception:
+                    pass
+        return {"is_timeline": True, "timeline": summary,
+                "note": "Address this timeline by name via the timeline tool."}
+    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","extract_frames","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer","get_timeline"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -22251,7 +22451,7 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
     elif action == "get_clip_color":
         return {"color": item.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(item.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(item, p["color"], kind="timeline item")
     elif action == "clear_clip_color":
         return {"success": bool(item.ClearClipColor())}
     return _unknown(action, ["add","get_all","get_by_custom_data","update_custom_data","get_custom_data","delete_by_color","delete_at_frame","delete_by_custom_data","add_flag","get_flags","clear_flags","get_clip_color","set_clip_color","clear_clip_color"])

package/src/utils/api_truth.py

@@ -863,7 +863,10 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "mix CAN be applied wholesale via "
                    "Project.ApplyFairlightPresetToCurrentTimeline(name), with the "
                    "available names from Resolve.GetFairlightPresets() — so "
-                   "'no Fairlight write path exists' would be too strong.",
+                   "'no Fairlight write path exists' would be too strong. Both "
+                   "methods require Resolve 20.2.2+; on 19.1.3 they are absent "
+                   "(confirmed live 2026-08-06), so on older builds the "
+                   "per-parameter gap really is the whole story.",
         "recommended": "To reapply a known mix, save it once as a Fairlight preset "
                        "in the UI and apply it per-timeline with "
                        "ApplyFairlightPresetToCurrentTimeline (exposed as "
@@ -1005,7 +1008,8 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "a normalised position vector (param 17). Exposed as "
                        "project_db list_subtitle_styles / set_subtitle_style "
                        "(font family/size/weight/italic + position). Confirmed "
-                       "live on 21.0 (2026-08-06): Resolve opens a patched track "
+                       "live on BOTH editions 2026-08-06 — Studio 19.1.3 and "
+                       "free 21.0.3, identical behaviour: Resolve opens a patched track "
                        "and re-serialises it back to its own zstd form with the "
                        "patched values intact, so it genuinely parses the write. "
                        "Caveats: whole-TRACK style not per-caption, project must "
@@ -1067,13 +1071,29 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "NOT refute the 21.0.0 record: if the bridge resolves any name "
                    "known to the RemoteObject method table rather than literally any "
                    "string, an invented name is correctly rejected on both builds and "
-                   "the probe never exercised the failing case. Re-running the probe "
-                   "with those five real names is what would settle it; until then, "
-                   "assume fabrication is possible.",
+                   "the probe never exercised the failing case. "
+                   "PARTLY SETTLED 2026-08-06 on Studio 19.1.3.7, DIRECT connection "
+                   "(not the bridge): the five real borrowed names were re-run as the "
+                   "entry asked, across Resolve, ProjectManager, Project, MediaPool, "
+                   "Timeline, Folder and TimelineItem — 42 checks. Every one returned "
+                   "getattr-callable False and dir()-absent, agreeing in all 42 cases, "
+                   "exactly like the invented control. So NO fabrication on the direct "
+                   "path on this build, and the borrowed-name case the 21.0.2.4 probe "
+                   "missed is now covered there. What the same run DID establish is "
+                   "narrower and worse than expected: bare hasattr() returns True for "
+                   "EVERY name on every object — real, borrowed or invented — while "
+                   "getattr returns None. hasattr alone is therefore not a weak probe, "
+                   "it is a constant True and carries no information at all. "
+                   "STILL OPEN: the 21.0.0 record was against the BRIDGE, which this "
+                   "run did not exercise, so bridge-side fabrication remains untested "
+                   "and the recommendation below stands unchanged.",
         "recommended": "Use dir(obj) membership for capability probes. It is correct "
                        "on every build measured, and it is the only form not affected "
-                       "by whichever way this resolves. server._has_method uses "
-                       "hasattr/getattr and so may over-report on builds where "
+                       "by whichever way this resolves. NEVER use bare hasattr(): it "
+                       "is a constant True on Resolve objects and cannot distinguish "
+                       "anything. server._has_method uses callable(getattr(...)), "
+                       "which agreed with dir() in all 42 direct-path checks on "
+                       "19.1.3.7 but may still over-report on a bridge build where "
                        "fabrication is live — that is the case _requires_method gates "
                        "guard, so it matters most exactly where it is least tested. "
                        "Calling a fabricated method typically returns None/False with "
@@ -1421,6 +1441,65 @@ API_TRUTH: List[Dict[str, Any]] = [
         "issue": 59,
         "mitigation": ["_render_format_id", "_render_codec_id"],
     },
+    {
+        "symbol": "SetClipColor (undocumented value space; marker constants are a decoy)",
+        "object": "TimelineItem / MediaPoolItem",
+        "signature": "(colorName) -> bool",
+        "reality": "SetClipColor accepts exactly 16 names — the Edit-page clip-colour "
+                   "palette — and refuses everything else with a bare False, no "
+                   "exception and no other signal. Enumerated live on Studio "
+                   "19.1.3.7 (2026-08-06) against both objects; the accepted set is "
+                   "IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, "
+                   "Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, "
+                   "Pink, Tan, Beige, Brown, Chocolate. The empty string is refused "
+                   "too. The trap is that the scripting reference documents "
+                   "colorName as a bare string with no enumerated values, while "
+                   "exporting the MARKER palette as constants (resolve.MARKER_ROSE, "
+                   "resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary "
+                   "reachable from the API surface is the wrong one. Cyan, Red, "
+                   "Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream "
+                   "are all marker-only and all refused. Five names overlap both "
+                   "palettes (Blue, Green, Yellow, Pink, Purple), which is why the "
+                   "decoy survives: reasoning from the marker constants scores 5 of "
+                   "16 and looks like the right vocabulary with a few gaps. The "
+                   "reporter's field experience sharpens this — the trap is not that "
+                   "a decoy vocabulary exists, it is that the decoy HALF-WORKS. "
+                   "Intermittent successes read as an unreliable API rather than as "
+                   "a wrong vocabulary, so the wrong conclusion is the natural one; "
+                   "a clean 0-for-8 would have exposed the mechanism immediately.",
+        "recommended": "Pass only the 16 clip-colour names; on False, treat it as an "
+                       "invalid name rather than an item/lock/page problem. The set "
+                       "is pinned in utils/clip_colors.py and named in the refusal "
+                       "remediation, but deliberately NOT enforced — it was measured "
+                       "on one build and a later Resolve could extend it.",
+        "tags": ["timeline-item", "media-pool", "silent-failure", "undocumented-enum"],
+        "submit": "missing",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
+    {
+        "symbol": "TimelineItem.SetClipColor on generator/title items",
+        "object": "TimelineItem",
+        "signature": "(colorName) -> bool",
+        "reality": "On a generator or title item SetClipColor returns True with a "
+                   "VALID colour name and the colour does not persist — GetClipColor "
+                   "still reads '' immediately afterwards, and ClearClipColor "
+                   "changes nothing because there is nothing to clear. Measured on "
+                   "Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A "
+                   "media-backed item on the SAME timeline in the same session "
+                   "persists correctly (SetClipColor('Teal') -> True, GetClipColor "
+                   "-> 'Teal'), so the bool is honest for some items and a lie for "
+                   "others, with nothing in the return value to tell them apart. A "
+                   "timeline item's colour is also independent of its backing "
+                   "MediaPoolItem's: colouring the item leaves the pool clip at ''.",
+        "recommended": "Never trust the bool alone — read GetClipColor back and "
+                       "compare. To mark a generator or title, use a timeline marker "
+                       "at its start instead; markers read back reliably.",
+        "tags": ["timeline-item", "silent-failure", "generator", "readback-lies"],
+        "submit": "bug",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
     {
         "symbol": "Project.SetRenderSettings (inherits the loaded preset)",
         "object": "Project",

package/src/utils/clip_colors.py

@@ -0,0 +1,94 @@
+"""The value space of SetClipColor, and an honest refusal when a name misses.
+
+`SetClipColor(colorName) --> Bool` is documented with `colorName` as a bare
+string and no enumerated values anywhere in the scripting reference. The same
+reference *does* export a discoverable colour vocabulary — the marker constants
+(`resolve.MARKER_ROSE`, `resolve.MARKER_FUCHSIA`, …) — so the only colour names
+reachable from the API surface come from the marker palette, and those are
+largely the ones `SetClipColor` refuses. Issue #124 named this a decoy
+vocabulary, which is exactly right.
+
+Enumerated live on **DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)**
+against both objects that expose the method. Both accept the same 16 names —
+the Edit-page clip-colour palette — and refuse everything else with a bare
+`False`, including every marker-only name and the empty string.
+
+The five names that overlap the two palettes (Blue, Green, Yellow, Pink,
+Purple) are what makes this trap so durable: an agent reasoning from the marker
+constants gets five hits out of sixteen and concludes the vocabulary is right.
+
+This set is deliberately NOT enforced. It was measured on one build, and a
+future Resolve could extend it; hard-rejecting an unlisted name would turn a
+working call into a failure on a build we have not seen. Callers pass the name
+through, and when Resolve refuses, the remediation names the measured-valid set.
+"""
+
+VERIFIED_ON = "DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)"
+
+# Accepted by BOTH TimelineItem.SetClipColor and MediaPoolItem.SetClipColor.
+CLIP_COLORS = (
+    "Orange", "Apricot", "Yellow", "Lime", "Olive", "Green", "Teal", "Navy",
+    "Blue", "Purple", "Violet", "Pink", "Tan", "Beige", "Brown", "Chocolate",
+)
+
+# Measured refused. Kept explicit because these are the names an agent actually
+# reaches for: every one is either a marker constant or a common colour word.
+REFUSED_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream", "Apple", "Magenta", "White", "Black", "Gray",
+    "Grey", "",
+)
+
+# The marker-palette names that are NOT clip colours — the decoy set proper.
+MARKER_ONLY_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream",
+)
+
+
+def is_known_clip_color(color) -> bool:
+    """True if `color` is in the measured-valid set. Case-sensitive, as Resolve is."""
+    return isinstance(color, str) and color in CLIP_COLORS
+
+
+def clip_color_refusal(color) -> dict:
+    """Error payload for a SetClipColor that came back False.
+
+    Separates 'you used a marker name' from 'Resolve refused for another
+    reason', because the caller cannot tell them apart from the bare bool.
+    """
+    marker_decoy = isinstance(color, str) and color in MARKER_ONLY_NAMES
+    if marker_decoy:
+        reason = (
+            f"'{color}' is a MARKER colour, not a clip colour. The scripting "
+            "reference enumerates the marker constants and nothing else, so it "
+            "is the vocabulary an agent finds first — and SetClipColor refuses "
+            "most of it with a bare False."
+        )
+    elif is_known_clip_color(color):
+        reason = (
+            f"'{color}' is a valid clip colour on {VERIFIED_ON}, so this refusal "
+            "is about the item or the session, not the name. Note that "
+            "SetClipColor returns True WITHOUT persisting on generator and title "
+            "items — check GetClipColor rather than the bool."
+        )
+    else:
+        reason = (
+            f"'{color}' is not in the clip-colour palette. SetClipColor refuses "
+            "undocumented names with a bare False and no other signal."
+        )
+    return {
+        "reason": reason,
+        "remediation": (
+            "Use one of the 16 Edit-page clip colours: "
+            + ", ".join(CLIP_COLORS)
+            + f". Measured on {VERIFIED_ON}; the set is not enforced here because "
+            "a later build could extend it."
+        ),
+        "state": {
+            "requested_color": color,
+            "valid_colors": list(CLIP_COLORS),
+            "is_marker_only_name": marker_decoy,
+            "verified_on": VERIFIED_ON,
+        },
+    }

package/src/utils/edit_engine.py

@@ -1742,6 +1742,12 @@ def plan_transcript_tighten(
         plan.get("keep_ranges") or [],
         source_duration_seconds=float(duration) if isinstance(duration, (int, float)) and duration else None,
     )
+    # The class this planner is structurally blind to. Its false-start heuristic
+    # only sees restarts the transcript actually reports; an immediate re-read is
+    # emitted ONCE with the pause and second take absorbed into one word, so the
+    # plan cannot propose removing what it was never told happened (issue #125).
+    from src.utils import swallowed_retakes as _swallowed
+    plan["possible_swallowed_retakes"] = _swallowed.swallowed_retake_report(words)
     return plan
 
 

package/src/utils/resolve_bridge_client.py

@@ -55,8 +55,10 @@ logger = logging.getLogger("resolve-mcp.bridge-client")
 DEFAULT_CONFIG_PATH = Path.home() / ".config/davinci-resolve-mcp/bridge.json"
 #: Env override, so a caller can point at a non-default bridge without editing code.
 ENV_CONFIG_PATH = "DAVINCI_RESOLVE_BRIDGE_CONFIG"
-#: Opt-in. Absent means "do not try the bridge", so nothing changes for existing
-#: installs until someone asks for it.
+#: Forces the bridge: it becomes the only transport tried, so its faults surface
+#: directly. Absent does NOT mean "never try the bridge" — `connect_resolve` falls
+#: back to it when a direct transport yields nothing, which is what lets the free
+#: edition work with no configuration beyond starting the in-Resolve script.
 ENV_ENABLE = "DAVINCI_RESOLVE_BRIDGE"
 
 #: Operations this client cannot work without. The in-Resolve script is a *copy*
@@ -390,7 +392,8 @@ def connect(*, timeout: float = DEFAULT_TIMEOUT_SECONDS, require_enabled: bool =
     """
     if require_enabled and not bridge_enabled():
         raise BridgeUnavailable(
-            f"The in-app bridge is opt-in: set {ENV_ENABLE}=1 to use it."
+            f"This caller required an explicitly-enabled bridge: set {ENV_ENABLE}=1, "
+            "or call connect(require_enabled=False) to use the bridge as a fallback."
         )
     path = config_path()
     try: