davinci-resolve-mcp 2.70.2 → 2.70.4

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 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.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
+orphaned itself and blocked the next session. Reported in issue #112 by
+@ZontarLives, with a self-contained repro.
+
+### The bug
+
+`serve()` detected host exit with a single test:
+
+```python
+if os.getppid() != expected_parent:
+    break
+```
+
+That is a POSIX signal. When a parent dies, POSIX reparents the orphan to init
+and the value changes. **Windows does not reparent** — the parent pid is a
+static field in the process record, so `os.getppid()` returns the dead parent's
+pid forever and the check can never fire.
+
+The consequence is not a cosmetic leak. The orphaned `fuscript.exe` keeps port
+49632 and keeps accepting connections while holding a dead `resolve` handle, so
+the next Resolve session's bridge cannot bind, and the client sees:
+
+```
+bridge_timeout: Resolve did not answer in time - check for an open modal dialog,
+which blocks its scripting API entirely
+```
+
+against a socket that `Get-NetTCPConnection` reports as healthily `LISTENING`.
+Every surface-level check passes and the suggested cause is a red herring, which
+is what made it expensive to diagnose.
+
+### The fix
+
+Liveness is now asked directly instead of inferred from a pid changing:
+
+- `parent_has_exited()` keeps the reparent test as the fast path where it works,
+  then checks whether the parent pid still resolves to a live process, then
+  whether that process still name-matches `PARENT_MARKERS`. The last step also
+  catches pid reuse, which the old check would have misread as "Resolve exited".
+- On Windows liveness comes from `OpenProcess` + `WaitForSingleObject` via
+  `ctypes`. Only "no such process" counts as death: access-denied and every
+  other error are *unknown*, and unknown never ends the session — the module's
+  standing rule is that a bridge which exits early is worse than one that
+  lingers.
+- `_process_name()` gained a Windows branch (`QueryFullProcessImageNameW`). It
+  previously tried `/proc` then `ps`, so it returned an empty string on every
+  Windows machine. `scripts/resolve_bridge_probe.py` gets the same treatment.
+
+Binding failures now name the likely cause and the way out, rather than
+surfacing a bare "address already in use" that sends people to check firewalls.
+
+The Windows branch is injectable so it is tested off Windows — a constant
+`getppid` plus a simulated liveness answer. The platform difference is precisely
+what kept this invisible to everyone developing on macOS or Linux.
+
+### Also confirmed
+
+`%APPDATA%` now joins `%PROGRAMDATA%` as a verified Windows bridge location; the
+#112 report served reads from it against free 21.0.3.7. README and `docs/SKILL.md`
+updated, along with guidance that a bridge which stops answering while
+`LISTENING` is a stale process rather than a modal dialog.
+
+### Also in this release
+
+Two offline guard tests built their "not a temp path" target from `os.getcwd()`,
+which failed — and wrote a real `look.cube` into the working directory — whenever
+the suite ran from a directory under `/tmp`. `tests/_paths.py` makes them
+independent of where the suite runs.
+
 ## What's New in v2.70.2
 
 The control panel could never reach the free edition, even with a perfectly

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.70.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.70.4-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)
@@ -58,10 +58,15 @@ menu. A Lua canary is installed alongside so you can tell that apart from a
 wrong folder.
 
 Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. The Windows paths
