davinci-resolve-mcp 2.104.0 → 2.104.2

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.104.0"
+VERSION = "2.104.2"
 
 import base64
 import os
@@ -44,6 +44,7 @@ for p in [current_dir, project_dir]:
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
+from src.utils import resolve_writes as _resolve_writes
 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
@@ -6421,12 +6422,28 @@ def _timeline_create_variant_from_ranges(proj, source_tl, p: Dict[str, Any]) ->
     new_tl = mp.CreateEmptyTimeline(name)
     if not new_tl:
         return _err(f"Failed to create timeline: {name}")
-    proj.SetCurrentTimeline(new_tl)
+    switch_err = _set_current_timeline_checked(proj, new_tl, what="building the variant")
+    if switch_err:
+        return switch_err
     if p.get("start_timecode"):
+        # A refused start timecode leaves the variant at the default hour while
+        # every record frame below was computed against the requested one, so
+        # the whole build lands at the wrong absolute time.
         try:
-            new_tl.SetStartTimecode(p["start_timecode"])
-        except Exception:
-            pass
+            start_tc_set = bool(new_tl.SetStartTimecode(p["start_timecode"]))
+            start_tc_error = None
+        except Exception as exc:
+            start_tc_set, start_tc_error = False, str(exc)
+        if not start_tc_set:
+            return _err(
+                f"SetStartTimecode({p['start_timecode']!r}) was refused on '{name}'",
+                code="START_TIMECODE_REFUSED", category="api_error", retryable=False,
+                reason=(start_tc_error or
+                        "Resolve returned False. The variant would sit at the default "
+                        "start timecode while its record frames assume the requested one."),
+                remediation="Check the timecode is valid for the timeline's frame rate, "
+                            "or omit start_timecode to build at the default start.",
+            )
     for track_type, needed in max_tracks.items():
         while int(new_tl.GetTrackCount(track_type) or 0) < needed:
             if not new_tl.AddTrack(track_type):
