davinci-resolve-mcp 2.70.3 → 2.71.0

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 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.71.0
+
+Keyed metadata getters honor a list of keys, and `delete_timelines` names the
+parameter it wants. Reported and fixed by @billcarroll in #113, from live
+cataloguing work.
+
+### Keyed getters silently returned everything
+
+Resolve's keyed getters take one string. Handed a list they ignore it and return
+the full dict, so a caller asking for three fields silently received all of them
+with no signal that the request had been dropped — the kind of thing that reads
+as working until someone counts.
+
+`get_metadata`, `get_third_party_metadata` and `get_clip_property` now share a
+`_keyed_get` helper that subsets locally, since there is no batch getter to
+delegate to. An empty or non-string list is a clear error rather than a silent
+superset.
+
+Missing keys deliberately report differently through the two forms: the list
+form maps them to `null`, which separates "absent" from "present but empty"; the
+string form still returns Resolve's `""`. All three actions document both the
+list form and that divergence.
+
+### `delete_timelines` leaked a KeyError
+
+Called with `timeline_names`, or without `timeline_ids` at all, it raised a bare
+`KeyError('timeline_ids')`. It now returns a proper error naming the expected
+parameter, and when `timeline_names` was passed it says explicitly that
+timelines are matched by unique ID rather than by name.
+
+## What's New in v2.70.4
+
+Three silent-failure fixes from community reports, plus the Windows bridge
+follow-ups from #112's live confirmation.
+
+### Thumbnails silently failed off the Color page (#110, @billcarroll)
+
+`Timeline.GetCurrentClipThumbnailImage` returns data only while Resolve is on
+the Color page — Blackmagic's own reference documents it as returning data "for
+current media in the Color Page". `thumbnail_contact_sheet` (and
+`marker_thumbnail_review`, which routes through it) reported "No thumbnail
+available at frame" for every sample from any other page, which reads as an
+empty timeline rather than a page requirement.
+
+A shared `color_page_for_thumbnails` context manager in `page_lock.py` switches
+under the existing page lock and restores the previous page after. The granular
+server's thumbnail tool shares it and gained a real error message in place of a
+bare `{"success": false}`. Where the current page cannot be read, no switch is
+attempted at all, so a skipped restore can never strand the user on Color.
+
+### probe_media_pool truncated silently, and good script runs reported failure (#108, @billcarroll)
+
+`_folder_probe` reported `subfolder_count` from the list it had *expanded*, so
+at the default depth every unexpanded folder looked like an empty leaf. In the
+field, a drive-rename relink sweep trusted `subfolder_count: 0` and skipped
+about 40 populated bins and 573 clips. The count is now the real
+`GetSubFolderList()` length at every level, and folders carry `truncated: true`
+at the cutoff so a walker can descend.
+
+Separately, `fusionscript`'s RemoteApp thread can SIGSEGV during interpreter
+teardown *after* a spawned script has finished its work, turning exit 0 into
+-11 and a successful run into `success: false`. Scripts now run via `runpy` and
+hard-exit before teardown. The guard catches `SystemExit`, so a script ending in
+`sys.exit(0)` cannot reopen the race, and repoints `sys.path[0]` at the script's
+directory — under `-c` it points at the server's cwd, which would break sibling
+imports and let stray files shadow real modules. The cost of `os._exit` (atexit
+handlers skipped, non-daemon threads not joined) is documented on the action.
+
+### Bridge: a dead listener no longer reads as a live one (#112)
+
+`serve()` treated "the serve thread is alive" as "the bridge is serving".
+`serve_forever()` keeps its thread alive, so that is a narrower question than it
+appears, and a bridge was reported lingering with nothing on its port while the
+serve loop kept polling. That divergence is not explained here, but a process
+running with no listener is useless either way, so the exit condition now asks
+the socket directly.
+
+The Win32 prototypes are declared rather than relying on ctypes' default
+int-sized handle. The default is safe by documented contract, but the reporter
+had to derive that from Microsoft's interop documentation to rule out
+truncation; declaring the signatures spares the next reader the exercise.
+
+**The v2.70.3 Windows fix is now confirmed on real hardware.** ZontarLives ran a
+same-machine control: on v2.70.2 the bridge outlived Resolve indefinitely; on
+v2.70.3 it exits 0.23s after. `_process_is_alive` returned `None` for pid 4
+(System), confirming that access-denied reads as unknown rather than death
+against a genuinely protected process.
+
 ## What's New in v2.70.3
 
 The free-edition bridge could never notice Resolve exiting on Windows, so it

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.70.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.71.0-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/SKILL.md

@@ -1339,7 +1339,11 @@ Key actions:
 - `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a
   normalized CDL and/or copy a source grade to multiple video items
 - `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve-rendered
-  thumbnails under the project analysis root for visual verification
+  thumbnails under the project analysis root for visual verification. Resolve
+  only serves these thumbnails on the Color page; the tool switches there
+  automatically and restores the previous page. Expect a page flash in the GUI,
+  and note that landing on Color can kick off cache/render work for the current
+  clip — on a large timeline the switch is not free
 - `edit_kernel_capabilities` — report supported, partially supported, and
   unsupported timeline edit kernel behavior
 - `probe_edit_kernel_item(clip_ids? selected? timeline_item?)` — read-only

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 21 missing capabilities, 20 bugs / unreliable behaviors.
+**Totals:** 22 missing capabilities, 20 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -48,6 +48,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Ask the user to set it in Project Settings > Master Settings > Playback frame rate as a SETUP step, before any timeline exists. Read it back to confirm; do not report it as set on the strength of the call alone.
 - **Tags:** project-settings, silent-failure, timeline
 
+### Timeline.GetCurrentClipThumbnailImage (Color page only)
+
+- **Object:** `Timeline`
+- **Signature:** `() -> {width, height, format, data} | None`
+- **Behavior:** Returns thumbnail data only while Resolve is on the Color page — the reference documents it as returning data 'for current media in the Color Page'. On every other page it silently returns None for every frame, indistinguishable from 'no thumbnail exists', with no error naming the page requirement.
+- **Workaround / current handling:** Switch to the Color page under the page lock before reading and restore the user's page after (src/utils/page_lock.py:color_page_for_thumbnails does exactly this); when the switch fails (headless), name the Color-page requirement in the error instead of reporting a missing thumbnail.
+- **Tags:** timeline, thumbnail, silent-failure, page-dependent
+
 ### Timeline.GetTimelineByName
 
 - **Object:** `Project`

package/install.py

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

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.70.3"
+VERSION = "2.71.0"
 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/timeline.py

@@ -2,6 +2,8 @@
 
 from src.granular.common import *  # noqa: F401,F403
 
+from src.utils.page_lock import color_page_for_thumbnails
+
 resolve = ResolveProxy()
 
 @mcp.resource("resolve://timelines")