-added in v2.70.1 (issue #106) shipped unverified; a report on free 21.0.1.11
-(issue #109) has since shown the bridge installing, listing and serving from
-`%PROGRAMDATA%` on Windows, so that path is now confirmed rather than assumed.
-`%APPDATA%` remains untested. Reports welcome.
+added in v2.70.1 (issue #106) shipped unverified; reports on free 21.0.1.11
+(issue #109) and free 21.0.3.7 (issue #112) have since shown the bridge
+installing, listing and serving from **both** `%PROGRAMDATA%` and `%APPDATA%` on
+Windows 11, so those paths are now confirmed rather than assumed.
+
+Note that the bridge holds its port for as long as it serves. Before v2.70.3 a
+Windows bridge could outlive Resolve and block the next session's listener; if
+you are on an older build and a bridge stops answering, check for a stale
+`fuscript.exe` still holding the port.
 
 This is the documented in-app path, not a licence circumvention, but Blackmagic
 could close it — treat it as a supported-until-it-is-not tier. Loopback only,

package/docs/SKILL.md

@@ -33,11 +33,17 @@ work unchanged. Two things to know when diagnosing it:
   Lua canary, which always lists, so "Python not detected" is distinguishable
   from "wrong folder". The preflight is macOS-only — off macOS Resolve finds
   Python by other means, and running the check there was a false alarm (#106).
-- **Windows: `%PROGRAMDATA%` confirmed, `%APPDATA%` still not.** Both script
-  folders have been targeted since v2.70.1; a free 21.0.1.11 report (#109) has
-  since shown Resolve listing and serving the bridge from `%PROGRAMDATA%`. If a
-  user reports the menu entry missing on Windows, ask whether the Lua canary
-  lists — that separates "wrong folder" from "Python not detected" there too.
+- **Windows: both script folders confirmed.** `%PROGRAMDATA%` (#109) and
+  `%APPDATA%` (#112) have each been shown serving the bridge on Windows 11 free
+  builds. If a user reports the menu entry missing on Windows, ask whether the
+  Lua canary lists — that separates "wrong folder" from "Python not detected".
+- **A bridge that stops answering while its socket is `LISTENING` is a stale
+  process, not a modal dialog.** Before v2.70.3 the Windows bridge could never
+  detect Resolve exiting (`os.getppid()` does not change there), so it outlived
+  Resolve holding the port and answering with a dead handle — and the
+  `bridge_timeout` message blamed a modal dialog. On any build, the way out is
+  the `shutdown` operation (`BridgeClient.bridge_shutdown()`); killing the
+  process is the fallback, not the first move.
 - The **control panel connects over the bridge too** (fixed in v2.70.2). It runs
   as a separate process with its own connector, so a panel that reports "Resolve
   unavailable" while tool calls work is a panel-side bug, not a broken bridge.
@@ -1333,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.2"
+VERSION = "2.70.4"
 # 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.2",
+  "version": "2.70.4",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/resolve_bridge_probe.py

@@ -35,6 +35,26 @@ PARENT_MARKERS = ("resolve", "fuscript", "fusion")
 
 def process_name(pid):
     """Best-effort process name; empty string when it cannot be read."""
+    if os.name == "nt":
+        # Windows has neither /proc nor ps, so the probe reported an empty
+        # parent name on every Windows machine (issue #112).
+        try:
+            import ctypes
+
+            kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            handle = kernel32.OpenProcess(0x1000, False, int(pid))
+            if not handle:
+                return ""
+            try:
+                size = ctypes.c_ulong(260)
+                buf = ctypes.create_unicode_buffer(size.value)
+                if not kernel32.QueryFullProcessImageNameW(handle, 0, buf, ctypes.byref(size)):
+                    return ""
+                return os.path.basename(buf.value)
+            finally:
+                kernel32.CloseHandle(handle)
+        except Exception:
+            return ""
     try:  # Linux
         with open("/proc/%d/comm" % pid) as handle:
             return handle.read().strip()

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.70.2"
+VERSION = "2.70.4"
 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.2"
+VERSION = "2.70.4"
 
 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}
@@ -25558,11 +25578,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 +26293,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

@@ -204,6 +204,8 @@ def _host_model(
 
 def _process_name(pid: int) -> str:
     """Best-effort process name; empty string when it cannot be read."""
+    if os.name == "nt":
+        return _windows_process_name(pid)
     try:  # Linux
         with open(f"/proc/{pid}/comm", "r", encoding="utf-8") as handle:
             return handle.read().strip()
@@ -221,6 +223,152 @@ def _process_name(pid: int) -> str:
         return ""
 
 
+def _windows_process_name(pid: int) -> str:  # pragma: no cover - exercised on Windows
+    """Image name for a pid via Win32, or "" when it cannot be read.
+
+    ctypes rather than `tasklist`: the bridge polls this, and spawning a console
+    process every second inside Resolve is both slow and visible.
+    """
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        kernel32 = _win_kernel32()
+        handle = kernel32.OpenProcess(_WIN_PROCESS_QUERY_LIMITED_INFORMATION, False, int(pid))
+        if not handle:
+            return ""
+        try:
+            size = wintypes.DWORD(260)
+            buf = ctypes.create_unicode_buffer(size.value)
+            if not kernel32.QueryFullProcessImageNameW(handle, 0, buf, ctypes.byref(size)):
+                return ""
+            return os.path.basename(buf.value)
+        finally:
+            kernel32.CloseHandle(handle)
+    except Exception:
+        return ""
+
+
+# Win32 constants used for parent-liveness detection.
+_WIN_PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+_WIN_SYNCHRONIZE = 0x00100000
+_WIN_WAIT_OBJECT_0 = 0x0
+_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.
+
+    `None` matters: this module's standing rule is that a bridge which exits
+    early is worse than one that lingers, so an undeterminable answer must not
+    be allowed to read as "the parent died".
+    """
+    if not pid or pid <= 0:
+        return None
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        try:
+            import ctypes
+
+            kernel32 = _win_kernel32()
+            access = _WIN_SYNCHRONIZE | _WIN_PROCESS_QUERY_LIMITED_INFORMATION
+            handle = kernel32.OpenProcess(access, False, int(pid))
+            if not handle:
+                # Only "no such process" is proof of death. Access-denied and
+                # everything else are unknown — a bridge must not quit because
+                # it could not open a handle.
+                return False if ctypes.get_last_error() == _WIN_ERROR_INVALID_PARAMETER else None
+            try:
+                status = kernel32.WaitForSingleObject(handle, 0)
+                if status == _WIN_WAIT_OBJECT_0:
+                    return False  # signalled == exited
+                if status == _WIN_WAIT_TIMEOUT:
+                    return True
+                return None
+            finally:
+                kernel32.CloseHandle(handle)
+        except Exception:
+            return None
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, owned by someone else
+    except OSError:
+        return None
+
+
+def parent_has_exited(expected_pid: int, expected_name: str = "",
+                      *, getppid: Callable[[], int] = os.getppid,
+                      is_alive: Callable[[int], Optional[bool]] = _process_is_alive,
+                      name_of: Callable[[int], str] = _process_name) -> bool:
+    """Has the Resolve that launched this script gone away?
+
+    `os.getppid() != expected_pid` is the POSIX signal — an orphan is reparented
+    to init, so the value changes. **Windows does not reparent.** The parent pid
+    is a static field in the process record, so `getppid()` returns the dead
+    parent's pid forever and a check written that way can never fire: the bridge
+    outlives Resolve, keeps its port, and answers with a dead handle. The next
+    session's bridge then cannot bind, and the client sees a timeout against a
+    socket that is `LISTENING` — every surface-level check passes (issue #112).
+
+    So liveness is asked directly, and reparenting is kept as the fast path
+    where it works. The name check additionally catches pid reuse, which the
+    reparent test would misread as "Resolve exited".
+
+    Unknown liveness is never treated as death, per the module's standing rule.
+    """
+    try:
+        if getppid() != expected_pid:
+            return True
+    except Exception:  # pragma: no cover - defensive
+        pass
+    alive = is_alive(expected_pid)
+    if alive is False:
+        return True
+    if alive is None:
+        return False
+    # Pid reuse: the number is alive but now belongs to something else. Only
+    # usable when the ORIGINAL name looked like Resolve — otherwise there is no
+    # baseline to have drifted from. `_host_model` documents that the parent
+    # name is routinely empty or non-matching under the App Store sandbox, where
+    # `ps` on another process is blocked; treating that as death would kill the
+    # bridge on its first poll, on the exact edition it exists for.
+    if expected_name and any(m in expected_name.lower() for m in PARENT_MARKERS):
+        current = (name_of(expected_pid) or "").lower()
+        if current and not any(marker in current for marker in PARENT_MARKERS):
+            return True
+    return False
+
+
 def probe_host_model() -> Dict[str, Any]:
     """Report the host model without starting a listener.
 
@@ -502,7 +650,23 @@ class Bridge:
         return held == MAX_CONCURRENT_CONNECTIONS
 
     def start(self) -> "Bridge":
-        self._server = _Server((self.config["host"], self.config["port"]), self)
+        host, port = self.config["host"], self.config["port"]
+        try:
+            self._server = _Server((host, port), self)
+        except OSError as exc:
+            # An orphaned bridge from a previous session is the likely cause,
+            # and a bare "address already in use" sends people looking at
+            # firewalls. Say what is actually holding the port and how to clear
+            # it — the alternative is a LISTENING socket answering with a dead
+            # Resolve handle, which reads as a broken install (issue #112).
+            raise BridgeConfigError(
+                f"cannot listen on {host}:{port} — {exc}. Another bridge is probably still "
+                "running from an earlier Resolve session. Ask it to stop (send the `shutdown` "
+                "operation, or `resolve_bridge_client.BridgeClient(...).bridge_shutdown()`), or "
+                "end the stale process: Windows `Get-NetTCPConnection -LocalPort "
+                f"{port} | Select-Object OwningProcess` then `Stop-Process -Id <pid>`; "
+                f"macOS/Linux `lsof -ti tcp:{port} | xargs kill`."
+            ) from exc
         self._thread = threading.Thread(target=self._server.serve_forever, name="ResolveBridge", daemon=True)
         self._thread.start()
         return self
@@ -518,7 +682,26 @@ class Bridge:
     def port(self) -> int:
         return self._server.server_address[1] if self._server else self.config["port"]
 
-    def serve(self, *, poll_seconds: float = 1.0, host_model: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    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.
 
         Returns immediately in-process (the caller keeps a reference alive);
@@ -535,16 +718,20 @@ class Bridge:
             model["stop_reason"] = None
             return model
         expected_parent = model["parent_pid"]
+        expected_name = model.get("parent_name") or ""
+        # Injectable so the Windows branch is testable off Windows — the bug
+        # this replaced was invisible on the maintainer's platform.
+        host_exited = parent_exited or parent_has_exited
         reason = "resolve_exited"
         try:
             while True:
                 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 os.getppid() != expected_parent:
+                if host_exited(expected_parent, expected_name):
                     break
                 # Waiting on the event rather than joining the thread makes a
                 # requested stop immediate instead of up to `poll_seconds` late.