davinci-resolve-mcp 2.98.3 → 2.98.5

package/CHANGELOG.md

@@ -2,6 +2,134 @@
 
 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.98.5
+
+**Every Fusion parameter this server wrote was ignored at render.** A value
+write (`SetInput` / `SetExpression`) wrapped in `Comp.Lock()`/`Unlock()` is
+stored in the graph and reads back correctly — `GetInput` returns it, and so
+did this server's own `get_input` — while the delivered render ignores it
+completely. Found on 2026-08-21 while re-running a Fusion isolation on Studio
+19.1.3.7 to settle a conflicting measurement reported in
+[#156](https://github.com/samuelgursky/davinci-resolve-mcp/pull/156).
+
+Measured on Studio 19.1.3.7 with `MediaIn -> Blur(XBlurSize 20) -> MediaOut` on
+a media-backed clip, rendering the same 48 frames to H.264 each time:
+
+| value written via | render vs no-comp baseline |
+| --- | --- |
+| `fusion_comp set_input` (write inside `Comp.Lock()`) | PSNR **inf** — bit-identical, ignored |
+| the same write, lock removed | PSNR **24.38 dB**, 2.0 MB → 727 KB |
+| raw `tool.XBlurSize = 20.0` | PSNR **24.38 dB** |
+| raw `tool.SetInput("XBlurSize", 20)` | PSNR **24.38 dB** |
+
+The variable was isolated against the comp handle (`AddFusionComp`,
+`GetFusionCompByIndex` and `GetFusionCompByName` all render), the node name, and
+the write form. Only the lock around the write decides it. **Structural** edits
+are unaffected — `AddTool` and `ConnectInput` inside a lock render normally — so
+this is not "Lock is unsafe"; the lock suppresses the parameter-change
+invalidation that a value write depends on.
+
+### Fixed
+
+- **Six value-write sites no longer hold a comp lock across the write:**
+  `fusion_comp set_input`, `fusion_comp safe_set_inputs`, `bulk_set_inputs`,
+  `bulk_set_expressions`, the Text+ writer behind `set_text`, and
+  `add_mask` — where the lock spanned `AddTool` *and* every input write, so a
+  mask was created at default size and position and every parameter the caller
+  passed did nothing. Structural work keeps its lock; in `add_mask` the lock now
+  closes after the node is created and renamed.
+
+### Why this went unnoticed
+
+Every readback the API offers agreed with the value that was written. This is
+the failure mode the repo's own guidance describes — prove a Fusion or grade
+claim with a rendered frame, never with readback — except the cause was ours,
+not Resolve's. It also explains an unknown share of past "the comp was ignored"
+reports, which look identical from the API side.
+
+### Tests
+
+- `tests/live_fusion_value_write_validation.py` — renders a baseline, writes a
+  blur size through the compound tool, renders again, and asserts PSNR actually
+  moved. Disposable project, synthetic media, restores the previous project.
+- `tests/test_fusion_value_write_lock.py` — AST guard failing any value write
+  that sits inside a `Comp.Lock()`/`Unlock()` region, with a self-check that the
+  guard can still see a known-bad shape.
+
+Both were mutation-checked against the pre-fix code: reintroducing the lock in
+`set_input` makes the live harness report `PSNR inf -> IGNORED at render` and
+fails the offline guard.
+
+- `api_truth`: new `Composition.Lock` entry; the `AddFusionComp` entry records
+  that its 2026-08-02 rooted-comp result **reproduced** on 19.1.3.7 (PSNR 24.38 dB).
+
+## What's New in v2.98.4
+
+**Setup reported success over an install that could never work.** Reported and
+fixed in [#154](https://github.com/samuelgursky/davinci-resolve-mcp/pull/154) by
+@DadManBlues, from a DaVinci Resolve Studio 21.0.4 install on `F:\Blackmagic
+Design\DaVinci Resolve` (Windows 11). The chain: `RESOLVE_PATHS["Windows"]["lib"]`
+held a single hardcoded `C:\Program Files\...` candidate, so `find_resolve_paths()`
+returned `lib_path=None`; `build_server_env()` wrote that out as
+`"RESOLVE_SCRIPT_LIB": ""`, which reads as configured in the config file but is
+falsy to the loader, so it fell back to the same missing path; the connection
+check then failed with `DLL load failed` in the middle of the output, and the
+installer's last line said `Setup complete!`. Every tool afterwards failed with
+`SCRIPTING_UNAVAILABLE`, whose remediation pointed at the Resolve edition and the
+External-scripting preference — both already correct.
+
+### Fixed
+
+- **Resolve is now found outside the default install location.**
+  `resolve_runtime.running_resolve_lib()` derives the scripting library from the
+  running Resolve's own image path, which needs no guessing on any platform, and
+  `platform.discover_scripting_lib()` covers cold installs: `%PROGRAMFILES%` /
+  `%PROGRAMW6432%` / `%PROGRAMFILES(X86)%` plus the existing drive letters on
+  Windows (two fixed paths each, no directory walk), both bundle locations on
+  macOS — the App Store build installs to `/Applications/DaVinci Resolve.app`
+  rather than `/Applications/DaVinci Resolve/DaVinci Resolve.app`, the same class
+  of miss — and the `/opt/resolve` layouts on Linux. Discovery runs only when the
+  platform default is absent and no usable env override exists, and the default
+  is kept when discovery finds nothing, so the error message still names the
+  location people expect.
+- **Empty environment values are omitted rather than written.**
+  `build_server_env()` no longer emits `"RESOLVE_SCRIPT_LIB": ""`.
+- **A failed verification is no longer reported as success.** The `Library: Not
+  found (optional — API path is sufficient)` line was wrong and is corrected; a
+  DLL-load failure is diagnosed explicitly, naming the current
+  `RESOLVE_SCRIPT_LIB`, before the Python 3.13+ ABI theory; and setup ends in
+  `Setup incomplete — the scripting API did not load.`, still listing any configs
+  it wrote and marking them non-functional.
+
+### Fixed in follow-up review
+
+- **The no-clients branch still printed `Environment ready!`** over a failed
+  verification, and **`main()` returned `None` either way**, so
+  `npx davinci-resolve-mcp setup` in a script or CI saw exit status 0 over a dead
+  install — the same lie as `Setup complete!`, one block further down. The
+  summary line and the exit status now agree.
+- **Two bare `except Exception` fallbacks narrowed to `ImportError`.** A defect
+  raised inside `running_resolve_lib()` or `discover_scripting_lib()` would have
+  been laundered into "nothing found" and the caller would have gone on to report
+  the platform default — this repo's recurring silent-fallback bug class.
+- **`_windows_lib_candidates` docstring corrected.** It claimed only fixed drives
+  are probed (there is no `GetDriveTypeW` check, so a connected network drive is
+  probed too) and that it runs on every connection attempt (`get_resolve_paths()`
+  is import-time, so the real cost is one `ps`/`wmic` spawn at server startup, and
+  only when the default is already missing).
+
+### Tests
+
+`tests/test_scripting_lib_discovery.py` (21 cases): library derivation on Windows
+and macOS layouts, WMIC-quoted command lines, the three `None` paths, the
+per-platform candidate lists, override-beats-discovery precedence, the surviving
+platform default, the omitted empty key, both reporting behaviours, and the exit
+status in all three of its states. The `GetResolvePathsDiscoveryTests` cases force
+the platform default absent — without that they check nothing on a machine where
+Resolve *is* at the default path, and on macOS they fail outright; neither the
+Linux CI box nor the Windows machine that prompted the fix shows it, because on
+both the default is already missing for real.
+
 ## What's New in v2.98.3
 
 **`fusion_comp` could never delete a Fusion keyframe.** Reported in

package/README.md

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

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -1690,6 +1690,17 @@ Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, o
 `timeline_item={track_type, track_index, item_index}`) or from the active Fusion
 page comp (omit timeline scope).
 
+READBACK IS NOT PROOF FOR FUSION PARAMETERS. Up to v2.98.4 every value write
+here ran inside a `Comp.Lock()`, and a value written under a comp lock is stored
+in the graph and returned by `get_input` while the RENDER ignores it entirely
+(Studio 19.1.3.7: PSNR inf vs the no-comp baseline — the delivered file was
+bit-identical to no comp at all). Fixed in v2.98.5, and guarded by
+`tests/test_fusion_value_write_lock.py` plus the rendered-frame harness
+`tests/live_fusion_value_write_validation.py`. The lesson outlives the bug: a
+Fusion parameter that reads back correctly has proven nothing about the output,
+so confirm any Fusion look with a rendered frame (`gallery_stills
+grab_and_export` or a frame from a delivered render), never with `get_input`.
+
 Key actions:
 - `add_tool(tool_type, x?, y?, name?)` — common types: `Merge`, `Background`,
   `TextPlus`, `Transform`, `Blur`, `ColorCorrector`, `RectangleMask`,

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 27 missing capabilities, 35 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 36 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -339,10 +339,18 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Author OTIO for Resolve by mirroring what Resolve itself exports, and give every event its media timecode origin. editorial.convert_to_interchange (target 'otio') does this and reports any event whose origin had to be assumed in `mediaOriginAssumed` — a non-empty list means the file will only import if that media really starts at 00:00:00:00. To debug a refusal, export any timeline with EXPORT_OTIO and diff your document against it; do NOT chase missing media or reach for sanitize_media, which cannot even parse a .otio (it is JSON, not XML).
 - **Tags:** timeline, import, interchange, otio, silent-failure, conform
 
+### Composition.Lock (suppresses render invalidation for value writes)
+
+- **Object:** `Composition (Fusion, via TimelineItem comps)`
+- **Signature:** `Lock() / Unlock()`
+- **Behavior:** A value write performed between Comp.Lock() and Comp.Unlock() — SetInput(), or Input.SetExpression() — is stored in the graph and reads back correctly from GetInput(), but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code.
+- **Workaround / current handling:** Never hold a comp lock across a value write. Lock only structural work (AddTool/ConnectInput) and set inputs outside it. Because every readback the API offers agrees with the value that was written, this failure is invisible without a render — prove Fusion parameter changes with a delivered frame or gallery_stills grab_and_export, never with GetInput.
+- **Tags:** fusion, silent-failure, render, readback
+
 ### TimelineItem.AddFusionComp / LoadFusionCompByName
 
 - **Object:** `TimelineItem (media-backed clip)`
-- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally.
+- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side.
 - **Workaround / current handling:** Wire the graph so MediaOut descends from MediaIn — that is the difference between a comp that renders and one that is silently bypassed, and it is what made this look like 'Fusion never renders from the API'. Never leave a tool unrooted: a MediaOut fed by a tool with no source failed the render job outright. For text or effects over picture, insert a Fusion title/generator as its own timeline clip and set its Text+ (fusion_comp set_text_plus), rather than attaching a comp to the media clip. Note the destination track cannot be chosen from the API (see the Track Selector entry), so overlaying onto an existing clip's track is not currently reachable end-to-end. Building the comp in the Fusion page UI works; only the API-created comp is ignored.
 - **Tags:** fusion, silent-failure, render
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.98.3"
+VERSION = "2.98.5"
 # 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
@@ -284,6 +284,24 @@ def find_resolve_paths():
             lib_path = expanded
             break
 
+    if lib_path is None:
+        # The literal candidates above only cover a default install. An explicit
+        # override wins outright; failing that, ask where Resolve actually is.
+        # Skipping this is what wrote an empty RESOLVE_SCRIPT_LIB into working
+        # configs and left the server importing a DLL that was never there.
+        env_lib = os.environ.get("RESOLVE_SCRIPT_LIB")
+        if env_lib and os.path.isfile(env_lib):
+            lib_path = env_lib
+        else:
+            # Narrow except: an ImportError here means the helper is absent,
+            # which is a real answer. Anything else raised *inside* discovery is
+            # a defect and must not be laundered into "no library found".
+            try:
+                from src.utils.platform import discover_scripting_lib
+            except ImportError:
+                discover_scripting_lib = None
+            lib_path = discover_scripting_lib() if discover_scripting_lib else None
+
     return api_path, lib_path
 
 
@@ -520,7 +538,14 @@ def get_python_base_install(python_path):
 
 
 def build_server_env(python_path, api_path, lib_path, system=SYSTEM, python_home=None):
-    """Build the env block used by all generated stdio MCP configs."""
+    """Build the env block used by all generated stdio MCP configs.
+
+    Keys whose value is empty are omitted rather than written as "". An empty
+    `RESOLVE_SCRIPT_LIB` is worse than an absent one: it reads as configured in
+    the config file, while `DaVinciResolveScript.py` treats it as unset and
+    silently reverts to its own hardcoded install path — so a machine with
+    Resolve elsewhere fails with a DLL-load error that names nothing useful.
+    """
     api_value = str(api_path or "")
     lib_value = str(lib_path or "")
     env = {
@@ -528,6 +553,7 @@ def build_server_env(python_path, api_path, lib_path, system=SYSTEM, python_home
         "RESOLVE_SCRIPT_LIB": lib_value,
         "PYTHONPATH": str(Path(api_value) / "Modules") if api_value else "",
     }
+    env = {key: value for key, value in env.items() if value}
 
     if system == "Windows":
         env["PYTHONHOME"] = str(python_home or get_python_base_install(python_path))
@@ -1921,7 +1947,13 @@ def main():
     if lib_path:
         print(f"  Library:   {green(lib_path)}")
     else:
-        print(f"  Library:   {yellow('Not found')} {dim('(optional — API path is sufficient)')}")
+        # Not optional, whatever this line used to claim: DaVinciResolveScript
+        # is a thin wrapper that loads this binary, so without it every tool
+        # fails at import. Saying "API path is sufficient" here sent people
+        # looking at their Resolve edition and their preferences instead.
+        print(f"  Library:   {red('Not found')} {dim('(required — the scripting API cannot load without it)')}")
+        print(f"  {dim('Set RESOLVE_SCRIPT_LIB to the fusionscript library inside your Resolve install,')}")
+        print(f"  {dim('or start Resolve and re-run setup so its location can be read from the process.')}")
 
     resolve_running = check_resolve_running()
     if resolve_running:
@@ -2122,6 +2154,7 @@ def main():
     if interactive:
         print_step(5, total_steps, "Verification")
 
+    verification_failed = False
     if api_path:
         success, message = verify_resolve_connection(python_path, api_path, lib_path)
         try:
@@ -2171,13 +2204,28 @@ def main():
             else:
                 print(f"  Connected: {green(message)}")
         else:
-            print(f"  Verify:    {yellow(message)}")
+            verification_failed = True
+            print(f"  Verify:    {red(message)}")
+            if "DLL load failed" in message or "cannot open shared object" in message:
+                # This is the shape of a wrong or missing library path, and it
+                # is the one failure the installer can diagnose precisely. Say
+                # so before offering the interpreter theory below — a reader who
+                # is told "try another Python" first will go and do that.
+                print(
+                    f"             The scripting library named by RESOLVE_SCRIPT_LIB did not load. "
+                    f"Current value: {lib_path or dim('(not set)')}"
+                )
+                print(
+                    "             Point RESOLVE_SCRIPT_LIB at the fusionscript library inside your "
+                    "Resolve install, or start Resolve and re-run setup."
+                )
             if py_abi_risk:
                 print(
                     f"             On Python 3.13+ this may be an ABI mismatch with Resolve's "
                     f"scripting library — try Python 3.10-3.12 if it persists."
                 )
     else:
+        verification_failed = True
         print(f"  {yellow('Skipped')} — Resolve API path not detected")
 
     # ══════════════════════════════════════════════════════════════════════
@@ -2185,7 +2233,25 @@ def main():
     # ══════════════════════════════════════════════════════════════════════
 
     print(f"\n  {'═' * 50}")
-    if configured or show_manual:
+    if verification_failed and (configured or show_manual):
+        # Writing the configs is not the job; a working connection is. Reporting
+        # "Setup complete!" over a failed verification is how an install that
+        # never worked gets handed to the user as finished — the error scrolls
+        # past mid-output and the last line says success.
+        print(f"  {yellow(bold('Setup incomplete — the scripting API did not load.'))}")
+        if configured:
+            print(f"  Configured: {', '.join(configured)} {dim('(written, but the server will fail to start)')}")
+        print()
+        print(f"  {bold('Fix the verification error above, then re-run:')}")
+        print(f"    {cyan('python install.py')}")
+        print()
+        print(f"  {dim(f'Server: {server_path}')}")
+        print(f"  {dim(f'Python: {python_path}')}")
+        if api_path:
+            print(f"  {dim(f'API:    {api_path}')}")
+        if lib_path:
+            print(f"  {dim(f'Library: {lib_path}')}")
+    elif configured or show_manual:
         print(f"  {green(bold('Setup complete!'))}")
         if configured:
             print(f"  Configured: {', '.join(configured)}")
@@ -2204,18 +2270,32 @@ def main():
         if api_path:
             print(f"  {dim(f'API:    {api_path}')}")
     elif not selected_ids:
-        print(f"  {green(bold('Environment ready!'))}")
-        print(f"  Run {cyan('python install.py --clients all')} to configure MCP clients later.")
+        # Same rule as the configured branch above: a failed verification is
+        # never "ready". Nothing was written here, so the remedy is the error
+        # itself rather than a re-run to fix a config.
+        if verification_failed:
+            print(f"  {yellow(bold('Environment incomplete — the scripting API did not load.'))}")
+            print(f"  {dim('No client configs were written.')}")
+            print()
+            print(f"  {bold('Fix the verification error above, then re-run:')}")
+            print(f"    {cyan('python install.py')}")
+        else:
+            print(f"  {green(bold('Environment ready!'))}")
+            print(f"  Run {cyan('python install.py --clients all')} to configure MCP clients later.")
     else:
         print(f"  {yellow('No clients configured.')}")
         print(f"  Run {cyan('python install.py')} again to retry.")
 
     print()
+    # Exit status has to agree with the summary line above. `npx
+    # davinci-resolve-mcp setup` is run from scripts and CI, where a zero over a
+    # dead install is the same lie as "Setup complete!" was.
+    return 1 if verification_failed else 0
 
 
 if __name__ == "__main__":
     try:
-        main()
+        sys.exit(main() or 0)
     except KeyboardInterrupt:
         print(f"\n\n  {dim('Interrupted.')}\n")
         sys.exit(1)

package/package.json

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

package/src/granular/common.py

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

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.98.3"
+VERSION = "2.98.5"
 
 import base64
 import os
@@ -25841,6 +25841,35 @@ def _fusion_group_settings_splice_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+# Why no comp.Lock() around Fusion VALUE writes.
+#
+# Wrapping a value write (SetInput / SetExpression) in comp.Lock()/Unlock()
+# leaves the value fully readable — GetInput returns it, and so does this
+# server's own get_input — while the RENDER ignores it entirely. Measured live
+# on Studio 19.1.3.7 with a MediaIn -> Blur(XBlurSize 20) -> MediaOut comp on a
+# media-backed clip: identical graph, identical readback, delivered render
+# bit-identical to the no-comp baseline (ffmpeg PSNR inf). Removing the lock
+# from the write renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB,
+# as a blur should. The variable was isolated against the comp handle
+# (AddFusionComp / GetFusionCompByIndex / GetFusionCompByName all render), the
+# node name, and the write form (attribute assignment and SetInput both render
+# unlocked) — only the lock around the write decides it.
+#
+# STRUCTURAL edits are a different case and KEEP their lock: AddTool,
+# ConnectInput and friends invalidate the render through another path and were
+# verified to render while locked. So this is not "Lock is unsafe", it is
+# "Lock suppresses the parameter-change invalidation that a value write needs".
+#
+# This is why grade/Fusion claims are proven with a rendered frame and never
+# with comp readback: every readback the API offers agreed the value was set.
+_FUSION_VALUE_WRITE_NOTE = (
+    "Fusion value writes (SetInput/SetExpression) must not be wrapped in "
+    "comp.Lock()/Unlock(): the value reads back correctly but is ignored at "
+    "render (Studio 19.1.3.7, PSNR inf vs baseline). Structural edits "
+    "(AddTool/ConnectInput) are unaffected and keep their lock."
+)
+
+
 def _fusion_group_settings_load(comp, p: Dict[str, Any]) -> Dict[str, Any]:
     group_name = p.get("group_name")
     if not group_name:
@@ -25946,16 +25975,13 @@ def _fusion_comp_bulk_set_expressions(p: Dict[str, Any]) -> Dict[str, Any]:
                 undo_started = True
             except Exception:
                 undo_started = False
-            comp.Lock()
-            try:
-                time = op.get("time", 0)
-                inp = tool[op["input_name"]]
-                if not inp:
-                    raise ValueError(f"Input {op['input_name']!r} not found on {op['tool_name']!r}")
-                inp.SetExpression(str(op["expression"]), time)
-                keep_undo = True
-            finally:
-                comp.Unlock()
+            # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+            time = op.get("time", 0)
+            inp = tool[op["input_name"]]
+            if not inp:
+                raise ValueError(f"Input {op['input_name']!r} not found on {op['tool_name']!r}")
+            inp.SetExpression(str(op["expression"]), time)
+            keep_undo = True
         except Exception as exc:
             error_message = str(exc)
         finally:
@@ -26074,15 +26100,12 @@ def _fusion_comp_bulk_set_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
                 undo_started = True
             except Exception:
                 undo_started = False
-            comp.Lock()
-            try:
-                if "time" in op:
-                    tool.SetInput(op["input_name"], op["value"], op["time"])
-                else:
-                    tool.SetInput(op["input_name"], op["value"])
-                keep_undo = True
-            finally:
-                comp.Unlock()
+            # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+            if "time" in op:
+                tool.SetInput(op["input_name"], op["value"], op["time"])
+            else:
+                tool.SetInput(op["input_name"], op["value"])
+            keep_undo = True
         except Exception as exc:
             error_message = str(exc)
         finally:
@@ -26255,25 +26278,22 @@ def _safe_set_fusion_inputs(comp, p: Dict[str, Any]):
     if p.get("dry_run"):
         return _ok(tool_name=tool_name, inputs=inputs, would_set=True)
     results = {}
-    comp.Lock()
-    try:
-        for input_name, value in inputs.items():
-            try:
-                if "time" in p:
-                    tool.SetInput(input_name, value, p["time"])
-                else:
-                    tool.SetInput(input_name, value)
-                row = {"success": True}
-                if p.get("readback", True):
-                    try:
-                        row["value"] = _ser(tool.GetInput(input_name, p["time"])) if "time" in p else _ser(tool.GetInput(input_name))
-                    except Exception as exc:
-                        row["readback_error"] = str(exc)
-                results[input_name] = row
-            except Exception as exc:
-                results[input_name] = {"success": False, "error": str(exc)}
-    finally:
-        comp.Unlock()
+    # No comp.Lock() around value writes — see _FUSION_VALUE_WRITE_NOTE.
+    for input_name, value in inputs.items():
+        try:
+            if "time" in p:
+                tool.SetInput(input_name, value, p["time"])
+            else:
+                tool.SetInput(input_name, value)
+            row = {"success": True}
+            if p.get("readback", True):
+                try:
+                    row["value"] = _ser(tool.GetInput(input_name, p["time"])) if "time" in p else _ser(tool.GetInput(input_name))
+                except Exception as exc:
+                    row["readback_error"] = str(exc)
+            results[input_name] = row
+        except Exception as exc:
+            results[input_name] = {"success": False, "error": str(exc)}
     return {"success": all(row.get("success") for row in results.values()), "tool_name": tool_name, "results": results}
 
 
@@ -26438,6 +26458,11 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
     y = p.get("y", -1)
     readback = bool(p.get("readback", True))
 
+    # The lock covers only the STRUCTURAL half (AddTool + rename). The input
+    # writes below must run outside it — see _FUSION_VALUE_WRITE_NOTE: a value
+    # written under the lock reads back correctly and is ignored at render,
+    # which on a mask means the shape exists at default size and position and
+    # every parameter the caller passed silently does nothing.
     comp.Lock()
     try:
         tool = comp.AddTool(tool_type, x, y)
@@ -26449,83 +26474,84 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
         name = p.get("name")
         if name:
             tool.SetAttrs({"TOOLS_Name": str(name)})
-        attrs = tool.GetAttrs() or {}
-        tool_name = attrs.get("TOOLS_Name", "")
-
-        results: List[Dict[str, Any]] = []
-
-        # Center: accept center=[x,y]/{1:x,2:y}, or center_x / center_y.
-        center = p.get("center")
-        cx, cy = p.get("center_x"), p.get("center_y")
-        if center is None and (cx is not None or cy is not None):
-            center = [cx if cx is not None else 0.5, cy if cy is not None else 0.5]
-        if center is not None:
-            ok, err, applied = _fusion_set_point_input(tool, "Center", center)
-            rec = {"input": "Center", "value": center, "success": ok}
-            if not ok:
-                rec["error"] = err
-            elif readback:
+    finally:
+        comp.Unlock()
+
+    attrs = tool.GetAttrs() or {}
+    tool_name = attrs.get("TOOLS_Name", "")
+
+    results: List[Dict[str, Any]] = []
+
+    # Center: accept center=[x,y]/{1:x,2:y}, or center_x / center_y.
+    center = p.get("center")
+    cx, cy = p.get("center_x"), p.get("center_y")
+    if center is None and (cx is not None or cy is not None):
+        center = [cx if cx is not None else 0.5, cy if cy is not None else 0.5]
+    if center is not None:
+        ok, err, applied = _fusion_set_point_input(tool, "Center", center)
+        rec = {"input": "Center", "value": center, "success": ok}
+        if not ok:
+            rec["error"] = err
+        elif readback:
+            try:
+                rec["readback"] = _ser(tool.GetInput("Center"))
+            except Exception as exc:
+                rec["readback_error"] = str(exc)
+        results.append(rec)
+
+    # Scalar inputs (friendly aliases) + any raw passthrough inputs.
+    to_set: List[tuple] = []
+    for friendly, fusion_id in _MASK_INPUT_ALIASES.items():
+        if friendly in p:
+            to_set.append((fusion_id, p[friendly]))
+    raw_inputs = p.get("inputs")
+    if isinstance(raw_inputs, dict):
+        for k, v in raw_inputs.items():
+            to_set.append((str(k), v))
+
+    for fusion_id, value in to_set:
+        rec = {"input": fusion_id, "value": value}
+        try:
+            tool.SetInput(fusion_id, value)
+            rec["success"] = True
+            if readback:
                 try:
-                    rec["readback"] = _ser(tool.GetInput("Center"))
+                    rec["readback"] = _ser(tool.GetInput(fusion_id))
                 except Exception as exc:
                     rec["readback_error"] = str(exc)
-            results.append(rec)
-
-        # Scalar inputs (friendly aliases) + any raw passthrough inputs.
-        to_set: List[tuple] = []
-        for friendly, fusion_id in _MASK_INPUT_ALIASES.items():
-            if friendly in p:
-                to_set.append((fusion_id, p[friendly]))
-        raw_inputs = p.get("inputs")
-        if isinstance(raw_inputs, dict):
-            for k, v in raw_inputs.items():
-                to_set.append((str(k), v))
-
-        for fusion_id, value in to_set:
-            rec = {"input": fusion_id, "value": value}
-            try:
-                tool.SetInput(fusion_id, value)
-                rec["success"] = True
-                if readback:
-                    try:
-                        rec["readback"] = _ser(tool.GetInput(fusion_id))
-                    except Exception as exc:
-                        rec["readback_error"] = str(exc)
-            except Exception as exc:
-                rec["success"] = False
-                rec["error"] = str(exc)
-            results.append(rec)
+        except Exception as exc:
+            rec["success"] = False
+            rec["error"] = str(exc)
+        results.append(rec)
 
-        out: Dict[str, Any] = {
-            "success": True,
-            "tool_name": tool_name,
-            "tool_type": attrs.get("TOOLS_RegID", tool_type),
-            "inputs_set": results,
-        }
+    out: Dict[str, Any] = {
+        "success": True,
+        "tool_name": tool_name,
+        "tool_type": attrs.get("TOOLS_RegID", tool_type),
+        "inputs_set": results,
+    }
 
-        # Optional wiring: connect this mask into a tool's mask input.
-        connect_to = p.get("connect_to")
-        if connect_to:
-            input_name = p.get("connect_input", "EffectMask")
-            target = comp.FindTool(str(connect_to))
-            if not target:
+    # Optional wiring: connect this mask into a tool's mask input.
+    connect_to = p.get("connect_to")
+    if connect_to:
+        input_name = p.get("connect_input", "EffectMask")
+        target = comp.FindTool(str(connect_to))
+        if not target:
+            out["connection"] = {
+                "success": False,
+                "error": f"connect_to tool '{connect_to}' not found",
+            }
+        else:
+            try:
+                ok = bool(target.ConnectInput(input_name, tool))
                 out["connection"] = {
-                    "success": False,
-                    "error": f"connect_to tool '{connect_to}' not found",
+                    "success": ok,
+                    "target": str(connect_to),
+                    "input_name": input_name,
                 }
-            else:
-                try:
-                    ok = bool(target.ConnectInput(input_name, tool))
-                    out["connection"] = {
-                        "success": ok,
-                        "target": str(connect_to),
-                        "input_name": input_name,
-                    }
-                except Exception as exc:
-                    out["connection"] = {"success": False, "error": str(exc)}
-        return out
-    finally:
-        comp.Unlock()
+            except Exception as exc:
+                out["connection"] = {"success": False, "error": str(exc)}
+    return out
 
 
 def _fusion_find_text_tool(comp, p: Dict[str, Any]):
@@ -26561,25 +26587,22 @@ def _fusion_set_text_plus(comp, p: Dict[str, Any]) -> Dict[str, Any]:
         return err
     input_id = p.get("input_name", "StyledText")
     readback = bool(p.get("readback", True))
-    comp.Lock()
+    # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
     try:
+        tool.SetInput(input_id, text)
+    except Exception as exc:
+        return _err(f"SetInput({input_id!r}) failed: {exc}")
+    out = {
+        "success": True,
+        "tool_name": (tool.GetAttrs() or {}).get("TOOLS_Name", ""),
+        "input_name": input_id,
+    }
+    if readback:
         try:
-            tool.SetInput(input_id, text)
+            out["readback"] = _ser(tool.GetInput(input_id))
         except Exception as exc:
-            return _err(f"SetInput({input_id!r}) failed: {exc}")
-        out = {
-            "success": True,
-            "tool_name": (tool.GetAttrs() or {}).get("TOOLS_Name", ""),
-            "input_name": input_id,
-        }
-        if readback:
-            try:
-                out["readback"] = _ser(tool.GetInput(input_id))
-            except Exception as exc:
-                out["readback_error"] = str(exc)
-        return out
-    finally:
-        comp.Unlock()
+            out["readback_error"] = str(exc)
+    return out
 
 
 def _fusion_keyframe_frames(inp) -> List[float]:
@@ -26956,15 +26979,12 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         tool = comp.FindTool(p["tool_name"])
         if not tool:
             return _err(f"Tool '{p['tool_name']}' not found")
-        comp.Lock()
-        try:
-            if "time" in p:
-                tool.SetInput(p["input_name"], p["value"], p["time"])
-            else:
-                tool.SetInput(p["input_name"], p["value"])
-            return _ok()
-        finally:
-            comp.Unlock()
+        # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+        if "time" in p:
+            tool.SetInput(p["input_name"], p["value"], p["time"])
+        else:
+            tool.SetInput(p["input_name"], p["value"])
+        return _ok()
 
     elif action == "get_input":
         tool = comp.FindTool(p["tool_name"])

package/src/utils/api_truth.py

@@ -403,6 +403,44 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "import", "interchange", "otio", "silent-failure", "conform"],
         "submit": "bug",
     },
