davinci-resolve-mcp 2.67.1 → 2.68.0

package/CHANGELOG.md

@@ -2,6 +2,105 @@
 
 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.68.0
+
+Six engines that let an agent judge its own output before shipping it — audio
+loudness, silence calibration, image QC, transcript editing, captions — plus the
+**in-app bridge**, which reaches the **free edition** of DaVinci Resolve, whose
+external scripting API refuses foreign processes entirely.
+
+### Added
+
+- **Audio delivery QC.** Delivery targets carry a named loudness contract
+  (`web`, `podcast`, `ebu_r128`, `atsc_a85`, `ott_dialogue_gated`) and project it
+  into the existing `loudness_qc` vocabulary. Dialogue-gated standards emit no
+  gradeable `integrated` figure — `loudness_qc` measures full-program, so grading
+  a dialogue-gated number against it produces a verdict that means nothing; it
+  travels as advisory metadata with the reason stated. No shipped target names a
+  standard, because a ProRes master has no inherent programme loudness.
+  `render(action='list_loudness_standards')`.
+- **Auto-calibrated silence gate.** `plan_silence_ripple` derives the threshold
+  from each clip's own dynamics instead of a fixed −30 dB. The metric is `astats`
+  **RMS trough** paired with RMS peak: `mean_volume` tracks programme level, and
+  `Noise floor dB` moved 19 dB between two fixtures sharing an identical noise
+  bed purely because one was quieter for longer. Against ground truth the fixed
+  threshold was wrong on all four fixtures. When calibration cannot be trusted
+  the item is **kept whole** rather than stripped — a fixed threshold applied to
+  material it does not suit is not a degraded answer, it is a wrong one.
+- **Image QC.** `media_analysis(action='assess_grade')` gives an agent
+  deterministic grounds to reject its own grade: tonal frame, noise
+  amplification, banding, highlight posterization and clipping growth, with
+  validated **CIEDE2000** (all 33 Sharma/Wu/Dalal reference pairs to 4 dp). A
+  clean grade costs zero tokens; vision is spent only where the numbers cannot
+  settle it. Non-display-referred working spaces are **refused, never guessed** —
+  the right transform depends on camera and project colour management, which a
+  frame cannot tell you.
+- **Word-level transcript editing.** `edit_engine(action='plan_transcript_tighten')`
+  removes fillers, false starts and over-long pauses at word boundaries with a
+  reason per cut, and `search_spoken_content` searches word timings across a
+  whole shoot to build selects. A lexical axis alongside `find_similar`'s
+  semantic-visual one.
+- **Captions.** `media_analysis(action='generate_captions')` emits SRT and WebVTT
+  under broadcast line rules, plus chapters and YouTube description text.
+- **The in-app bridge — live read and write control of the FREE edition.**
+  Opt-in with `DAVINCI_RESOLVE_BRIDGE=1`; unset changes nothing for existing
+  installs. A script launched from Workspace ▸ Scripts is handed the live
+  `resolve` object on any edition and re-exports it over an authenticated
+  loopback listener, which `connect_resolve` uses as a third transport beside
+  Local and Network. Existing call sites need no changes. This is the documented
+  in-app path, not a licence circumvention — but Blackmagic could close it, so
+  treat it as supported-until-it-is-not.
+- **`shutdown` and `reload` for the bridge.** The launcher blocks (correctly — a
+  Scripts-menu script is a child process, so a daemon thread dies the instant it
+  returns), which used to mean a stale in-Resolve copy could only be replaced by
+  quitting Resolve. `reload` re-imports the runtime from disk in place, and
+  refuses before stopping if the new sources will not compile.
+
+### Fixed
+
+- **The bridge was unreachable on the machine it exists for.** `_try_connect`
+  returned on `dvr_script is None` before calling `connect_resolve`, the function
+  that accepts None in bridge mode. Blackmagic's scripting module ships with the
+  *installer*, not the App Store build, so a free-edition-only machine has no
+  `Developer/Scripting/Modules` tree and the import fails. Verified by blocking
+  the import against a healthy live bridge: `get_resolve()` answered None.
+- **Auto-launch started the wrong Resolve, or one nobody asked for.** The macOS
+  path list contained only the installer location, so a free-only machine found
+  nothing and a machine with both always started Studio. In bridge mode it now
+  refuses outright: launching cannot create a listener that only a Scripts-menu
+  run creates.
+- **Interchange export over the bridge was degrading silently.** Resolve's API
+  constants (`EXPORT_AAF`, `AUDIO_SYNC_*`) are plain attributes and `dir()` does
+  not list them — measured on 21.0.3.7, `dir(resolve)` returns 34 names with no
+  `EXPORT_*` among them while the constants read back as real values. The proxy
+  could only call methods, so `hasattr` said False and the server fell through to
+  handing Resolve the bare string `"EXPORT_AAF"`.
+- **The proxy broke every chain longer than one call.** Every live Resolve object
+  reports `type(obj).__name__ == "PyRemoteObject"` — root 34 methods, Project 49,
+  TimelineItem 88, one class name — so caching method sets on it let the first
+  object touched define `hasattr` for everything after. Method sets are now keyed
+  on provenance, and absence is re-verified against the object itself.
+- **Bridge error codes never crossed the transport.** Every surface code was
+  flattened to `operation_failed`, so `stale_handle` (re-fetch) and
+  `ambiguous_locator` (disambiguate) arrived as one undifferentiated failure.
+
+### Validated live
+
+On **DaVinci Resolve 21.0.3.7 (App Store, free, sandboxed)**, with Blackmagic's
+scripting module blocked to reproduce a free-only machine: 34 tools, 583 declared
+actions, **165 read-shaped actions attempted, 145 clean, zero bridge-attributable
+failures**; 109 of the 112 API read methods the tools actually call exercised on
+the live object graph; a render completed to a non-empty file; AAF/DRT/EDL/FCPXML
+all written by `Timeline.Export`; 400 clips appended in 1.23 s and enumerated at
+0.81 ms/item; an evicted handle refusing with `stale_handle` rather than
+resolving to another object; and reads *and* writes continuing to work with a
+native file dialog open, because the bridge runs in its own process.
+
+`scripts/bridge_differential.py --mode differential` diffs the bridge against
+native scripting on one Studio instance. That comparison has **not** been run
+yet, so the evidenced claim is that the bridge carries the surface the tools use
+on the free edition — not that it is byte-identical to native scripting.
+
 ## What's New in v2.67.1
 
 Documentation correction. No code changes — v2.67.0 already ships the correct

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.67.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.68.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
@@ -22,7 +22,7 @@ A local browser control panel ships with the server for inspecting Resolve state
 npx davinci-resolve-mcp setup
 ```
 
-Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, and JetBrains IDEs.
+Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. (On the **free edition** that preference does not help — see [Free edition](#free-edition-in-app-bridge) below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, and JetBrains IDEs.
 
 For source installs:
 
@@ -36,6 +36,31 @@ For platform paths, client-specific config, and manual setup, see [Installation
 
 The installer and server check the latest GitHub release for MCP updates. Checks are best-effort and throttled; the server never blocks MCP startup for a prompt. The installer can prompt, snooze, ignore a release, disable checks, or apply an opt-in safe auto-update for clean git checkouts.
 
+## Free edition (in-app bridge)
+
+Blackmagic gates *external* scripting to Studio: on the free edition
+`scriptapp("Resolve")` refuses a foreign process, whatever the preference says.
+The **Workspace ▸ Scripts** menu is not gated — a script launched from it is
+handed the live `resolve` object on any edition — so the server can reach the
+free edition through a small script that runs *inside* Resolve and re-exports it
+over an authenticated loopback listener.
+
+```bash
+python scripts/install_resolve_bridge.py
+# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge
+export DAVINCI_RESOLVE_BRIDGE=1      # opt-in; unset changes nothing
+```
+
+Requires a **framework Python** (python.org). Resolve enumerates `.py` scripts
+only when it finds one — Homebrew, pyenv and conda interpreters are not
+detected, and the script silently never appears in the 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. 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, HMAC-signed requests, one-use
+nonces.
+
 ## Local Control Panel
 
 Launch the single-user local control panel from the repository root:

package/docs/SKILL.md

@@ -19,6 +19,26 @@ configured to the Resolve host IP (use `127.0.0.1` on the same machine). The
 server auto-launches Resolve if it is not running, but that first connection can
 take up to 60 seconds.
 
+**Free edition.** Both of those preferences are Studio features; on the free
+edition `scriptapp("Resolve")` refuses a foreign process regardless. A third
+transport reaches it — a script run from **Workspace ▸ Scripts** is handed the
+live `resolve` object on any edition and re-exports it over an authenticated
+loopback listener. Install with `python scripts/install_resolve_bridge.py`, start
+it from that menu, and set `DAVINCI_RESOLVE_BRIDGE=1`. Existing tool call sites
+work unchanged. Two things to know when diagnosing it:
+
+- Resolve lists `.py` scripts only when it can find a **framework Python**
+  (python.org). Homebrew/pyenv/conda are not detected and the script simply never
+  appears, with no error. The installer preflights this and ships a Lua canary,
+  which always lists, so "Python not detected" is distinguishable from "wrong
+  folder".
+- The in-Resolve runtime is a **copy taken at install time**. After changing the
+  repository, re-run the installer and then ask the running bridge to reload —
+  it re-imports from disk in place, so Resolve does not need restarting.
+
+The bridge is a documented in-app path rather than a licence circumvention, but
+Blackmagic could close it; treat it as a supported-until-it-is-not tier.
+
 Network scripting permits remote control of Resolve. Use Local mode when remote
 access is unnecessary; otherwise restrict access with host firewall and network
 controls.

package/install.py

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

package/package.json

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

package/scripts/bridge_differential.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+"""Qualify the in-app bridge by differencing it against native scripting.
+
+    # Studio: both transports reach the same application — the real differential.
+    python scripts/bridge_differential.py --mode differential
+
+    # Free edition: no native side exists, so prove reachability and shape.
+    python scripts/bridge_differential.py --mode coverage
+
+    # Add the write scenarios (render, interchange export, SetLUT, scale, modal).
+    python scripts/bridge_differential.py --mode coverage --scenarios
+
+`--mode differential` requires Studio, because external scripting is Studio-gated
+— which is the entire reason the bridge exists. It also requires the in-app
+bridge to be running *in that same Studio instance*: two transports into one
+application is what makes a difference attributable to the transport rather than
+to the two Resolves having different projects open.
+
+Nothing here writes to a project unless `--scenarios` is passed, and every
+scenario undoes what it did. Read `SCENARIOS` before running it against anything
+you care about.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.utils import bridge_differential as bd  # noqa: E402
+
+
+def connect_bridge() -> Any:
+    from src.utils import resolve_bridge_client as client
+
+    os.environ.setdefault(client.ENV_ENABLE, "1")
+    return client.connect()
+
+
+def connect_native() -> Any:
+    """Blackmagic's own module, deliberately without the bridge in the way."""
+    from src.utils import resolve_bridge_client as client
+
+    previous = os.environ.pop(client.ENV_ENABLE, None)
+    try:
+        import DaVinciResolveScript as dvr
+
+        return dvr.scriptapp("Resolve")
+    finally:
+        if previous is not None:
+            os.environ[client.ENV_ENABLE] = previous
+
+
+# ── write scenarios ──────────────────────────────────────────────────────────
+#
+# The enumeration routes anything that mutates to a named scenario, because a
+# blind call cannot set up its preconditions or clean up after itself. Each one
+# returns a dict of observations; the differential compares those dicts.
+
+
+def scenario_render(resolve: Any, workspace: Path) -> Dict[str, Any]:
+    """The delivery path end to end, to a real file on disk.
+
+    Untested until now, and the most consequential thing the bridge could get
+    wrong: a render that reports success and produces nothing is indistinguishable
+    from a render that worked, right up until someone looks for the file.
+    """
+    project = resolve.GetProjectManager().GetCurrentProject()
+    observations: Dict[str, Any] = {}
+    formats = project.GetRenderFormats() or {}
+    observations["format_count"] = len(formats)
+    observations["codec_count_for_mov"] = len(project.GetRenderCodecs("mov") or {})
+
+    output = workspace / "bridge_render_probe"
+    output.mkdir(parents=True, exist_ok=True)
+    observations["set_format"] = project.SetCurrentRenderFormatAndCodec("mov", "H.264")
+    observations["set_settings"] = project.SetRenderSettings({
+        "TargetDir": str(output),
+        "CustomName": "bridge_render_probe",
+        "MarkIn": int(project.GetCurrentTimeline().GetStartFrame()),
+        "MarkOut": int(project.GetCurrentTimeline().GetStartFrame()) + 4,
+    })
+    job = project.AddRenderJob()
+    observations["job_added"] = bool(job)
+    if not job:
+        return observations
+    try:
+        observations["started"] = project.StartRendering([job], False)
+        deadline = time.time() + 120
+        while time.time() < deadline and project.IsRenderingInProgress():
+            time.sleep(0.5)
+        status = project.GetRenderJobStatus(job) or {}
+        observations["job_status"] = status.get("JobStatus")
+        produced = sorted(p.name for p in output.iterdir() if p.is_file())
+        observations["files_written"] = len(produced)
+        observations["nonempty_output"] = any((output / n).stat().st_size > 0 for n in produced)
+    finally:
+        project.DeleteRenderJob(job)
+    return observations
+
+
+def scenario_interchange_export(resolve: Any, workspace: Path) -> Dict[str, Any]:
+    """Timeline.Export to each conform format. The conform surface, untested."""
+    timeline = resolve.GetProjectManager().GetCurrentProject().GetCurrentTimeline()
+    observations: Dict[str, Any] = {}
+    targets = [
+        ("EDL", "EXPORT_EDL", "EXPORT_CDL", ".edl"),
+        ("FCPXML", "EXPORT_FCP_7_XML", "EXPORT_NONE", ".xml"),
+        ("DRT", "EXPORT_DRT", "EXPORT_NONE", ".drt"),
+        ("AAF", "EXPORT_AAF", "EXPORT_AAF_NEW", ".aaf"),
+    ]
+    for label, export_type, subtype, suffix in targets:
+        path = workspace / f"bridge_export_probe{suffix}"
+        if path.exists():
+            path.unlink()
+        constant = getattr(resolve, export_type, None)
+        sub = getattr(resolve, subtype, None)
+        try:
+            if constant is None:
+                observations[label] = {"ok": False, "reason": "constant_absent"}
+                continue
+            ok = timeline.Export(str(path), constant, sub) if sub is not None else \
+                timeline.Export(str(path), constant)
+            observations[label] = {
+                "ok": bool(ok),
+                "written": path.exists(),
+                "bytes": path.stat().st_size if path.exists() else 0,
+            }
+        except Exception as exc:  # noqa: BLE001 - the failure is the observation
+            observations[label] = {"ok": False, "reason": type(exc).__name__, "message": str(exc)[:120]}
+    return observations
+
+
+def scenario_set_lut(resolve: Any, _workspace: Path) -> Dict[str, Any]:
+    """SetLUT specifically — last time GetLUT was called and the rest inferred.
+
+    Read back after writing, and restore. A write that returns True and does not
+    land is the failure mode this exists to catch, and only the read-back sees it.
+    """
+    timeline = resolve.GetProjectManager().GetCurrentProject().GetCurrentTimeline()
+    items = timeline.GetItemListInTrack("video", 1) or []
+    if not items:
+        return {"skipped": "no clip on video track 1"}
+    item = items[0]
+    observations: Dict[str, Any] = {"node_count": item.GetNumNodes()}
+    original = item.GetLUT(1)
+    observations["lut_before"] = original
+    # An empty path is the documented way to clear a node's LUT, so it is a
+    # write we can make and unmake without shipping a .cube anywhere.
+    observations["set_empty"] = item.SetLUT(1, "")
+    observations["lut_after_clear"] = item.GetLUT(1)
+    if original:
+        observations["restored"] = item.SetLUT(1, original)
+    observations["set_out_of_range_node"] = item.SetLUT(999, "")
+    return observations
+
+
+def scenario_scale(resolve: Any, _workspace: Path) -> Dict[str, Any]:
+    """Enumerate every item on every track and time it.
+
+    The round trip is 0.6 ms and the handle table holds 4096 entries; both only
+    matter at a size nobody has run yet. This measures where they start to.
+    """
+    timeline = resolve.GetProjectManager().GetCurrentProject().GetCurrentTimeline()
+    observations: Dict[str, Any] = {"tracks": {}}
+    started = time.time()
+    total = 0
+    names: List[str] = []
+    for kind in ("video", "audio"):
+        count = int(timeline.GetTrackCount(kind) or 0)
+        for index in range(1, count + 1):
+            items = timeline.GetItemListInTrack(kind, index) or []
+            observations["tracks"][f"{kind}{index}"] = len(items)
+            for item in items:
+                names.append(item.GetName())
+                total += 1
+    elapsed = time.time() - started
+    observations["items"] = total
+    observations["distinct_names"] = len(set(names))
+    observations["elapsed_seconds"] = round(elapsed, 3)
+    observations["ms_per_item"] = round(elapsed / total * 1000, 3) if total else None
+    return observations
+
+
+def scenario_handle_pressure(resolve: Any, _workspace: Path) -> Dict[str, Any]:
+    """Push past the 4096-handle ceiling and check what an evicted handle does.
+
+    The table is bounded so a long session cannot pin every enumerated object
+    inside Resolve forever. Eviction is therefore normal, and the property that
+    matters is that a lost handle says `stale_handle` — a client can re-fetch from
+    that. The failure this guards against is an evicted id being reused and
+    silently resolving to a *different* object, which is a wrong-target edit with
+    no error anywhere.
+    """
+    from src.utils import resolve_bridge_client as client
+
+    transport = getattr(resolve, "_transport", None)
+    if transport is None:
+        return {"skipped": "native scripting has no handle table"}
+
+    timeline = resolve.GetProjectManager().GetCurrentProject().GetCurrentTimeline()
+    first_batch = timeline.GetItemListInTrack("video", 1) or []
+    if not first_batch:
+        return {"skipped": "no clip on video track 1"}
+    observations: Dict[str, Any] = {"batch_size": len(first_batch)}
+
+    # Two handles from the same first batch. One is touched every round, the
+    # other is left alone — because access promotes an entry, so "does a handle
+    # survive" has two different answers and only measuring one of them would
+    # report the wrong ceiling.
+    kept_warm, left_cold = first_batch[0], first_batch[-1]
+
+    minted = len(first_batch)
+    rounds = 0
+    started = time.time()
+    while minted < 6000 and rounds < 400 and time.time() - started < 180:
+        minted += len(timeline.GetItemListInTrack("video", 1) or [])
+        rounds += 1
+        try:
+            kept_warm.GetName()
+            observations["warm_valid_at"] = minted
+        except client.BridgeCallError as exc:
+            observations["warm_evicted_at"] = minted
+            observations["warm_code"] = exc.code
+            break
+    observations["handles_minted"] = minted
+    observations["rounds"] = rounds
+    observations["seconds"] = round(time.time() - started, 2)
+
+    try:
+        left_cold.GetName()
+        observations["cold_survived"] = True
+    except client.BridgeCallError as exc:
+        observations["cold_evicted"] = True
+        observations["cold_code"] = exc.code
+        # The property that actually matters: an evicted handle refuses. If a
+        # recycled id resolved to a different object instead, the caller would
+        # edit the wrong clip with nothing to indicate it.
+        observations["cold_refused_cleanly"] = exc.code == "stale_handle"
+    return observations
+
+
+SCENARIOS: Dict[str, Callable[[Any, Path], Dict[str, Any]]] = {
+    "render": scenario_render,
+    "interchange_export": scenario_interchange_export,
+    "set_lut": scenario_set_lut,
+    "scale": scenario_scale,
+    "handle_pressure": scenario_handle_pressure,
+}
+
+#: Name of the timeline `--build-timeline` creates. Distinctive so it is obvious
+#: what it is and safe to delete.
+SCALE_TIMELINE = "MCP Bridge Scale Test - delete me"
+
+
+def build_scale_timeline(resolve: Any, items: int) -> Dict[str, Any]:
+    """Create a timeline with `items` clips, so the scale scenario has a subject.
+
+    Writes. Only runs when `--build-timeline` is passed. Doubles as a test of
+    argument encoding depth: `AppendToTimeline` takes a list of dicts each
+    holding a live MediaPoolItem, so the proxy has to send objects back *inside*
+    a nested structure, not merely as a top-level argument.
+    """
+    project = resolve.GetProjectManager().GetCurrentProject()
+    pool = project.GetMediaPool()
+    clips = [c for c in (pool.GetRootFolder().GetClipList() or [])
+             if (c.GetClipProperty("Type") or "") != "Timeline"]
+    if not clips:
+        return {"failed": "the media pool has no clip to append"}
+    source = clips[0]
+    timeline = pool.CreateEmptyTimeline(SCALE_TIMELINE)
+    if not timeline:
+        return {"failed": f"could not create {SCALE_TIMELINE!r} (does it already exist?)"}
+    project.SetCurrentTimeline(timeline)
+    started = time.time()
+    appended = pool.AppendToTimeline(
+        [{"mediaPoolItem": source, "startFrame": 0, "endFrame": 5} for _ in range(items)]
+    )
+    return {
+        "timeline": SCALE_TIMELINE,
+        "requested": items,
+        "appended": len(appended) if isinstance(appended, list) else bool(appended),
+        "seconds": round(time.time() - started, 2),
+    }
+
+
+def run_scenarios(resolve: Any, workspace: Path, only: Optional[List[str]] = None) -> Dict[str, Any]:
+    results: Dict[str, Any] = {}
+    for name, function in SCENARIOS.items():
+        if only and name not in only:
+            continue
+        try:
+            results[name] = function(resolve, workspace)
+        except Exception as exc:  # noqa: BLE001 - a scenario failing is a result
+            results[name] = {"failed": type(exc).__name__, "message": str(exc)[:300]}
+    return results
+
+
+# ── modal behaviour ──────────────────────────────────────────────────────────
+
+
+def probe_modal_timeout(resolve: Any, timeout: float) -> Dict[str, Any]:
+    """Does a blocked Resolve hang the client, or does it come back?
+
+    Measured on free 21.0.3.7 with dialogs genuinely open, and the answer was
+    better than the question assumed: **the bridge is not blocked by modals.**
+    With Project Settings open, and again with a native file-open dialog up,
+    reads and writes both went through — a 400-item enumeration finished in
+    0.17 s. The reason is the host model: a Scripts-menu script is a separate
+    process, so a modal that owns Resolve's UI thread does not own the scripting
+    IPC. The child-process lifecycle was forced on us by a different question and
+    turns out to buy modal immunity as a side effect.
+
+    One difference was observed under the file dialog and is recorded rather than
+    generalised from: `Timeline.SetName` returned None where the same call
+    returns False with no dialog open. A single observation, so treat it as a
+    reason to keep `false_is_error` catching None as well as False, not as a
+    characterisation of every write.
+
+    This probe cannot open a dialog itself, so it verifies the fallback that
+    matters if some future modal *does* block: the client gives up on a bounded
+    schedule with an actionable code rather than pinning a tool call.
+    """
+    from src.utils import resolve_bridge_client as client
+
+    transport = getattr(resolve, "_transport", None)
+    if transport is None:
+        return {"skipped": "native transport has no timeout to probe"}
+    previous = transport.timeout
+    transport.timeout = timeout
+    started = time.time()
+    try:
+        resolve.GetProductName()
+        return {"answered": True, "seconds": round(time.time() - started, 3),
+                "note": "nothing was blocking; run again with a dialog open in Resolve"}
+    except client.BridgeCallError as exc:
+        return {"answered": False, "code": exc.code, "seconds": round(time.time() - started, 3),
+                "message": exc.message[:200]}
+    finally:
+        transport.timeout = previous
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--mode", choices=("differential", "coverage", "surface"), default="coverage")
+    parser.add_argument("--scenarios", action="store_true", help="run the write scenarios (mutates the project)")
+    parser.add_argument("--only", action="append", help="restrict to one scenario; repeatable")
+    parser.add_argument("--build-timeline", type=int, metavar="N",
+                        help=f"create {SCALE_TIMELINE!r} with N clips first (writes)")
+    parser.add_argument("--workspace", default=str(Path.home() / "Movies" / "mcp_bridge_test"))
+    parser.add_argument("--json", dest="json_path", help="write the full report here")
+    arguments = parser.parse_args()
+
+    surface = bd.probe_surface()
+    report: Dict[str, Any] = {"surface": {k: v for k, v in surface.items() if k != "sources"}}
+
+    if arguments.mode == "surface":
+        print(json.dumps(report, indent=2))
+        return 0
+
+    workspace = Path(arguments.workspace).expanduser()
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    bridge = connect_bridge()
+    report["bridge_health"] = bridge.bridge_health()
+    if arguments.build_timeline:
+        report["built"] = build_scale_timeline(bridge, arguments.build_timeline)
+        print("built       : %s" % json.dumps(report["built"], sort_keys=True))
+    bridged = bd.run_probes(bridge, surface["safe_to_probe"])
+    report["coverage"] = bd.coverage_report(surface, bridged)
+    report["modal_timeout"] = probe_modal_timeout(bridge, timeout=5.0)
+
+    if arguments.mode == "differential":
+        native = connect_native()
+        if native is None:
+            print("native scripting is unavailable — Studio only. Use --mode coverage.",
+                  file=sys.stderr)
+            return 2
+        product = native.GetProductName()
+        if product != report["bridge_health"]["product"]:
+            # Two different applications would make every difference meaningless.
+            print(f"refusing to diff: native sees {product!r}, the bridge sees "
+                  f"{report['bridge_health']['product']!r}. Both transports must reach the "
+                  "same running Resolve.", file=sys.stderr)
+            return 2
+        report["diff"] = bd.compare(bd.run_probes(native, surface["safe_to_probe"]), bridged)
+        if arguments.scenarios:
+            report["scenarios"] = {
+                "native": run_scenarios(native, workspace, arguments.only),
+                "bridge": run_scenarios(bridge, workspace, arguments.only),
+            }
+    elif arguments.scenarios:
+        report["scenarios"] = {"bridge": run_scenarios(bridge, workspace, arguments.only)}
+
+    if arguments.json_path:
+        Path(arguments.json_path).write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+
+    coverage = report["coverage"]
+    print("bridge      : %s %s (%s)" % (report["bridge_health"]["product"],
+                                        report["bridge_health"]["version"],
+                                        report["bridge_health"]["edition"]))
+    print("surface     : %d methods called by the tools, %d safe to probe"
+          % (coverage["called_by_tools"], coverage["safe_to_probe"]))
+    print("exercised   : %d/%d read methods on the live object graph"
+          % (coverage["exercised"], coverage["safe_to_probe"]))
+    if coverage["unreachable_objects"]:
+        print("unreachable : %s (no such object in this project)"
+              % ", ".join(coverage["unreachable_objects"]))
+    if coverage["not_exercised"]:
+        print("not covered : %s" % ", ".join(coverage["not_exercised"]))
+    if "diff" in report:
+        diff = report["diff"]
+        print("differential: %d probes compared, %d differences"
+              % (diff["compared"], len(diff["differences"])))
+        for difference in diff["differences"][:20]:
+            print("  ! %-46s %s" % (difference["key"], difference["kind"]))
+    for name, outcome in (report.get("scenarios", {}).get("bridge", {}) or {}).items():
+        print("scenario %-19s %s" % (name, json.dumps(outcome, sort_keys=True)[:180]))
+    failed = "diff" in report and not report["diff"]["identical"]
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())