@@ -930,6 +932,9 @@ def timeline_get_current_video_item() -> Dict[str, Any]:
 def timeline_get_current_clip_thumbnail(width: int = 320, height: int = 180) -> Dict[str, Any]:
     """Get thumbnail image data for the current clip.
 
+    Switches to the Color page for the read (GetCurrentClipThumbnailImage only
+    returns data there) and restores the previous page after.
+
     Args:
         width: Thumbnail width. Default: 320.
         height: Thumbnail height. Default: 180.
@@ -937,10 +942,19 @@ def timeline_get_current_clip_thumbnail(width: int = 320, height: int = 180) ->
     _, tl, err = _get_timeline()
     if err:
         return err
-    result = tl.GetCurrentClipThumbnailImage()
+    with color_page_for_thumbnails(resolve) as on_color:
+        result = tl.GetCurrentClipThumbnailImage()
     if result:
-        return {"success": True, "has_data": bool(result)}
-    return {"success": False}
+        return {"success": True, "has_data": True}
+    return {
+        "success": False,
+        "error": (
+            "No thumbnail available for the current clip"
+            if on_color
+            else "No thumbnail: GetCurrentClipThumbnailImage requires the "
+            "Color page and automatic switching failed (headless or page locked)"
+        ),
+    }
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.70.3"
+VERSION = "2.71.0"
 
 import base64
 import os
@@ -48,7 +48,11 @@ from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
 from src.utils.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 open_page_serialized as _open_page_serialized
+from src.utils.page_lock import (
+    color_page_for_thumbnails as _color_page_for_thumbnails,
+    open_page_serialized as _open_page_serialized,
+    page_lock as _page_lock,
+)
 from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
 from src.utils.render_ids import (
@@ -5513,32 +5517,42 @@ def _timeline_thumbnail_contact_sheet(proj, tl, p: Dict[str, Any]) -> Dict[str,
         original_timecode = tl.GetCurrentTimecode()
     except Exception:
         pass
+    # GetCurrentClipThumbnailImage only returns data "for current media in the
+    # Color Page" (docs/reference/resolve_scripting_api.txt); on any other page
+    # every frame silently yields None. Switch there for the sampling loop and
+    # restore the user's page afterwards.
     sampled = []
-    try:
-        for sample in samples:
-            timecode, tc_err = _timeline_frame_id_to_timecode(tl, _marker_display_frame(tl, sample["frame"]))
-            if tc_err:
-                sample["error"] = tc_err.get("error")
+    with _color_page_for_thumbnails(get_resolve()) as on_color:
+        try:
+            for sample in samples:
+                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)
+                    continue
+                try:
+                    tl.SetCurrentTimecode(timecode)
+                    thumbnail = tl.GetCurrentClipThumbnailImage()
+                    if not thumbnail:
+                        sample["error"] = (
+                            "No thumbnail available at frame"
+                            if on_color
+                            else "No thumbnail: GetCurrentClipThumbnailImage requires the "
+                            "Color page and automatic switching failed (headless or page locked)"
+                        )
+                    else:
+                        sample["timecode"] = timecode
+                        sample["thumbnail_rgb"] = _thumbnail_raw_rgb(thumbnail)
+                        sample["thumbnail_available"] = True
+                except Exception as exc:
+                    sample["error"] = str(exc)
                 sampled.append(sample)
-                continue
-            try:
-                tl.SetCurrentTimecode(timecode)
-                thumbnail = tl.GetCurrentClipThumbnailImage()
-                if not thumbnail:
-                    sample["error"] = "No thumbnail available at frame"
-                else:
-                    sample["timecode"] = timecode
-                    sample["thumbnail_rgb"] = _thumbnail_raw_rgb(thumbnail)
-                    sample["thumbnail_available"] = True
-            except Exception as exc:
-                sample["error"] = str(exc)
-            sampled.append(sample)
-    finally:
-        if original_timecode:
-            try:
-                tl.SetCurrentTimecode(original_timecode)
-            except Exception:
-                pass
+        finally:
+            if original_timecode:
+                try:
+                    tl.SetCurrentTimecode(original_timecode)
+                except Exception:
+                    pass
     sheet_samples = [sample for sample in sampled if sample.get("thumbnail_rgb")]
     if not sheet_samples:
         return {"success": False, "samples": sampled, "error": "No thumbnails could be sampled"}
@@ -10877,9 +10891,10 @@ def _folder_probe(folder, depth: int = 1):
     clips = []
     for clip in (folder.GetClipList() or []):
         clips.append(_media_pool_item_summary(clip))
+    subs = folder.GetSubFolderList() or []
     subfolders = []
     if depth > 0:
-        for sub in (folder.GetSubFolderList() or []):
+        for sub in subs:
             subfolders.append(_folder_probe(sub, depth - 1))
     stale = None
     try:
@@ -10892,8 +10907,11 @@ def _folder_probe(folder, depth: int = 1):
         "stale": stale,
         "clip_count": len(clips),
         "clips": clips,
-        "subfolder_count": len(subfolders),
+        # True count even below the depth cutoff — reporting len(subfolders)
+        # here made unexpanded folders look like empty leaves.
+        "subfolder_count": len(subs),
         "subfolders": subfolders,
+        "truncated": len(subs) > len(subfolders),
     }
 
 
@@ -16449,6 +16467,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       import_folder(path, source_clips_path?) -> {success}
       ingest_capabilities() -> {supported, partially_supported, unsupported}
       probe_media_pool(depth?) -> {media_pool_id, methods, root, current_folder, selected_clips}
+        depth defaults to 1, max 4. Folders below the cutoff have truncated:true
+        and a real subfolder_count; re-probe deeper or use folder.get_subfolders.
       probe_ingest_item(clip_ids? selected?) -> {items, count}
       safe_import_media(paths, target_folder?, dry_run?) -> {success, imported, clips}
       safe_import_sequence(FilePath|file_path|pattern, StartIndex?, EndIndex?, target_folder?, dry_run?) -> {success, imported, clips}
@@ -16606,11 +16626,18 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
 
         return _run_maybe_background("media_pool.import_timeline", p, _work)
     elif action == "delete_timelines":
+        ids = p.get("timeline_ids")
+        if not isinstance(ids, list) or not ids:
+            hint = (" ('timeline_names' is not supported — timelines are matched"
+                    " by unique ID, e.g. from timeline.get_unique_id)"
+                    if "timeline_names" in p else "")
+            return _err("delete_timelines requires 'timeline_ids', a non-empty"
+                        " list of timeline unique IDs" + hint)
         count = proj.GetTimelineCount()
         timelines = []
         for i in range(1, count + 1):
             tl = proj.GetTimelineByIndex(i)
-            if tl and tl.GetUniqueId() in p["timeline_ids"]:
+            if tl and tl.GetUniqueId() in ids:
                 timelines.append(tl)
         if not timelines:
             return _err("No timelines found")
@@ -16986,6 +17013,22 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
 # TOOL 13: media_pool_item
 # ═══════════════════════════════════════════════════════════════════════════════
 
+def _keyed_get(getter, key):
+    """Resolve's keyed getters take one string key; passed a list they silently
+    ignore it and return the full dict. Subset it ourselves instead.
+
+    Returns (value, error) — exactly one is non-None unless value is legitimately
+    empty."""
+    if isinstance(key, list):
+        if not key or not all(isinstance(k, str) for k in key):
+            return None, _err("'key' must be a string or a non-empty list of strings")
+        full = getter("")
+        if not isinstance(full, dict):
+            full = {}
+        return {k: full.get(k) for k in key}, None
+    return getter(key), None
+
+
 @mcp.tool()
 @_guard_missing_params
 def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -16994,11 +17037,26 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     Actions:
       get_name(clip_id) -> {name}
       get_metadata(clip_id, key?) -> {metadata}
+        — key: one string, or a list of strings to get just that subset.
+          Missing keys: the list form maps them to null (distinguishing
+          absent from empty); the string form passes Resolve's own answer
+          through unchanged, which is "" or null depending on the getter
+          and build (get_clip_property returns null on Studio 19.1.3.7).
       set_metadata(clip_id, key, value) OR set_metadata(clip_id, metadata) -> {success}
       get_third_party_metadata(clip_id, key?) -> {metadata}
+        — key: one string, or a list of strings to get just that subset.
+          Missing keys: the list form maps them to null (distinguishing
+          absent from empty); the string form passes Resolve's own answer
+          through unchanged, which is "" or null depending on the getter
+          and build (get_clip_property returns null on Studio 19.1.3.7).
       set_third_party_metadata(clip_id, key, value) -> {success}
       get_media_id(clip_id) -> {media_id}
       get_clip_property(clip_id, key?) -> {properties}
+        — key: one string, or a list of strings to get just that subset.
+          Missing keys: the list form maps them to null (distinguishing
+          absent from empty); the string form passes Resolve's own answer
+          through unchanged, which is "" or null depending on the getter
+          and build (get_clip_property returns null on Studio 19.1.3.7).
       set_clip_property(clip_id, key, value) -> {success}
       get_clip_color(clip_id) -> {color}
       set_clip_color(clip_id, color) -> {success}
@@ -17160,7 +17218,10 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "get_name":
         return {"name": clip.GetName()}
     elif action == "get_metadata":
-        return {"metadata": _ser(clip.GetMetadata(p.get("key", "")))}
+        value, key_err = _keyed_get(clip.GetMetadata, p.get("key", ""))
+        if key_err:
+            return key_err
+        return {"metadata": _ser(value)}
     elif action == "set_metadata":
         if "metadata" in p:
             ok = bool(clip.SetMetadata(p["metadata"]))
@@ -17176,13 +17237,19 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
                 return silent
         return {"success": ok}
     elif action == "get_third_party_metadata":
-        return {"metadata": _ser(clip.GetThirdPartyMetadata(p.get("key", "")))}
+        value, key_err = _keyed_get(clip.GetThirdPartyMetadata, p.get("key", ""))
+        if key_err:
+            return key_err
+        return {"metadata": _ser(value)}
     elif action == "set_third_party_metadata":
         return {"success": bool(clip.SetThirdPartyMetadata(p["key"], p["value"]))}
     elif action == "get_media_id":
         return {"media_id": clip.GetMediaId()}
     elif action == "get_clip_property":
-        return {"properties": _ser(clip.GetClipProperty(p.get("key", "")))}
+        value, key_err = _keyed_get(clip.GetClipProperty, p.get("key", ""))
+        if key_err:
+            return key_err
+        return {"properties": _ser(value)}
     elif action == "set_clip_property":
         ok = bool(clip.SetClipProperty(p["key"], p["value"]))
         if ok:
@@ -25558,11 +25625,44 @@ def _python_env_for_resolve() -> Dict[str, str]:
     return env
 
 
+# fusionscript's RemoteApp thread keeps dispatching packets from Resolve while
+# the interpreter tears down at exit, and can SIGSEGV *after* the script has
+# finished — turning a successful run into exit code -11 / success:false.
+# Run the script via runpy and hard-exit before teardown so the exit code is
+# truthful. SystemExit must be caught here: uncaught, a plain sys.exit(0) at
+# the end of a script would take the normal teardown path and reopen the
+# segfault window. sys.path[0] is pointed at the script's directory to mimic
+# `python script.py` (under -c it points at the server's cwd, which both
+# breaks sibling imports and lets stray files there shadow real modules).
+# Cost of os._exit: atexit handlers never run and non-daemon threads are not
+# joined — documented in script_plugin's execute action.
+_PY_SCRIPT_EXIT_GUARD = (
+    "import os, runpy, sys, traceback\n"
+    "sys.argv = sys.argv[1:]\n"
+    "sys.path[0] = os.path.dirname(os.path.abspath(sys.argv[0]))\n"
+    "code = 0\n"
+    "try:\n"
+    "    runpy.run_path(sys.argv[0], run_name='__main__')\n"
+    "except SystemExit as e:\n"
+    "    if isinstance(e.code, int):\n"
+    "        code = e.code\n"
+    "    elif e.code is not None:\n"
+    "        print(e.code, file=sys.stderr)\n"
+    "        code = 1\n"
+    "except BaseException:\n"
+    "    traceback.print_exc()\n"
+    "    code = 1\n"
+    "sys.stdout.flush()\n"
+    "sys.stderr.flush()\n"
+    "os._exit(code)\n"
+)
+
+
 def _execute_python_script(path: str, args: List[str],
                             timeout: int) -> Dict[str, Any]:
     # Ensure Resolve is running so the script can connect.
     get_resolve()
-    cmd = [sys.executable, path] + [str(a) for a in args]
+    cmd = [sys.executable, "-c", _PY_SCRIPT_EXIT_GUARD, path] + [str(a) for a in args]
     try:
         result = safe_run(cmd, env=_python_env_for_resolve(),
                           capture_output=True, text=True, timeout=timeout)
@@ -26240,6 +26340,10 @@ def script_plugin(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
         — args: list of CLI args for the Python subprocess (Python only).
         — timeout: seconds (default 120 for execute, 60 for run_inline).
         — Auto-launches Resolve if not running.
+        — Python scripts hard-exit after the script body (guards against
+          fusionscript's segfault-at-exit race), so atexit handlers do not
+          run and non-daemon threads are not joined. Do cleanup inline or
+          in try/finally, not in atexit.
       run_inline(source, language, timeout?) -> {success, stdout?, stderr?, result?}
         — Python: writes to temp file with `resolve`/`project`/`mp`/`timeline`
           pre-bound, runs as subprocess, captures stdout/stderr.

package/src/utils/api_truth.py

@@ -354,6 +354,26 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["fusion", "unreliable-return"],
         "submit": "bug",
     },
+    {
+        "symbol": "Timeline.GetCurrentClipThumbnailImage (Color page only)",
+        "object": "Timeline",
+        "signature": "() -> {width, height, format, data} | None",
+        "reality": "Returns thumbnail data only while Resolve is on the Color "
+                   "page — the reference documents it as returning data 'for "
+                   "current media in the Color Page'. On every other page it "
+                   "silently returns None for every frame, indistinguishable "
+                   "from 'no thumbnail exists', with no error naming the page "
+                   "requirement.",
+        "recommended": "Switch to the Color page under the page lock before "
+                       "reading and restore the user's page after "
+                       "(src/utils/page_lock.py:color_page_for_thumbnails does "
+                       "exactly this); when the switch fails (headless), name "
+                       "the Color-page requirement in the error instead of "
+                       "reporting a missing thumbnail.",
+        "tags": ["timeline", "thumbnail", "silent-failure", "page-dependent"],
+        "submit": "missing",
+        "mitigation": ["color_page_for_thumbnails", "_timeline_thumbnail_contact_sheet"],
+    },
     {
         "symbol": "Timeline.GetTimelineByName",
         "object": "Project",

package/src/utils/page_lock.py

@@ -77,3 +77,39 @@ def open_page_serialized(resolve, page):
     """Switch Resolve to `page` under the page lock. Returns OpenPage's result."""
     with page_lock():
         return resolve.OpenPage(page)
+
+
+@contextmanager
+def color_page_for_thumbnails(resolve):
+    """Hold the Color page for the block, restoring the user's page after.
+
+    GetCurrentClipThumbnailImage returns data only "for current media in the
+    Color Page" (docs/reference/resolve_scripting_api.txt) — on every other
+    page it silently returns None. Yields True when Resolve is on the Color
+    page for the block. 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 Color page.
+
+    Switching to Color is not free in the GUI: besides the visible page flash,
+    Resolve may start cache/render work for the current clip.
+    """
+    original = None
+    try:
+        original = resolve.GetCurrentPage() if resolve else None
+    except Exception:
+        original = None
+    with page_lock():
+        on_color = original == "color"
+        if original and not on_color:
+            try:
+                on_color = bool(resolve.OpenPage("color"))
+            except Exception:
+                pass
+        try:
+            yield on_color
+        finally:
+            if original and original != "color":
+                try:
+                    resolve.OpenPage(original)
+                except Exception:
+                    pass

package/src/utils/resolve_bridge.py

@@ -233,7 +233,7 @@ def _windows_process_name(pid: int) -> str:  # pragma: no cover - exercised on W
         import ctypes
         from ctypes import wintypes
 
-        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel32 = _win_kernel32()
         handle = kernel32.OpenProcess(_WIN_PROCESS_QUERY_LIMITED_INFORMATION, False, int(pid))
         if not handle:
             return ""
