davinci-resolve-mcp 2.44.0 → 2.46.0

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.44.0"
+VERSION = "2.46.0"
 
 import base64
 import os
@@ -112,6 +112,7 @@ from src.utils.fusion_group_settings import (
 )
 from src.utils import analysis_runs as _analysis_runs
 from src.utils import brain_edits as _brain_edits
+from src.utils import edit_engine as _edit_engine_mod
 from src.utils import media_pool_changes as _media_pool_changes
 from src.utils import timeline_versioning as _timeline_versioning
 from src.utils import project_spec as _project_spec
@@ -782,6 +783,10 @@ _destructive_hook.register_preference_provider(_destructive_preference_provider)
 _TOKEN_GATED_DESTRUCTIVE_ACTIONS = frozenset({
     ("timeline", "delete_track"),
     ("timeline", "apply_cuts"),
+    # Phase E edit-engine loops: plan → confirm → execute.
+    ("edit_engine", "execute_selects"),
+    ("edit_engine", "execute_tighten"),
+    ("edit_engine", "execute_swap"),
     ("graph", "apply_grade_from_drx"),
     ("graph", "reset_all_grades"),
     # 21.0 AI ops that render/generate NEW media files (additive, but expensive
@@ -1342,6 +1347,46 @@ def _timeline_timecode_to_frame_id(tl, timecode):
     return _timecode_to_frame_id(timecode, fps)
 
 
+def _marker_rebase_to_timeline_start(tl, frame):
+    """Rebase an absolute frame to a Timeline marker frameId.
+
+    Timeline.AddMarker frameIds are relative to the timeline start (frame 0 ==
+    first frame of the timeline), while GetCurrentTimecode and the timecodes
+    shown in the Resolve UI are absolute. GetMarkers() echoes back whatever
+    frameId was passed without validating, so a marker stored at an absolute
+    frame displays past the end of the timeline (invisible in the UI).
+    Frames below the timeline start are treated as already relative (elapsed
+    time), and the frame passes through unchanged when the start frame is
+    unavailable.
+    """
+    start = _timeline_start_frame(tl)
+    if start and frame >= start:
+        return frame - start
+    return frame
+
+
+def _marker_timecode_to_frame_id(tl, timecode):
+    frame, err = _timeline_timecode_to_frame_id(tl, timecode)
+    if err:
+        return None, err
+    return _marker_rebase_to_timeline_start(tl, frame), None
+
+
+def _marker_display_frame(tl, frame):
+    """Absolute frame for driving the playhead at a stored marker frameId.
+
+    Inverse of _marker_rebase_to_timeline_start: stored timeline marker keys
+    are relative to the timeline start, while SetCurrentTimecode is absolute.
+    Frames at or past the start frame are assumed to be legacy absolute keys
+    and pass through unchanged so they still sample the intended frame.
+    """
+    frame = int(frame)
+    start = _timeline_start_frame(tl)
+    if start and frame < start:
+        return frame + start
+    return frame
+
+
 def _frame_id_to_timecode(frame: int, fps: float, separator: str = ":") -> str:
     nominal_fps = max(1, int(round(float(fps))))
     frame = max(0, int(frame))
@@ -1359,6 +1404,7 @@ def _timeline_frame_id_to_timecode(tl, frame: int) -> Tuple[Optional[str], Optio
 
 
 def _current_timeline_frame_id(tl):
+    """Absolute frame at the playhead, matching TimelineItem.GetStart()."""
     if tl is None:
         return None, _err("current playhead marker requires a timeline")
     try:
@@ -1370,23 +1416,37 @@ def _current_timeline_frame_id(tl):
     return _timeline_timecode_to_frame_id(tl, timecode)
 
 
+def _current_timeline_marker_frame_id(tl):
+    frame, err = _current_timeline_frame_id(tl)
+    if err:
+        return None, err
+    return _marker_rebase_to_timeline_start(tl, frame), None
+
+
 def _marker_frame_from_params(p: Dict[str, Any], tl=None, default_to_current=False):
+    """Resolve marker frame params to a marker frameId.
+
+    With a timeline, timecodes (and the playhead default) are rebased so the
+    returned frameId is relative to the timeline start. Raw frame numbers are
+    passed through unchanged: timeline marker frames are relative to the
+    timeline start, clip marker frames are relative to the clip start.
+    """
     raw_timecode = _first_param(p, "timecode", "time_code", "tc")
     if raw_timecode is not None:
-        return _timeline_timecode_to_frame_id(tl, raw_timecode)
+        return _marker_timecode_to_frame_id(tl, raw_timecode)
 
     raw_frame = _first_param(p, "frame", "frame_id", "frameId", "frame_num", "frameNum")
     if raw_frame is not None:
         if isinstance(raw_frame, str):
             lowered = raw_frame.strip().lower()
             if lowered in {"current", "playhead", "current_playhead", "now"}:
-                return _current_timeline_frame_id(tl)
+                return _current_timeline_marker_frame_id(tl)
             if ":" in raw_frame or ";" in raw_frame:
-                return _timeline_timecode_to_frame_id(tl, raw_frame)
+                return _marker_timecode_to_frame_id(tl, raw_frame)
         return _coerce_marker_number(raw_frame, "frame")
 
     if default_to_current:
-        return _current_timeline_frame_id(tl)
+        return _current_timeline_marker_frame_id(tl)
     return None, _err("Missing marker frame. Provide frame, frame_id/frameId, or timecode.")
 
 
@@ -4816,7 +4876,7 @@ def _timeline_thumbnail_contact_sheet(proj, tl, p: Dict[str, Any]) -> Dict[str,
     sampled = []
     try:
         for sample in samples:
-            timecode, tc_err = _timeline_frame_id_to_timecode(tl, int(sample["frame"]))
+            timecode, tc_err = _timeline_frame_id_to_timecode(tl, _marker_display_frame(tl, sample["frame"]))
             if tc_err:
                 sample["error"] = tc_err.get("error")
                 sampled.append(sample)
@@ -6134,6 +6194,7 @@ _MEDIA_POOL_KERNEL_ACTIONS = [
     "metadata_field_inventory",
     "safe_relink",
     "safe_unlink",
+    "check_proxy_media_compatibility",
     "link_proxy_checked",
     "link_full_resolution_checked",
     "set_clip_marks",
@@ -9469,7 +9530,8 @@ def _media_pool_ingest_capabilities():
                 "relink/unlink through Resolve MediaPool APIs",
                 "media_pool.safe_relink and safe_unlink with path/clip validation",
                 "proxy link/unlink through MediaPoolItem APIs",
-                "media_pool.link_proxy_checked with file validation",
+                "media_pool.check_proxy_media_compatibility with ffprobe/source signature diagnostics",
+                "media_pool.link_proxy_checked with file validation and optional compatibility guard",
                 "full-resolution media link where Resolve 20 exposes it",
                 "media_pool.link_full_resolution_checked with version/path validation",
             ],
@@ -9954,6 +10016,466 @@ def _safe_unlink(mp, root, p: Dict[str, Any]):
     return {"success": bool(mp.UnlinkClips(clips)), "count": len(clips), "missing": missing}
 
 
+def _parse_rate(value):
+    if value in (None, "", "0/0", "N/A"):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value).strip()
+    if not text:
+        return None
+    if "/" in text:
+        left, right = text.split("/", 1)
+        try:
+            numerator = float(left.strip())
+            denominator = float(right.strip())
+            return numerator / denominator if denominator else None
+        except (TypeError, ValueError):
+            return None
+    match = re.search(r"\d+(?:\.\d+)?", text.replace(",", "."))
+    return float(match.group(0)) if match else None
+
+
+def _parse_int_text(value):
+    if value in (None, "", "N/A"):
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    match = re.search(r"\d+", str(value).replace(",", ""))
+    return int(match.group(0)) if match else None
+
+
+def _parse_resolution(value):
+    if value in (None, "", "N/A"):
+        return None
+    if isinstance(value, (list, tuple)) and len(value) >= 2:
+        width = _parse_int_text(value[0])
+        height = _parse_int_text(value[1])
+        return (width, height) if width and height else None
+    match = re.search(r"(\d+)\s*[xX]\s*(\d+)", str(value))
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def _normalize_media_token(value):
+    return re.sub(r"[^a-z0-9]+", "", str(value or "").lower())
+
+
+def _media_token_matches(actual, expected):
+    expected_token = _normalize_media_token(expected)
+    if not expected_token:
+        return True
+    actual_token = _normalize_media_token(actual)
+    return bool(actual_token) and (
+        actual_token == expected_token
+        or expected_token in actual_token
+        or actual_token in expected_token
+    )
+
+
+def _clip_media_signature(clip):
+    properties, properties_error = _safe_clip_call(clip, "GetClipProperty", "")
+    properties = properties if isinstance(properties, dict) else {}
+    resolution = _parse_resolution(
+        properties.get("Resolution")
+        or properties.get("Video Resolution")
+        or properties.get("Image Size")
+    )
+    signature = {
+        "name": _safe_media_pool_item_name(clip),
+        "id": _safe_media_pool_item_id(clip),
+        "file_path": properties.get("File Path") or properties.get("FilePath"),
+        "resolution": {"width": resolution[0], "height": resolution[1]} if resolution else None,
+        "fps": _parse_rate(
+            properties.get("FPS")
+            or properties.get("Frame Rate")
+            or properties.get("Video Frame Rate")
+        ),
+        "frames": _parse_int_text(
+            properties.get("Frames")
+            or properties.get("Frame Count")
+            or properties.get("Duration Frames")
+        ),
+        "sample_rate": _parse_int_text(
+            properties.get("Sample Rate")
+            or properties.get("Audio Sample Rate")
+        ),
+    }
+    if properties_error:
+        signature["properties_error"] = properties_error
+    return signature
+
+
+def _probe_media_file(path: str):
+    ffprobe = shutil.which("ffprobe")
+    if not ffprobe:
+        return {
+            "success": False,
+            "code": "FFPROBE_MISSING",
+            "error": "ffprobe is not installed or not on PATH",
+            "path": path,
+        }
+    try:
+        proc = subprocess.run(
+            [
+                ffprobe,
+                "-v",
+                "error",
+                "-show_streams",
+                "-of",
+                "json",
+                path,
+            ],
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=20,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired:
+        return {"success": False, "code": "FFPROBE_TIMEOUT", "error": "ffprobe timed out", "path": path}
+    except Exception as exc:
+        return {"success": False, "code": "FFPROBE_FAILED", "error": str(exc), "path": path}
+    if proc.returncode != 0:
+        return {
+            "success": False,
+            "code": "FFPROBE_FAILED",
+            "returncode": proc.returncode,
+            "error": (proc.stderr or proc.stdout or "").strip(),
+            "path": path,
+        }
+    try:
+        payload = json.loads(proc.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        return {"success": False, "code": "FFPROBE_JSON_ERROR", "error": str(exc), "path": path}
+    streams = payload.get("streams") if isinstance(payload, dict) else []
+    streams = streams if isinstance(streams, list) else []
+    video = next((stream for stream in streams if stream.get("codec_type") == "video"), {})
+    audio = next((stream for stream in streams if stream.get("codec_type") == "audio"), {})
+    return {"success": True, "path": path, "video": video, "audio": audio, "stream_count": len(streams)}
+
+
+def _proxy_media_signature(probe: Dict[str, Any]):
+    video = probe.get("video") if isinstance(probe.get("video"), dict) else {}
+    audio = probe.get("audio") if isinstance(probe.get("audio"), dict) else {}
+    width = _parse_int_text(video.get("width"))
+    height = _parse_int_text(video.get("height"))
+    return {
+        "path": probe.get("path"),
+        "codec": video.get("codec_name"),
+        "codec_long_name": video.get("codec_long_name"),
+        "profile": video.get("profile"),
+        "resolution": {"width": width, "height": height} if width and height else None,
+        "fps": _parse_rate(video.get("avg_frame_rate") or video.get("r_frame_rate")),
+        "frames": _parse_int_text(video.get("nb_frames") or (video.get("tags") or {}).get("NUMBER_OF_FRAMES")),
+        "sample_rate": _parse_int_text(audio.get("sample_rate")),
+        "channels": _parse_int_text(audio.get("channels")),
+    }
+
+
+def _add_proxy_resolution_mismatch(result: Dict[str, Any], source, proxy):
+    """Flag resolution only when the aspect ratio differs.
+
+    Proxies are routinely lower resolution than the source — Resolve links a
+    half/quarter-res proxy happily (that is the point of proxies; verified live
+    on Resolve Studio 21). Only a different aspect ratio means the file cannot
+    be a proxy of this source.
+    """
+    if not source or not proxy:
+        return
+    src_w, src_h = source.get("width"), source.get("height")
+    pxy_w, pxy_h = proxy.get("width"), proxy.get("height")
+    if not (src_w and src_h and pxy_w and pxy_h):
+        return
+    if (src_w, src_h) == (pxy_w, pxy_h):
+        return
+    src_aspect = src_w / src_h
+    pxy_aspect = pxy_w / pxy_h
+    if abs(src_aspect - pxy_aspect) / src_aspect <= 0.02:
+        result["warnings"].append(
+            f"Proxy is a same-aspect downscale ({src_w}x{src_h} -> {pxy_w}x{pxy_h})"
+        )
+        return
+    result["mismatches"].append({"field": "resolution", "source": source, "proxy": proxy})
+
+
+def _add_proxy_mismatch(mismatches: List[Dict[str, Any]], field: str, source, proxy, *, tolerance: float = 0.0):
+    if source is None or proxy is None:
+        return
+    if isinstance(source, (int, float)) and isinstance(proxy, (int, float)):
+        if abs(float(source) - float(proxy)) <= tolerance:
+            return
+    elif source == proxy:
+        return
+    mismatches.append({"field": field, "source": source, "proxy": proxy})
+
+
+def _check_proxy_media_compatibility(
+    clip,
+    proxy_path: str,
+    *,
+    expected_codec: Optional[str] = None,
+    expected_profile: Optional[str] = None,
+):
+    source = _clip_media_signature(clip)
+    probe = _probe_media_file(proxy_path)
+    proxy = _proxy_media_signature(probe) if probe.get("success") else {"path": proxy_path}
+    result = {
+        "success": bool(probe.get("success")),
+        "compatible": False,
+        "source": source,
+        "proxy": proxy,
+        "mismatches": [],
+        "warnings": [],
+    }
+    if not probe.get("success"):
+        result["error"] = probe.get("error", "Unable to probe proxy media")
+        result["code"] = probe.get("code", "FFPROBE_FAILED")
+        return result
+
+    _add_proxy_resolution_mismatch(result, source.get("resolution"), proxy.get("resolution"))
+    _add_proxy_mismatch(result["mismatches"], "fps", source.get("fps"), proxy.get("fps"), tolerance=0.01)
+    _add_proxy_mismatch(result["mismatches"], "frames", source.get("frames"), proxy.get("frames"), tolerance=1)
+    _add_proxy_mismatch(result["mismatches"], "sample_rate", source.get("sample_rate"), proxy.get("sample_rate"))
+
+    if expected_codec and not (
+        _media_token_matches(proxy.get("codec"), expected_codec)
+        or _media_token_matches(proxy.get("codec_long_name"), expected_codec)
+    ):
+        result["mismatches"].append({
+            "field": "expected_codec",
+            "expected": expected_codec,
+            "proxy": proxy.get("codec") or proxy.get("codec_long_name"),
+        })
+    if expected_profile and not _media_token_matches(proxy.get("profile"), expected_profile):
+        result["mismatches"].append({
+            "field": "expected_profile",
+            "expected": expected_profile,
+            "proxy": proxy.get("profile"),
+        })
+
+    result["compatible"] = not result["mismatches"]
+    if source.get("resolution") is None:
+        result["warnings"].append("Source clip resolution was not available from GetClipProperty")
+    if source.get("fps") is None:
+        result["warnings"].append("Source clip FPS was not available from GetClipProperty")
+    if proxy.get("frames") is None:
+        result["warnings"].append("Proxy frame count was not available from ffprobe")
+    return result
+
+
+def _proxy_link_readback(clip):
+    properties, properties_error = _safe_clip_call(clip, "GetClipProperty", "")
+    properties = properties if isinstance(properties, dict) else {}
+    readback = {"clip_properties": properties}
+    if properties_error:
+        readback["properties_error"] = properties_error
+    proxy_keys = [
+        "Proxy",
+        "Proxy Media",
+        "Proxy Media Path",
+        "Proxy Path",
+        "Proxy Status",
+        "ProxyMediaPath",
+    ]
+    observed = {key: properties.get(key) for key in proxy_keys if key in properties}
+    if observed:
+        readback["proxy_fields"] = observed
+    return readback
+
+
+def _normalized_path_for_compare(path):
+    if not path or not isinstance(path, str):
+        return None
+    return os.path.normcase(os.path.abspath(os.path.expanduser(path)))
+
+
+def _proxy_readback_matches_path(readback: Dict[str, Any], proxy_path: str):
+    expected = _normalized_path_for_compare(proxy_path)
+    if not expected:
+        return False
+    proxy_fields = readback.get("proxy_fields") if isinstance(readback, dict) else {}
+    proxy_fields = proxy_fields if isinstance(proxy_fields, dict) else {}
+    for value in proxy_fields.values():
+        if _normalized_path_for_compare(value) == expected:
+            return True
+    return False
+
+
+def _proxy_link_journal_event(event_type: str, clip, proxy_path: str, *, success=None, verified=False, compatibility=None):
+    event = {
+        "type": event_type,
+        "clip_id": _safe_media_pool_item_id(clip),
+        "clip_name": _safe_media_pool_item_name(clip),
+        "proxy_path": proxy_path,
+        "success": success,
+        "verified": bool(verified),
+    }
+    if compatibility is not None:
+        event["compatible"] = bool(compatibility.get("compatible"))
+        if compatibility.get("mismatches"):
+            event["mismatch_fields"] = [row.get("field") for row in compatibility.get("mismatches", [])]
+    return event
+
+
+def _verified_operation(
+    name: str,
+    *,
+    requested: Dict[str, Any],
+    preflight: Dict[str, Any],
+    execution: Dict[str, Any],
+    verification_status: str,
+    readback=None,
+    journal_event=None,
+):
+    return {
+        "name": name,
+        "preflight": preflight,
+        "requested": requested,
+        "execution": execution,
+        "readback": readback,
+        "verified": verification_status == "readback_verified",
+        "verification_status": verification_status,
+        "journal_event": journal_event,
+    }
+
+
+def _check_proxy_media_compatibility_checked(root, p: Dict[str, Any]):
+    clip = _find_clip(root, p.get("clip_id", ""))
+    if not clip:
+        return _err(f"Clip not found: {p.get('clip_id')}")
+    proxy_path = p.get("proxy_path") or p.get("path")
+    path_err = _path_error(proxy_path, must_be_file=True)
+    if path_err:
+        return _err(path_err)
+    return _check_proxy_media_compatibility(
+        clip,
+        proxy_path,
+        expected_codec=p.get("expected_codec") or p.get("codec"),
+        expected_profile=p.get("expected_profile") or p.get("profile"),
+    )
+
+
+def _timeline_append_readback_snapshot(proj):
+    try:
+        tl = proj.GetCurrentTimeline() if proj else None
+    except Exception as exc:
+        return {"available": False, "error": f"GetCurrentTimeline failed: {exc}"}
+    if not tl:
+        return {"available": False, "error": "No current timeline"}
+
+    timeline = {}
+    try:
+        timeline["name"] = tl.GetName()
+    except Exception:
+        timeline["name"] = None
+    try:
+        timeline["id"] = tl.GetUniqueId()
+    except Exception:
+        timeline["id"] = None
+
+    tracks = {}
+    item_count = 0
+    warnings = []
+    for track_type in ("video", "audio", "subtitle"):
+        track_count = _timeline_track_count(tl, track_type)
+        rows = []
+        for track_index in range(1, track_count + 1):
+            try:
+                items = tl.GetItemListInTrack(track_type, track_index) or []
+            except Exception as exc:
+                warnings.append(f"GetItemListInTrack({track_type}, {track_index}) failed: {exc}")
+                items = []
+            item_count += len(items)
+            rows.append({
+                "track_index": track_index,
+                "item_count": len(items),
+                "item_ids": _timeline_item_ids(items),
+            })
+        tracks[track_type] = {"track_count": track_count, "tracks": rows}
+    return {
+        "available": True,
+        "timeline": timeline,
+        "item_count": item_count,
+        "tracks": tracks,
+        "warnings": warnings,
+    }
+
+
+def _compare_timeline_append_readback(before, observed, expected_count: int):
+    before_count = before.get("item_count") if isinstance(before, dict) and before.get("available") else None
+    after_count = observed.get("item_count") if isinstance(observed, dict) and observed.get("available") else None
+    delta = after_count - before_count if before_count is not None and after_count is not None else None
+    return {
+        "verified": delta is not None and delta >= expected_count and expected_count > 0,
+        "before_item_count": before_count,
+        "after_item_count": after_count,
+        "item_count_delta": delta,
+        "expected_item_count_delta": expected_count,
+    }
+
+
+def _append_to_timeline_with_verification(proj, mp, append_payload, requested: Dict[str, Any], expected_count: int):
+    raw_result = {"value": None}
+    before = _timeline_append_readback_snapshot(proj)
+
+    def mutate():
+        raw_result["value"] = mp.AppendToTimeline(append_payload)
+        return bool(raw_result["value"])
+
+    verification = verify_by_readback(
+        mutate=mutate,
+        observe=lambda: _timeline_append_readback_snapshot(proj),
+        snapshot=lambda: before,
+        compare=lambda before_snapshot, observed: _compare_timeline_append_readback(
+            before_snapshot,
+            observed,
+            expected_count,
+        ),
+        intent=requested,
+        label="media_pool.append_to_timeline",
+    )
+    return raw_result["value"], verification, before
+
+
+def _append_to_timeline_verified_operation(requested: Dict[str, Any], verification: Dict[str, Any], before):
+    success = bool(verification.get("success_raw"))
+    verified = bool(verification.get("verified"))
+    verification_status = "readback_verified" if verified else ("api_failed" if not success else "api_success_unverified")
+    readback = {
+        "before": before,
+        "after": verification.get("observed"),
+        "before_item_count": verification.get("before_item_count"),
+        "after_item_count": verification.get("after_item_count"),
+        "item_count_delta": verification.get("item_count_delta"),
+        "expected_item_count_delta": verification.get("expected_item_count_delta"),
+    }
+    return _verified_operation(
+        "media_pool.append_to_timeline",
+        requested=requested,
+        preflight={
+            "ok": True,
+            "current_timeline_available": bool(isinstance(before, dict) and before.get("available")),
+            "expected_item_count_delta": requested.get("expected_count"),
+        },
+        execution={"api": "MediaPool.AppendToTimeline", "attempted": True, "success": success},
+        readback=readback,
+        verification_status=verification_status,
+        journal_event={
+            "type": "timeline.appended" if verified else ("timeline.append.failed" if not success else "timeline.append.unverified"),
+            "success": success,
+            "verified": verified,
+            "expected_count": requested.get("expected_count"),
+            "item_count_delta": verification.get("item_count_delta"),
+        },
+    )
+
+
 def _link_proxy_checked(root, p: Dict[str, Any]):
     clip = _find_clip(root, p.get("clip_id", ""))
     if not clip:
@@ -9962,9 +10484,123 @@ def _link_proxy_checked(root, p: Dict[str, Any]):
     path_err = _path_error(proxy_path, must_be_file=True)
     if path_err:
         return _err(path_err)
+    missing = _requires_method(clip, "LinkProxyMedia", "17.0")
+    if missing:
+        return missing
+    check_compatibility = bool(
+        p.get("check_compatibility")
+        or p.get("require_compatible")
+        or p.get("expected_codec")
+        or p.get("expected_profile")
+        or p.get("codec")
+        or p.get("profile")
+    )
+    compatibility = None
+    if check_compatibility:
+        compatibility = _check_proxy_media_compatibility(
+            clip,
+            proxy_path,
+            expected_codec=p.get("expected_codec") or p.get("codec"),
+            expected_profile=p.get("expected_profile") or p.get("profile"),
+        )
+    requested = {
+        "clip_id": p.get("clip_id"),
+        "proxy_path": proxy_path,
+        "dry_run": bool(p.get("dry_run")),
+        "check_compatibility": check_compatibility,
+        "require_compatible": bool(p.get("require_compatible")),
+        "expected_codec": p.get("expected_codec") or p.get("codec"),
+        "expected_profile": p.get("expected_profile") or p.get("profile"),
+    }
+    preflight = {
+        "ok": True,
+        "clip_found": True,
+        "proxy_path_valid": True,
+        "method_available": True,
+        "compatibility_checked": compatibility is not None,
+    }
+    if compatibility is not None:
+        preflight["compatible"] = bool(compatibility.get("compatible"))
     if p.get("dry_run"):
-        return _ok(clip=_media_pool_item_summary(clip), proxy_path=proxy_path)
-    return {"success": bool(clip.LinkProxyMedia(proxy_path))}
+        out = _ok(clip=_media_pool_item_summary(clip), proxy_path=proxy_path)
+        if compatibility is not None:
+            out["compatibility"] = compatibility
+        out["verified_operation"] = _verified_operation(
+            "media_pool.link_proxy_checked",
+            requested=requested,
+            preflight=preflight,
+            execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": False, "success": None},
+            readback=None,
+            verification_status="dry_run",
+            journal_event=_proxy_link_journal_event(
+                "proxy.link.preview",
+                clip,
+                proxy_path,
+                success=None,
+                verified=False,
+                compatibility=compatibility,
+            ),
+        )
+        return out
+    if p.get("require_compatible") and compatibility is not None and not compatibility.get("compatible"):
+        out = _err(
+            "Proxy media is not compatible with the source clip; refusing LinkProxyMedia",
+            code="PROXY_INCOMPATIBLE",
+            category="invalid_input",
+            remediation="Use a proxy with matching resolution, FPS, frame count, sample rate, and requested codec/profile.",
+        )
+        out["compatibility"] = compatibility
+        out["verified_operation"] = _verified_operation(
+            "media_pool.link_proxy_checked",
+            requested=requested,
+            preflight={**preflight, "ok": False},
+            execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": False, "success": None},
+            readback=None,
+            verification_status="blocked",
+            journal_event=_proxy_link_journal_event(
+                "proxy.link.blocked",
+                clip,
+                proxy_path,
+                success=False,
+                verified=False,
+                compatibility=compatibility,
+            ),
+        )
+        return out
+    verification = verify_by_readback(
+        mutate=lambda: clip.LinkProxyMedia(proxy_path),
+        observe=lambda: _proxy_link_readback(clip),
+        compare=lambda _before, observed: {
+            "verified": _proxy_readback_matches_path(observed, proxy_path),
+        },
+        intent={"clip_id": p.get("clip_id"), "proxy_path": proxy_path},
+        label="media_pool.link_proxy_checked",
+    )
+    success = bool(verification.get("success_raw"))
+    readback = verification.get("observed")
+    verified = bool(verification.get("verified"))
+    verification_status = "readback_verified" if verified else ("api_failed" if not success else "api_success_unverified")
+    event_type = "proxy.linked" if success else "proxy.link.failed"
+    out = {"success": success, "readback": readback}
+    if compatibility is not None:
+        out["compatibility"] = compatibility
+    out["verified_operation"] = _verified_operation(
+        "media_pool.link_proxy_checked",
+        requested=requested,
+        preflight=preflight,
+        execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": True, "success": success},
+        readback=readback,
+        verification_status=verification_status,
+        journal_event=_proxy_link_journal_event(
+            event_type,
+            clip,
+            proxy_path,
+            success=success,
+            verified=verified,
+            compatibility=compatibility,
+        ),
+    )
+    return out
 
 
 def _link_full_resolution_checked(root, p: Dict[str, Any]):
@@ -12548,6 +13184,35 @@ class _SpecLiveExecutor:
         self._spec = spec
         self._proj = pm.GetCurrentProject()
 
+    def _media_pool_bin_paths(self) -> List[str]:
+        if not self._proj or not getattr(self._spec, "bins", None):
+            return []
+        try:
+            mp = self._proj.GetMediaPool()
+            root = mp.GetRootFolder() if mp else None
+        except Exception:
+            return []
+        if root is None:
+            return []
+        paths: List[str] = []
+
+        def walk(folder, prefix: str) -> None:
+            paths.append(prefix)
+            try:
+                subfolders = folder.GetSubFolderList() or []
+            except Exception:
+                subfolders = []
+            for subfolder in subfolders:
+                try:
+                    name = subfolder.GetName()
+                except Exception:
+                    name = ""
+                if name:
+                    walk(subfolder, f"{prefix}/{name}")
+
+        walk(root, "Master")
+        return paths
+
     def live_state(self) -> Dict[str, Any]:
         proj = self._proj
         projects = list(self._pm.GetProjectListInCurrentFolder() or [])
@@ -12597,6 +13262,7 @@ class _SpecLiveExecutor:
             "project": proj.GetName() if proj else None,
             "projects": projects,
             "settings": settings,
+            "bins": self._media_pool_bin_paths(),
             "timelines": timelines,
         }
 
@@ -12618,6 +13284,18 @@ class _SpecLiveExecutor:
         except Exception:
             return False
 
+    def ensure_bin(self, path: str) -> bool:
+        if not self._proj:
+            return False
+        try:
+            mp = self._proj.GetMediaPool()
+        except Exception:
+            return False
+        if mp is None:
+            return False
+        _, err = _ensure_folder_path(mp, path)
+        return err is None
+
     def ensure_timeline(self, name: str, fps: Optional[float]) -> bool:
         if not self._proj:
             return False
@@ -12746,13 +13424,36 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
         except Exception:
             pass
         item_count = 0
+        video_item_count = 0
+        audio_item_count = 0
+        subtitle_item_count = 0
         try:
-            vc = int(tl.GetTrackCount("video") or 0)
-            for ti in range(1, vc + 1):
-                item_count += len(tl.GetItemListInTrack("video", ti) or [])
+            for track_type, key in (
+                ("video", "video_item_count"),
+                ("audio", "audio_item_count"),
+                ("subtitle", "subtitle_item_count"),
+            ):
+                track_total = 0
+                track_count = int(tl.GetTrackCount(track_type) or 0)
+                for ti in range(1, track_count + 1):
+                    track_total += len(tl.GetItemListInTrack(track_type, ti) or [])
+                if key == "video_item_count":
+                    video_item_count = track_total
+                elif key == "audio_item_count":
+                    audio_item_count = track_total
+                elif key == "subtitle_item_count":
+                    subtitle_item_count = track_total
+                item_count += track_total
         except Exception:
             pass
-        timelines.append({"name": tl.GetName(), "fps": fps, "item_count": item_count})
+        timelines.append({
+            "name": tl.GetName(),
+            "fps": fps,
+            "item_count": item_count,
+            "video_item_count": video_item_count,
+            "audio_item_count": audio_item_count,
+            "subtitle_item_count": subtitle_item_count,
+        })
     state["timelines"] = timelines
     settings: Dict[str, Any] = {}
     try:
@@ -13818,7 +14519,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       metadata_field_inventory(clip_ids|selected, include_values?) -> {items, ui_group_names}
       safe_relink(clip_ids|selected, folder_path, dry_run?) -> {success}
       safe_unlink(clip_ids|selected, dry_run?) -> {success}
-      link_proxy_checked(clip_id, proxy_path|path, dry_run?) -> {success}
+      check_proxy_media_compatibility(clip_id, proxy_path|path, expected_codec?, expected_profile?) -> {compatible, mismatches}
+      link_proxy_checked(clip_id, proxy_path|path, dry_run?, check_compatibility?, require_compatible?, expected_codec?, expected_profile?) -> {success}
       link_full_resolution_checked(clip_id, path|full_res_media_path, dry_run?) -> {success}
       set_clip_marks(clip_ids|selected, mark_in, mark_out, type?, dry_run?) -> {success, results}
       clear_clip_marks(clip_ids|selected, type?, dry_run?) -> {success, results}
@@ -13960,7 +14662,18 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 if row_err:
                     return row_err
                 built.append(row)
-            result = mp.AppendToTimeline(built)
+            requested = {
+                "mode": "clip_infos",
+                "clip_info_count": len(raw),
+                "expected_count": len(built),
+            }
+            result, verification, before = _append_to_timeline_with_verification(
+                proj,
+                mp,
+                built,
+                requested,
+                len(built),
+            )
             if not result:
                 return _err("Failed to append clip_infos to timeline")
             items_out = []
@@ -13969,14 +14682,38 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 if item_err:
                     return item_err
                 items_out.append(item_out)
-            return _ok(count=len(result), items=items_out)
+            out = _ok(count=len(result), items=items_out)
+            out["verified_operation"] = _append_to_timeline_verified_operation(
+                requested,
+                verification,
+                before,
+            )
+            return out
         clip_ids = p.get("clip_ids")
         if not clip_ids:
             return _err("Provide clip_ids (simple append) or clip_infos (positioned append)")
         clips = [_find_clip(root, cid) for cid in clip_ids]
         clips = [c for c in clips if c]
-        result = mp.AppendToTimeline(clips)
-        return _ok(count=len(result) if result else 0)
+        requested = {
+            "mode": "clip_ids",
+            "clip_ids": list(clip_ids),
+            "resolved_clip_count": len(clips),
+            "expected_count": len(clips),
+        }
+        result, verification, before = _append_to_timeline_with_verification(
+            proj,
+            mp,
+            clips,
+            requested,
+            len(clips),
+        )
+        out = _ok(count=len(result) if result else 0)
+        out["verified_operation"] = _append_to_timeline_verified_operation(
+            requested,
+            verification,
+            before,
+        )
+        return out
     elif action == "import_media":
         if p.get("clip_infos") is not None:
             raw = p["clip_infos"]
@@ -14081,6 +14818,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         return _safe_relink(mp, root, p)
     elif action == "safe_unlink":
         return _safe_unlink(mp, root, p)
+    elif action == "check_proxy_media_compatibility":
+        return _check_proxy_media_compatibility_checked(root, p)
     elif action == "link_proxy_checked":
         return _link_proxy_checked(root, p)
     elif action == "link_full_resolution_checked":
@@ -15758,6 +16497,506 @@ def timeline_versioning(action: str, params: Optional[Dict[str, Any]] = None) ->
     return _err(f"Unknown action: {action}")
 
 
+def _edit_engine_collect_items(tl, *, track_index: Optional[int] = None) -> List[Dict[str, Any]]:
+    """Serialize video timeline items with the source mapping the planner needs."""
+    rows: List[Dict[str, Any]] = []
+    track_count = int(tl.GetTrackCount("video") or 0)
+    indices = [int(track_index)] if track_index else range(1, track_count + 1)
+    for index in indices:
+        try:
+            items = tl.GetItemListInTrack("video", index) or []
+        except Exception:
+            continue
+        for item in items:
+            try:
+                row: Dict[str, Any] = {
+                    "track_index": index,
+                    "item_name": item.GetName(),
+                    "timeline_start_frame": _frame_int(item.GetStart()),
+                    "timeline_end_frame": _frame_int(item.GetEnd()),
+                }
+            except Exception:
+                continue
+            source_start = None
+            if _has_method(item, "GetSourceStartFrame"):
+                try:
+                    source_start = _frame_int(item.GetSourceStartFrame())
+                except Exception:
+                    source_start = None
+            if source_start is None and _has_method(item, "GetLeftOffset"):
+                try:
+                    source_start = _frame_int(item.GetLeftOffset())
+                except Exception:
+                    source_start = None
+            row["source_start_frame"] = source_start or 0
+            try:
+                mpi = item.GetMediaPoolItem()
+                if mpi is not None:
+                    row["media_ref"] = mpi.GetUniqueId()
+                    try:
+                        row["media_path"] = mpi.GetClipProperty("File Path")
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+            rows.append(row)
+    return rows
+
+
+def _edit_engine_timeline_fps(tl) -> float:
+    try:
+        fps = float(tl.GetSetting("timelineFrameRate") or 0)
+        return fps if fps > 0 else 24.0
+    except Exception:
+        return 24.0
+
+
+def _edit_engine_capture(tl) -> Dict[str, Any]:
+    """Duration/clip-count readback for execute results."""
+    out: Dict[str, Any] = {}
+    try:
+        out["duration_seconds"] = _brain_edits.capture_metric(_brain_edits.METRIC_DURATION_SECONDS, tl)
+        out["clip_count"] = _brain_edits.capture_metric(_brain_edits.METRIC_CLIP_COUNT, tl)
+    except Exception:
+        pass
+    return out
+
+
+@mcp.tool()
+@_destructive_op("edit_engine")
+def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Evidence-driven edit loops (Phase E): selects assembly, tighten, swap.
+
+    Every loop is plan → confirm → execute. plan_* actions are dry-run by
+    construction: they query the DB-canonical analysis store and return a
+    per-decision rationale plus a stored plan_id. execute_* actions require a
+    confirm_token, run under the version-on-mutate hook (the timeline is
+    archived first), and return before/after metrics as readback.
+
+    Actions:
+    - plan_selects(min_select_potential?, max_duration_seconds?, timeline_name?,
+      max_shots?, handle_seconds?, analysis_root?) — rank shots by deep-tier
+      select potential (clip-level fallback), story-spine order. Additive.
+    - execute_selects(plan_id, confirm_token?) — creates a NEW selects timeline
+      from the plan's clip in/out ranges. Nothing existing is touched.
+    - plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
+      handle_seconds?) — dead-air lifts from transcript-gap evidence for the
+      current (or named) timeline.
+    - execute_tighten(plan_id, confirm_token?) — duplicates the timeline and
+      applies the lifts (ripple) to the DUPLICATE, never the original.
+    - plan_swap(track_index?, timeline_start_frame | item_name, kind?, limit?)
+      — alternates for one timeline item via the similarity index.
+    - execute_swap(plan_id, alternate_index, confirm_token?) — replaces the
+      item in place (lift + positioned append, same slot) on the current
+      timeline (version-archived first).
+    - list_plans(limit?) / get_plan(plan_id)
+    """
+    p = params or {}
+
+    def _project_context(*, need_resolve: bool) -> Tuple[Optional[Any], Optional[Any], Optional[str], Optional[Dict[str, Any]]]:
+        # An explicit analysis_root always wins — the evidence DB the caller
+        # analyzed into may differ from the provider's derived root (e.g. a
+        # headless analysis keyed by project name only).
+        analysis_root = p.get("analysis_root") or p.get("analysisRoot")
+        explicit_root = str(analysis_root) if analysis_root and os.path.isdir(str(analysis_root)) else None
+        vctx = _destructive_versioning_provider()
+        if vctx is not None:
+            r, proj, project_root, _name = vctx
+            return r, proj, explicit_root or project_root, None
+        if not need_resolve and explicit_root:
+            return None, None, explicit_root, None
+        return None, None, None, _err(
+            "No project context — open a Resolve project (or pass analysis_root for plan_selects)."
+        )
+
+    if action == "list_plans":
+        _r, _proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        return _edit_engine_mod.list_plans(project_root, limit=int(p.get("limit") or 20))
+
+    if action == "get_plan":
+        _r, _proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        plan = _edit_engine_mod.load_plan(project_root, str(p.get("plan_id") or p.get("planId") or ""))
+        if not plan:
+            return _err("plan not found")
+        if plan.get("_corrupt"):
+            return _err("plan file failed its fingerprint check — re-plan")
+        return {"success": True, "plan": plan}
+
+    if action == "plan_selects":
+        _r, _proj, project_root, err = _project_context(need_resolve=False)
+        if err:
+            return err
+        return _edit_engine_mod.plan_selects(
+            project_root,
+            timeline_name=p.get("timeline_name") or p.get("timelineName"),
+            max_duration_seconds=p.get("max_duration_seconds") or p.get("maxDurationSeconds"),
+            min_select_potential=str(p.get("min_select_potential") or p.get("minSelectPotential") or "medium"),
+            handle_seconds=float(p.get("handle_seconds") or p.get("handleSeconds") or _edit_engine_mod.DEFAULT_HANDLE_SECONDS),
+            max_shots=int(p.get("max_shots") or p.get("maxShots") or 60),
+        )
+
+    if action == "plan_tighten":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        tl = (_find_timeline_by_name(proj, p.get("timeline_name") or p.get("timelineName"))[0] if (p.get("timeline_name") or p.get("timelineName")) else proj.GetCurrentTimeline())
+        if not tl:
+            return _err("Timeline not found")
+        items = _edit_engine_collect_items(tl, track_index=p.get("track_index") or p.get("trackIndex"))
+        return _edit_engine_mod.plan_tighten(
+            project_root,
+            items=items,
+            timeline_name=tl.GetName(),
+            timeline_fps=_edit_engine_timeline_fps(tl),
+            target_ratio=p.get("target_ratio") or p.get("targetRatio"),
+            min_pause_seconds=float(p.get("min_pause_seconds") or p.get("minPauseSeconds") or _edit_engine_mod.DEFAULT_MIN_PAUSE_SECONDS),
+            handle_seconds=float(p.get("handle_seconds") or p.get("handleSeconds") or _edit_engine_mod.DEFAULT_HANDLE_SECONDS),
+        )
+
+    if action == "plan_swap":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        tl = (_find_timeline_by_name(proj, p.get("timeline_name") or p.get("timelineName"))[0] if (p.get("timeline_name") or p.get("timelineName")) else proj.GetCurrentTimeline())
+        if not tl:
+            return _err("Timeline not found")
+        items = _edit_engine_collect_items(tl, track_index=p.get("track_index") or p.get("trackIndex"))
+        target = None
+        wanted_start = p.get("timeline_start_frame") if p.get("timeline_start_frame") is not None else p.get("timelineStartFrame")
+        wanted_name = p.get("item_name") or p.get("itemName")
+        for row in items:
+            if wanted_start is not None and int(row["timeline_start_frame"]) == int(wanted_start):
+                target = row
+                break
+            if wanted_name and row.get("item_name") == wanted_name:
+                target = row
+                break
+        if target is None:
+            return _err(
+                "Target item not found — pass timeline_start_frame or item_name "
+                f"(items: {[{'name': r.get('item_name'), 'start': r['timeline_start_frame']} for r in items[:20]]})"
+            )
+        return _edit_engine_mod.plan_swap(
+            project_root,
+            item=target,
+            timeline_name=tl.GetName(),
+            timeline_fps=_edit_engine_timeline_fps(tl),
+            kind=str(p.get("kind") or "visual"),
+            limit=int(p.get("limit") or 5),
+        )
+
+    if action == "execute_selects":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        plan = _edit_engine_mod.load_plan(project_root, str(p.get("plan_id") or p.get("planId") or ""))
+        if not plan or plan.get("_corrupt"):
+            return _err("plan not found (or failed its fingerprint check) — re-plan")
+        if plan.get("kind") != "selects":
+            return _err(f"plan {plan.get('plan_id')} is a {plan.get('kind')} plan")
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="edit_engine.execute_selects", params=p,
+                preview={
+                    "operation": "edit_engine.execute_selects",
+                    "warning": "Creates a NEW selects timeline; no existing timeline is modified.",
+                    "timeline_name": plan.get("timeline_name"),
+                    "decision_count": len(plan.get("decisions") or []),
+                    "estimated_duration_seconds": plan.get("estimated_duration_seconds"),
+                },
+            )
+        blocked = _consume_confirm_token(action="edit_engine.execute_selects", params=p)
+        if blocked:
+            return blocked
+        mp = proj.GetMediaPool()
+        if not mp:
+            return _err("No media pool")
+        root_folder = mp.GetRootFolder()
+        name = str(plan.get("timeline_name") or "Selects")
+        if _find_timeline_by_name(proj, name)[0]:
+            name = f"{name} {time.strftime('%H%M%S')}"
+        tl = mp.CreateEmptyTimeline(name)
+        if not tl:
+            return _err("Failed to create selects timeline")
+        try:
+            proj.SetCurrentTimeline(tl)
+        except Exception:
+            pass
+        timeline_start = _timeline_start_frame(tl)
+        built = []
+        build_errors = []
+        record_cursor = 0
+        for i, ci in enumerate(plan.get("clip_infos") or []):
+            append_ci = dict(ci)
+            # Sequential assembly: each select lands after the previous one.
+            append_ci.setdefault("record_frame", record_cursor)
+            append_ci.setdefault("track_index", 1)
+            row, row_err = _build_append_clip_info_dict(root_folder, append_ci, i, timeline_start)
+            if row_err:
+                build_errors.append({"index": i, "error": row_err.get("error")})
+                continue
+            built.append(row)
+            record_cursor += int(append_ci.get("end_frame", 0)) - int(append_ci.get("start_frame", 0)) + 1
+        appended = mp.AppendToTimeline(built) if built else None
+        readback = _edit_engine_capture(tl)
+        run_id = _analysis_runs.current_run_id()
+        try:
+            _brain_edits.log_brain_edit(
+                project_root=project_root,
+                analysis_run_id=run_id or "edit-engine",
+                edit_type="edit_engine.selects_result",
+                tool_name="edit_engine",
+                action_name="execute_selects",
+                timeline_after=tl.GetName(),
+                target_metric=_brain_edits.METRIC_CLIP_COUNT,
+                metric_direction="target_value",
+                after_value=readback.get("clip_count"),
+                rationale=plan.get("summary"),
+                params={"plan_id": plan.get("plan_id")},
+                result_summary={"appended": len(built), "build_errors": build_errors},
+            )
+        except Exception:
+            pass
+        _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
+            "timeline_name": tl.GetName(),
+            "appended": len(built),
+            "build_errors": build_errors,
+            **readback,
+        })
+        return {
+            "success": bool(appended),
+            "timeline_name": tl.GetName(),
+            "appended": len(built),
+            "build_errors": build_errors,
+            "readback": readback,
+            "plan_id": plan.get("plan_id"),
+        }
+
+    if action == "execute_tighten":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        plan = _edit_engine_mod.load_plan(project_root, str(p.get("plan_id") or p.get("planId") or ""))
+        if not plan or plan.get("_corrupt"):
+            return _err("plan not found (or failed its fingerprint check) — re-plan")
+        if plan.get("kind") != "tighten":
+            return _err(f"plan {plan.get('plan_id')} is a {plan.get('kind')} plan")
+        lifts = plan.get("lifts") or []
+        keep_ranges = plan.get("keep_ranges") or []
+        if not keep_ranges:
+            return _err("plan has no keep_ranges — re-plan with this version")
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="edit_engine.execute_tighten", params=p,
+                preview={
+                    "operation": "edit_engine.execute_tighten",
+                    "warning": (
+                        "Assembles a tightened VARIANT timeline from the plan's keep "
+                        "ranges; the original timeline is not modified."
+                    ),
+                    "timeline_name": plan.get("timeline_name"),
+                    "lift_count": len(lifts),
+                    "keep_range_count": len(keep_ranges),
+                    "estimated_removed_seconds": sum(l.get("duration_seconds") or 0 for l in lifts),
+                },
+            )
+        blocked = _consume_confirm_token(action="edit_engine.execute_tighten", params=p)
+        if blocked:
+            return blocked
+        source_tl, _src_index = _find_timeline_by_name(proj, plan.get("timeline_name"))
+        if not source_tl:
+            return _err(f"Timeline '{plan.get('timeline_name')}' not found")
+        before = _edit_engine_capture(source_tl)
+        variant_name = f"{plan.get('timeline_name')} — tightened {time.strftime('%H%M%S')}"
+        variant = _timeline_create_variant_from_ranges(proj, source_tl, {
+            "ranges": keep_ranges,
+            "name": variant_name,
+        })
+        if not variant.get("success"):
+            return {"success": False, "error": f"variant assembly failed: {variant.get('error')}", "variant": variant}
+        new_tl, _new_index = _find_timeline_by_name(proj, variant.get("name") or variant_name)
+        after = _edit_engine_capture(new_tl) if new_tl else {}
+        run_id = _analysis_runs.current_run_id()
+        try:
+            _brain_edits.log_brain_edit(
+                project_root=project_root,
+                analysis_run_id=run_id or "edit-engine",
+                edit_type="edit_engine.tighten_result",
+                tool_name="edit_engine",
+                action_name="execute_tighten",
+                timeline_before=plan.get("timeline_name"),
+                timeline_after=variant.get("name") or variant_name,
+                target_metric=_brain_edits.METRIC_DURATION_SECONDS,
+                metric_direction="decrease",
+                before_value=before.get("duration_seconds"),
+                after_value=after.get("duration_seconds"),
+                rationale=plan.get("summary"),
+                params={"plan_id": plan.get("plan_id")},
+                result_summary={"keep_ranges": len(keep_ranges), "lifts": len(lifts)},
+            )
+        except Exception:
+            pass
+        _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
+            "variant_timeline": variant.get("name") or variant_name,
+            "keep_ranges": len(keep_ranges),
+            "lifts": len(lifts),
+            "before": before,
+            "after": after,
+        })
+        return {
+            "success": True,
+            "original_timeline": plan.get("timeline_name"),
+            "variant_timeline": variant.get("name") or variant_name,
+            "lifts_applied": len(lifts),
+            "keep_ranges": len(keep_ranges),
+            "lift_rationales": [
+                {"lift": [l["timeline_start_frame"], l["timeline_end_frame"]], "rationale": l.get("rationale")}
+                for l in lifts
+            ],
+            "readback": {
+                "before": before,
+                "after": after,
+                "removed_seconds": (
+                    round(before["duration_seconds"] - after["duration_seconds"], 2)
+                    if before.get("duration_seconds") is not None and after.get("duration_seconds") is not None
+                    else None
+                ),
+            },
+            "plan_id": plan.get("plan_id"),
+        }
+
+    if action == "execute_swap":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        plan = _edit_engine_mod.load_plan(project_root, str(p.get("plan_id") or p.get("planId") or ""))
+        if not plan or plan.get("_corrupt"):
+            return _err("plan not found (or failed its fingerprint check) — re-plan")
+        if plan.get("kind") != "swap":
+            return _err(f"plan {plan.get('plan_id')} is a {plan.get('kind')} plan")
+        alternates = plan.get("alternates") or []
+        try:
+            alt_index = int(p.get("alternate_index") if p.get("alternate_index") is not None else p.get("alternateIndex"))
+        except (TypeError, ValueError):
+            return _err(f"execute_swap requires alternate_index (0-{len(alternates) - 1})")
+        if not (0 <= alt_index < len(alternates)):
+            return _err(f"alternate_index out of range (0-{len(alternates) - 1})")
+        alternate = alternates[alt_index]
+        item_block = plan.get("item") or {}
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="edit_engine.execute_swap", params=p,
+                preview={
+                    "operation": "edit_engine.execute_swap",
+                    "warning": (
+                        "Replaces one timeline item in place (lift + positioned append). "
+                        "A timeline version is archived first."
+                    ),
+                    "timeline_name": plan.get("timeline_name"),
+                    "slot": [item_block.get("timeline_start_frame"), item_block.get("timeline_end_frame")],
+                    "replacement": {
+                        "clip_name": alternate.get("clip_name"),
+                        "shot_index": alternate.get("shot_index"),
+                        "score": alternate.get("score"),
+                    },
+                },
+            )
+        blocked = _consume_confirm_token(action="edit_engine.execute_swap", params=p)
+        if blocked:
+            return blocked
+        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
+        before = _edit_engine_capture(tl)
+        lift = _timeline_lift_range_impl(tl, {
+            "start_frame": item_block.get("timeline_start_frame"),
+            "end_frame": item_block.get("timeline_end_frame"),
+            "allow_partial_item_delete": True,
+            "ripple": False,
+        })
+        if not lift.get("success"):
+            return {"success": False, "error": f"lift failed: {lift.get('error')}", "lift": lift}
+        mp = proj.GetMediaPool()
+        root_folder = mp.GetRootFolder()
+        timeline_start = _timeline_start_frame(tl)
+        frame_range = alternate.get("source_frame_range") or [0, 0]
+        ci = {
+            "clip_id": alternate.get("resolve_clip_id"),
+            "start_frame": int(frame_range[0]),
+            "end_frame": int(frame_range[1]),
+            # Item starts come from item.GetStart() — absolute timeline frames.
+            "record_frame": int(item_block.get("timeline_start_frame")),
+            "record_frame_mode": "absolute",
+            "track_index": int(item_block.get("track_index") or 1),
+        }
+        row, row_err = _build_append_clip_info_dict(root_folder, ci, 0, timeline_start)
+        if row_err:
+            return {"success": False, "error": f"swap append failed: {row_err.get('error')}", "lifted": lift}
+        appended = mp.AppendToTimeline([row])
+        after = _edit_engine_capture(tl)
+        run_id = _analysis_runs.current_run_id()
+        try:
+            _brain_edits.log_brain_edit(
+                project_root=project_root,
+                analysis_run_id=run_id or "edit-engine",
+                edit_type="edit_engine.swap_result",
+                tool_name="edit_engine",
+                action_name="execute_swap",
+                timeline_after=tl.GetName(),
+                target_metric=_brain_edits.METRIC_CLIP_COUNT,
+                metric_direction="target_value",
+                before_value=before.get("clip_count"),
+                after_value=after.get("clip_count"),
+                rationale=(
+                    f"Swapped slot {item_block.get('timeline_start_frame')}-"
+                    f"{item_block.get('timeline_end_frame')} with "
+                    f"{alternate.get('clip_name')} shot {alternate.get('shot_index')}: "
+                    f"{alternate.get('rationale')}"
+                ),
+                params={"plan_id": plan.get("plan_id"), "alternate_index": alt_index},
+                result_summary={"appended": bool(appended)},
+            )
+        except Exception:
+            pass
+        _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
+            "alternate_index": alt_index,
+            "replacement": alternate.get("clip_name"),
+            "before": before,
+            "after": after,
+        })
+        return {
+            "success": bool(appended),
+            "timeline_name": tl.GetName(),
+            "replaced_slot": [item_block.get("timeline_start_frame"), item_block.get("timeline_end_frame")],
+            "replacement": {
+                "clip_name": alternate.get("clip_name"),
+                "shot_index": alternate.get("shot_index"),
+                "score": alternate.get("score"),
+            },
+            "readback": {"before": before, "after": after},
+            "plan_id": plan.get("plan_id"),
+        }
+
+    return _unknown(action, [
+        "plan_selects",
+        "execute_selects",
+        "plan_tighten",
+        "execute_tighten",
+        "plan_swap",
+        "execute_swap",
+        "list_plans",
+        "get_plan",
+    ])
+
+
 @mcp.tool()
 @_destructive_op("timeline")
 def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -15825,6 +17064,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?) -> {success}
         # example: action_help(name='<action_name>')
       thumbnail_contact_sheet(frames?|max_samples?, analysis_root?) -> {path, samples}
+        frames are relative to the timeline start (frame 0 = first frame), like marker frameIds.
       marker_thumbnail_review(max_samples?, analysis_root?) -> {path, samples, review_guidance}
       edit_kernel_capabilities() -> {supported, partially_supported, unsupported}
       probe_edit_kernel_item(clip_ids? selected? timeline_item?) -> {items, count}
@@ -16431,6 +17671,12 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
 def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
     """Markers and playhead operations on the current timeline.
 
+    Marker frames are RELATIVE to the timeline start: frame 0 is the first
+    frame of the timeline, even when the timeline starts at 01:00:00:00.
+    Timecode params are absolute timeline timecode as shown in the Resolve UI
+    (timecodes before the start timecode are treated as elapsed time) and are
+    converted to relative frames automatically.
+
     Actions:
       add(frame|frame_id|frameId|timecode?, color?, name?, note?, duration?, custom_data?) -> {success, frame}
         If frame/timecode is omitted, add uses the current playhead timecode.