davinci-resolve-mcp 2.103.1 → 2.103.3

package/CHANGELOG.md

@@ -2,6 +2,125 @@
 
 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.103.3
+
+**A batch transcription fix that would have failed every clip.** Issue #160 by
+@techsolvehq-source was real and precisely reported: a Whisper transcription that
+hit the 90s wall-clock cap already returned `success: False`, but
+`execute_plan_async` then hard-set `clip_result["success"] = True`, so the batch
+job counted the clip as succeeded, closed as `completed`, and left `last_error`
+unset. PR #161 by @Steve0x2a fixed that by giving transcription the failure
+annotation vision already had.
+
+The gate it landed with keyed on `success` alone, and that is where it went wrong.
+Transcription is enabled by default, and `allow_model_download` is off by default,
+so `_transcribe` returns `success: False, status: "skipped"` on a stock install —
+no Whisper backend, or one the user has not opted into model downloads for. Every
+clip of every batch would have been marked failed and no batch job could have
+reached `completed`. Vision can treat every non-success as a failure because
+vision defaults to *disabled*; transcription cannot.
+
+So the failure class is now drawn by status rather than by `success`: skipped,
+disabled, and not_implemented mean the backend never ran, while timeouts, caps
+refusals, and backend errors are real failures. The original timeout bug stays
+fixed.
+
+**Antigravity's config path, settled without picking a winner.** Issue #159 by
+@KMiNT21 reports `~/.gemini/config/mcp_config.json`; commit 85afe82 wrote
+`~/.gemini/antigravity/mcp_config.json`. Neither is verifiable from macOS, and
+swapping one unverifiable path for another is a coin flip that breaks it for
+whichever contributor was right — this repo has already been bitten by a
+documented-but-decoy config path (Claude Desktop MSIX, issue #93). The installer
+now probes: `~/.gemini/config/` first, because the installer has never written
+there, so that file existing is evidence something else created it. It looks for
+the file rather than the directory, since `~/.gemini/antigravity/` holds runtime
+state on every install.
+
+### Fixed
+
+- A transcription backend that is unavailable, disabled, or not implemented no
+  longer marks a batch clip failed. `transcription_attempt_failed` in
+  `src/utils/media_analysis.py` screens the "never ran" statuses out of the
+  failure class; timeouts, caps refusals, and backend errors stay in it.
+- Whisper wall-clock timeouts are reported as failed batch clips instead of
+  silently succeeding (#160, PR #161 by @Steve0x2a).
+- `install.py` resolves Antigravity's MCP config path from what is on disk
+  instead of a hard-coded guess (#159).
+- `scripts/gen_api_limitations.py --help` prints usage instead of silently
+  overwriting the generated report (PR #163 by @diesdaas).
+
+### Changed
+
+- The read/write symmetry audit resolves `_unknown(action, ...)` groups through
+  the AST rather than a regex, so action lists expressed as named, starred,
+  annotated, or concatenated module constants are now scanned. This surfaced a
+  genuine readback gap (`set_clip_marks`) the regex was missing, and known
+  readback aliases such as `get_cache_enabled` and `mcp_update_status` no longer
+  register as false gaps (PR #162 by @diesdaas).
+- `scripts/audit_readwrite_symmetry.py` writes `docs/reference/readwrite-symmetry.md`
+  by default and gains `--check` and `--stdout`, matching the
+  `gen_api_limitations.py` convention. The report is pinned to `src/server.py` by
+  a drift guard, so it needed a regeneration path: the check now runs in the
+  release checklist, and both the script and the failing test name the command
+  that clears it.
+
+## What's New in v2.103.2
+
+**A Windows setup that failed with nothing to read.** Reported in issue #158 by
+@KMiNT21 on a machine carrying both Python 3.12 and 3.13: `npx davinci-resolve-mcp`
+exited without a traceback, a log line, or an error. Three defects compounded.
+
+The first is the one that mattered. The npm launcher tested for the Windows `py`
+launcher with `py --version`, and that result gated the entire `py -3.12 / -3.11 /
+-3.10` candidate list. `py` does not accept `--version` on every build — it exits
+101 on the ones it does not — so on those machines the probe reported no launcher,
+every version-pinned candidate was discarded, and selection fell through to bare
+`python`: the 3.13 that the candidate ordering exists specifically to avoid. The
+3.13 protections added in v2.26.1 were not wrong; they were being skipped past.
+
+The fix removes the probe rather than correcting its flag. `checkPython()` already
+validates each candidate by running it, so a machine without `py` costs one failed
+spawn. A probe that can produce a false negative earns its place only if something
+downstream cannot do without it, and nothing here needed it.
+
+### Fixed
+
+- `bin/davinci-resolve-mcp.mjs` no longer gates the `py -3.x` candidates behind a
+  `py --version` probe.
+- An access-violation exit is now explained instead of propagated bare. Windows
+  reports `STATUS_ACCESS_VIOLATION` as an exit code (`3221225477`, or `-1073741819`
+  read signed), not as a signal — the interpreter dies inside the native library
+  with no chance to print. Both the launcher and `install.py`'s connection probe now
+  name the code, say why there is no traceback, and give the remedy. Previously the
+  probe could only report `Process exited with code 3221225477`.
+- `scripts/doctor.py` consults the runtime discovery helpers when every candidate
+  path misses, so Resolve installed off the conventional root (the reporter had it
+  on `D:`) is found rather than reported as four FAILs on a machine `install.py` had
+  just configured correctly. Same shape as issue #106.
+- `scripts/doctor.py` no longer reports a client config as `missing` because of path
+  escaping. A Windows path written into JSON comes back with doubled separators, and
+  the literal substring test could never match it — a false negative in the tool
+  whose job is to say whether setup worked.
+
+### Not changed
+
+Python 3.13 is still permitted. The policy set in v2.26.1 is a 3.10 floor with no
+cap — warn, do not block — and issue #158 proposed enforcing 3.10-3.12 on Windows.
+The candidate ordering already prefers the lower-risk interpreters; the bug was that
+ordering being bypassed, which is now fixed.
+
+### Coverage and its limits
+
+`tests/test_windows_python_crash.py` pins the launcher's candidate shape and the
+crash-code translation; `tests/test_doctor_paths.py` gains the discovery and
+path-escaping cases. All were confirmed to fail against the unfixed code.
+
+What is **not** covered, and is not coverable from macOS: whether `py --version`
+actually fails on any given Windows build. That claim comes from the reporter. The
+fix does not rest on it — it removes the probe rather than correcting it, so the
+code no longer has an opinion either way. The access-violation paths are likewise
+tested by injecting the exit code, not by producing a real crash.
+
 ## What's New in v2.103.1
 
 **A loudness measurement could silently become a single frame's reading.**

package/README.md

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

package/bin/davinci-resolve-mcp.mjs

@@ -179,14 +179,6 @@ function syncManagedInstall(root) {
   return root;
 }
 
-function commandExists(command, args = []) {
-  const result = spawnSync(command, [...args, "--version"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  return result.status === 0;
-}
-
 function parseExecutable(value) {
   if (!value) {
     return null;
@@ -207,7 +199,14 @@ function pythonCandidates() {
   // Prefer the lowest-ABI-risk interpreters first, then newer ones, then the
   // generic launchers. All 3.10+ are accepted; ordering just picks the safest
   // when several are installed.
-  if (process.platform === "win32" && commandExists("py")) {
+  // No existence probe in front of these. `py --version` is not a reliable
+  // one — the Windows launcher does not accept it on every build, and it
+  // exits 101 on the ones it does not (issue #158). A probe that gets that
+  // wrong discards every version-pinned candidate below and falls through to
+  // bare `python`, which is exactly the 3.13 the ordering exists to avoid.
+  // checkPython() runs each candidate anyway, so a missing `py` costs one
+  // failed spawn and is skipped.
+  if (process.platform === "win32") {
     candidates.push(
       { command: "py", args: ["-3.12"] },
       { command: "py", args: ["-3.11"] },
@@ -317,6 +316,24 @@ function venvPython(root) {
   return info;
 }
 
+// Windows reports a hard access violation as the process exit code, not as a
+// signal and not as a traceback: the interpreter is gone before it can say
+// anything. Loading Resolve's fusionscript under a Python its C ABI does not
+// match is one way to get there, so name that possibility rather than letting
+// the run end in a bare unexplained code (issue #158).
+const WINDOWS_ACCESS_VIOLATION = [3221225477, -1073741819];
+
+function accessViolationNote(code) {
+  return [
+    `The Python process was terminated by an access violation (0x${(code >>> 0).toString(16).toUpperCase()}).`,
+    "It crashed inside a native library before it could report anything, so there is no traceback above.",
+    "The usual cause is Resolve's scripting library being loaded by a Python whose C ABI it was not built",
+    "against. If you are on Python 3.13+, install Python 3.10-3.12 and pin it:",
+    "  DAVINCI_RESOLVE_MCP_PYTHON=C:\\Path\\To\\python3.12.exe",
+    "then re-run setup so the managed venv is rebuilt on that interpreter.",
+  ].join("\n");
+}
+
 function run(command, args, options = {}) {
   const child = spawn(command, args, {
     cwd: options.cwd,
@@ -329,6 +346,9 @@ function run(command, args, options = {}) {
       process.kill(process.pid, signal);
       return;
     }
+    if (WINDOWS_ACCESS_VIOLATION.includes(code)) {
+      console.error(accessViolationNote(code));
+    }
     process.exit(code ?? 1);
   });
   child.on("error", (error) => {

package/docs/install.md

@@ -86,6 +86,7 @@ The installer can automatically configure any of these clients:
 
 | Client | Config Written To |
 |--------|-------------------|
+| Antigravity (Google) | `~/.gemini/config/mcp_config.json`, or `~/.gemini/antigravity/mcp_config.json` if that file already exists (all platforms) |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS); `%APPDATA%\Claude\claude_desktop_config.json` (Windows, see MSIX note below) |
 | Claude Code | `.mcp.json` (project root) |
 | Cursor | `~/.cursor/mcp.json` |

package/docs/process/release-process.md

@@ -73,6 +73,7 @@ venv/bin/python tests/test_import.py
 npm install --package-lock-only --no-audit --no-fund   # re-stage package-lock.json if it moved
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
+venv/bin/python scripts/audit_readwrite_symmetry.py --check
 node scripts/agent-rules/generate.mjs --check
 venv/bin/python -m unittest tests.test_static_undefined_names tests.test_duplicate_definitions tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
 node bin/davinci-resolve-mcp.mjs --help

package/docs/reference/readwrite-symmetry.md

@@ -2,24 +2,21 @@
 
 # Read/Write Symmetry Audit
 
-- write-style actions scanned: **106**
-- with a matching read: **57**
-- `set_` actions with no `get_`/`list_` (real readback gaps): **11**
+- write-style action occurrences scanned: **116**
+- write-style action occurrences with a matching read: **67**
+- distinct high-signal `set_` actions without a direct/known readback: **8**
 
-## High-signal gaps — `set_` with no read counterpart
+## High-signal gaps — `set_` with no direct/known readback
 
-- `set_cache`
 - `set_cdl`
+- `set_clip_marks`
 - `set_clips_linked`
 - `set_high_priority`
 - `set_keyframe_interpolation`
-- `set_mcp_update_policy`
 - `set_name`
 - `set_node_enabled`
 - `set_title_text`
-- `set_track_enable`
-- `set_track_lock`
 
-## Low-signal (create/add/insert/import — usually expected): 37
+## Low-signal (create/add/insert/apply/import — usually expected): 40 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_burnin`, `import_comp`, `import_folder`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.103.1"
+VERSION = "2.103.3"
 # 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
@@ -393,6 +393,33 @@ def vscode_global_storage():
         return xdg_config() / "Code" / "User" / "globalStorage"
 
 
+def antigravity_config():
+    """Antigravity's MCP config path, resolved by what is on disk (issue #159).
+
+    Two contributors report two different locations and neither is verifiable
+    from here: 85afe82 added ~/.gemini/antigravity/mcp_config.json, and #159
+    reports ~/.gemini/config/mcp_config.json, with ~/.gemini/antigravity/ being
+    runtime state (logs, crash reports, brain state). Swapping one unverifiable
+    path for the other is a coin flip that breaks it for whoever was right, and
+    this repo has already been bitten by a documented-but-decoy config path
+    (Claude Desktop MSIX, issue #93).
+
+    So probe instead of choosing. ~/.gemini/config/ is checked first because
+    the installer has never written there — if that file exists, something else
+    created it, which is real evidence. ~/.gemini/antigravity/mcp_config.json
+    may exist merely because an earlier run of this installer put it there.
+    With neither present, fall back to ~/.gemini/config/ as #159 documents.
+    """
+    candidates = (
+        home() / ".gemini" / "config" / "mcp_config.json",
+        home() / ".gemini" / "antigravity" / "mcp_config.json",
+    )
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]
+
+
 # Each client entry:
 #   id, name, config_path_fn, config_key, merge_strategy, notes
 # config_path_fn returns the path; config_key is the JSON key wrapping the server entry
@@ -402,7 +429,7 @@ MCP_CLIENTS = [
     {
         "id": "antigravity",
         "name": "Antigravity",
-        "get_path": lambda: home() / ".gemini" / "antigravity" / "mcp_config.json",
+        "get_path": antigravity_config,
         "config_key": "mcpServers",
         "notes": "Google's agentic AI coding assistant (VS Code fork)",
     },
@@ -1253,6 +1280,54 @@ def install_dependencies(venv_path, project_dir):
 
 # ─── Connection Verification ─────────────────────────────────────────────────
 
+#: Windows surfaces a hard access violation (STATUS_ACCESS_VIOLATION) as a
+#: process exit code. Both spellings appear in the wild: the unsigned value and
+#: the signed reading of the same 32 bits. The interpreter dies inside the
+#: native library, so there is no traceback and no stderr to report — without
+#: this translation the probe can only say "exited with code 3221225477",
+#: which is the shape issue #158 was reported as.
+WINDOWS_ACCESS_VIOLATION_CODES = (3221225477, -1073741819)
+
+
+def _version_parts(version):
+    """A `(major, minor, ...)` int tuple, or None if it cannot be read.
+
+    `is_abi_risk_python_version` unpacks `version[:2]`, so handing it the string
+    "3.13.3" yields `("3", ".")` and a quiet False — the interpreter most likely
+    to have caused the crash would be reported as not at risk. Normalizing here
+    means a caller cannot make that mistake by passing the obvious thing.
+    """
+    if version is None:
+        return None
+    if isinstance(version, str):
+        try:
+            return tuple(int(part) for part in version.split(".")[:3])
+        except ValueError:
+            return None
+    try:
+        return tuple(int(part) for part in tuple(version)[:3])
+    except (TypeError, ValueError):
+        return None
+
+
+def access_violation_message(returncode, version=None):
+    """Explain an access-violation exit, naming the ABI theory when it fits."""
+    text = (
+        "Python crashed with an access violation (0xC0000005) while loading "
+        "Resolve's scripting library — no traceback is possible, the process "
+        "was terminated by the OS."
+    )
+    parts = _version_parts(version)
+    if parts is None or is_abi_risk_python_version(parts):
+        text += (
+            " This is the signature of a C ABI mismatch: recreate the venv on "
+            "Python 3.10-3.12 (e.g. DAVINCI_RESOLVE_MCP_PYTHON=...\\python3.12.exe)."
+        )
+    else:
+        text += " Check that RESOLVE_SCRIPT_LIB names the library from your Resolve install."
+    return text
+
+
 def verify_resolve_connection(python_path, api_path, lib_path):
     """Try to import DaVinciResolveScript and connect."""
     if not api_path:
@@ -1311,6 +1386,12 @@ def verify_resolve_connection(python_path, api_path, lib_path):
         elif output.startswith("IMPORTED_OK:"):
             return True, "API module loaded (Resolve not running)"
         else:
+            if result.returncode in WINDOWS_ACCESS_VIOLATION_CODES:
+                try:
+                    version = _version_for_python(python_path)
+                except Exception:
+                    version = None
+                return False, access_violation_message(result.returncode, version)
             if output:
                 return False, output
             return False, f"Process exited with code {result.returncode}"
@@ -2219,7 +2300,10 @@ def main():
                     "             Point RESOLVE_SCRIPT_LIB at the fusionscript library inside your "
                     "Resolve install, or start Resolve and re-run setup."
                 )
-            if py_abi_risk:
+            if py_abi_risk and "0xC0000005" not in message:
+                # The access-violation message already carries this remedy, and
+                # states it as a diagnosis rather than a maybe. Do not follow it
+                # with a weaker restatement of itself.
                 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."

package/package.json

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

package/scripts/audit_readwrite_symmetry.py

@@ -7,15 +7,22 @@ asymmetries. The goal is to find write-without-read gaps before users have to
 the repeatable feature-discovery method behind R5.
 
 Reads the `_unknown(action, [...])` lists in src/server.py, which enumerate every
-action a tool accepts. Prints a markdown report.
+action a tool accepts. Writes docs/reference/readwrite-symmetry.md.
+
+`--check` verifies the committed report matches the current server surface; it is
+what tests/test_readwrite_audit.py and the release checklist gate on. `--stdout`
+prints the report instead of writing it.
 """
+import argparse
 import ast
 import os
-import re
 import sys
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 SERVER = os.path.join(ROOT, "src", "server.py")
+DOC_PATH = os.path.join(ROOT, "docs", "reference", "readwrite-symmetry.md")
+DOC_REL = os.path.relpath(DOC_PATH, ROOT)
+REGEN_COMMAND = "venv/bin/python scripts/audit_readwrite_symmetry.py"
 
 READ_PREFIXES = ("get_", "list_", "probe_", "is_", "has_", "find_")
 # `set_` is the high-signal class: a set with no get is a genuine readback gap.
@@ -24,20 +31,94 @@ READ_PREFIXES = ("get_", "list_", "probe_", "is_", "has_", "find_")
 HIGH_SIGNAL = ("set_",)
 LOW_SIGNAL = ("add_", "create_", "insert_", "apply_", "import_")
 
+STEM_READ_ALIASES = {
+    # Resolve's public names often use enable/lock verbs on writes but enabled/
+    # locked nouns on reads; keep the audit focused on real missing readbacks.
+    "cache": ("cache_enabled",),
+    "caps_preset": ("caps",),
+    "track_enable": ("track_enabled",),
+    "track_lock": ("track_locked",),
+}
+
+DIRECT_READ_ALIASES = {
+    # mcp_update_status returns the persisted prompt policy and effective
+    # decision, so set_mcp_update_policy has a direct readback without a get_
+    # name.
+    "mcp_update_policy": ("mcp_update_status",),
+}
+
+
+def _module_constants(tree: ast.Module):
+    """Collect module-level named assignments without evaluating the module."""
+    constants = {}
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, ast.AnnAssign):
+            targets = (node.target,)
+        else:
+            continue
+        for target in targets:
+            if isinstance(target, ast.Name):
+                constants[target.id] = node.value
+    return constants
+
+
+def _resolve_actions(expr, constants, seen=None):
+    """Resolve supported action-list expressions or return None."""
+    seen = set() if seen is None else seen
+    if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
+        return [expr.value]
+    if isinstance(expr, ast.Name):
+        if expr.id in seen or expr.id not in constants:
+            return None
+        return _resolve_actions(expr=constants[expr.id], constants=constants,
+                                 seen=seen | {expr.id})
+    if isinstance(expr, (ast.List, ast.Tuple)):
+        actions = []
+        for element in expr.elts:
+            if isinstance(element, ast.Starred):
+                element = element.value
+            resolved = _resolve_actions(element, constants, seen)
+            if resolved is None:
+                return None
+            actions.extend(resolved)
+        return actions
+    if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.Add):
+        left = _resolve_actions(expr.left, constants, seen)
+        right = _resolve_actions(expr.right, constants, seen)
+        if left is None or right is None:
+            return None
+        return left + right
+    return None
+
 
 def _action_lists(src: str):
-    """Yield lists of action-name string literals from each _unknown(action, [...])."""
-    for m in re.finditer(r"_unknown\(action,\s*\[(.*?)\]\)", src, re.DOTALL):
-        names = re.findall(r'"([a-z][a-z0-9_]*)"', m.group(1))
-        if names:
-            yield names
+    """Yield action lists passed to ``_unknown(action, ...)`` calls."""
+    tree = ast.parse(src)
+    constants = _module_constants(tree)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        if not (isinstance(node.func, ast.Name)
+                and node.func.id == "_unknown"
+                and len(node.args) >= 2
+                and isinstance(node.args[0], ast.Name)
+                and node.args[0].id == "action"):
+            continue
+        actions = _resolve_actions(node.args[1], constants)
+        if actions is not None:
+            yield actions
 
 
 def _has_read(stem: str, aset: set) -> bool:
     # Match get_<stem>, list_<stem>, and plural get_<stem>s (e.g. add_keyframe -> get_keyframes).
-    candidates = {rp + stem for rp in READ_PREFIXES}
-    candidates |= {rp + stem + "s" for rp in READ_PREFIXES}
-    candidates |= {rp + stem.rstrip("s") for rp in READ_PREFIXES}
+    stems = {stem, *STEM_READ_ALIASES.get(stem, ())}
+    candidates = set(DIRECT_READ_ALIASES.get(stem, ()))
+    for candidate_stem in stems:
+        candidates |= {rp + candidate_stem for rp in READ_PREFIXES}
+        candidates |= {rp + candidate_stem + "s" for rp in READ_PREFIXES}
+        candidates |= {rp + candidate_stem.rstrip("s") for rp in READ_PREFIXES}
     return bool(candidates & aset)
 
 
@@ -60,19 +141,76 @@ def audit(src: str):
     return total, covered, sorted(high), sorted(low)
 
 
-def main():
-    src = open(SERVER, encoding="utf-8").read()
+def render_report(src: str) -> str:
     total, covered, high, low = audit(src)
-    print("# Read/Write Symmetry Audit\n")
-    print(f"- write-style actions scanned: **{total}**")
-    print(f"- with a matching read: **{covered}**")
-    print(f"- `set_` actions with no `get_`/`list_` (real readback gaps): **{len(high)}**\n")
+    lines = [
+        "<!-- Generated by scripts/audit_readwrite_symmetry.py — do not edit by hand. -->",
+        "",
+        "# Read/Write Symmetry Audit",
+        "",
+        f"- write-style action occurrences scanned: **{total}**",
+        f"- write-style action occurrences with a matching read: **{covered}**",
+        f"- distinct high-signal `set_` actions without a direct/known readback: **{len(high)}**",
+        "",
+    ]
     if high:
-        print("## High-signal gaps — `set_` with no read counterpart\n")
+        lines += [
+            "## High-signal gaps — `set_` with no direct/known readback",
+            "",
+        ]
         for a in high:
-            print(f"- `{a}`")
-    print(f"\n## Low-signal (create/add/insert/import — usually expected): {len(low)}\n")
-    print(", ".join(f"`{a}`" for a in low))
+            lines.append(f"- `{a}`")
+    lines += [
+        "",
+        f"## Low-signal (create/add/insert/apply/import — usually expected): "
+        f"{len(low)} distinct names",
+        "",
+        ", ".join(f"`{a}`" for a in low),
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _parse_args(argv):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="fail if the committed report is out of date",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print the report instead of writing it",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = _parse_args(argv)
+    with open(SERVER, encoding="utf-8") as fh:
+        src = fh.read()
+    content = render_report(src)
+    if args.stdout:
+        print(content, end="")
+        return 0
+    if args.check:
+        current = ""
+        if os.path.exists(DOC_PATH):
+            with open(DOC_PATH, encoding="utf-8") as fh:
+                current = fh.read()
+        if current != content:
+            print(
+                f"STALE: {DOC_REL} is out of date.\nRun: {REGEN_COMMAND}",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"OK: {DOC_REL} is up to date.")
+        return 0
+    with open(DOC_PATH, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    print(f"Wrote {DOC_REL}")
     return 0
 
 

package/scripts/doctor.py

@@ -95,13 +95,64 @@ def _platform_key(platform: str | None = None) -> str:
     return "linux"
 
 
+def _discovered_default(kind: str) -> str | None:
+    """Ask the runtime helpers where Resolve actually is.
+
+    The candidate table above is a table of *conventional* locations. Resolve is
+    routinely installed somewhere else — a second drive is the common case,
+    because the application and its caches are large (issue #158 reported
+    `D:\\Programs\\DaVinci Resolve`). install.py already looks past the table
+    via these helpers; doctor did not, so it reported FAIL on installs the
+    installer had just configured correctly. That disagreement between two tools
+    describing one machine is the same failure shape as issue #106.
+
+    Only consulted when no candidate exists, and only for the two kinds the
+    helpers can answer. `api` has no discovery helper, so a non-default install
+    can still miss there — worth knowing when reading a report.
+    """
+    if str(REPO) not in sys.path:
+        # doctor is run standalone (`python scripts/doctor.py`) as often as it is
+        # run through the launcher, and only the latter puts the repo on the path.
+        sys.path.insert(0, str(REPO))
+
+    if kind == "lib":
+        try:
+            from src.utils.platform import discover_scripting_lib
+        except Exception:
+            return None
+        try:
+            discovered = discover_scripting_lib()
+        except Exception:
+            return None
+        return str(discovered) if discovered and Path(discovered).exists() else None
+
+    if kind == "app":
+        try:
+            from src.utils.resolve_runtime import _executable_from_line, resolve_processes
+        except Exception:
+            return None
+        try:
+            processes = resolve_processes() or []
+        except Exception:
+            return None
+        for line in processes:
+            executable = _executable_from_line(line)
+            if executable and Path(executable).exists():
+                return str(executable)
+    return None
+
+
 def _resolve_default(kind: str, platform: str | None = None) -> str:
-    """First candidate of `kind` that exists, else the first (so the FAIL line
-    names the canonical location rather than an arbitrary miss)."""
+    """First candidate of `kind` that exists, then discovery, else the first
+    candidate (so the FAIL line names the canonical location rather than an
+    arbitrary miss)."""
     candidates = _RESOLVE_PATH_CANDIDATES[_platform_key(platform)][kind]
     for candidate in candidates:
         if Path(candidate).exists():
             return candidate
+    discovered = _discovered_default(kind)
+    if discovered:
+        return discovered
     return candidates[0]
 
 
@@ -170,11 +221,27 @@ def check(results: list[dict[str, str]], status: str, name: str, detail: str) ->
     results.append({"status": status, "name": name, "detail": detail})
 
 
+def _normalize_separators(text: str) -> str:
+    r"""Collapse every run of backslashes to a single forward slash.
+
+    A Windows path does not survive a literal substring test against the file it
+    was written into: JSON escapes `C:\Users\x` as `C:\\Users\\x`, and TOML
+    may keep it single-escaped or write a literal string. doctor compared the
+    unescaped path against the raw file text and so reported the entry missing
+    on configs it had itself just written (issue #158).
+
+    Collapsing runs — rather than only the doubled form — is what makes both
+    spellings compare equal, and normalizing the needle the same way keeps the
+    comparison symmetric.
+    """
+    return re.sub(r"\\+", "/", text)
+
+
 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]
+    text = _normalize_separators(path.read_text(errors="replace"))
+    missing = [needle for needle in needles if _normalize_separators(needle) not in text]
     if missing:
         return False, "missing: " + ", ".join(missing)
     return True, "contains davinci-resolve MCP entry"

package/scripts/gen_api_limitations.py

@@ -17,6 +17,7 @@ Run with ``--check`` to fail (exit 1) when the committed doc is stale.
 """
 from __future__ import annotations
 
+import argparse
 import sys
 from pathlib import Path
 
@@ -122,9 +123,22 @@ def render() -> str:
     return "\n".join(out).rstrip() + "\n"
 
 
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="fail if the committed report is out of date",
+    )
+    return parser.parse_args(argv)
+
+
 def main(argv: list[str]) -> int:
+    if argv is None:
+        raise TypeError("argv must not be None")
+    args = _parse_args(argv)
     content = render()
-    if "--check" in argv:
+    if args.check:
         current = DOC_PATH.read_text() if DOC_PATH.exists() else ""
         if current != content:
             print(

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.103.1"
+VERSION = "2.103.3"
 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.103.1"
+VERSION = "2.103.3"
 
 import base64
 import os

package/src/utils/media_analysis.py

@@ -200,6 +200,62 @@ def _annotate_clip_vision_failure(clip_result: Dict[str, Any], vision: Any) -> N
         })
 
 
+# Transcription statuses that mean "never attempted", as opposed to "attempted
+# and did not produce a transcript". Transcription is on by default
+# (DEFAULT_TRANSCRIPTION_ENABLED) and allow_model_download is off by default, so
+# a machine with no Whisper backend — or one that has simply not opted into model
+# downloads — reports "skipped" on every clip. Those are configuration states,
+# not clip failures, and counting them as failures fails every clip of every
+# batch on a default install.
+TRANSCRIPTION_UNATTEMPTED_STATUSES = frozenset({"skipped", "disabled", "not_implemented"})
+
+
+def transcription_attempt_failed(transcript: Any, *, enabled: bool) -> bool:
+    """True when requested transcription ran and still produced no transcript.
+
+    The vision counterpart is visual_analysis_completed, but vision defaults to
+    disabled, so it can treat every non-success as a failure. Transcription
+    defaults to enabled, so it has to separate "the backend refused to start" —
+    which is the normal state of an install without Whisper — from a real
+    failure such as a wall-clock timeout, a caps refusal, or a backend error.
+    """
+    if not enabled or not isinstance(transcript, dict):
+        return False
+    if transcript.get("success"):
+        return False
+    status = str(transcript.get("status") or "").strip().lower()
+    return status not in TRANSCRIPTION_UNATTEMPTED_STATUSES
+
+
+def _annotate_clip_transcript_failure(clip_result: Dict[str, Any], transcript: Any) -> None:
+    """Mark a clip failed when requested transcription did not complete.
+
+    execute_plan_async writes the analysis JSON and then hard-sets success True.
+    Vision already overwrites that via _annotate_clip_vision_failure; a
+    transcription timeout had no equivalent, so batch jobs counted an empty
+    transcript as succeeded. Callers gate on transcription_attempt_failed, which
+    keeps the "backend never ran" statuses out of the failure class.
+    """
+    status = ""
+    reason = ""
+    if isinstance(transcript, dict):
+        status = str(transcript.get("status") or "").strip()
+        reason = str(transcript.get("reason") or transcript.get("error") or "").strip()
+    if status == "wall_clock_timeout":
+        message = "Transcription timed out before a transcript was produced."
+        if reason:
+            message = f"{message} {reason}"
+    elif reason:
+        message = f"Transcription was requested but did not complete: {reason}"
+    else:
+        message = "Transcription was requested but did not complete."
+    clip_result.update({
+        "success": False,
+        "error": message,
+        "transcription": transcript,
+    })
+
+
 def _annotate_partial_success(manifest: Dict[str, Any]) -> None:
     """D3 — Mark batch manifests with explicit completed/failed clip-id lists.
 
@@ -5697,6 +5753,13 @@ async def execute_plan_async(
             and not vision_pending
             and not visual_analysis_completed(vision)
         )
+        transcript_failed = transcription_attempt_failed(
+            transcript,
+            enabled=_coerce_bool(
+                (options.get("transcription") or {}).get("enabled"),
+                default=DEFAULT_TRANSCRIPTION_ENABLED,
+            ),
+        )
         frame_count = int(clip_plan.get("analysis_keyframe_budget") or 0)
         marker_plan = _build_clip_marker_plan(
             record,
@@ -5757,6 +5820,8 @@ async def execute_plan_async(
             manifest["vision_pending"] = True
         elif vision_failed:
             _annotate_clip_vision_failure(clip_result, vision)
+        if transcript_failed:
+            _annotate_clip_transcript_failure(clip_result, transcript)
         manifest["clips"].append(clip_result)
 
     manifest["completed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

package/src/utils/media_analysis_jobs.py

@@ -745,6 +745,8 @@ def run_batch_job_slice(
                     _event(conn, job_id, "info", f"Clip {row['position'] + 1} {status}", {"clip": clip_result.get("record")})
                 else:
                     error = clip_result.get("error") or manifest.get("error") or "Clip analysis failed"
+                    if not isinstance(error, str):
+                        error = str(error)
                     conn.execute(
                         """
                         UPDATE job_clips
@@ -753,6 +755,10 @@ def run_batch_job_slice(
                         """,
                         (error, completed_at, completed_at, row["id"]),
                     )
+                    conn.execute(
+                        "UPDATE jobs SET last_error = ?, updated_at = ? WHERE job_id = ?",
+                        (error, completed_at, job_id),
+                    )
                     processed.append({"position": row["position"], "status": "failed", "error": error})
                     _event(conn, job_id, "error", f"Clip {row['position'] + 1} failed", {"error": error})
             except Exception as exc:  # pragma: no cover - defensive for arbitrary media/tool failures
@@ -766,6 +772,10 @@ def run_batch_job_slice(
                     (str(exc), completed_at, completed_at, row["id"]),
                 )
                 processed.append({"position": row["position"], "status": "failed", "error": str(exc)})
+                conn.execute(
+                    "UPDATE jobs SET last_error = ?, updated_at = ? WHERE job_id = ?",
+                    (str(exc), completed_at, job_id),
+                )
                 _event(conn, job_id, "error", f"Clip {row['position'] + 1} raised an exception", {"error": str(exc)})
             _sync_job_counts(conn, job_id)
             conn.commit()