+    {
+        "symbol": "Composition.Lock (suppresses render invalidation for value writes)",
+        "object": "Composition (Fusion, via TimelineItem comps)",
+        "signature": "Lock() / Unlock()",
+        "reality": "A value write performed between Comp.Lock() and "
+                   "Comp.Unlock() — SetInput(), or Input.SetExpression() — is "
+                   "stored in the graph and reads back correctly from "
+                   "GetInput(), but is NOT applied when the timeline is "
+                   "rendered. Measured live on Studio 19.1.3.7 (2026-08-21) "
+                   "with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a "
+                   "media-backed clip: written under the lock the delivered "
+                   "H.264 render is bit-identical to the no-comp baseline "
+                   "(ffmpeg PSNR inf); the identical write with the lock "
+                   "removed renders at PSNR 24.38 dB and the file shrinks "
+                   "2.0 MB -> 727 KB, as a blur should. The variable was "
+                   "isolated against the comp handle (AddFusionComp, "
+                   "GetFusionCompByIndex and GetFusionCompByName all render), "
+                   "the node name, and the write form (attribute assignment "
+                   "and SetInput both render unlocked). STRUCTURAL edits are "
+                   "unaffected: AddTool and ConnectInput inside a lock render "
+                   "normally, so the lock is not broadly unsafe — it "
+                   "suppresses the parameter-change invalidation that a value "
+                   "write depends on. Lock() is widely recommended for "
+                   "batching Fusion edits, which is how this reaches "
+                   "production code.",
+        "recommended": "Never hold a comp lock across a value write. Lock only "
+                       "structural work (AddTool/ConnectInput) and set inputs "
+                       "outside it. Because every readback the API offers "
+                       "agrees with the value that was written, this failure "
+                       "is invisible without a render — prove Fusion "
+                       "parameter changes with a delivered frame or "
+                       "gallery_stills grab_and_export, never with GetInput.",
+        "tags": ["fusion", "silent-failure", "render", "readback"],
+        "submit": "bug",
+        "mitigation": ["_FUSION_VALUE_WRITE_NOTE",
+                       "tests/live_fusion_value_write_validation.py",
+                       "tests/test_fusion_value_write_lock.py"],
+    },
     {
         "symbol": "TimelineItem.AddFusionComp / LoadFusionCompByName",
         "object": "TimelineItem (media-backed clip)",
@@ -434,7 +472,16 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "either. Contrast InsertFusionTitleIntoTimeline, whose comp "
                    "DOES render — text set via SetInput('StyledText') appears in "
                    "the output — so this is specific to comps attached to "
-                   "media-backed clips, not to Fusion through the API generally.",
+                   "media-backed clips, not to Fusion through the API generally. "
+                   "REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted "
+                   "MediaIn -> Blur -> MediaOut comp built entirely through "
+                   "the API renders (PSNR 24.38 dB vs the no-comp baseline), "
+                   "so the 2026-08-02 correction stands. Note that an "
+                   "important share of 'the comp was ignored' readings are "
+                   "NOT this entry at all but the Composition.Lock bug above "
+                   "— a parameter written under a comp lock reads back "
+                   "correctly and never reaches the render, which looks "
+                   "identical from the API side.",
         "recommended": "Wire the graph so MediaOut descends from MediaIn — that "
                        "is the difference between a comp that renders and one "
                        "that is silently bypassed, and it is what made this look "

package/src/utils/platform.py

@@ -64,6 +64,12 @@ def get_resolve_paths():
     env_lib = os.environ.get("RESOLVE_SCRIPT_LIB")
     if env_lib and os.path.isfile(env_lib):
         lib_path = env_lib
+    elif not os.path.isfile(lib_path):
+        # No usable override and nothing at the default: look for the real
+        # install before handing back a path we already know is not there.
+        # The default is kept as the return value when discovery finds nothing,
+        # so the failure message still names the location people expect.
+        lib_path = discover_scripting_lib(platform_name) or lib_path
 
     return {
         "api_path": api_path,
@@ -71,6 +77,101 @@ def get_resolve_paths():
         "modules_path": modules_path
     }
 
+
+def _windows_lib_candidates():
+    r"""Plausible `fusionscript.dll` locations on this machine.
+
+    `%PROGRAMFILES%` is not a constant — a 64-bit install can sit under
+    `%PROGRAMW6432%` — and Resolve is routinely moved to a second drive
+    because the application and its caches are large. Every drive letter that
+    responds to `isdir` is probed, two fixed paths each, no directory walk;
+    A: and B: are skipped so a machine with a floppy-mapped letter does not
+    stall. No drive-type check is made, so a mapped network drive that happens
+    to be connected is probed too — the cost is bounded (two `isfile` calls)
+    and the alternative is a `GetDriveTypeW` ctypes call for a case that only
+    arises once, on the path where the default was already missing.
+
+    This is reached from `get_resolve_paths()`, which runs at import time, so
+    the real cost is one `ps`/`wmic` spawn at server startup and only when the
+    platform default is absent.
+    """
+    relative = os.path.join("Blackmagic Design", "DaVinci Resolve", "fusionscript.dll")
+    candidates = []
+    for variable in ("PROGRAMFILES", "PROGRAMW6432", "PROGRAMFILES(X86)"):
+        base = os.environ.get(variable)
+        if base:
+            candidates.append(os.path.join(base, relative))
+    for letter in "CDEFGHIJKLMNOPQRSTUVWXYZ":
+        drive = f"{letter}:\\"
+        if not os.path.isdir(drive):
+            continue
+        candidates.append(os.path.join(drive, relative))
+        candidates.append(os.path.join(drive, "Program Files", relative))
+    return candidates
+
+
+def _macos_lib_candidates():
+    """The App Store bundle as well as the installer one.
+
+    The default above names `/Applications/DaVinci Resolve/DaVinci Resolve.app`.
+    The App Store build installs to `/Applications/DaVinci Resolve.app` instead —
+    the same class of miss as a Windows install on another drive, and
+    `resolve_runtime.MACOS_RESOLVE_APPS` already records both.
+    """
+    inside_bundle = os.path.join("Contents", "Libraries", "Fusion", "fusionscript.so")
+    bundles = (
+        "/Applications/DaVinci Resolve/DaVinci Resolve.app",
+        "/Applications/DaVinci Resolve.app",
+    )
+    return [os.path.join(bundle, inside_bundle) for bundle in bundles]
+
+
+def _linux_lib_candidates():
+    """The documented /opt layouts, both of which Blackmagic has shipped."""
+    return [
+        "/opt/resolve/libs/Fusion/fusionscript.so",
+        "/opt/resolve/libs/fusionscript.so",
+        "/opt/resolve/bin/fusionscript.so",
+    ]
+
+
+def discover_scripting_lib(platform_name=None):
+    """Locate the scripting library of a Resolve installed outside the default.
+
+    Order: the running Resolve first — its executable path is the install
+    location, so it needs no guessing and covers every platform — then the
+    conventional roots for that platform, for when Resolve is not up at the
+    moment (installer runs, cold starts).
+
+    Returns None when nothing is found, which leaves the caller's default in
+    place rather than substituting a second guess.
+    """
+    if platform_name is None:
+        platform_name = get_platform()
+
+    # Relative import and a narrow except: this repo has had a run of
+    # silent-fallback bugs, and a bare `except Exception` here would swallow a
+    # real defect inside running_resolve_lib() as "Resolve is not running".
+    try:
+        from .resolve_runtime import running_resolve_lib
+    except ImportError:
+        running_resolve_lib = None
+    running = running_resolve_lib() if running_resolve_lib else None
+    if running and os.path.isfile(running):
+        return running
+
+    by_platform = {
+        'windows': _windows_lib_candidates,
+        'darwin': _macos_lib_candidates,
+        'linux': _linux_lib_candidates,
+    }
+    builder = by_platform.get(platform_name)
+    candidates = builder() if builder else []
+    for candidate in candidates:
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
 def get_resolve_plugin_paths():
     """Get platform-specific paths for Resolve plugin install dirs.
 

package/src/utils/resolve_runtime.py

@@ -122,11 +122,21 @@ def _is_resolve_command(line: str) -> bool:
     the executable is exactly what sits inside the first quoted span; anything
     after the closing quote is arguments, and the flag loop never sees it.
     """
+    return _matches_pattern(_executable_from_line(line))
+
+
+def _executable_from_line(line: str) -> str:
+    """The executable path from a command line, with argument tokens removed.
+
+    Split out of `_is_resolve_command` so the install-location lookup below
+    agrees with the "is this Resolve" test about where the path ends. See that
+    function's docstring for why the quoting and flag-stripping rules are these.
+    """
     text = line.strip()
     if text.startswith('"'):
         close = text.find('"', 1)
         if close > 1:
-            return _matches_pattern(text[1:close])
+            return text[1:close]
     while True:
         stripped = text.rstrip()
         cut = stripped.rfind(" -")
@@ -138,7 +148,7 @@ def _is_resolve_command(line: str) -> bool:
         if not candidate:
             break
         text = candidate
-    return _matches_pattern(text)
+    return text
 
 
 def resolve_processes() -> Optional[List[str]]:
@@ -149,6 +159,52 @@ def resolve_processes() -> Optional[List[str]]:
     return [line for line in lines if _is_resolve_command(line)]
 
 
+#: Where the scripting library sits relative to the Resolve executable. The
+#: library ships *inside* the application, so the running executable's own path
+#: is the only locator that is right by construction — every hardcoded install
+#: root is a guess about where the user chose to put Resolve.
+_LIB_RELATIVE_TO_EXECUTABLE = {
+    "windows": ("fusionscript.dll",),
+    "darwin": ("../Libraries/Fusion/fusionscript.so",),
+    "linux": (
+        "../libs/Fusion/fusionscript.so",
+        "../libs/fusionscript.so",
+        "fusionscript.so",
+    ),
+}
+
+
+def running_resolve_lib() -> Optional[str]:
+    """Scripting library of the *running* Resolve, or None.
+
+    Blackmagic's own `DaVinciResolveScript.py` falls back to one hardcoded
+    install path per platform, and this project's defaults mirror it. A Resolve
+    installed anywhere else — a second drive, an external volume, a custom
+    directory — is therefore invisible to both, and the failure is silent: the
+    module imports, the DLL behind it does not load, and the user is told the
+    edition or the preference is at fault.
+
+    The running process settles it without guessing. Returns None when nothing
+    is running, the process list is unavailable, or the derived path does not
+    exist; callers keep their existing defaults in that case.
+    """
+    processes = resolve_processes()
+    if not processes:
+        return None
+    suffixes = _LIB_RELATIVE_TO_EXECUTABLE.get(platform.system().lower(), ())
+    for line in processes:
+        executable_dir = os.path.dirname(_executable_from_line(line))
+        if not executable_dir:
+            continue
+        for suffix in suffixes:
+            candidate = os.path.normpath(
+                os.path.join(executable_dir, *suffix.split("/"))
+            )
+            if os.path.isfile(candidate):
+                return candidate
+    return None
+
+
 def runtime_mode() -> Dict[str, Any]:
     """`{running, headless, instances, command_lines, determinable}`.