@@ -6673,7 +6690,16 @@ def _timeline_thumbnail_contact_sheet(proj, tl, p: Dict[str, Any]) -> Dict[str,
                     sampled.append(sample)
                     continue
                 try:
-                    tl.SetCurrentTimecode(timecode)
+                    # A refused playhead move means the thumbnail below is the
+                    # frame the playhead was ALREADY on -- a sheet of the wrong
+                    # frames, labelled with the frames that were asked for.
+                    if not tl.SetCurrentTimecode(timecode):
+                        sample["error"] = (
+                            f"Playhead would not move to {timecode}; no thumbnail was "
+                            "sampled here rather than sampling the wrong frame"
+                        )
+                        sampled.append(sample)
+                        continue
                     thumbnail = tl.GetCurrentClipThumbnailImage()
                     if not thumbnail:
                         sample["error"] = (
@@ -6690,11 +6716,7 @@ def _timeline_thumbnail_contact_sheet(proj, tl, p: Dict[str, Any]) -> Dict[str,
                     sample["error"] = str(exc)
                 sampled.append(sample)
         finally:
-            if original_timecode:
-                try:
-                    tl.SetCurrentTimecode(original_timecode)
-                except Exception:
-                    pass
+            _restore_playhead(tl, original_timecode, what="the contact sheet")
     sheet_samples = [sample for sample in sampled if sample.get("thumbnail_rgb")]
     if not sheet_samples:
         return {"success": False, "samples": sampled, "error": "No thumbnails could be sampled"}
@@ -6982,6 +7004,41 @@ _BINARY_INTERCHANGE_EXTS = {".aaf"}
 _JSON_INTERCHANGE_EXTS = {".otio"}
 
 
+_FCP7_SEQUENCE_NAME_RE = re.compile(
+    r"(<sequence\b[^>]*>(?:(?!<name>|</sequence>)[\s\S])*?<name>)([\s\S]*?)(</name>)"
+)
+
+
+def _rewrite_fcp7_sequence_name(xml_path: str, new_name: str):
+    """Copy an FCP7 XML with its first <sequence><name> replaced; (path, changed, error).
+
+    Resolve honours the sequence name INSIDE the file, not the timelineName
+    import option: when the internal name matches an existing timeline, the
+    import silently hands back that existing timeline (issue #171). Rewriting
+    the internal name is the only way to make the option mean what it says.
+    Surgical text replacement on a temp copy — the original is never touched,
+    and everything but the one name survives byte-for-byte (an XML re-serialize
+    would drop the xmeml DOCTYPE).
+    """
+    try:
+        with open(xml_path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except OSError as exc:
+        return None, False, f"could not read {xml_path}: {exc}"
+    escaped = (
+        new_name.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+    text, count = _FCP7_SEQUENCE_NAME_RE.subn(
+        lambda m: m.group(1) + escaped + m.group(3), text, count=1
+    )
+    if not count:
+        return None, False, None
+    fd, out_path = tempfile.mkstemp(prefix="timeline_name_", suffix=".xml")
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    return out_path, True, None
+
+
 def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     path = p.get("path")
     if not path:
@@ -7112,6 +7169,22 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             ) if k in sres
         }
 
+    # Resolve honours the interchange file's internal sequence name over the
+    # timelineName option (issue #171): with a stale internal name that matches
+    # an existing timeline, the import "succeeds" by returning the existing
+    # timeline. For FCP7 XML the name is rewritable in place; for formats we
+    # cannot rewrite, the created_new gate below turns the case into an error.
+    requested_name = options.get("timelineName")
+    sequence_name_rewritten = False
+    if requested_name and not is_binary and not is_json:
+        rewritten_path, sequence_name_rewritten, rewrite_err = _rewrite_fcp7_sequence_name(
+            import_path, str(requested_name)
+        )
+        if rewrite_err:
+            return _err(f"Could not rewrite the sequence name: {rewrite_err}")
+        if sequence_name_rewritten:
+            import_path = rewritten_path
+
     if p.get("dry_run"):
         out = _ok(path=path, import_path=import_path, options=options, would_import=True)
         if sanitize_report is not None:
@@ -7198,14 +7271,38 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             relink_result = _binary_post_import_relink(imported, mp, search_roots)
             if relink_result.get("after"):
                 media = relink_result["after"]
+        created_new = imported_id not in before_ids
+        if requested_name and not created_new:
+            # The caller asked for a NEW timeline by name and got an existing
+            # one back — the interchange file's internal sequence name matched
+            # it and Resolve ignored the option (issue #171). success:true with
+            # created_new:false read as an import; an iterating loop would
+            # operate on the same timeline forever.
+            return _err(
+                f"Import returned the EXISTING timeline {imported.GetName()!r} "
+                f"({imported_id}) instead of creating {requested_name!r}. Resolve "
+                "honours the sequence name inside the file over the timelineName "
+                "option, and this file's internal name matched an existing "
+                "timeline.",
+                category="api_error",
+                remediation=(
+                    "Rewrite the sequence name inside the interchange file to the "
+                    "new name before importing (for FCP7 XML this wrapper does it "
+                    f"automatically; it could not for this file{' — the <sequence><name> pattern was not found' if not sequence_name_rewritten else ''}), "
+                    "or delete/rename the existing timeline first."
+                ),
+                state={"existing_name": imported.GetName(), "existing_id": imported_id},
+            )
         out = _ok(
             name=imported.GetName(),
             id=imported_id,
-            created_new=imported_id not in before_ids,
+            created_new=created_new,
             timeline_count=proj.GetTimelineCount(),
             api_returned_object=api_returned_object,
             media=media,
         )
+        if sequence_name_rewritten:
+            out["sequence_name_rewritten"] = True
         if sanitize_report is not None:
             out["sanitize"] = sanitize_report
         if relink_result is not None:
@@ -8781,15 +8878,28 @@ def _setup_multicam_timeline(proj, mp, p: Dict[str, Any]):
     new_tl = mp.CreateEmptyTimeline(plan["name"])
     if not new_tl:
         return _err(f"Failed to create multicam setup timeline: {plan['name']}")
-    try:
-        proj.SetCurrentTimeline(new_tl)
-    except Exception:
-        pass
+    switch_err = _set_current_timeline_checked(proj, new_tl, what="stacking the angles")
+    if switch_err:
+        return switch_err
     if plan.get("start_timecode"):
+        # Same as the variant builder: the angle stack's record frames assume
+        # this start, so a refusal puts every angle at the wrong absolute time.
         try:
-            new_tl.SetStartTimecode(plan["start_timecode"])
-        except Exception:
-            pass
+            start_tc_set = bool(new_tl.SetStartTimecode(plan["start_timecode"]))
+            start_tc_error = None
+        except Exception as exc:
+            start_tc_set, start_tc_error = False, str(exc)
+        if not start_tc_set:
+            return _err(
+                f"SetStartTimecode({plan['start_timecode']!r}) was refused on "
+                f"'{plan['name']}'",
+                code="START_TIMECODE_REFUSED", category="api_error", retryable=False,
+                reason=(start_tc_error or
+                        "Resolve returned False. The angle stack would land at the "
+                        "wrong absolute time."),
+                remediation="Check the timecode is valid for the timeline's frame rate, "
+                            "or omit start_timecode.",
+            )
 
     audio_type = str(p.get("audio_type", p.get("audioType", "stereo")) or "stereo")
     video_tracks = _ensure_timeline_tracks(new_tl, "video", plan.get("max_video_track", 0))
@@ -10502,7 +10612,18 @@ def _apply_sync_event_markers(proj, detection: Dict[str, Any], p: Dict[str, Any]
                 skipped.append({"clip_id": clip_id, "frame": marker["frame"], "reason": "Marker already exists", "custom_data": custom_data})
                 continue
             if existing and replace_existing and _has_method(clip, "DeleteMarkerByCustomData"):
-                clip.DeleteMarkerByCustomData(custom_data)
+                # A discarded False leaves the old marker in place, and AddMarker
+                # then refuses the occupied frame -- reported as "add failed"
+                # when the real failure was the delete.
+                if not clip.DeleteMarkerByCustomData(custom_data):
+                    failed.append({
+                        "clip_id": clip_id, "frame": marker["frame"],
+                        "custom_data": custom_data,
+                        "reason": "replace_existing was requested but "
+                                  "DeleteMarkerByCustomData refused; the existing "
+                                  "marker is still there and nothing was replaced",
+                    })
+                    continue
         result = _add_marker(clip, marker)
         if result.get("success"):
             added.append({
@@ -10899,7 +11020,20 @@ def _apply_media_analysis_clip_markers(clip, markers: List[Dict[str, Any]], p: D
                 skipped.append({"frame": marker.get("frame"), "name": marker.get("name"), "reason": "Marker already exists", "custom_data": custom_data})
                 continue
             if existing and replace_existing and _has_method(clip, "DeleteMarkerByCustomData"):
-                clip.DeleteMarkerByCustomData(custom_data)
+                # A discarded False leaves the old marker in place, and AddMarker
+                # then refuses the occupied frame -- reported as "add failed"
+                # when the real failure was the delete.
+                if not clip.DeleteMarkerByCustomData(custom_data):
+                    failed.append({
+                        "marker": marker,
+                        "result": {
+                            "success": False,
+                            "reason": "replace_existing was requested but "
+                                      "DeleteMarkerByCustomData refused; the existing "
+                                      "marker is still there and nothing was replaced",
+                        },
+                    })
+                    continue
         result = _add_marker(clip, marker)
         if result.get("success"):
             added.append({"frame": result.get("frame"), "name": marker.get("name"), "custom_data": custom_data})
@@ -12506,11 +12640,24 @@ def _set_current_folder_temporarily(mp, target_path: Optional[str]):
 
 
 def _restore_current_folder(mp, previous):
-    if previous:
-        try:
-            mp.SetCurrentFolder(previous)
-        except Exception:
-            pass
+    """Put the Media Pool's current folder back. Logged, never raised.
+
+    Fire-and-forget by design: this runs after the real work, the current
+    folder is UI state that nothing downstream reads, and turning a failed
+    teardown into a failed operation would report a successful import as a
+    failure. Logged rather than swallowed, because a bin left open somewhere
+    unexpected is otherwise unexplained.
+    """
+    if not previous:
+        return
+    try:
+        restored = mp.SetCurrentFolder(previous)
+    except Exception as exc:
+        logger.debug("could not restore the current Media Pool folder: %s", exc)
+        return
+    if not restored:
+        logger.debug("could not restore the current Media Pool folder: "
+                     "SetCurrentFolder returned %r", restored)
 
 
 def _ensure_folder_path(mp, path: str):
@@ -13812,11 +13959,7 @@ def _playhead_frame_preview(tl, p: Dict[str, Any]):
                 width, height, raw = _box_downscale_rgb(width, height, raw, int(max_width))
             return Image(data=_rgb_to_png_bytes(width, height, raw), format="png")
         finally:
-            if original_tc:
-                try:
-                    tl.SetCurrentTimecode(original_tc)
-                except Exception:
-                    pass
+            _restore_playhead(tl, original_tc, what="the thumbnail capture")
 
 
 def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
@@ -13929,7 +14072,11 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         if not job:
             return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
         before = set(os.listdir(folder))
-        if not proj.StartRendering([job], isInteractiveMode=False):
+        # Positional on purpose: the free-edition bridge proxies method calls
+        # positionally, and a keyword argument dies inside _BoundMethod with
+        # "unexpected keyword argument 'isInteractiveMode'" before reaching
+        # Resolve (reported on 21.0.4.5 free/Windows, PR #165).
+        if not proj.StartRendering([job], False):
             return _err("StartRendering refused the job", code="RENDER_START_FAILED", category="api_error")
         waited = 0.0
         while proj.IsRenderingInProgress() and waited < 120:
@@ -13967,11 +14114,22 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
             except Exception:
                 pass
         if original_fc:
+            # A failed restore leaves the Deliver page on the capture's format
+            # and codec, which the user's next render would silently inherit.
+            # This runs in a teardown path, so it is logged rather than raised.
             try:
-                proj.SetCurrentRenderFormatAndCodec(
+                restored_fc = proj.SetCurrentRenderFormatAndCodec(
                     original_fc.get("format"), original_fc.get("codec"))
-            except Exception:
-                pass
+            except Exception as exc:
+                restored_fc, restore_exc = False, exc
+            else:
+                restore_exc = None
+            if not restored_fc:
+                logger.warning(
+                    "frame capture could not restore the render format/codec to %s/%s: %s",
+                    original_fc.get("format"), original_fc.get("codec"),
+                    restore_exc or "SetCurrentRenderFormatAndCodec returned False",
+                )
         # Best-effort, not a restore: without GetRenderSettings there is nothing
         # to restore FROM, so put the mark range back to the whole timeline
         # rather than leaving it pinned to the captured frame.
@@ -13995,11 +14153,7 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                 os.rmdir(folder)
         except OSError:
             pass
-        if original_tc:
-            try:
-                tl.SetCurrentTimecode(original_tc)
-            except Exception:
-                pass
+        _restore_playhead(tl, original_tc, what="the render capture")
         if original_page and original_page != "deliver":
             try:
                 _open_page_serialized(resolve, original_page)
@@ -14110,11 +14264,7 @@ def _playhead_frame_full(proj, tl, p: Dict[str, Any]):
                     album.DeleteStills([still])
                 except Exception:
                     pass
-            if original_tc:
-                try:
-                    tl.SetCurrentTimecode(original_tc)
-                except Exception:
-                    pass
+            _restore_playhead(tl, original_tc, what="the still capture")
             try:
                 for name in os.listdir(folder):
                     if name.startswith(prefix):
@@ -14188,10 +14338,71 @@ def _playhead_frame_capture(p: Dict[str, Any]):
         return _playhead_frame_render(proj, tl, p)
     finally:
         if original_tl is not None:
-            try:
-                proj.SetCurrentTimeline(original_tl)
-            except Exception:
-                pass
+            # Best-effort by necessity: this runs in a finally, so raising or
+            # returning here would replace the caller's real result (or its real
+            # exception) with a restore failure. It is still not silent -- a
+            # failed restore leaves the editor on a different timeline, which is
+            # visible immediately, and it is logged.
+            restore_err = _set_current_timeline_checked(
+                proj, original_tl, what="restoring the timeline after the capture")
+            if restore_err:
+                logger.warning(
+                    "frame capture could not restore the current timeline: %s",
+                    restore_err["error"]["message"],
+                )
+
+
+def _restore_playhead(tl, timecode, *, what: str) -> None:
+    """Put the playhead back after a capture. Logged, never raised.
+
+    Deliberately fire-and-forget on the CALLER's behalf: every use of this runs
+    in a `finally`, so raising or returning an error would replace the caller's
+    real result -- or its real exception -- with a teardown failure. What it is
+    not is silent. A refused restore leaves the editor's playhead somewhere
+    else, and a support log that says so is the difference between a two-minute
+    diagnosis and an afternoon.
+    """
+    if not timecode:
+        return
+    try:
+        moved = tl.SetCurrentTimecode(timecode)
+    except Exception as exc:
+        logger.warning("could not restore the playhead to %s after %s: %s",
+                       timecode, what, exc)
+        return
+    if not moved:
+        logger.warning("could not restore the playhead to %s after %s: "
+                       "SetCurrentTimecode returned %r", timecode, what, moved)
+
+
+def _set_current_timeline_checked(proj, tl, *, what: str):
+    """Switch the project's current timeline and PROVE it switched.
+
+    Returns None on success, or an error envelope naming what did not happen.
+
+    This is not UI polish. `AppendToTimeline`, `GetCurrentTimeline` and every
+    other "current timeline" call writes to whatever the PROJECT believes is
+    current, not to the handle in scope. A discarded False here sends the
+    assembly to the timeline the editor was looking at while the tool reports
+    the new timeline's name and id, which is the worst possible shape of
+    failure: the work happened, on the wrong timeline, under a success.
+
+    The bare bool is not trusted on its own. A Resolve attached to no database
+    answers version queries normally while every project mutation returns False
+    or None, and a True that did not take has been observed there, so the
+    switch is confirmed by reading the current timeline back.
+    """
+    ok, detail = _resolve_writes.set_current_timeline(proj, tl)
+    if ok:
+        return None
+    return _err(
+        _resolve_writes.describe_switch_failure(detail, what),
+        code="TIMELINE_SWITCH_FAILED", category="api_error", retryable=False,
+        reason="A discarded False here writes the work to the wrong timeline.",
+        remediation="Quit and restart Resolve if it came up with no database attached "
+                    "(resolve_control runtime_mode reports that), then retry.",
+        state=detail,
+    )
 
 
 def _unknown(action, valid):
@@ -16271,14 +16482,31 @@ def _resolve_restore_state(p: Dict[str, Any]) -> Dict[str, Any]:
             for i in range(1, count + 1):
                 tl = proj.GetTimelineByIndex(i)
                 if tl and tl.GetUniqueId() == state["current_timeline_id"]:
-                    proj.SetCurrentTimeline(tl)
+                    # The one function whose whole job is putting things back
+                    # must not claim it did. restored[] is written only on a
+                    # verified switch; a failure is reported, not swallowed.
+                    switch_err = _set_current_timeline_checked(
+                        proj, tl, what="restoring the saved state")
+                    if switch_err:
+                        restored["current_timeline_error"] = switch_err["error"]["message"]
+                        break
                     restored["current_timeline_id"] = state["current_timeline_id"]
                     if state.get("current_timecode"):
+                        # restored[] is a claim about what was put back. Writing
+                        # it before checking made restore_state report a playhead
+                        # position it had not reached.
                         try:
-                            tl.SetCurrentTimecode(state["current_timecode"])
+                            moved = bool(tl.SetCurrentTimecode(state["current_timecode"]))
+                        except Exception as exc:
+                            moved, restored["current_timecode_error"] = False, str(exc)
+                        if moved:
                             restored["current_timecode"] = state["current_timecode"]
-                        except Exception:
-                            pass
+                        else:
+                            restored.setdefault(
+                                "current_timecode_error",
+                                f"SetCurrentTimecode({state['current_timecode']!r}) "
+                                "returned False; the playhead is elsewhere",
+                            )
                     break
         except Exception as exc:
             restored["timeline_error"] = str(exc)
@@ -16292,9 +16520,20 @@ def _resolve_restore_state(p: Dict[str, Any]) -> Dict[str, Any]:
                 for cid in state["selected_clip_ids"]:
                     found, parent = _find_clip_with_parent(root, cid)
                     if found and parent is not None:
-                        mp.SetCurrentFolder(parent)
-                        mp.SetSelectedClip(found)
-                        restored["selected_clip_id"] = cid
+                        # Both report with a bare bool. Claiming the selection
+                        # was restored when SetSelectedClip refused is the same
+                        # lie as the timeline and timecode above.
+                        folder_ok = bool(mp.SetCurrentFolder(parent))
+                        selected_ok = bool(mp.SetSelectedClip(found))
+                        if selected_ok:
+                            restored["selected_clip_id"] = cid
+                        else:
+                            restored["selection_error"] = (
+                                f"SetSelectedClip({cid!r}) returned False"
+                                + ("" if folder_ok else
+                                   " (SetCurrentFolder also refused, so the bin was "
+                                   "never opened)")
+                            )
                         break  # SetSelectedClip is singular; pick the first
         except Exception as exc:
             restored["selection_error"] = str(exc)
@@ -17155,10 +17394,16 @@ class _SpecLiveExecutor:
             if tl is None:
                 return False
         if fps is not None:
+            # A refused rate is the silent wrong-fps timeline: everything built
+            # on it is laid at a rate nobody asked for and the durations read
+            # back wrong. Resolve only accepts this on an EMPTY project, so the
+            # refusal is common and must not be reported as success.
             try:
-                tl.SetSetting("timelineFrameRate", str(fps))
+                rate_set = bool(tl.SetSetting("timelineFrameRate", str(fps)))
             except Exception:
-                pass
+                rate_set = False
+            if not rate_set:
+                return False
         return True
 
     def set_timeline_setting(self, tl_name: str, key: str, value: Any) -> bool:
@@ -18580,11 +18825,16 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
       delete_all_jobs() -> {success}
       list_jobs() -> {jobs}
       get_job_status(job_id) -> {status}
-      verify_output(job_id) -> {status, output_path, output_exists, output_size_bytes, output_probe, expected_duration_seconds, duration_ratio, warnings, verified}
+      verify_output(job_id, expected_frames?, expected_duration_seconds?) -> {status, output_path, output_exists, output_size_bytes, output_probe, mark_range_frames, timeline_item_extent_frames, expected_duration_seconds, duration_ratio, warnings, verified}
         JobStatus reports Complete even when the render produced a near-empty
-        stub (content before the timeline start, issue #164) — this checks the
-        actual output file against the job's mark range. Verify BEFORE deleting
-        the job; deleted jobs carry no TargetDir to check.
+        stub (content before the timeline start, issue #164), and Resolve
+        rewrites the job's own MarkIn/MarkOut down to the collapsed extent, so
+        the job metadata lies too. This checks the actual output file, and
+        cross-checks the job's timeline items (which read back their real
+        positions): items before the timeline start and a mark range far
+        smaller than the item extent both warn. Pass expected_frames or
+        expected_duration_seconds when you know what the render should hold.
+        Verify BEFORE deleting the job; deleted jobs carry no TargetDir.
       start(job_ids?, interactive?) -> {success}
       stop() -> {success}
       is_rendering() -> {rendering}
@@ -18675,6 +18925,71 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         else:
             warnings.append("Job carries no TargetDir/OutputFilename to verify against.")
         result["output_path"] = output_path
+        # The job's own MarkIn/MarkOut cannot be the only truth source: when
+        # timeline content sits before the timeline's start frame (issue #164)
+        # Resolve rewrites the job's mark range down to the collapsed extent,
+        # so the job metadata lies right along with JobStatus (measured live on
+        # Studio 19.1.3.7: 96 frames of content before start -> job range of 1
+        # frame, Complete at 100%, a 1-frame black stub). Cross-check the
+        # job's timeline items, which DO read back their real positions, and
+        # let the caller override expected duration outright.
+        try:
+            fps = float(str(job.get("FrameRate")))
+        except (TypeError, ValueError):
+            fps = None
+        try:
+            mark_frames = int(job.get("MarkOut")) - int(job.get("MarkIn")) + 1
+        except (TypeError, ValueError):
+            mark_frames = None
+        result["mark_range_frames"] = mark_frames
+        tl_for_job = None
+        try:
+            for i in range(1, int(proj.GetTimelineCount() or 0) + 1):
+                cand = proj.GetTimelineByIndex(i)
+                if cand and cand.GetName() == job.get("TimelineName"):
+                    tl_for_job = cand
+                    break
+        except Exception:
+            tl_for_job = None
+        if tl_for_job is not None:
+            try:
+                tl_start = int(tl_for_job.GetStartFrame())
+                extent_lo, extent_hi, before_start = None, None, 0
+                for ti in range(1, int(tl_for_job.GetTrackCount("video") or 0) + 1):
+                    for it in tl_for_job.GetItemListInTrack("video", ti) or []:
+                        it_start, it_end = int(it.GetStart()), int(it.GetEnd())
+                        extent_lo = it_start if extent_lo is None else min(extent_lo, it_start)
+                        extent_hi = it_end if extent_hi is None else max(extent_hi, it_end)
+                        if it_start < tl_start:
+                            before_start += 1
+                if before_start:
+                    warnings.append(
+                        f"{before_start} video item(s) on timeline "
+                        f"{job.get('TimelineName')!r} start before the timeline's "
+                        f"start frame {tl_start} — the render engine never visits "
+                        "that content (recordFrame counts from absolute frame "
+                        "zero, issue #164). The items read back as placed; the "
+                        "render is a stub."
+                    )
+                if (extent_lo is not None and mark_frames is not None
+                        and mark_frames < (extent_hi - extent_lo) * 0.5):
+                    warnings.append(
+                        f"The job's mark range ({mark_frames} frame(s)) is under "
+                        f"half the timeline's item extent "
+                        f"({extent_hi - extent_lo} frames) — Resolve rewrote the "
+                        "range down to a collapsed extent, which is how a stub "
+                        "render reports a clean duration ratio."
+                    )
+                result["timeline_item_extent_frames"] = (
+                    None if extent_lo is None else extent_hi - extent_lo
+                )
+            except Exception:
+                pass
+        else:
+            warnings.append(
+                f"Timeline {job.get('TimelineName')!r} was not found in the "
+                "project, so item-extent cross-checks were skipped."
+            )
         if output_path:
             exists = os.path.exists(output_path)
             result["output_exists"] = exists
@@ -18684,13 +18999,21 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                 if probe:
                     result["output_probe"] = probe
                     duration = probe.get("duration_seconds")
-                    # Expected duration from the job's own mark range and rate.
-                    try:
-                        frames = int(job.get("MarkOut")) - int(job.get("MarkIn")) + 1
-                        fps = float(str(job.get("FrameRate")))
-                        expected = frames / fps if fps > 0 else None
-                    except (TypeError, ValueError):
-                        expected = None
+                    # Expected duration: caller-supplied truth wins; the job's
+                    # mark range is the fallback (see collapse caveat above).
+                    expected = None
+                    if p.get("expected_duration_seconds") is not None:
+                        try:
+                            expected = float(p["expected_duration_seconds"])
+                        except (TypeError, ValueError):
+                            expected = None
+                    elif p.get("expected_frames") is not None and fps:
+                        try:
+                            expected = int(p["expected_frames"]) / fps
+                        except (TypeError, ValueError):
+                            expected = None
+                    elif mark_frames is not None and fps:
+                        expected = mark_frames / fps
                     result["expected_duration_seconds"] = expected
                     if duration is not None and expected and expected > 0:
                         result["duration_ratio"] = round(duration / expected, 4)
@@ -19087,10 +19410,10 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
             tl = mp.CreateEmptyTimeline(create_name)
             if not tl:
                 return _err("Failed to create timeline from clip_infos")
-            try:
-                proj.SetCurrentTimeline(tl)
-            except Exception:
-                pass
+            switch_err = _set_current_timeline_checked(
+                proj, tl, what="appending the clip_infos")
+            if switch_err:
+                return switch_err
             timeline_start = _timeline_start_frame(tl)
             built = []
             for i, ci in enumerate(raw):
@@ -19703,11 +20026,19 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
                     mark_set = {"applied": False, "error": str(exc)}
 
         # Navigate the bin to the clip's folder so the clip is visible to select.
+        # Not fatal on its own (SetSelectedClip may still work), but a discarded
+        # False meant the caller could not tell "the bin did not move" from
+        # "the bin moved and the clip is right there", which is the whole point
+        # of the action.
+        folder_ok: Optional[bool] = None
+        folder_error: Optional[str] = None
         if parent is not None:
             try:
-                mp.SetCurrentFolder(parent)
-            except Exception:
-                pass  # not fatal; SetSelectedClip below may still work
+                folder_ok = bool(mp.SetCurrentFolder(parent))
+            except Exception as exc:
+                folder_ok, folder_error = False, str(exc)
+            if not folder_ok:
+                folder_error = folder_error or "SetCurrentFolder returned False"
         select_ok = bool(mp.SetSelectedClip(clip))
 
         # Bring Resolve to the foreground so the editor doesn't have to
@@ -19732,6 +20063,8 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             "clip_id": clip.GetUniqueId(),
             "clip_name": clip.GetName(),
             "folder_name": parent.GetName() if parent else None,
+            "bin_opened": folder_ok,
+            "bin_error": folder_error,
             "page": page,
             "mark_set": mark_set,
             "focus": focus_result,
@@ -22573,10 +22906,10 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         tl = mp.CreateEmptyTimeline(name)
         if not tl:
             return _err("Failed to create selects timeline")
-        try:
-            proj.SetCurrentTimeline(tl)
-        except Exception:
-            pass
+        switch_err = _set_current_timeline_checked(
+            proj, tl, what="assembling the selects")
+        if switch_err:
+            return switch_err
         timeline_start = _timeline_start_frame(tl)
         built = []
         build_errors = []
@@ -22960,10 +23293,14 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         tl, _tl_index = _find_timeline_by_name(proj, plan.get("timeline_name"))
         if not tl:
             return _err(f"Timeline '{plan.get('timeline_name')}' not found")
-        try:
-            proj.SetCurrentTimeline(tl)
-        except Exception:
-            pass
+        # The lift is handle-based and hits the right timeline; the append that
+        # puts the replacement back is current-timeline-based. A failed switch
+        # here punches a hole in the target and drops the alternate on whatever
+        # the editor had open, under a reported success.
+        switch_err = _set_current_timeline_checked(
+            proj, tl, what="swapping the item")
+        if switch_err:
+            return switch_err
         before = _edit_engine_capture(tl)
         before["track_counts"] = _edit_engine_track_counts(tl)
         slot_start = int(item_block.get("timeline_start_frame"))
@@ -26513,9 +26850,17 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
                 used_format = try_fmt
                 break
             time.sleep(0.3)
-        # Clean up still from gallery
+        # Clean up still from gallery. Cleanup, not the operation: the export
+        # above is what the caller asked for and it has already been verified by
+        # the file listing below. A leftover still is visible in the Gallery
+        # rather than silent, so this is logged, not raised.
         if delete_after:
-            album.DeleteStills([still])
+            try:
+                if not album.DeleteStills([still]):
+                    logger.warning("DeleteStills returned False; a still is left in "
+                                   "the Gallery album after the export")
+            except Exception as exc:
+                logger.warning("DeleteStills raised after the export: %s", exc)
         if not export_ok:
             _discard_still_staging(staging)
             return _err("ExportStills failed — ensure the Gallery panel is open on the Color page (Workspace > Gallery)")
@@ -26668,12 +27013,20 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
             # not the per-user dir that dctl install writes to. Relocate and retry.
             relocated = _ensure_lut_in_master(lut_path)
             if relocated:
+                # The retry below only works if Resolve re-scanned the master
+                # LUT dir. A discarded False here turns the retry into a second
+                # identical failure with no explanation.
+                refreshed = None
                 try:
                     _, proj, _lut_err = _check()
                     if proj:
-                        proj.RefreshLUTList()
-                except Exception:
-                    pass
+                        refreshed = bool(proj.RefreshLUTList())
+                except Exception as exc:
+                    logger.warning("RefreshLUTList raised before the SetLUT retry: %s", exc)
+                if refreshed is False:
+                    logger.warning(
+                        "RefreshLUTList returned False; the relocated LUT may not be "
+                        "visible to SetLUT yet")
                 ok = bool(g.SetLUT(node_index, relocated))
                 if ok:
                     return {"success": True, "resolved_lut": relocated,
@@ -26941,6 +27294,19 @@ def _fusion_group_settings_load(comp, p: Dict[str, Any]) -> Dict[str, Any]:
         group.SaveSettings(backup_path)
     except Exception as exc:
         return _err(f"backup SaveSettings failed: {exc}")
+    # SaveSettings reports through the Lua bridge and its return is not
+    # reliable, but the file it was asked to write is. This backup is the only
+    # way back from the LoadSettings below, so loading without it would be an
+    # irreversible replacement of the group's graph presented as a reversible one.
+    if not os.path.isfile(backup_path):
+        return _err(
+            f"backup SaveSettings did not create a file at {backup_path!r}",
+            code="FUSION_BACKUP_NOT_WRITTEN", category="api_error", retryable=False,
+            reason="LoadSettings replaces the group's graph. Without the backup on "
+                   "disk there is no way back, so nothing was loaded.",
+            remediation="Check the backup_path directory is writable, or pass an "
+                        "explicit backup_path somewhere that is.",
+        )
 
     undo_name = p.get("undo_name", f"MCP group_settings_load {group_name}")
     undo_started = False
@@ -28086,7 +28452,31 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             except Exception:
                 _already_animated = False
             if not _already_animated:
+                # AddModifier reports through the Lua bridge, which resolves an
+                # unknown attribute to None rather than raising, so the return is
+                # not reliable evidence on its own. The readback below is: if the
+                # input still has no connected output, the assignment on the next
+                # line would set a STATIC value and _ok() would report a keyframe
+                # that does not exist.
                 tool.AddModifier(p["input_name"], p.get("modifier", "BezierSpline"))
+                try:
+                    attached = tool[p["input_name"]].GetConnectedOutput() is not None
+                except Exception:
+                    attached = False
+                if not attached:
+                    return _err(
+                        f"Could not animate '{p['input_name']}' on "
+                        f"'{p['tool_name']}': no spline modifier attached.",
+                        code="FUSION_ADD_MODIFIER_FAILED", category="api_error",
+                        retryable=False,
+                        reason="Without a spline, assigning at a time sets a STATIC "
+                               "value (last write wins) and creates no keyframe. "
+                               "Reporting success here would claim a keyframe that "
+                               "does not exist.",
+                        remediation="Check the input accepts the modifier type "
+                                    f"({p.get('modifier', 'BezierSpline')!r}); Point "
+                                    "inputs take 'Path'.",
+                    )
             tool[p["input_name"]][p["time"]] = p["value"]
             return _ok()
         finally:
@@ -29060,10 +29450,24 @@ def _run_inline_lua(source: str) -> Dict[str, Any]:
     )
 
     # Clear prior slots so we can detect if RunScript silently did nothing.
-    fusion.SetData("__mcp_done__", "")
-    fusion.SetData("__mcp_stdout__", "")
-    fusion.SetData("__mcp_result__", "")
-    fusion.SetData("__mcp_error__", "")
+    # SetData goes through the Lua bridge and returns nil whether or not it
+    # took, so the return is not evidence -- but GetData is. The __mcp_done__
+    # slot is the one that matters: a stale "1" left by the previous run makes
+    # the poll below exit immediately and return the PREVIOUS run's stdout,
+    # result and error as this run's.
+    for slot in ("__mcp_done__", "__mcp_stdout__", "__mcp_result__", "__mcp_error__"):
+        fusion.SetData(slot, "")
+    stale = fusion.GetData("__mcp_done__")
+    if stale not in ("", None):
+        return _err(
+            "Could not clear the Fusion completion sentinel before running.",
+            code="FUSION_SENTINEL_NOT_CLEARED", category="api_error", retryable=True,
+            reason=f"__mcp_done__ still reads {stale!r} after SetData. The poll would "
+                   "exit immediately and hand back the previous run's output as this "
+                   "run's.",
+            remediation="Retry; if it persists, restart Resolve to clear the Fusion "
+                        "app's data slots.",
+        )
 
     with tempfile.NamedTemporaryFile(mode='w', suffix='.lua',
                                       prefix='mcp-lua-inline-',