davinci-resolve-mcp 2.77.0 → 2.78.1

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.78.1
+
+`Timeline.DeleteClips` is page-gated. Contributed by
+[@billcarroll](https://github.com/billcarroll) in
+[#117](https://github.com/samuelgursky/davinci-resolve-mcp/pull/117).
+
+### Fixed
+
+- **Every delete-capable action failed whenever the UI was left on another page.**
+  `Timeline.DeleteClips` deterministically returns False and deletes nothing off
+  the Edit page (verified: Fairlight), retries included — the readback-and-retry
+  helper from v2.71.1 handles a *flaky* False correctly, but retrying cannot clear
+  a page gate. Live verification on Studio 21.0: three identical retries against
+  132 valid, unlocked, present items all returned False with all 132 still on the
+  track; one `OpenPage("edit")` and the same call returned True and left 0. Track
+  lock and enable state were clear throughout — a page gate, not a lock.
+  `timeline` `delete_clips` / `move_clips` / `overwrite_range` / `lift_range` /
+  `apply_cuts` and `edit_engine execute_swap` now hold the Edit page for the call
+  and restore the caller's page after.
+
+The guard is serialized through `page_lock`, alongside the existing Color-page
+guard for thumbnail capture: Resolve has one globally-active page, so an
+unserialized switch-work-restore races every other page-switching operation, and
+under the threaded dispatch from v2.62.0 a concurrent thumbnail capture flipping
+to Color mid-delete would land the delete on the wrong page — reintroducing this
+same bug. `apply_cuts` holds the guard once around its loop rather than per cut,
+which would otherwise cost 2N page flips for N cuts.
+
+The `api_truth` entry is restructured into the two distinct failures now known to
+share this call: wrong page (deterministic, mechanism identified, verified) and
+flaky first attempt (one observation, cause not established — and the entry now
+records that the page state at the time was not captured, so it cannot be ruled in
+or out as the first failure in disguise).
+
+## What's New in v2.78.0
+
+The AAF probe reports where in the *source* an event actually lives, not where it
+lives in the consolidated fragment the AAF happens to reference.
+
+### Fixed
+
+- **`srcIn`/`srcOut` were handle offsets, not positions in the take.** A
+  `SourceClip`'s `start` is an offset into whatever mob it references *directly*,
+  and for consolidated media that mob is a per-cut fragment carrying handles — not
+  the take. On a real turnover 774 of 878 events reported `srcIn <= 45`, and one
+  take used thirteen times reported `srcIn 40` all thirteen times; two cuts of one
+  take cannot both begin at frame 42 of it. A consumer placing those numbers
+  against camera originals lands on the right cut of the right take showing the
+  **wrong moment**, and the number fits inside the file, so no range check catches
+  it. The consumer measured 2 of 526 cuts matching its picture reference before
+  this.
+
+### Added
+
+- **Physical source position and timecode per event** — `srcPos`, `srcTcFrame`,
+  `srcTc`, `srcTcFps`, `srcTcDrop`. The chase sums `start` down the mob chain and
+  reads the nearest mob's timecode slot, so a consumer that links camera originals
+  can place `sourceTc − fileStartTc` instead of a fragment-relative number. Emitted
+  only when actually read: a chain that adds nothing emits nothing rather than
+  restating `srcIn`, and per-sequence `sourcePositionCoverage` counters let a
+  consumer distinguish "this AAF carries none" from "this probe is too old to emit
+  it." `srcIn`/`srcOut` are unchanged — this is additive.
+
+Verified on the fixture: 869/878 events carry `srcPos`, 876 carry source timecode,
+and the take used thirteen times separates into thirteen distinct positions.
+Frame-exact against an independent witness — at the frame the turnover's own
+picture reference burned 21:19:28:21, the probe says 21:19:28:21.
+
 ## What's New in v2.77.0
 
 Folder addressing fails loud instead of quietly answering about whichever bin the

package/README.md

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

package/docs/reference/api-limitations.md

@@ -374,13 +374,17 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
 - **Tags:** unreliable-return, silent-failure, metadata, reel-name
 
-### Timeline.DeleteClips (flaky first attempt)
+### Timeline.DeleteClips (requires the Edit page; flaky first attempt)
 
 - **Object:** `Timeline`
 - **Signature:** `([TimelineItem], ripple) -> bool`
-- **Behavior:** Can return False on the first call even when every item in the list is a valid, present TimelineItem; an identical immediate retry succeeds. Observed once, on Studio 21.0 during a cut-video edit session (items confirmed still present after the False, deleted cleanly on retry). Cause unknown — do NOT read this as the ProjectManager.DeleteProject shape: that one has an identified mechanism (the project being, or recently having been, current) that retrying does not clear, whereas a single retry cleared this in the one instance seen. One observation is not a mechanism; if a retry is ever seen to fail repeatedly here, this entry needs revisiting.
-- **Workaround / current handling:** Treat a False return as advisory: re-list the track and check whether the items are actually gone; if still present, retry the identical call once before failing. A readback that raised, enumerated nothing, or covered items whose unique ID cannot be read is UNKNOWN, not gone — never report an unverifiable delete as success, and do not spend a second destructive call on an outcome you equally cannot read.
-- **Tags:** unreliable-return, flaky, timeline, edit
+- **Behavior:** Two distinct failures share this call.
+
+  **1. Wrong page (deterministic, has a mechanism).** With the UI on the Fairlight page, DeleteClips returns False and deletes nothing, no matter how many times it is retried. Verified 2026-08-04 on Studio 21.0: three identical retries against 132 valid, unlocked, present TimelineItems all returned False with all 132 still on the track; a single `Resolve.OpenPage("edit")` followed by the same call returned True and left 0 items. Track lock and enable state were confirmed clear before and after, so this is a page gate, not a lock. This is the case the previous entry's falsification condition anticipated — a retry seen to fail repeatedly — and revisiting it found the mechanism.
+
+  **2. Flaky first attempt (one observation, no mechanism).** Independently of the page, the call has been seen once to return False with every item still present, where an identical immediate retry succeeded (Studio 21.0, cut-video edit session). Whether the UI was on the Edit page at the time was not recorded, so it cannot be ruled in or out as failure 1 in disguise. Do NOT read this as the ProjectManager.DeleteProject shape: that one has an identified mechanism (the project being, or recently having been, current) that retrying does not clear. One observation is still not a mechanism; if an immediate retry is ever seen to fail repeatedly while the UI is confirmed on the Edit page, this sub-entry needs revisiting.
+- **Workaround / current handling:** Open the Edit page first (`Resolve.OpenPage("edit")`) — a caller that deletes clips from a script must not assume the user left the UI on Edit, and a Fairlight or Color session is a completely ordinary place for them to be. Then treat a False return as advisory: re-list the track and check whether the items are actually gone; if still present, retry the identical call once before failing. A readback that raised, enumerated nothing, or covered items whose unique ID cannot be read is UNKNOWN, not gone — never report an unverifiable delete as success, and do not spend a second destructive call on an outcome you equally cannot read.
+- **Tags:** unreliable-return, flaky, silent-failure, page-dependent, timeline, edit
 
 ### MediaPool.AppendToTimeline with mixed-fps sources (duration floor)
 

package/install.py

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

package/package.json

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

package/resolve-advanced/server/aaf_probe.py

@@ -160,6 +160,133 @@ def _source_name(clip):
     return _usable_name(clip) or "UNKNOWN"
 
 
+# ── Physical source position + timecode (the "which frames" question) ─────────
+#
+# MEASURED 2026-08-05 on a consolidated Avid turnover: a SourceClip's own
+# `start` is the offset into whatever mob it references DIRECTLY, and for
+# consolidated media that is a per-cut fragment with ~40-frame handles — so 774
+# of 878 events reported srcIn <= 45, and takes used several times all reported
+# the SAME srcIn with different lengths. Two different cuts of one take cannot
+# both begin at frame 42 of that take; those 42s were handles on separate
+# fragments.
+#
+# The real position is the SUM of the `start` offsets down the mob chain, and
+# the anchor that survives relinking to different media is the physical source
+# TIMECODE: the referenced mob's timecode start plus that accumulated offset.
+# A consumer that links camera originals can then place
+# `sourceTc - fileStartTc` instead of a fragment-relative number that merely
+# FITS inside the file.
+#
+# Emitted per event as srcPos / srcTcFrame / srcTc / srcTcFps / srcTcDrop, and
+# only when actually found — a consumer must be able to tell "this AAF carries
+# no source timecode" from "this probe is too old to emit it", which is what
+# the per-sequence sourceTimecodeCoverage counters are for.
+
+
+def _mob_timecode(mob, _cache={}):
+    """(startFrame, rate, drop) from a mob's timecode slot, or None."""
+    try:
+        key = str(getattr(mob, "mob_id", "") or id(mob))
+    except Exception:
+        key = str(id(mob))
+    if key in _cache:
+        return _cache[key]
+    found = None
+    for slot in getattr(mob, "slots", None) or []:
+        try:
+            if _slot_media_kind(slot) != _TIMECODE_KIND:
+                continue
+        except Exception:
+            continue
+        tc = _timecode_component(getattr(slot, "segment", None))
+        if tc is None:
+            continue
+        try:
+            start = int(getattr(tc, "start"))
+            rate = int(round(float(getattr(tc, "fps", 0) or 0)))
+            drop = bool(getattr(tc, "drop", False))
+        except Exception:
+            continue
+        if rate > 0 and start >= 0:
+            found = (start, rate, drop)
+            break
+    _cache[key] = found
+    return found
+
+
+def _chase_source_position(clip):
+    """Physical source position + timecode for a SourceClip's FIRST frame.
+
+    Walks clip -> referenced mob -> that mob's own SourceClip, accumulating each
+    hop's `start`. Returns (position, timecode_or_None) where `timecode` is
+    (tc_start, rate, drop, position_at_that_mob) for the NEAREST mob carrying a
+    timecode slot. Bounded and cycle-guarded like _source_name.
+    """
+    current = clip
+    position = 0
+    timecode = None
+    seen = set()
+    for _ in range(_MAX_MOB_CHASE):
+        try:
+            position += int(getattr(current, "start", 0) or 0)
+        except Exception:
+            pass
+        try:
+            mob = getattr(current, "mob", None)
+        except Exception:
+            mob = None
+        if mob is None:
+            break
+        try:
+            key = str(getattr(mob, "mob_id", "") or id(mob))
+        except Exception:
+            key = str(id(mob))
+        if key in seen:
+            break  # reference cycle — stop rather than spin
+        seen.add(key)
+        if timecode is None:
+            tc = _mob_timecode(mob)
+            if tc is not None:
+                timecode = (tc[0], tc[1], tc[2], position)
+        nxt = None
+        for slot in getattr(mob, "slots", None) or []:
+            nxt = _find_source_clip(getattr(slot, "segment", None))
+            if nxt is not None:
+                break
+        if nxt is None:
+            break
+        current = nxt
+    return position, timecode
+
+
+def _source_position_fields(clip):
+    """The srcPos/srcTc* keys for an event. Empty dict when nothing is knowable."""
+    try:
+        position, timecode = _chase_source_position(clip)
+    except Exception:
+        return {}
+    fields = {}
+    try:
+        own_start = int(getattr(clip, "start", 0) or 0)
+    except Exception:
+        own_start = 0
+    if position != own_start:
+        # Only meaningful when the chain actually went deeper than the clip's
+        # own reference — otherwise srcPos would just restate srcIn.
+        fields["srcPos"] = position
+    if timecode is not None:
+        tc_start, rate, drop, at = timecode
+        fields.update(
+            {
+                "srcTcFrame": tc_start + at,
+                "srcTc": _frames_to_timecode(tc_start + at, rate, drop),
+                "srcTcFps": rate,
+                "srcTcDrop": drop,
+            }
+        )
+    return fields
+
+
 def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
     """Turn a SourceClip into a normalized event. Returns (event, length)."""
     try:
@@ -183,6 +310,7 @@ def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
         "transition": transition,
         "fps": fps,
     }
+    event.update(_source_position_fields(clip))
     return event, length
 
 
@@ -884,6 +1012,15 @@ def probe(path):
                     "name": str(name) if name else f"Sequence {len(sequences) + 1}",
                     "eventCount": len(events),
                     **_sequence_start_timecode(mob, edit_fps),
+                    # How much of this sequence carries a physical source position
+                    # / timecode. Always present, so a consumer can tell "this AAF
+                    # has none" (zeros) from "this probe is too old to emit it"
+                    # (key absent) — the same reasoning as _NO_START_TIMECODE.
+                    "sourcePositionCoverage": {
+                        "events": len(events),
+                        "withSourcePosition": sum(1 for e in events if "srcPos" in e),
+                        "withSourceTimecode": sum(1 for e in events if "srcTcFrame" in e),
+                    },
                     # Component classes we could not model, by name+count. Empty {} means
                     # a structurally complete read; non-empty means events are INCOMPLETE.
                     "unhandled": dict(sorted(state["unhandled"].items())),

package/src/granular/common.py

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

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.77.0"
+VERSION = "2.78.1"
 
 import base64
 import os
@@ -50,6 +50,7 @@ from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
     color_page_for_thumbnails as _color_page_for_thumbnails,
+    edit_page_for_timeline_edits as _edit_page_for_timeline_edits,
     open_page_serialized as _open_page_serialized,
     page_lock as _page_lock,
 )
