davinci-resolve-mcp 4.8.22 → 4.8.23

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 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 v4.8.23 — a frame capture no longer leaves Resolve on the Deliver page
+
+### Fixed
+
+- **`timeline_frame` capture left Resolve on the Deliver page.** ([#270](https://github.com/samuelgursky/davinci-resolve-mcp/issues/270), reported by @Dragonfist76 on Studio 21.1.0.17)
+  The render route (`quality="frame"`, `"preview"`, `"full"`) recorded the page
+  to return to *after* calling `Project.GetCurrentRenderMode()`. That getter
+  switches Resolve to the Deliver page by itself (measured on Studio 19.1.3.7
+  from Edit, Color and Fairlight), so the page recorded was always `deliver` and
+  the restore was skipped as having nothing to do. The page is now read before
+  any render call. Live on 19.1.3.7: 14 captures from seven starting pages all
+  ended on the page they started on.
+- **A restore that does not take is no longer silent.** The switch back is read
+  back with `GetCurrentPage()`. If the page, playhead, current timeline, render
+  mode, render format or render range is not put back, the image is followed by
+  a `{"warnings": [...]}` block naming what was left changed and the call that
+  restores it; an error result carries the same `warnings` key. A clean capture
+  is unchanged: one image.
+- **The render range was never restored after a capture.** The restore shared a
+  `SetRenderSettings` payload with `CustomName: ""`, and Resolve refuses an empty
+  `CustomName` by rejecting the whole payload (measured on 19.1.3.7: `False`, and
+  a job queued afterwards still carried `MarkIn == MarkOut ==` the captured
+  frame). The range now goes in its own payload and its result is checked. Live
+  on 19.1.3.7: a job queued after each capture carried the whole timeline.
+- **`render get_mode`, `render probe_render_settings` and the granular
+  `get_current_render_mode` left Resolve on the Deliver page**, for the same
+  reason: they call the same getter. They now return to the page they were
+  called from.
+- **`resolve_control restore_state` reported the page as restored without
+  checking.** `OpenPage`'s return was discarded. `restored.page` is now written
+  only when the page reads back, and `page_error` says why otherwise.
+- The Color-page and Edit-page guards used by thumbnails and timeline edits
+  discarded `OpenPage` on their way back too. Both now read the page back and
+  log a failure.
+
+### Changed
+
+- `timeline_frame capabilities` returns `render_settings_restorable`, which its
+  docstring already listed. `TargetDir` and `CustomName` are `false`: there is no
+  `GetRenderSettings`, so after a render capture they stay on the capture's
+  temporary folder and name. The docs previously said they were reset.
+
+### Documentation
+
+- `api_truth` gains two measured entries, both on Studio 19.1.3.7:
+  `Project.GetCurrentRenderMode` switches to the Deliver page (with the list of
+  render calls that do and do not), and `Project.SetRenderSettings` rejects a
+  whole payload over an empty `CustomName`. `docs/reference/api-limitations.md`
+  is regenerated.
+
+### Tests
+
+- `tests/test_playhead_frame_capture.py`: the render fake now behaves as
+  measured (the mode getter switches page; an empty `CustomName` refuses the
+  payload). New tests cover the page coming back, a refused or lying `OpenPage`
+  being reported with the image, the warning reaching an MCP client as a text
+  block after the image, and the range Resolve holds after a capture. The two
+  regression tests fail against v4.8.22.
+- `tests/test_page_restore.py`: `restore_page`, `restoring_page`, both page
+  guards, the three render-mode readers and `restore_state`.
+- `tests/test_discarded_resolve_returns.py` now treats `OpenPage` and the
+  `open_page_serialized` wrapper as mutators whose return must be used.
+- `tests/live_frame_capture_page_restore_validation.py`: the live harness behind
+  the numbers above.
+
 ## What's New in v4.8.22 — the control panel port check cannot hang on a wedged lsof
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.8.22-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.8.23-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-37%20(389%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.8.22-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.8.23-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-37%20(389%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v4.8.22 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.8.23 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -1860,11 +1860,19 @@ metadata. (For the raw camera file instead, use
   `frame` is the absolute timeline frame. Omit both to capture the playhead.
 
 The playhead, page, current timeline and Gallery are restored. The render route
-additionally touches project render settings: format and codec are restored and
-the render job is deleted, but `TargetDir`/`CustomName`/mark range cannot be read
-back on builds without `GetRenderSettings`, so they are reset to the full
-timeline rather than restored. Reach for `quality="thumbnail"` when zero side
-effects matter more than accuracy.
+additionally touches project render settings: render mode, format, codec and the
+mark range are restored and the render job is deleted. `TargetDir` and
+`CustomName` cannot be read back (there is no `GetRenderSettings`), so they are
+not restored: they stay on the capture's temporary folder and name, and
+`capabilities` reports them under `render_settings_restorable`. Set your own
+before the next render. Reach for `quality="thumbnail"` when zero side effects
+matter more than accuracy.
+
+The render calls pull Resolve onto the Deliver page. The capture switches back
+and reads the page to confirm it. If a restore does not take (page, playhead,
+timeline, render mode, format or range), the image is followed by a
+`{"warnings": [...]}` block naming what was left changed and the call that puts
+it back. No warnings block means every restore was confirmed.
 
 ```
 timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 41 missing capabilities, 54 bugs / unreliable behaviors.
+**Totals:** 41 missing capabilities, 56 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -689,6 +689,24 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #123](https://github.com/samuelgursky/davinci-resolve-mcp/issues/123)
 - **Tags:** render, deliver, silent-failure, preset, readback-lies
 
+### Project.GetCurrentRenderMode (switches to the Deliver page)
+
+- **Object:** `Project`
+- **Signature:** `() -> int`
+- **Behavior:** A getter with a side effect: calling it switches Resolve to the Deliver page. Measured 2026-09-30 on Studio 19.1.3.7 from the Edit, Color and Fairlight pages: GetCurrentPage() read 'deliver' immediately afterwards, every time. The other render readers do not do this — GetCurrentRenderFormatAndCodec, GetRenderFormats, GetRenderCodecs, GetRenderResolutions, GetRenderJobList, GetRenderPresetList, IsRenderingInProgress and Timeline.GetMarkInOut all left the page alone in the same run. The render WRITERS all switch: SetCurrentRenderMode, SetCurrentRenderFormatAndCodec, SetRenderSettings, AddRenderJob and StartRendering each moved Edit to Deliver; DeleteRenderJob did not. Nothing switches back on its own. Issue #270 reported the consequence on Studio 21.1.0.17 — a frame capture that left the user on Deliver — but the per-call measurement was not repeated on that build.
+- **Workaround / current handling:** Read GetCurrentPage() BEFORE the first render call, not after, and OpenPage back when done. A page read after GetCurrentRenderMode is always 'deliver', which makes a restore look unnecessary — that ordering is how the capture stranded users. src/utils/page_lock.py:restoring_page reads first, restores after, and reads the page back to confirm.
+- **Reference:** [issue #270](https://github.com/samuelgursky/davinci-resolve-mcp/issues/270)
+- **Tags:** render, deliver, page, side-effect, getter
+
+### Project.SetRenderSettings (an empty CustomName rejects the whole payload)
+
+- **Object:** `Project`
+- **Signature:** `({settings}) -> bool`
+- **Behavior:** SetRenderSettings returns False for {'CustomName': ''} and for {'CustomName': None}, and when that key rides in a larger payload the WHOLE payload is rejected, not just the name. Measured 2026-09-30 on Studio 19.1.3.7: with the render range pinned to one frame, {SelectAllFrames: True, MarkIn: start, MarkOut: end, CustomName: ''} returned False and a job added afterwards still carried MarkIn == MarkOut == the pinned frame; the same payload without CustomName returned True and the job carried the whole timeline. A single space IS accepted, and becomes the file name. So a custom name, once set, cannot be cleared through this API, and there is no GetRenderSettings to read the previous one back from.
+- **Workaround / current handling:** Never send an empty CustomName, and never bundle a best-effort key with keys that matter: send the range in its own payload and check its return. To see what a job will inherit, AddRenderJob, read MarkIn/MarkOut/TargetDir/OutputFilename off GetRenderJobList, then DeleteRenderJob.
+- **Reference:** [issue #270](https://github.com/samuelgursky/davinci-resolve-mcp/issues/270)
+- **Tags:** render, deliver, silent-failure, unreliable-return
+
 ### ProjectManager.SaveProject
 
 - **Object:** `ProjectManager`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.8.22"
+VERSION = "4.8.23"
 # 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": "4.8.22",
+  "version": "4.8.23",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

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

package/src/granular/project.py

@@ -1,6 +1,7 @@
 """Project, render, cache, cloud, and project-property tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+from src.utils.page_lock import restoring_page
 
 resolve = ResolveProxy()
 
@@ -1338,7 +1339,10 @@ def get_current_render_mode() -> Dict[str, Any]:
     project = resolve.GetProjectManager().GetCurrentProject()
     if not project:
         return {"error": "No project currently open"}
-    mode = project.GetCurrentRenderMode()
+    # The getter itself switches Resolve to the Deliver page (api_truth
+    # 'Project.GetCurrentRenderMode'); a read must not move the user.
+    with restoring_page(resolve, what="a render-mode read"):
+        mode = project.GetCurrentRenderMode()
     return {"render_mode": mode, "mode_name": "Individual Clips" if mode == 0 else "Single Clip"}
 
 

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.8.22"
+VERSION = "4.8.23"
 
 import base64
 import os
@@ -67,6 +67,8 @@ 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,
+    restore_page as _restore_page,
+    restoring_page as _restoring_page,
     page_lock as _page_lock,
 )
 from src.utils.proc import safe_run
@@ -14975,7 +14977,8 @@ def _render_job_completed(status: Optional[Dict[str, Any]]) -> bool:
         return False
 
 
-def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
+def _playhead_frame_render(proj, tl, p: Dict[str, Any],
+                           teardown: Optional[List[str]] = None):
     """Render exactly one frame — the only frame-accurate capture route.
 
     The two cheaper routes cannot do this job (both measured on Studio 19.1.3.7,
@@ -14995,11 +14998,20 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
       - The mark range is readable via Timeline.GetMarkInOut, so a range the
         caller had set is put back (offset into SetRenderSettings' absolute
         frame space); with no range set it falls back to the whole timeline.
-      - TargetDir and CustomName are readable from nowhere, so they are reset to
-        sane values rather than restored.
+      - TargetDir and CustomName are readable from nowhere, so they are NOT
+        restored: they stay on the capture's temporary folder and name. An
+        empty CustomName cannot be written back either (refused on 19.1.3.7).
     Callers who need a strictly side-effect-free read should use
     quality="thumbnail" and accept per-clip granularity.
+
+    `teardown` collects one sentence per restore that did not take (render
+    mode, format/codec, render range, playhead, page). The restores run in a
+    `finally`, which cannot change the value already being returned, so the
+    caller passes the list in and attaches it to the result afterwards (issue
+    #270: the user was left on Deliver with nothing in the result to say so).
     """
+    if teardown is None:
+        teardown = []
     fmt = str(p.get("format", "jpg")).lower().lstrip(".")
     if fmt == "jpeg":
         fmt = "jpg"
@@ -15042,6 +15054,24 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
     os.makedirs(folder, exist_ok=True)
     name = f"capture-{int(time.time() * 1000)}"
 
+    # Where the user is comes FIRST, before any render call. Issue #270: this
+    # was read after GetCurrentRenderMode(), and that getter itself switches
+    # Resolve to the Deliver page (measured on Studio 19.1.3.7 from Edit, Color
+    # and Fairlight; api_truth 'Project.GetCurrentRenderMode'). So the page
+    # recorded here was always 'deliver', the restore below was skipped as
+    # "nothing to restore", and every capture left the user on Deliver.
+    # Rendering can move the playhead as well. Both are ours to put back.
+    resolve = get_resolve()
+    original_page = None
+    try:
+        original_page = resolve.GetCurrentPage() if resolve else None
+    except Exception:
+        original_page = None
+    original_tc = None
+    try:
+        original_tc = tl.GetCurrentTimecode()
+    except Exception:
+        pass
     original_fc = None
     try:
         original_fc = proj.GetCurrentRenderFormatAndCodec()
@@ -15059,20 +15089,6 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         original_mode = proj.GetCurrentRenderMode()
     except Exception:
         original_mode = None
-    # Rendering pulls Resolve onto the Deliver page and moves the playhead;
-    # measured leaving the user on Deliver at a different frame. Both are ours
-    # to put back.
-    resolve = get_resolve()
-    original_page = None
-    try:
-        original_page = resolve.GetCurrentPage() if resolve else None
-    except Exception:
-        original_page = None
-    original_tc = None
-    try:
-        original_tc = tl.GetCurrentTimecode()
-    except Exception:
-        pass
     # The capture pins the render range to the captured frame, and there is no
     # GetRenderSettings to read the surrounding settings back from (still absent
     # in 21.1). The mark range is the exception: Timeline.GetMarkInOut reports it
@@ -15109,6 +15125,7 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
             original_marks = None
 
     job = None
+    range_pinned = False
     try:
         if original_mode is not None and original_mode != 1:
             if not proj.SetCurrentRenderMode(1):
@@ -15143,6 +15160,7 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                 code="RENDER_SETTINGS_REFUSED", category="api_error",
                 state={"frame": frame},
             )
+        range_pinned = True
         job = proj.AddRenderJob()
         if not job:
             return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
@@ -15213,6 +15231,10 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                     "frame capture could not restore render mode %r: %s",
                     original_mode, mode_exc or "SetCurrentRenderMode returned False",
                 )
+                teardown.append(
+                    f"The render mode was left on single clip (1); restoring {original_mode!r} "
+                    "failed. Put it back with render(action='set_mode')."
+                )
         if original_fc:
             # A failed restore leaves the Deliver page on the capture's format
             # and codec, which the user's next render would silently inherit.
@@ -15230,6 +15252,11 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                     original_fc.get("format"), original_fc.get("codec"),
                     restore_exc or "SetCurrentRenderFormatAndCodec returned False",
                 )
+                teardown.append(
+                    "The render format/codec was left on the capture's "
+                    f"({fmt}); restoring {original_fc.get('format')}/{original_fc.get('codec')} "
+                    "failed, so the next render job would inherit it."
+                )
         # Still not a full restore — GetRenderSettings does not exist, so the
         # other settings cannot be read back. The mark range can: put the user's
         # own range back when they had one, and fall back to the whole timeline
@@ -15237,6 +15264,12 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         # frame for the next render job to inherit.
         # (original_marks is already in SetRenderSettings' absolute space — see
         # the offset above.)
+        #
+        # The range goes in a payload of its own. It used to travel with
+        # CustomName "", and SetRenderSettings refuses an empty CustomName by
+        # rejecting the WHOLE payload (measured on Studio 19.1.3.7: False, and a
+        # job added afterwards still carried MarkIn == MarkOut == the captured
+        # frame). So the range was never put back, and the False was discarded.
         try:
             if original_marks:
                 restored_marks = {
@@ -15250,8 +15283,25 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                     "MarkIn": tl.GetStartFrame(),
                     "MarkOut": tl.GetEndFrame(),
                 }
-            restored_marks["CustomName"] = ""
-            proj.SetRenderSettings(restored_marks)
+            marks_restored = bool(proj.SetRenderSettings(restored_marks))
+            marks_exc = None
+        except Exception as exc:
+            marks_restored, marks_exc = False, exc
+        if not marks_restored:
+            logger.warning(
+                "frame capture could not restore the render range: %s",
+                marks_exc or "SetRenderSettings returned False",
+            )
+            if range_pinned:
+                teardown.append(
+                    f"The render range was left pinned to the captured frame ({frame}); "
+                    "restoring it failed, so the next render job would render one "
+                    "frame. Set the range again before rendering."
+                )
+        # Best effort, and expected to be refused on 19.1.3.7 (see above): where
+        # a build does accept it, the capture's name stops being inherited.
+        try:
+            proj.SetRenderSettings({"CustomName": ""})
         except Exception:
             pass
         try:
@@ -15265,12 +15315,22 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                 os.rmdir(folder)
         except OSError:
             pass
-        _restore_playhead(tl, original_tc, what="the render capture")
+        if not _restore_playhead(tl, original_tc, what="the render capture"):
+            teardown.append(
+                f"The playhead was not put back at {original_tc}. Restore it with "
+                "timeline_markers(action='set_current_timecode')."
+            )
+        # Last, and checked: the render calls pull Resolve onto Deliver. The
+        # switch back is read back, and reported when it does not take.
         if original_page and original_page != "deliver":
-            try:
-                _open_page_serialized(resolve, original_page)
-            except Exception:
-                pass
+            page = _restore_page(resolve, original_page, what="the render capture")
+            if not page["restored"]:
+                teardown.append(
+                    f"Resolve is not back on the {original_page!r} page (it reads "
+                    f"{page['page']!r}): the switch failed after {page['attempts']} "
+                    f"attempt(s) ({page['error']}). Restore it with "
+                    f"resolve_control(action='open_page', params={{'page': {original_page!r}}})."
+                )
 
 
 def _playhead_frame_full(proj, tl, p: Dict[str, Any]):
@@ -15442,19 +15502,22 @@ def _playhead_frame_capture(p: Dict[str, Any]):
                 f"Failed to make {wanted!r} the current timeline",
                 code="SET_TIMELINE_FAILED", category="api_error",
             )
+    # One sentence per restore that did not take. A capture is promised to be a
+    # read, so a restore that failed is part of the answer, not just of the log.
+    teardown: List[str] = []
     try:
         if quality == "thumbnail":
-            return _playhead_frame_preview(tl, p)
-        if quality == "still":
-            return _playhead_frame_full(proj, tl, p)
-        return _playhead_frame_render(proj, tl, p)
+            result = _playhead_frame_preview(tl, p)
+        elif quality == "still":
+            result = _playhead_frame_full(proj, tl, p)
+        else:
+            result = _playhead_frame_render(proj, tl, p, teardown)
     finally:
         if original_tl is not None:
             # Best-effort by necessity: this runs in a finally, so raising or
             # returning here would replace the caller's real result (or its real
-            # exception) with a restore failure. It is still not silent -- a
-            # failed restore leaves the editor on a different timeline, which is
-            # visible immediately, and it is logged.
+            # exception) with a restore failure. It is logged, and reported
+            # alongside the result below.
             restore_err = _set_current_timeline_checked(
                 proj, original_tl, what="restoring the timeline after the capture")
             if restore_err:
@@ -15462,11 +15525,36 @@ def _playhead_frame_capture(p: Dict[str, Any]):
                     "frame capture could not restore the current timeline: %s",
                     restore_err["error"]["message"],
                 )
+                teardown.append(
+                    "The current timeline was not switched back after the capture: "
+                    f"{restore_err['error']['message']}"
+                )
+    return _capture_with_teardown(result, teardown)
+
 
+def _capture_with_teardown(result, teardown: List[str]):
+    """Attach failed restores to a capture result without replacing the capture.
 
-def _restore_playhead(tl, timecode, *, what: str) -> None:
+    An image comes back as [image, {"warnings": [...]}] -- MCP content is a list
+    of blocks anyway, so the frame is still the first block and the warnings
+    follow as text. An error envelope gains a "warnings" key. With nothing to
+    report the result is returned untouched, so a clean capture is exactly what
+    it was before: one image.
+    """
+    if not teardown:
+        return result
+    if isinstance(result, dict):
+        result["warnings"] = list(result.get("warnings") or []) + list(teardown)
+        return result
+    return [result, {"warnings": list(teardown)}]
+
+
+def _restore_playhead(tl, timecode, *, what: str) -> bool:
     """Put the playhead back after a capture. Logged, never raised.
 
+    Returns False when the restore did not take, True otherwise (including when
+    there was no timecode to restore).
+
     Deliberately fire-and-forget on the CALLER's behalf: every use of this runs
     in a `finally`, so raising or returning an error would replace the caller's
     real result -- or its real exception -- with a teardown failure. What it is
@@ -15475,16 +15563,30 @@ def _restore_playhead(tl, timecode, *, what: str) -> None:
     diagnosis and an afternoon.
     """
     if not timecode:
-        return
+        return True
     try:
         moved = tl.SetCurrentTimecode(timecode)
     except Exception as exc:
         logger.warning("could not restore the playhead to %s after %s: %s",
                        timecode, what, exc)
-        return
+        return False
     if not moved:
         logger.warning("could not restore the playhead to %s after %s: "
                        "SetCurrentTimecode returned %r", timecode, what, moved)
+        return False
+    # The return is not the evidence. A True that did not move the playhead has
+    # been observed on Studio 19.1.3.7 (straight after leaving the Deliver
+    # page), so read it back wherever it can be read.
+    try:
+        landed = tl.GetCurrentTimecode()
+    except Exception:
+        return True
+    if isinstance(landed, str) and landed and landed != timecode:
+        logger.warning("could not restore the playhead to %s after %s: "
+                       "SetCurrentTimecode returned True but the playhead reads %s",
+                       timecode, what, landed)
+        return False
+    return True
 
 
 def _set_current_timeline_checked(proj, tl, *, what: str):
@@ -18112,11 +18214,13 @@ def _resolve_restore_state(p: Dict[str, Any]) -> Dict[str, Any]:
 
     # Restore page first so subsequent ops land in the right context
     if state.get("page"):
-        try:
-            r.OpenPage(state["page"])
+        # Reported from a readback, not from having asked: OpenPage's return
+        # used to be discarded and the page listed as restored regardless.
+        page = _restore_page(r, state["page"], what="restore_state")
+        if page["restored"]:
             restored["page"] = state["page"]
-        except Exception as exc:
-            restored["page_error"] = str(exc)
+        else:
+            restored["page_error"] = page["error"]
 
     pm = r.GetProjectManager()
     proj = pm.GetCurrentProject() if pm else None
@@ -21043,7 +21147,10 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
             )
         return {"success": True, "format_id": _format_id, "codec_id": _codec_id}
     elif action == "get_mode":
-        return {"mode": proj.GetCurrentRenderMode()}
+        # The getter itself switches Resolve to the Deliver page (api_truth
+        # 'Project.GetCurrentRenderMode'); a read must not move the user.
+        with _restoring_page(get_resolve(), what="a render-mode read"):
+            return {"mode": proj.GetCurrentRenderMode()}
     elif action == "set_mode":
         return {"success": bool(proj.SetCurrentRenderMode(p["mode"]))}
     elif action == "get_resolutions":
@@ -21102,7 +21209,9 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "probe_render_matrix":
         return _probe_render_matrix(proj, p)
     elif action == "probe_render_settings":
-        return _render_settings_snapshot(proj)
+        # Reads the render mode, which switches to Deliver; see get_mode.
+        with _restoring_page(get_resolve(), what="a render-settings read"):
+            return _render_settings_snapshot(proj)
     elif action == "validate_render_settings":
         return _validate_render_settings_action(p)
     elif action == "safe_set_render_settings":
@@ -26578,6 +26687,7 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
 
     Actions:
       capture(timecode?|frame?, quality?, max_width?, format?, timeline_name?) -> MCP image content
+        (followed by a {"warnings": [...]} block only when a restore failed; see below)
       capabilities() -> {quality_modes, ffmpeg, render_settings_restorable, ...}
 
     capture parameters:
@@ -26599,11 +26709,13 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
     Choosing a quality — the trade-off is accuracy against side effects:
 
       'frame'/'preview'  Frame-exact. Renders one frame, so it changes
-                   project-level render settings. Format and codec are restored;
-                   TargetDir, CustomName and the mark range cannot be read back
-                   on builds without GetRenderSettings, so they are reset to the
-                   full timeline rather than truly restored. Refuses while
-                   another render is running.
+                   project-level render settings. Render mode, format, codec
+                   and the mark range are restored. TargetDir and CustomName
+                   cannot be read back (there is no GetRenderSettings), so they
+                   are NOT restored: they stay on the capture's temporary folder
+                   and name, and capabilities() lists them under
+                   render_settings_restorable. Set your own before the next
+                   render. Refuses while another render is running.
       'thumbnail'  Changes nothing and returns instantly, but it is NOT frame
                    accurate: GetCurrentClipThumbnailImage returns the clip's
                    thumbnail, identical for every frame of that clip (measured
@@ -26614,8 +26726,13 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
                    be open on the Color page — no scripting call can open it,
                    so this fails with a bare refusal when it is closed.
 
-    The playhead, the Color page, the current timeline and the Gallery are all
-    restored; a capture is a read of the picture, not an edit of the cut.
+    The playhead, the page you were on, the current timeline and the Gallery
+    are all restored; a capture is a read of the picture, not an edit of the
+    cut. The render calls pull Resolve onto the Deliver page, so the render
+    route switches back and reads the page to confirm it. If any restore does
+    not take, the image is followed by {"warnings": [...]} naming what was left
+    changed and the call that puts it back (an error result carries the same
+    "warnings" key). No warnings block means every restore was confirmed.
     """
     p = _params(params)
     if action == "capture":
@@ -26634,6 +26751,16 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
             "ffmpeg": bool(shutil.which("ffmpeg")),
             "max_width_supported": bool(shutil.which("ffmpeg")),
             "current_page": current_page,
+            # What the render route ('frame'/'preview') puts back afterwards.
+            # False means left on the capture's own value, because Resolve
+            # offers no way to read the original: there is no GetRenderSettings.
+            "render_settings_restorable": {
+                "render_mode": True,
+                "format_codec": True,
+                "mark_range": True,
+                "TargetDir": False,
+                "CustomName": False,
+            },
         }
         _, tl, err = _get_tl()
         if err:

package/src/utils/api_truth.py

@@ -2653,6 +2653,65 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["render", "deliver", "audio", "unsupported"],
         "submit": "missing",
     },
+    {
+        "symbol": "Project.GetCurrentRenderMode (switches to the Deliver page)",
+        "object": "Project",
+        "signature": "() -> int",
+        "reality": "A getter with a side effect: calling it switches Resolve to "
+                   "the Deliver page. Measured 2026-09-30 on Studio 19.1.3.7 from "
+                   "the Edit, Color and Fairlight pages: GetCurrentPage() read "
+                   "'deliver' immediately afterwards, every time. The other "
+                   "render readers do not do this — GetCurrentRenderFormatAndCodec, "
+                   "GetRenderFormats, GetRenderCodecs, GetRenderResolutions, "
+                   "GetRenderJobList, GetRenderPresetList, IsRenderingInProgress "
+                   "and Timeline.GetMarkInOut all left the page alone in the same "
+                   "run. The render WRITERS all switch: SetCurrentRenderMode, "
+                   "SetCurrentRenderFormatAndCodec, SetRenderSettings, "
+                   "AddRenderJob and StartRendering each moved Edit to Deliver; "
+                   "DeleteRenderJob did not. Nothing switches back on its own. "
+                   "Issue #270 reported the consequence on Studio 21.1.0.17 — a "
+                   "frame capture that left the user on Deliver — but the "
+                   "per-call measurement was not repeated on that build.",
+        "recommended": "Read GetCurrentPage() BEFORE the first render call, not "
+                       "after, and OpenPage back when done. A page read after "
+                       "GetCurrentRenderMode is always 'deliver', which makes a "
+                       "restore look unnecessary — that ordering is how the "
+                       "capture stranded users. "
+                       "src/utils/page_lock.py:restoring_page reads first, "
+                       "restores after, and reads the page back to confirm.",
+        "tags": ["render", "deliver", "page", "side-effect", "getter"],
+        "submit": "bug",
+        "issue": 270,
+        "verified_on": "DaVinci Resolve Studio 19.1.3.7",
+        "mitigation": ["_restoring_page", "_playhead_frame_render"],
+    },
+    {
+        "symbol": "Project.SetRenderSettings (an empty CustomName rejects the whole payload)",
+        "object": "Project",
+        "signature": "({settings}) -> bool",
+        "reality": "SetRenderSettings returns False for {'CustomName': ''} and "
+                   "for {'CustomName': None}, and when that key rides in a larger "
+                   "payload the WHOLE payload is rejected, not just the name. "
+                   "Measured 2026-09-30 on Studio 19.1.3.7: with the render range "
+                   "pinned to one frame, {SelectAllFrames: True, MarkIn: start, "
+                   "MarkOut: end, CustomName: ''} returned False and a job added "
+                   "afterwards still carried MarkIn == MarkOut == the pinned "
+                   "frame; the same payload without CustomName returned True and "
+                   "the job carried the whole timeline. A single space IS "
+                   "accepted, and becomes the file name. So a custom name, once "
+                   "set, cannot be cleared through this API, and there is no "
+                   "GetRenderSettings to read the previous one back from.",
+        "recommended": "Never send an empty CustomName, and never bundle a "
+                       "best-effort key with keys that matter: send the range in "
+                       "its own payload and check its return. To see what a job "
+                       "will inherit, AddRenderJob, read MarkIn/MarkOut/TargetDir/"
+                       "OutputFilename off GetRenderJobList, then DeleteRenderJob.",
+        "tags": ["render", "deliver", "silent-failure", "unreliable-return"],
+        "submit": "bug",
+        "issue": 270,
+        "verified_on": "DaVinci Resolve Studio 19.1.3.7",
+        "mitigation": ["_playhead_frame_render"],
+    },
     {
         "symbol": "ProjectManager.SaveProject",
         "object": "ProjectManager",

package/src/utils/page_lock.py

@@ -19,11 +19,15 @@ Usage:
         resolve.OpenPage("color")
         ... do color-page work, read results ...
 """
+import logging
 import os
 import tempfile
 import threading
+import time
 from contextlib import contextmanager
 
+logger = logging.getLogger("resolve-mcp.page-lock")
+
 try:
     import fcntl  # type: ignore
     _HAS_FCNTL = True
@@ -79,6 +83,98 @@ def open_page_serialized(resolve, page):
         return resolve.OpenPage(page)
 
 
+# A refused page switch has not been measured on any build: on Studio 19.1.3.7
+# OpenPage back to the caller's page took on the first call, straight after a
+# render. The short retry is a hedge against a transient refusal, not a fix for
+# a known one. The readback is the point — it is what turns a switch that did
+# not take into something the caller hears about.
+PAGE_RESTORE_ATTEMPTS = 3
+PAGE_RESTORE_DELAY = 0.25
+
+
+def _read_page(resolve):
+    """The current page as a non-empty string, or None when it cannot be read."""
+    try:
+        page = resolve.GetCurrentPage()
+    except Exception:
+        return None
+    return page if isinstance(page, str) and page else None
+
+
+def restore_page(resolve, page, *, what, attempts=PAGE_RESTORE_ATTEMPTS,
+                 delay=PAGE_RESTORE_DELAY):
+    """Put Resolve back on `page` and PROVE it got there. Logged, never raised.
+
+    Every caller runs this in a `finally`, after the work the user asked for,
+    so a failure here must not replace that work's result — but it must not
+    vanish either. A discarded OpenPage strands the user on a page they did
+    not choose with nothing to say why. The outcome is returned for callers
+    that can pass it on, and a failure is logged for the ones that cannot.
+
+    Already on `page` is a success with zero attempts: nothing is switched.
+
+    Returns {target, restored, page, attempts[, error]}: `page` is the last
+    page read back (None when unreadable), `attempts` the OpenPage calls made.
+    OpenPage's own True is accepted only when GetCurrentPage cannot be read at
+    all; a readable page that is not the target is a failure whatever OpenPage
+    returned.
+    """
+    outcome = {"target": page, "restored": False, "page": None, "attempts": 0}
+    error = None
+    with page_lock():
+        for attempt in range(1, max(1, int(attempts)) + 1):
+            current = _read_page(resolve)
+            if current == page:
+                outcome.update(restored=True, page=current)
+                break
+            try:
+                opened = bool(resolve.OpenPage(page))
+                error = None if opened else "OpenPage returned False"
+            except Exception as exc:
+                opened, error = False, f"OpenPage raised {exc}"
+            outcome["attempts"] = attempt
+            current = _read_page(resolve)
+            outcome["page"] = current
+            if current == page or (opened and current is None):
+                outcome["restored"] = True
+                break
+            if opened:
+                error = f"OpenPage returned True but Resolve is on {current!r}"
+            if attempt < attempts:
+                time.sleep(delay)
+    if not outcome["restored"]:
+        outcome["error"] = error or "OpenPage did not take"
+        logger.warning(
+            "could not restore the %r page after %s: %s (Resolve is on %r, %d attempt(s))",
+            page, what, outcome["error"], outcome["page"], outcome["attempts"],
+        )
+    return outcome
+
+
+@contextmanager
+def restoring_page(resolve, *, what):
+    """Put Resolve back on the page it was on when the block began.
+
+    For calls that move the page as a side effect. Several of the render calls
+    do, and one of them is a getter: measured on Studio 19.1.3.7,
+    Project.GetCurrentRenderMode() leaves Resolve on the Deliver page from
+    Edit, Color and Fairlight alike (api_truth has the full list). Issue #270
+    was that getter running before the page was read, so the page recorded as
+    "where the user was" was already Deliver and nothing was put back.
+
+    The page is read BEFORE the block runs, which is the whole contract. If it
+    cannot be read, nothing is restored, so a skipped restore can never move
+    the user somewhere they were not. Yields the page that will be restored.
+    """
+    original = _read_page(resolve) if resolve is not None else None
+    with page_lock():
+        try:
+            yield original
+        finally:
+            if original:
+                restore_page(resolve, original, what=what)
+
+
 @contextmanager
 def color_page_for_thumbnails(resolve):
     """Hold the Color page for the block, restoring the user's page after.
@@ -109,10 +205,7 @@ def color_page_for_thumbnails(resolve):
             yield on_color
         finally:
             if original and original != "color":
-                try:
-                    resolve.OpenPage(original)
-                except Exception:
-                    pass
+                restore_page(resolve, original, what="a Color-page read")
 
 
 @contextmanager
@@ -159,7 +252,4 @@ def edit_page_for_timeline_edits(resolve):
             # 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
+                restore_page(resolve, original, what="an Edit-page edit")