@@ -257,6 +257,32 @@ _WIN_WAIT_TIMEOUT = 0x102
 _WIN_ERROR_INVALID_PARAMETER = 87
 
 
+def _win_kernel32():  # pragma: no cover - exercised on Windows
+    """kernel32 with prototypes declared.
+
+    Undeclared, ctypes treats the returned HANDLE as a 32-bit `c_int` while a
+    Win64 HANDLE is 64 bits. That is safe here by documented contract — Windows
+    keeps handle values within 32 bits for 32/64-bit interop, and observed
+    values are in the low thousands — but relying on it silently means the next
+    reader has to re-derive that argument, so declare the signatures instead.
+    """
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    kernel32.WaitForSingleObject.restype = wintypes.DWORD
+    kernel32.QueryFullProcessImageNameW.argtypes = [
+        wintypes.HANDLE, wintypes.DWORD, wintypes.LPWSTR, ctypes.POINTER(wintypes.DWORD)
+    ]
+    kernel32.QueryFullProcessImageNameW.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    return kernel32
+
+
 def _process_is_alive(pid: int) -> Optional[bool]:
     """True / False / None when it genuinely cannot be determined.
 
@@ -270,7 +296,7 @@ def _process_is_alive(pid: int) -> Optional[bool]:
         try:
             import ctypes
 
-            kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            kernel32 = _win_kernel32()
             access = _WIN_SYNCHRONIZE | _WIN_PROCESS_QUERY_LIMITED_INFORMATION
             handle = kernel32.OpenProcess(access, False, int(pid))
             if not handle:
@@ -656,6 +682,24 @@ class Bridge:
     def port(self) -> int:
         return self._server.server_address[1] if self._server else self.config["port"]
 
+    def _listener_is_live(self) -> bool:
+        """Is the socket still open, not merely: is the thread still running?
+
+        `serve_forever()` keeps a thread alive, so `is_alive()` answers a
+        narrower question than it appears to. A bridge was reported lingering
+        with nothing listening on its port while its serve loop kept polling
+        (issue #112) — that combination is unexplained, but a process still
+        running with no listener is useless either way, so the exit condition
+        asks about the socket directly rather than inferring it from the thread.
+        """
+        server = self._server
+        if server is None:
+            return False
+        try:
+            return server.fileno() >= 0
+        except Exception:
+            return False
+
     def serve(self, *, poll_seconds: float = 1.0, host_model: Optional[Dict[str, Any]] = None,
               parent_exited: Optional[Callable[[int, str], bool]] = None) -> Dict[str, Any]:
         """Start, then block or return according to the detected host model.
@@ -684,7 +728,7 @@ class Bridge:
                 if self._stop_event.is_set():
                     reason = self._stop_mode or "exit"
                     break
-                if self._thread is None or not self._thread.is_alive():
+                if self._thread is None or not self._thread.is_alive() or not self._listener_is_live():
                     reason = "listener_died"
                     break
                 if host_exited(expected_parent, expected_name):