@@ -3918,12 +3919,31 @@ def _timeline_items_presence(tl, items):
     return "absent"
 
 
-def _timeline_delete_clips_verified(tl, items, ripple):
-    """Timeline.DeleteClips with readback-and-retry.
+def _timeline_delete_clips_verified(tl, items, ripple, *, resolve=None):
+    """Timeline.DeleteClips with a page guard and readback-and-retry.
 
-    api_truth 'Timeline.DeleteClips (flaky first attempt)': the call can
-    return False while every item is still present, and an identical retry
-    then succeeds. On a False, read the tracks back:
+    api_truth 'Timeline.DeleteClips (requires the Edit page; flaky first
+    attempt)' records two distinct failures behind this one call.
+
+    Wrong page (deterministic): with the UI on some pages (verified:
+    Fairlight) the call returns False and deletes nothing, retries included —
+    retrying cannot help. When a `resolve` handle is supplied, the guard
+    switches to the Edit page for the call and restores the caller's page
+    after. Guard failures are swallowed: the delete attempt itself stays the
+    source of truth. `resolve` is an explicit parameter, not an internal
+    get_resolve(), so offline tests calling this helper directly can never
+    touch a live Resolve UI.
+
+    The guard is page_lock's edit_page_for_timeline_edits, not a local
+    OpenPage pair, because the switch has to be serialized against every other
+    page-switching operation (thumbnail capture takes the Color page the same
+    way). Unlocked, a concurrent switch lands this delete on some other page —
+    reintroducing the very failure the guard prevents. Callers deleting in a
+    loop should hold that guard around the loop; nesting it here is free.
+
+    Flaky first attempt: the call can return False while every item is still
+    present, and an identical retry then succeeds. On a False, read the
+    tracks back:
 
       absent  -> the delete landed despite the False; report success.
       present -> retry the identical call once, then read back again.
@@ -3938,14 +3958,20 @@ def _timeline_delete_clips_verified(tl, items, ripple):
     handles to already-deleted items included. That could not be made to
     misbehave against a fake; it is recorded, not resolved.
     """
-    if bool(tl.DeleteClips(items, ripple)):
-        return True
-    presence = _timeline_items_presence(tl, items)
-    if presence != "present":
-        return presence == "absent"
-    if bool(tl.DeleteClips(items, ripple)):
-        return True
-    return _timeline_items_presence(tl, items) == "absent"
+    def _delete_with_readback():
+        if bool(tl.DeleteClips(items, ripple)):
+            return True
+        presence = _timeline_items_presence(tl, items)
+        if presence != "present":
+            return presence == "absent"
+        if bool(tl.DeleteClips(items, ripple)):
+            return True
+        return _timeline_items_presence(tl, items) == "absent"
+
+    if resolve is None:
+        return _delete_with_readback()
+    with _edit_page_for_timeline_edits(resolve):
+        return _delete_with_readback()
 
 
 def _timeline_items_by_ids(tl, ids, track_types=("video", "audio", "subtitle")):
@@ -4110,7 +4136,7 @@ def _append_and_recover_timeline_item(
     return result, duplicate_item, None
 
 
-def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_sources: bool = False):
+def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_sources: bool = False, resolve=None):
     ids = p.get("clip_ids") or p.get("ids")
     selected = bool(p.get("selected", False))
     if ids is not None and not isinstance(ids, list):
@@ -4321,7 +4347,7 @@ def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_source
                 seen_delete_ids.add(item_id)
         if delete_items:
             try:
-                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)))
+                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)), resolve=resolve)
                 out["deleted_source_ids"] = _timeline_item_ids(delete_items)
             except Exception as exc:
                 out["deleted_sources"] = False
@@ -4399,7 +4425,7 @@ def _collect_timeline_items_in_range(tl, p: Dict[str, Any]):
     return start, end, items, None
 
 
-def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool = False):
+def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool = False, resolve=None):
     start, end, items, err = _collect_timeline_items_in_range(tl, p)
     if err:
         return err
@@ -4436,7 +4462,7 @@ def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool =
                     if existing_start < dest_end and existing_end > dest_start:
                         delete_targets.append(existing)
         if delete_targets:
-            deleted = _timeline_delete_clips_verified(tl, delete_targets, False)
+            deleted = _timeline_delete_clips_verified(tl, delete_targets, False, resolve=resolve)
 
     results = []
     for track_type, source_track, item, overlap_start, overlap_end in items:
@@ -4499,7 +4525,7 @@ def _apply_cuts_skip_reason(cut):
     return None
 
 
-def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
+def _timeline_lift_range_impl(tl, p: Dict[str, Any], *, resolve=None):
     start, end, items, err = _collect_timeline_items_in_range(tl, p)
     if err:
         return err
@@ -4529,7 +4555,7 @@ def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
         return {"success": True, "deleted": 0, "range": {"start": start, "end": end}}
     deleted_ids = _timeline_item_ids(delete_items)
     return {
-        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False))),
+        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)), resolve=resolve),
         "deleted": len(delete_items),
         "deleted_ids": deleted_ids,
         "range": {"start": start, "end": end},
@@ -20499,7 +20525,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             "track_indices": [target_track],
             "allow_partial_item_delete": True,
             "ripple": False,
-        })
+        }, resolve=_r)
         if not lift.get("success"):
             return {"success": False, "error": f"lift failed: {lift.get('error')}", "lift": lift}
         audio_lift = None
@@ -20511,7 +20537,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 "track_indices": linked_audio_indices,
                 "allow_partial_item_delete": True,
                 "ripple": False,
-            })
+            }, resolve=_r)
             if not audio_lift.get("success"):
                 return {
                     "success": False,
@@ -21005,7 +21031,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             blocked = _consume_confirm_token(action="timeline.delete_clips_ripple", params=p)
             if blocked:
                 return blocked
-        return {"success": _timeline_delete_clips_verified(tl, found, ripple)}
+        return {"success": _timeline_delete_clips_verified(tl, found, ripple, resolve=get_resolve())}
     elif action == "set_clips_linked":
         ids_set = set(p["clip_ids"])
         found = []
@@ -21023,13 +21049,13 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "copy_clips":
         return _timeline_duplicate_clips_impl(proj, tl, p)
     elif action == "move_clips":
-        return _timeline_duplicate_clips_impl(proj, tl, p, delete_sources=True)
+        return _timeline_duplicate_clips_impl(proj, tl, p, delete_sources=True, resolve=get_resolve())
     elif action in {"copy_range", "duplicate_range"}:
         return _timeline_copy_range_impl(proj, tl, p)
     elif action == "overwrite_range":
-        return _timeline_copy_range_impl(proj, tl, p, overwrite=True)
+        return _timeline_copy_range_impl(proj, tl, p, overwrite=True, resolve=get_resolve())
     elif action == "lift_range":
-        return _timeline_lift_range_impl(tl, p)
+        return _timeline_lift_range_impl(tl, p, resolve=get_resolve())
     elif action == "story_spine_report":
         return _timeline_story_spine_report(tl, p)
     elif action == "create_variant_from_ranges":
@@ -21184,15 +21210,21 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
 
         allow_partial = bool(p.get("allow_partial_item_delete", True))
         results = []
-        for c in applicable:
-            sp = c["span"]
-            res = _timeline_lift_range_impl(tl, {
-                "start_frame": sp["start"],
-                "end_frame": sp["end"],
-                "ripple": c["action"] == "ripple_delete",
-                "allow_partial_item_delete": allow_partial,
-            })
-            results.append({"action": c["action"], "span": sp, "result": res})
+        resolve_obj = get_resolve()
+        # Hold the Edit page once for the whole run. The per-delete guard nests
+        # harmlessly inside (it finds the page already on edit), but without this
+        # each cut would switch and restore on its own: from Fairlight, N cuts
+        # cost 2N page flips instead of 2.
+        with _edit_page_for_timeline_edits(resolve_obj):
+            for c in applicable:
+                sp = c["span"]
+                res = _timeline_lift_range_impl(tl, {
+                    "start_frame": sp["start"],
+                    "end_frame": sp["end"],
+                    "ripple": c["action"] == "ripple_delete",
+                    "allow_partial_item_delete": allow_partial,
+                }, resolve=resolve_obj)
+                results.append({"action": c["action"], "span": sp, "result": res})
         applied = sum(1 for r in results
                       if isinstance(r["result"], dict) and r["result"].get("success"))
         return {"success": True, "applied": applied, "total": len(applicable),

package/src/utils/api_truth.py

@@ -951,30 +951,53 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
     {
-        "symbol": "Timeline.DeleteClips (flaky first attempt)",
+        "symbol": "Timeline.DeleteClips (requires the Edit page; flaky first attempt)",
         "object": "Timeline",
         "signature": "([TimelineItem], ripple) -> bool",
-        "reality": "Can return False on the first call even when every item in "
-                   "the list is a valid, present TimelineItem; an identical "
-                   "immediate retry succeeds. Observed once, on Studio 21.0 "
-                   "during a cut-video edit session (items confirmed still "
-                   "present after the False, deleted cleanly on retry). Cause "
-                   "unknown — do NOT read this as the ProjectManager."
-                   "DeleteProject shape: that one has an identified mechanism "
-                   "(the project being, or recently having been, current) that "
-                   "retrying does not clear, whereas a single retry cleared "
-                   "this in the one instance seen. One observation is not a "
-                   "mechanism; if a retry is ever seen to fail repeatedly here, "
-                   "this entry needs revisiting.",
-        "recommended": "Treat a False return as advisory: re-list the track and "
-                       "check whether the items are actually gone; if still "
-                       "present, retry the identical call once before failing. "
-                       "A readback that raised, enumerated nothing, or covered "
-                       "items whose unique ID cannot be read is UNKNOWN, not "
-                       "gone — never report an unverifiable delete as success, "
-                       "and do not spend a second destructive call on an "
-                       "outcome you equally cannot read.",
-        "tags": ["unreliable-return", "flaky", "timeline", "edit"],
+        "reality": "Two distinct failures share this call.\n"
+                   "\n"
+                   "  **1. Wrong page (deterministic, has a mechanism).** With "
+                   "the UI on the Fairlight page, DeleteClips returns False and "
+                   "deletes nothing, no matter how many times it is retried. "
+                   "Verified 2026-08-04 on Studio 21.0: three identical retries "
+                   "against 132 valid, unlocked, present TimelineItems all "
+                   "returned False with all 132 still on the track; a single "
+                   "`Resolve.OpenPage(\"edit\")` followed by the same call "
+                   "returned True and left 0 items. Track lock and enable state "
+                   "were confirmed clear before and after, so this is a page "
+                   "gate, not a lock. This is the case the previous entry's "
+                   "falsification condition anticipated — a retry seen to fail "
+                   "repeatedly — and revisiting it found the mechanism.\n"
+                   "\n"
+                   "  **2. Flaky first attempt (one observation, no "
+                   "mechanism).** Independently of the page, the call has been "
+                   "seen once to return False with every item still present, "
+                   "where an identical immediate retry succeeded (Studio 21.0, "
+                   "cut-video edit session). Whether the UI was on the Edit "
+                   "page at the time was not recorded, so it cannot be ruled "
+                   "in or out as failure 1 in disguise. Do NOT read this as "
+                   "the ProjectManager.DeleteProject shape: that one has an "
+                   "identified mechanism (the project being, or recently "
+                   "having been, current) that retrying does not clear. One "
+                   "observation is still not a mechanism; if an immediate "
+                   "retry is ever seen to fail repeatedly while the UI is "
+                   "confirmed on the Edit page, this sub-entry needs "
+                   "revisiting.",
+        "recommended": "Open the Edit page first (`Resolve.OpenPage(\"edit\")`) "
+                       "— a caller that deletes clips from a script must not "
+                       "assume the user left the UI on Edit, and a Fairlight or "
+                       "Color session is a completely ordinary place for them "
+                       "to be. Then treat a False return as advisory: re-list "
+                       "the track and check whether the items are actually "
+                       "gone; if still present, retry the identical call once "
+                       "before failing. A readback that raised, enumerated "
+                       "nothing, or covered items whose unique ID cannot be "
+                       "read is UNKNOWN, not gone — never report an "
+                       "unverifiable delete as success, and do not spend a "
+                       "second destructive call on an outcome you equally "
+                       "cannot read.",
+        "tags": ["unreliable-return", "flaky", "silent-failure",
+                 "page-dependent", "timeline", "edit"],
         "submit": "bug",
         "mitigation": ["_timeline_delete_clips_verified", "_timeline_items_presence"],
     },

package/src/utils/page_lock.py

@@ -113,3 +113,53 @@ def color_page_for_thumbnails(resolve):
                     resolve.OpenPage(original)
                 except Exception:
                     pass
+
+
+@contextmanager
+def edit_page_for_timeline_edits(resolve):
+    """Hold the Edit page for the block, restoring the user's page after.
+
+    api_truth 'Timeline.DeleteClips (requires the Edit page; flaky first
+    attempt)': off the Edit page the call returns False and deletes nothing,
+    retries included — retrying cannot clear a page gate. Yields True when
+    Resolve is on the Edit page for the block.
+
+    Same shape as color_page_for_thumbnails, and for the same reason it lives
+    here rather than at the callsite: the switch must be serialized. Resolve has
+    one globally-active page, so an unlocked switch-work-restore races every
+    other page-switching operation — and losing that race puts the delete on
+    some other page, which is exactly the failure this guard exists to prevent.
+
+    Nesting is free (page_lock is reentrant, and an inner guard finds the page
+    already on edit and switches nothing), so a caller that deletes in a LOOP
+    should hold this once around the loop. Otherwise it pays a switch and a
+    restore per iteration: from Fairlight, N cuts cost 2N page flips, each a
+    visible flash and possible cache/render work.
+
+    If the current page can't be captured (GetCurrentPage returned None or
+    raised), no switch is attempted, so a skipped restore can never strand the
+    user on the Edit page.
+    """
+    original = None
+    try:
+        original = resolve.GetCurrentPage() if resolve else None
+    except Exception:
+        original = None
+    with page_lock():
+        on_edit = original == "edit"
+        if original and not on_edit:
+            try:
+                on_edit = bool(resolve.OpenPage("edit"))
+            except Exception:
+                pass
+        try:
+            yield on_edit
+        finally:
+            # Restore only a page we actually left: `on_edit` is False here when
+            # OpenPage refused, and restoring then would flip a page the user is
+            # still on.
+            if original and original != "edit" and on_edit:
+                try:
+                    resolve.OpenPage(original)
+                except Exception:
+                    pass