davinci-resolve-mcp 2.36.1 → 2.37.1

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.37.1
+
+Test-suite hygiene — no server behavior changed.
+
+- **Fixed** the legacy live-harness scripts (`test_all_tools`, `test_phase2`–`5`)
+  exiting at import when Resolve is unavailable, which crashed pytest
+  collection and surfaced as five loader errors under unittest discovery.
+  They now skip cleanly under both runners and keep the hard-exit behavior
+  when run as standalone scripts. (Adapted from a contribution by @diesdaas.)
+- **Fixed** pytest mis-collecting `test_resolve20_api.py`'s internal `test()`
+  helper (renamed to `run_live_check()`), and made the batch-CLI synthetic-job
+  test independent of which transcription backends the host has installed.
+- **CI**: the npm publish workflow no longer reports failure when the registry
+  accepted the publish but npm's retried request hit a consumed OIDC token;
+  it now verifies the published tarball shasum before failing. Runner actions
+  bumped to their Node 24 majors.
+
+## What's New in v2.37.0
+
+Render format-id fix, offline-media diagnosis, and a setup doctor.
+
+- **Fixed** render helpers passing the display name from `GetRenderFormats()`
+  (e.g. `QuickTime`) into `GetRenderCodecs`, `GetRenderResolutions`, and
+  `SetCurrentRenderFormatAndCodec`, which expect the format id (e.g. `mov`).
+  `GetRenderCodecs("QuickTime")` returned empty, so `probe_render_matrix`
+  reported no QuickTime codecs and `prepare_render_job` could not target
+  ProRes (e.g. `ProRes422LT` proxy renders). Display names and format ids are
+  now both accepted as input and normalized to the id for Resolve API calls;
+  `probe_render_matrix` rows include `format_id`. Closes #59.
+- **Fixed** the destructive confirm-token gate referencing a stale function
+  name, which made it silently ignore the `destructive.require_confirm_token`
+  preference and always fall back to the default.
+- **Added** a `diagnosis` block to `timeline.detect_missing_media`:
+  deduplicated missing Media Pool items, volume/folder mounted checks, a
+  primary cause (`volume_not_mounted` / `folder_not_found` /
+  `files_missing_or_renamed`), and a recommended next step. Optional
+  `sanitized`/`sanitize_paths` redacts raw media paths.
+- **Added** bounds to `timeline.build_relink_plan`: skips the broad scan by
+  default when a source volume (e.g. a camera card) is not mounted, dedupes
+  missing basenames, and caps the search with `max_depth`, `max_seconds`
+  (default 20s), and `max_files_scanned` (default 50k), reporting per-candidate
+  scan stats.
+- **Fixed** `media_analysis` accepting `vision: true/false` boolean shorthand
+  (now normalized to the full options dict) and `timeline_markers.get_thumbnail`
+  returning a structured error instead of raw `None` when no thumbnail is
+  available.
+- **Added** `scripts/doctor.py`, a read-only setup diagnostic that checks the
+  checkout, Python, Resolve app/scripting paths, and MCP client configs, and
+  probes the scripting bridge end to end with OK/WARN/FAIL output (`--json`
+  supported).
+
 ## What's New in v2.36.1
 
 Bug fix — restore the `fusion_comp` MCP tool.

package/README.md

@@ -1,9 +1,9 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.36.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.37.1-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-32%20(341%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-33%20(341%20full)-blue.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
@@ -49,7 +49,7 @@ The command starts a localhost server and opens the control panel in your browse
 
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
-| Compound | `src/server.py` | 32 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
+| Compound | `src/server.py` | 33 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
 | Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 341 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.

package/docs/SKILL.md

@@ -807,10 +807,19 @@ structure, interchange, comparison, missing-media, and relink-planning helpers:
 - `import_timeline_checked(path, options?, timeline_name?, import_source_clips?, require_temp_path?, dry_run?)`
 - `compare_timelines(right_timeline_id?|right_timeline_index?|left_snapshot?, right_snapshot?)`
 - `probe_interchange_roundtrip(format?, output_dir?, cleanup_imported?)`
-- `detect_missing_media`
-- `build_relink_plan(search_roots)`
+- `detect_missing_media(sanitized?|sanitize_paths?, omit_raw_paths?)`
+- `build_relink_plan(search_roots, max_depth?, max_seconds?, max_files_scanned?, skip_search_when_volume_missing?, sanitized?)`
 - `conform_boundary_report`
 
+For offline media, prefer the sanitized readback first:
+`timeline(action="detect_missing_media", params={"sanitized": true})`. The
+response includes a `diagnosis` block with deduplicated Media Pool items,
+missing volume roots, sample basenames, and a recommended next step. If a source
+volume such as a camera card is not mounted, `build_relink_plan` skips broad
+search by default and reports `skip_reason="missing_source_volume_not_mounted"`;
+mount the volume or pass `skip_search_when_volume_missing=false` only when a
+bounded scan of approved roots is intentional.
+
 Audio / Fairlight kernel actions (v2.14.0+) add live-tested audio state,
 mapping, voice-isolation, sync, transcription, subtitle, and Fairlight boundary
 helpers:

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -35,8 +35,8 @@ All actions are exposed through `timeline`.
 | `import_timeline_checked` | Guard timeline imports from temp locations and normalize import options. |
 | `compare_timelines` | Compare current timeline to another timeline or two supplied snapshots. |
 | `probe_interchange_roundtrip` | Export, import, compare, and optionally delete the imported timeline. |
-| `detect_missing_media` | Detect missing/offline media using Resolve status fields and file-path existence. |
-| `build_relink_plan` | Read-only search-root scan for relink candidates by missing file basename. |
+| `detect_missing_media` | Detect missing/offline media using Resolve status fields and file-path existence, with a sanitized diagnosis block for mounted-volume/folder/file failure modes. |
+| `build_relink_plan` | Read-only, bounded search-root scan for relink candidates by missing file basename. Skips broad scans by default when the source volume is not mounted. |
 | `conform_boundary_report` | Return capabilities, timeline structure, gaps/overlaps, source ranges, and missing-media summary. |
 
 ## Interchange Matrix
@@ -74,8 +74,11 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
   relationships.
 - The public API exposes timeline items, source ranges, markers, and some media
   references, but not full transition/effect/retime semantics for every format.
-- `build_relink_plan` is intentionally read-only. Execute relinks through
-  `media_pool.safe_relink` only with synthetic or explicitly approved paths.
+- `build_relink_plan` is intentionally read-only. It deduplicates missing
+  basenames, supports `max_depth`, `max_seconds`, and `max_files_scanned`, and
+  skips broad scans by default when a source volume such as a camera card is not
+  mounted. Execute relinks through `media_pool.safe_relink` only with synthetic
+  or explicitly approved paths.
 - Missing-media status fields vary by Resolve build. The kernel combines status
   text with local file existence when a file path is available.
 - Export and import helpers require temp paths by default because they write

package/install.py

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

package/scripts/doctor.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Read-only diagnostics for a local DaVinci Resolve MCP setup.
+
+Checks the checkout, Python interpreter, Resolve app and scripting-API paths,
+MCP client configs, and probes the DaVinciResolveScript bridge without
+mutating anything. Prints OK/WARN/FAIL lines (or JSON with --json) and exits
+nonzero only when a FAIL is present.
+
+Run: `python3 scripts/doctor.py`
+
+Overridable via environment: DAVINCI_MCP_REPO, DAVINCI_MCP_PYTHON,
+CODEX_HOME, CLAUDE_DESKTOP_CONFIG, RESOLVE_APP, RESOLVE_SCRIPT_API,
+RESOLVE_SCRIPT_MODULES, RESOLVE_SCRIPT_LIB.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def find_repo_root() -> Path:
+    env_repo = os.environ.get("DAVINCI_MCP_REPO")
+    if env_repo:
+        return Path(env_repo).expanduser().resolve()
+    current = Path(__file__).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "src" / "server.py").exists():
+            return candidate
+    return current.parents[1]
+
+
+REPO = find_repo_root()
+PYTHON = Path(os.environ.get("DAVINCI_MCP_PYTHON", REPO / "venv" / "bin" / "python")).expanduser()
+if not PYTHON.exists():
+    PYTHON = REPO / ".venv" / "bin" / "python"
+if not PYTHON.exists():
+    PYTHON = Path(sys.executable)
+SERVER = REPO / "src" / "server.py"
+CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+CODEX_CONFIG = CODEX_HOME / "config.toml"
+CLAUDE_CONFIG = Path(
+    os.environ.get(
+        "CLAUDE_DESKTOP_CONFIG",
+        "~/Library/Application Support/Claude/claude_desktop_config.json",
+    )
+).expanduser()
+RESOLVE_APP = Path(os.environ.get("RESOLVE_APP", "/Applications/DaVinci Resolve/DaVinci Resolve.app"))
+RESOLVE_API = Path(
+    os.environ.get(
+        "RESOLVE_SCRIPT_API",
+        "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting",
+    )
+)
+RESOLVE_MODULES = Path(os.environ.get("RESOLVE_SCRIPT_MODULES", RESOLVE_API / "Modules"))
+RESOLVE_LIB = Path(
+    os.environ.get(
+        "RESOLVE_SCRIPT_LIB",
+        "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so",
+    )
+)
+
+
+def run(cmd: list[str], timeout: int = 12) -> dict[str, Any]:
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return {
+            "ok": proc.returncode == 0,
+            "returncode": proc.returncode,
+            "stdout": proc.stdout.strip(),
+            "stderr": proc.stderr.strip(),
+        }
+    except Exception as exc:
+        return {"ok": False, "returncode": None, "stdout": "", "stderr": str(exc)}
+
+
+def run_in_repo(cmd: list[str], timeout: int = 12) -> dict[str, Any]:
+    try:
+        proc = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True, timeout=timeout)
+        return {
+            "ok": proc.returncode == 0,
+            "returncode": proc.returncode,
+            "stdout": proc.stdout.strip(),
+            "stderr": proc.stderr.strip(),
+        }
+    except Exception as exc:
+        return {"ok": False, "returncode": None, "stdout": "", "stderr": str(exc)}
+
+
+def check(results: list[dict[str, str]], status: str, name: str, detail: str) -> None:
+    results.append({"status": status, "name": name, "detail": detail})
+
+
+def file_contains(path: Path, needles: list[str]) -> tuple[bool, str]:
+    if not path.exists():
+        return False, "missing"
+    text = path.read_text(errors="replace")
+    missing = [needle for needle in needles if needle not in text]
+    if missing:
+        return False, "missing: " + ", ".join(missing)
+    return True, "contains davinci-resolve MCP entry"
+
+
+def version_from_server() -> str:
+    if not SERVER.exists():
+        return "unknown"
+    match = re.search(r'^VERSION\s*=\s*"([^"]+)"', SERVER.read_text(errors="replace"), re.M)
+    return match.group(1) if match else "unknown"
+
+
+def git_summary() -> str:
+    if not (REPO / ".git").exists():
+        return "not a git checkout"
+    status = run_in_repo(["git", "status", "--short", "--branch"], timeout=8)
+    return status["stdout"] or status["stderr"] or "git status produced no output"
+
+
+def git_head() -> str:
+    if not (REPO / ".git").exists():
+        return "not a git checkout"
+    head = run_in_repo(["git", "describe", "--tags", "--always", "--dirty"], timeout=8)
+    return head["stdout"] or head["stderr"] or "git describe produced no output"
+
+
+def resolve_probe() -> dict[str, Any]:
+    if not PYTHON.exists():
+        return {"import_ok": False, "error": f"{PYTHON} is missing"}
+
+    code = f"""
+import json
+import sys
+sys.path.insert(0, {str(RESOLVE_MODULES)!r})
+try:
+    import DaVinciResolveScript as dvr
+    resolve = dvr.scriptapp("Resolve")
+    payload = {{
+        "import_ok": True,
+        "module": getattr(dvr, "__file__", None),
+        "resolve_connected": bool(resolve),
+        "product": resolve.GetProductName() if resolve else None,
+        "version": resolve.GetVersionString() if resolve else None,
+    }}
+except Exception as exc:
+    payload = {{"import_ok": False, "error": repr(exc)}}
+print(json.dumps(payload))
+"""
+    env = {
+        **os.environ,
+        "RESOLVE_SCRIPT_API": str(RESOLVE_API),
+        "RESOLVE_SCRIPT_LIB": str(RESOLVE_LIB),
+        "PYTHONPATH": str(RESOLVE_MODULES),
+    }
+    proc = subprocess.run([str(PYTHON), "-c", code], capture_output=True, text=True, timeout=12, env=env)
+    output = (proc.stdout or proc.stderr).strip()
+    try:
+        payload = json.loads(output)
+    except json.JSONDecodeError:
+        payload = {"import_ok": False, "error": output or f"probe exited {proc.returncode}"}
+    payload["returncode"] = proc.returncode
+    return payload
+
+
+def collect() -> list[dict[str, str]]:
+    results: list[dict[str, str]] = []
+
+    check(results, "OK" if REPO.exists() else "FAIL", "MCP checkout", str(REPO))
+    check(results, "OK" if SERVER.exists() else "FAIL", "Server entrypoint", str(SERVER))
+    check(results, "OK" if PYTHON.exists() else "FAIL", "Python", str(PYTHON))
+    check(results, "OK" if RESOLVE_APP.exists() else "FAIL", "Resolve app", str(RESOLVE_APP))
+    check(results, "OK" if RESOLVE_API.exists() else "FAIL", "Resolve scripting API", str(RESOLVE_API))
+    check(results, "OK" if RESOLVE_MODULES.exists() else "FAIL", "Resolve scripting modules", str(RESOLVE_MODULES))
+    check(results, "OK" if RESOLVE_LIB.exists() else "FAIL", "Resolve scripting library", str(RESOLVE_LIB))
+
+    needles = [str(SERVER)]
+    ok, detail = file_contains(CODEX_CONFIG, needles)
+    check(results, "OK" if ok else "WARN", "Codex MCP config", f"{CODEX_CONFIG}: {detail}")
+    ok, detail = file_contains(CLAUDE_CONFIG, needles)
+    check(results, "OK" if ok else "WARN", "Claude Desktop MCP config", f"{CLAUDE_CONFIG}: {detail}")
+
+    pyver = run([str(PYTHON), "--version"]) if PYTHON.exists() else {"ok": False, "stdout": "", "stderr": "missing"}
+    check(results, "OK" if pyver["ok"] else "FAIL", "Python version", pyver["stdout"] or pyver["stderr"])
+
+    probe = resolve_probe()
+    if probe.get("import_ok"):
+        check(results, "OK", "DaVinciResolveScript import", str(probe.get("module")))
+        if probe.get("resolve_connected"):
+            detail = f"{probe.get('product')} {probe.get('version')}"
+            check(results, "OK", "Resolve scripting connection", detail)
+        else:
+            check(
+                results,
+                "WARN",
+                "Resolve scripting connection",
+                'Module import worked, but scriptapp("Resolve") returned no object. Open DaVinci Resolve Studio, set Preferences > General > External scripting using = Local, and restart Resolve.',
+            )
+    else:
+        check(results, "FAIL", "DaVinciResolveScript import", str(probe.get("error")))
+
+    check(results, "OK", "MCP server version", version_from_server())
+    check(results, "OK", "MCP git head", git_head())
+    check(results, "OK", "Git status", git_summary())
+    return results
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON")
+    args = parser.parse_args()
+
+    results = collect()
+    if args.json:
+        print(json.dumps({"checks": results}, indent=2))
+    else:
+        for item in results:
+            print(f"[{item['status']}] {item['name']}: {item['detail']}")
+
+    return 1 if any(item["status"] == "FAIL" for item in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.36.1"
+VERSION = "2.37.1"
 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 341-tool granular server instead
 """
 
-VERSION = "2.36.1"
+VERSION = "2.37.1"
 
 import base64
 import os
@@ -973,7 +973,7 @@ def _confirm_token_gc():
 def _confirm_token_required() -> bool:
     """Honor setup default destructive.require_confirm_token (default True)."""
     try:
-        prefs = _media_analysis_preferences_read() if "_media_analysis_preferences_read" in globals() else {}
+        prefs = _read_media_analysis_preferences() if "_read_media_analysis_preferences" in globals() else {}
     except Exception:
         prefs = {}
     destructive = prefs.get("destructive") if isinstance(prefs.get("destructive"), dict) else {}
@@ -5185,6 +5185,123 @@ def _probe_interchange_roundtrip(proj, mp, tl, p: Dict[str, Any]):
     }
 
 
+def _sanitize_media_path(path: Any, *, keep_filename: bool = True) -> Optional[str]:
+    if not path:
+        return None
+    text = str(path)
+    filename = os.path.basename(text.rstrip(os.sep))
+    parts = [part for part in text.split(os.sep) if part]
+    if text.startswith("/Volumes/") and len(parts) >= 2:
+        root = f"/Volumes/{parts[1]}"
+        return f"{root}/.../{filename}" if keep_filename and filename else f"{root}/..."
+    if text.startswith(os.sep):
+        return f"/.../{filename}" if keep_filename and filename else "/..."
+    return f".../{filename}" if keep_filename and filename else "..."
+
+
+def _media_path_volume_root(path: Any) -> Optional[str]:
+    if not path:
+        return None
+    text = str(path)
+    parts = [part for part in text.split(os.sep) if part]
+    if text.startswith("/Volumes/") and len(parts) >= 2:
+        return f"/Volumes/{parts[1]}"
+    if text.startswith(os.sep) and parts:
+        return os.sep + parts[0]
+    return None
+
+
+def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    by_media_pool_item: Dict[str, Dict[str, Any]] = {}
+    missing_volumes: Dict[str, Dict[str, Any]] = {}
+    missing_folders: Dict[str, Dict[str, Any]] = {}
+
+    for row in missing_rows:
+        file_path = row.get("file_path")
+        media_pool_item_id = row.get("media_pool_item_id") or file_path or row.get("name")
+        basename = os.path.basename(str(file_path or row.get("media_pool_item_name") or row.get("name") or ""))
+        item = by_media_pool_item.setdefault(
+            str(media_pool_item_id),
+            {
+                "media_pool_item_id": row.get("media_pool_item_id"),
+                "media_pool_item_name": row.get("media_pool_item_name") or row.get("name"),
+                "wanted_basename": basename,
+                "file_path_sanitized": _sanitize_media_path(file_path),
+                "volume_root_sanitized": _sanitize_media_path(_media_path_volume_root(file_path), keep_filename=False),
+                "timeline_occurrence_count": 0,
+                "track_refs": [],
+            },
+        )
+        item["timeline_occurrence_count"] += 1
+        item["track_refs"].append(
+            {
+                "track_type": row.get("track_type"),
+                "track_index": row.get("track_index"),
+                "timeline_item_id": row.get("timeline_item_id"),
+            }
+        )
+
+        volume_root = _media_path_volume_root(file_path)
+        if volume_root:
+            volume_row = missing_volumes.setdefault(
+                volume_root,
+                {
+                    "volume_root_sanitized": _sanitize_media_path(volume_root, keep_filename=False),
+                    "mounted": os.path.isdir(volume_root),
+                    "clip_count": 0,
+                    "sample_basenames": [],
+                },
+            )
+            volume_row["clip_count"] += 1
+            if basename and basename not in volume_row["sample_basenames"] and len(volume_row["sample_basenames"]) < 8:
+                volume_row["sample_basenames"].append(basename)
+
+        folder = os.path.dirname(str(file_path)) if file_path else ""
+        if folder:
+            folder_row = missing_folders.setdefault(
+                folder,
+                {
+                    "folder_sanitized": _sanitize_media_path(folder, keep_filename=False),
+                    "exists": os.path.isdir(folder),
+                    "clip_count": 0,
+                    "sample_basenames": [],
+                },
+            )
+            folder_row["clip_count"] += 1
+            if basename and basename not in folder_row["sample_basenames"] and len(folder_row["sample_basenames"]) < 8:
+                folder_row["sample_basenames"].append(basename)
+
+    unique_items = list(by_media_pool_item.values())
+    missing_volume_rows = list(missing_volumes.values())
+    missing_folder_rows = list(missing_folders.values())
+    absent_volumes = [row for row in missing_volume_rows if not row.get("mounted")]
+    absent_folders = [row for row in missing_folder_rows if not row.get("exists")]
+    primary_cause = "none"
+    recommended_next_step = "No offline media detected."
+    if absent_volumes:
+        primary_cause = "volume_not_mounted"
+        labels = ", ".join(row["volume_root_sanitized"] for row in absent_volumes[:3])
+        recommended_next_step = f"Mount the missing volume(s): {labels}."
+    elif absent_folders:
+        primary_cause = "folder_not_found"
+        labels = ", ".join(row["folder_sanitized"] for row in absent_folders[:3])
+        recommended_next_step = f"Attach or locate the missing media folder(s): {labels}."
+    elif unique_items:
+        primary_cause = "files_missing_or_renamed"
+        recommended_next_step = "Search approved media roots for the wanted basenames, then relink with media_pool.safe_relink."
+
+    return {
+        "unique_media_pool_item_count": len(unique_items),
+        "timeline_occurrence_count": len(missing_rows),
+        "primary_cause": primary_cause,
+        "recommended_next_step": recommended_next_step,
+        "missing_volumes": missing_volume_rows,
+        "missing_folders": missing_folder_rows,
+        "unique_media_pool_items": unique_items,
+        "sanitized": True,
+    }
+
+
 def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
     missing = []
     present = []
@@ -5210,12 +5327,80 @@ def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
                     missing.append(row)
                 else:
                     present.append(row)
-    return {"missing": missing, "present_count": len(present), "missing_count": len(missing)}
+    diagnosis = _missing_media_diagnosis(missing)
+    return {
+        "missing": missing,
+        "present_count": len(present),
+        "missing_count": len(missing),
+        "diagnosis": diagnosis,
+    }
 
 
 def _detect_missing_media(tl, p: Dict[str, Any]):
     snapshot = _timeline_conform_snapshot(tl, {**p, "include_clip_properties": True})
-    return _detect_missing_media_from_snapshot(snapshot)
+    report = _detect_missing_media_from_snapshot(snapshot)
+    if p.get("sanitize_paths") or p.get("sanitized"):
+        report = dict(report)
+        report["missing"] = [
+            {
+                **row,
+                "file_path_sanitized": _sanitize_media_path(row.get("file_path")),
+                "file_path": None if p.get("omit_raw_paths", True) else row.get("file_path"),
+            }
+            for row in report.get("missing", [])
+        ]
+    return report
+
+
+def _bounded_basename_matches(
+    wanted: str,
+    search_roots: List[str],
+    p: Dict[str, Any],
+) -> Tuple[List[str], Dict[str, Any]]:
+    started = time.monotonic()
+    max_seconds = float(p.get("max_seconds", p.get("timeout_seconds", 20)) or 20)
+    max_files = int(p.get("max_files_scanned", p.get("maxFilesScanned", 50000)) or 50000)
+    max_depth_raw = p.get("max_depth", p.get("maxDepth"))
+    max_depth = int(max_depth_raw) if max_depth_raw is not None else None
+    all_matches = bool(p.get("all_matches", False))
+    matches: List[str] = []
+    files_scanned = 0
+    dirs_scanned = 0
+    stopped_reason = None
+
+    for root in search_roots:
+        root_depth = len(os.path.abspath(root).rstrip(os.sep).split(os.sep))
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirs_scanned += 1
+            if max_depth is not None:
+                current_depth = len(os.path.abspath(dirpath).rstrip(os.sep).split(os.sep)) - root_depth
+                if current_depth >= max_depth:
+                    dirnames[:] = []
+            files_scanned += len(filenames)
+            if wanted in filenames:
+                matches.append(os.path.join(dirpath, wanted))
+                if not all_matches:
+                    return matches, {
+                        "files_scanned": files_scanned,
+                        "dirs_scanned": dirs_scanned,
+                        "stopped_reason": "first_match",
+                    }
+            if files_scanned >= max_files:
+                stopped_reason = "max_files_scanned"
+                break
+            if time.monotonic() - started >= max_seconds:
+                stopped_reason = "max_seconds"
+                break
+        if matches and not all_matches:
+            break
+        if stopped_reason:
+            break
+
+    return matches, {
+        "files_scanned": files_scanned,
+        "dirs_scanned": dirs_scanned,
+        "stopped_reason": stopped_reason,
+    }
 
 
 def _build_relink_plan(tl, p: Dict[str, Any]):
@@ -5226,26 +5411,55 @@ def _build_relink_plan(tl, p: Dict[str, Any]):
     if invalid:
         return _err(f"search_roots must be existing directories: {invalid}")
     missing_report = _detect_missing_media(tl, p)
+    diagnosis = missing_report.get("diagnosis") or _missing_media_diagnosis(missing_report.get("missing", []))
+    if p.get("skip_search_when_volume_missing", True) and any(
+        not row.get("mounted") for row in diagnosis.get("missing_volumes", [])
+    ):
+        return {
+            "success": True,
+            "dry_run": True,
+            "search_skipped": True,
+            "skip_reason": "missing_source_volume_not_mounted",
+            "search_roots": [_sanitize_media_path(root, keep_filename=False) for root in search_roots],
+            "candidate_count": 0,
+            "missing_count": missing_report.get("missing_count", 0),
+            "diagnosis": diagnosis,
+            "candidates": [],
+            "execution_note": "Mount the missing source volume or pass skip_search_when_volume_missing=false to scan approved roots.",
+        }
     candidates = []
+    rows_by_basename: Dict[str, List[Dict[str, Any]]] = {}
     for row in missing_report.get("missing", []):
         wanted = os.path.basename(str(row.get("file_path") or row.get("media_pool_item_name") or row.get("name") or ""))
+        if wanted:
+            rows_by_basename.setdefault(wanted, []).append(row)
+    for wanted, rows in rows_by_basename.items():
+        row = rows[0]
         matches = []
+        scan = {"files_scanned": 0, "dirs_scanned": 0, "stopped_reason": None}
         if wanted:
-            for root in search_roots:
-                for dirpath, _, filenames in os.walk(root):
-                    if wanted in filenames:
-                        matches.append(os.path.join(dirpath, wanted))
-                        if not p.get("all_matches", False):
-                            break
-                if matches and not p.get("all_matches", False):
-                    break
-        candidates.append({**row, "wanted_basename": wanted, "candidate_paths": matches, "candidate_count": len(matches)})
+            matches, scan = _bounded_basename_matches(wanted, search_roots, p)
+        sanitized_matches = [_sanitize_media_path(path) for path in matches]
+        candidates.append(
+            {
+                **row,
+                "wanted_basename": wanted,
+                "timeline_occurrence_count": len(rows),
+                "candidate_paths": [] if p.get("sanitize_paths") or p.get("sanitized") else matches,
+                "candidate_paths_sanitized": sanitized_matches,
+                "candidate_count": len(matches),
+                "scan": scan,
+            }
+        )
     return {
         "success": True,
         "dry_run": True,
-        "search_roots": search_roots,
+        "search_roots": [] if p.get("sanitize_paths") or p.get("sanitized") else search_roots,
+        "search_roots_sanitized": [_sanitize_media_path(root, keep_filename=False) for root in search_roots],
         "candidate_count": sum(1 for row in candidates if row["candidate_count"]),
         "missing_count": missing_report.get("missing_count", 0),
+        "unique_missing_basename_count": len(candidates),
+        "diagnosis": diagnosis,
         "candidates": candidates,
         "execution_note": "Review this plan, then use media_pool.safe_relink with explicit synthetic or approved paths if desired.",
     }
@@ -8373,6 +8587,13 @@ def _has_any_param(p: Dict[str, Any], *keys: str) -> bool:
     return any(key in p and p[key] is not None for key in keys)
 
 
+def _media_analysis_vision_options(enabled: bool) -> Dict[str, Any]:
+    options = {"enabled": bool(enabled)}
+    if enabled:
+        options["provider"] = HOST_CHAT_PATHS_PROVIDER
+    return options
+
+
 def _media_analysis_transcription_options(enabled: bool) -> Dict[str, Any]:
     options = {"enabled": bool(enabled)}
     if enabled:
@@ -8596,20 +8817,21 @@ def _media_analysis_apply_setup_defaults(action: str, p: Dict[str, Any]) -> Dict
 
     if action in {"plan", "analyze_file", "analyze_clip", "analyze_bin", "analyze_project", "analyze_timeline", "analyze_sequence", "start_batch_job", "review_timeline_markers", "publish_clip_metadata"}:
         include_visuals = _first_param(out, "include_visuals", "includeVisuals")
-        if not _has_any_param(out, "vision"):
+        if isinstance(out.get("vision"), bool):
+            out["vision"] = _media_analysis_vision_options(out["vision"])
+            applied["vision_shorthand"] = out["vision"]["enabled"]
+        elif not _has_any_param(out, "vision"):
             if include_visuals is not None:
                 visuals_enabled = _media_analysis_bool(include_visuals, True)
-                out["vision"] = {"enabled": visuals_enabled}
-                if visuals_enabled:
-                    out["vision"]["provider"] = HOST_CHAT_PATHS_PROVIDER
+                out["vision"] = _media_analysis_vision_options(visuals_enabled)
                 applied["include_visuals"] = visuals_enabled
             else:
                 vision_default = prefs.get("vision_default")
                 if vision_default == "on":
-                    out["vision"] = {"enabled": True, "provider": HOST_CHAT_PATHS_PROVIDER}
+                    out["vision"] = _media_analysis_vision_options(True)
                     applied["vision_default"] = vision_default
                 elif vision_default in {"off", "technical_only"}:
-                    out["vision"] = {"enabled": False}
+                    out["vision"] = _media_analysis_vision_options(False)
                     applied["vision_default"] = vision_default
         include_transcription = _first_param(out, "include_transcription", "includeTranscription")
         if not _has_any_param(out, "transcription"):
@@ -12862,9 +13084,47 @@ def _render_formats(proj):
     return _ser(formats)
 
 
-def _render_codecs(proj, fmt: str):
+def _render_format_id_from_formats(formats: Any, fmt: str) -> str:
+    if not isinstance(fmt, str) or not fmt or not isinstance(formats, dict):
+        return fmt
+    if fmt in formats:
+        return formats.get(fmt) or fmt
+    if fmt in formats.values():
+        return fmt
+    needle = fmt.lower()
+    for label, format_id in formats.items():
+        label_text = str(label)
+        id_text = str(format_id)
+        if label_text.lower() == needle:
+            return id_text or fmt
+        if id_text.lower() == needle:
+            return id_text
+    return fmt
+
+
+def _render_format_id(proj, fmt: str, formats: Optional[Dict[str, Any]] = None) -> str:
+    if formats is None:
+        formats = _render_formats(proj)
+    return _render_format_id_from_formats(formats, fmt)
+
+
+def _render_format_requested(requested: Optional[List[Any]], label: str, extension: Any, format_id: str, formats: Dict[str, Any]) -> bool:
+    if not requested:
+        return True
+    extension_text = str(extension)
+    for item in requested:
+        if item == label or item == extension or item == format_id:
+            return True
+        if isinstance(item, str) and _render_format_id_from_formats(formats, item) == format_id:
+            return True
+        if isinstance(item, str) and item.lower() in {label.lower(), extension_text.lower(), format_id.lower()}:
+            return True
+    return False
+
+
+def _render_codecs(proj, fmt: str, formats: Optional[Dict[str, Any]] = None):
     try:
-        return _ser(proj.GetRenderCodecs(fmt) or {})
+        return _ser(proj.GetRenderCodecs(_render_format_id(proj, fmt, formats)) or {})
     except Exception as exc:
         return {"error": str(exc)}
 
@@ -12909,10 +13169,11 @@ def _probe_render_matrix(proj, p: Dict[str, Any]):
     pair_count = 0
     errors = []
     for fmt, extension in formats.items():
-        if requested and fmt not in requested:
+        format_id = _render_format_id_from_formats(formats, fmt)
+        if not _render_format_requested(requested, fmt, extension, format_id, formats):
             continue
-        codecs = _render_codecs(proj, fmt)
-        format_row = {"format": fmt, "extension": extension, "codecs": [], "codec_count": 0}
+        codecs = _render_codecs(proj, format_id, formats)
+        format_row = {"format": fmt, "extension": extension, "format_id": format_id, "codecs": [], "codec_count": 0}
         if isinstance(codecs, dict) and codecs.get("error"):
             format_row["error"] = codecs["error"]
             errors.append({"format": fmt, "error": codecs["error"]})
@@ -12925,11 +13186,11 @@ def _probe_render_matrix(proj, p: Dict[str, Any]):
                     break
                 row = {"label": label, "codec": codec}
                 try:
-                    row["resolutions"] = _ser(proj.GetRenderResolutions(fmt, codec) or [])
+                    row["resolutions"] = _ser(proj.GetRenderResolutions(format_id, codec) or [])
                     row["resolution_count"] = len(row["resolutions"])
                 except Exception as exc:
                     row["error"] = str(exc)
-                    errors.append({"format": fmt, "codec": codec, "error": str(exc)})
+                    errors.append({"format": fmt, "format_id": format_id, "codec": codec, "error": str(exc)})
                 format_row["codecs"].append(row)
                 pair_count += 1
         matrix.append(format_row)
@@ -13057,7 +13318,7 @@ def _prepare_render_job(proj, p: Dict[str, Any]):
     before = _render_settings_snapshot(proj)
     format_success = None
     if p.get("format") and p.get("codec"):
-        format_success = bool(proj.SetCurrentRenderFormatAndCodec(p["format"], p["codec"]))
+        format_success = bool(proj.SetCurrentRenderFormatAndCodec(_render_format_id(proj, p["format"]), p["codec"]))
     settings_success = bool(proj.SetRenderSettings(settings))
     job_id = proj.AddRenderJob() if settings_success else None
     return {
@@ -13208,17 +13469,17 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
     elif action == "get_formats":
         return {"formats": _ser(proj.GetRenderFormats())}
     elif action == "get_codecs":
-        return {"codecs": _ser(proj.GetRenderCodecs(p["format"]))}
+        return {"codecs": _render_codecs(proj, p["format"])}
     elif action == "get_format_and_codec":
         return _ser(proj.GetCurrentRenderFormatAndCodec())
     elif action == "set_format_and_codec":
-        return {"success": bool(proj.SetCurrentRenderFormatAndCodec(p["format"], p["codec"]))}
+        return {"success": bool(proj.SetCurrentRenderFormatAndCodec(_render_format_id(proj, p["format"]), p["codec"]))}
     elif action == "get_mode":
         return {"mode": proj.GetCurrentRenderMode()}
     elif action == "set_mode":
         return {"success": bool(proj.SetCurrentRenderMode(p["mode"]))}
     elif action == "get_resolutions":
-        return {"resolutions": _ser(proj.GetRenderResolutions(p["format"], p["codec"]))}
+        return {"resolutions": _ser(proj.GetRenderResolutions(_render_format_id(proj, p["format"]), p["codec"]))}
     elif action == "get_settings":
         missing = _requires_method(proj, "GetRenderSettings", "unknown")
         if missing:
@@ -15298,8 +15559,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       import_timeline_checked(path, options?, timeline_name?, import_source_clips?, require_temp_path?, dry_run?) -> {success, name, id}
       compare_timelines(right_timeline_id?|right_timeline_index?|left_snapshot?, right_snapshot?) -> {match, differences}
       probe_interchange_roundtrip(format?, output_dir?, cleanup_imported?) -> {success, export, import, comparison}
-      detect_missing_media() -> {missing, missing_count}
-      build_relink_plan(search_roots) -> {candidates}
+      detect_missing_media(sanitized?|sanitize_paths?, omit_raw_paths?) -> {missing, missing_count, diagnosis}
+      build_relink_plan(search_roots, max_depth?, max_seconds?, max_files_scanned?, skip_search_when_volume_missing?, sanitized?) -> {candidates, diagnosis}
       conform_boundary_report(...) -> {capabilities, timeline, gaps_overlaps, source_ranges, missing_media}
       audio_capabilities() -> {supported, partially_supported, unsupported}
       probe_audio_item(track_type?, track_index?, item_index?) -> {summary, audio_properties, source_audio_mapping}
@@ -15914,7 +16175,14 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
         it = tl.GetCurrentVideoItem()
         return {"name": it.GetName(), "id": it.GetUniqueId()} if it else {"name": None, "id": None}
     elif action == "get_thumbnail":
-        return _ser(tl.GetCurrentClipThumbnailImage())
+        thumbnail = tl.GetCurrentClipThumbnailImage()
+        if thumbnail is None:
+            return {
+                "success": False,
+                "thumbnail": None,
+                "error": "Resolve did not return a thumbnail for the current playhead. Open the Color page and ensure a video item is under the playhead.",
+            }
+        return _ser(thumbnail)
     elif action == "get_thumbnail_image":
         thumbnail = tl.GetCurrentClipThumbnailImage()
         if not thumbnail: