davinci-resolve-mcp 2.214.0 → 2.214.2

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 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.214.2 — a running Resolve is counted by its executable path, not only by its argument vector
+
+### Fixed
+
+- **`resolve_control runtime_mode` could report `running: false, instances: 0`
+  while Resolve was up and answering scripting calls.** Seen on 2026-09-08
+  against Studio 19.1.3.7 at the stock macOS path, in the same minute
+  `get_version` connected. The scan read only `ps`'s argument-vector column
+  and required the line to *end* in the executable after flag stripping, so
+  it had a single point of failure that the exact trigger did not need to be
+  known to remove: the kernel withholds argv for some processes (`ps` prints
+  `(Resolve)`), a launch argument after the path — a project file — is not a
+  flag and defeated the suffix test, and `ps` was not asked for wide output.
+  The scan now reads two columns keyed by pid: the executable path (`comm`,
+  the full path on macOS, readable whenever the process is) decides whether an
+  instance exists; the argument vector decides its mode. An instance whose
+  argv cannot be read is counted with `headless: null` — never `false`, since
+  a wrong "it has a UI" is what makes an agent wait for a dialog that never
+  opens, and the tool's callers consult it before every project switch for
+  exactly that reason. `ps` is run with `-ww`. The "a shell line that merely
+  names the binary is not an instance" rule is kept and extended to the
+  unquoted `sh -c /opt/resolve/bin/resolve -nogui` shape.
+- **The exact 2026-09-08 condition was not reproduced.** The same install,
+  restarted, matched the old scan. The fix is a removal of the scan's
+  dependence on argv parsing, verified against a fake process table built
+  from the real `ps` rows of that machine (pid 39560 at the stock path, its
+  IOXPC helper beside it), plus the unreadable-argv, positional-argument,
+  wide-output and one-column-failing cases.
+
+### Validation
+
+- Seven new tests in `tests/test_headless_runtime.py` pin those cases; the
+  existing 29 pass unchanged against the new scan (their bare-command-line
+  fake tables are read as both columns of one process). Live on this machine:
+  `running: true, instances: 1, headless: false` at the stock path. Full
+  offline suite, drift guards and the advanced Node suite green.
+
+## What's New in v2.214.1 — grade calls fail silently off the Color page; apply_trace_plan switches for you
+
+### Fixed
+
+- **`apply_trace_plan` grades on the Color page and restores your page after.**
+  Measured on Studio 19.1.3.7 during the second live pass of the conform trace:
+  with the GUI on the Edit page, `TimelineItem.AddVersion` and
+  `Graph.ApplyGradeFromDRX` returned False for all 12 clips of a batch, with no
+  exception and no other signal; `OpenPage("color")` and nothing else, then 12
+  of 12 applied. The earlier 254-clip batch had succeeded only because the page
+  happened to be Color. The driver now reads `GetCurrentPage()` before the
+  batch, switches to Color, puts the page back afterwards, and reports
+  `page: {before, switched, restored}`; if the switch fails it refuses with
+  `PAGE_SWITCH_FAILED` before touching a clip.
+- **api_truth records the page dependence** ("TimelineItem.AddVersion /
+  Graph.ApplyGradeFromDRX (page-dependent)"), so the False can be told apart
+  from a bad `.drx` or a locked clip.
+
+### Live-validated
+
+- The 12 name-only matches from the v2.214.0 run (same files, sections the
+  source never graded) applied with `min_confidence: 0.6`: 12 of 12, version
+  `traced V07 Sizing` added per clip, node graphs read back with the source's
+  tools.
+
 ## What's New in v2.214.0 — color_trace reads exported .drp files, and the trace is live-validated
 
 ### Added

package/README.md

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

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.214.0"
+VERSION = "2.214.2"
 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.214.0"
+VERSION = "2.214.2"
 
 import base64
 import os
@@ -27194,28 +27194,62 @@ def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
     if blocked:
         return blocked
 
-    applied: List[Dict[str, Any]] = []
-    failed: List[Dict[str, Any]] = []
-    for r in to_apply:
-        item = r["_item"]
-        rec = {k: v for k, v in r.items() if not k.startswith("_")}
-        ok = False
+    # Measured on Studio 19.1.3.7 (2026-09-08): with the GUI on the EDIT page,
+    # TimelineItem.AddVersion and Graph.ApplyGradeFromDRX both return False for
+    # every clip — 12/12 failed, then 12/12 applied after OpenPage("color") with
+    # nothing else changed. Grade the batch on the color page and put the page
+    # back afterwards; refuse up front rather than hand back 254 "returned
+    # False" rows.
+    page: Dict[str, Any] = {"before": None, "switched": False, "restored": None}
+    resolve = get_resolve()
+    try:
+        page["before"] = resolve.GetCurrentPage() if resolve else None
+    except Exception as exc:
+        page["read_error"] = str(exc)
+    if page["before"] and page["before"] != "color":
         try:
-            if version_name:
-                # AddVersion switches the item to the NEW version, so the apply
-                # lands there and the previous version stays intact.
-                rec["version_added"] = bool(item.AddVersion(version_name, 0))
-            graph = item.GetNodeGraph()
-            if not _has_method(graph, "ApplyGradeFromDRX"):
-                rec["error"] = "item graph does not expose ApplyGradeFromDRX"
-            else:
-                ok = bool(graph.ApplyGradeFromDRX(r["drx_path"], grade_mode))
-                if not ok:
-                    rec["error"] = "ApplyGradeFromDRX returned False"
+            page["switched"] = bool(resolve.OpenPage("color"))
         except Exception as exc:
-            rec["error"] = str(exc)
-        rec["status"] = "applied" if ok else "failed"
-        (applied if ok else failed).append(rec)
+            page["switch_error"] = str(exc)
+        if not page["switched"]:
+            err = _err(
+                f"Resolve is on the {page['before']!r} page and could not switch to the color page; "
+                "AddVersion and ApplyGradeFromDRX return False from any other page (19.1.3.7).",
+                code="PAGE_SWITCH_FAILED", category="resolve_api_failed", retryable=True,
+                remediation="resolve_control(action='open_page', params={'page': 'color'}) then re-call.",
+            )
+            err["page"] = page
+            return err
+
+    applied: List[Dict[str, Any]] = []
+    failed: List[Dict[str, Any]] = []
+    try:
+        for r in to_apply:
+            item = r["_item"]
+            rec = {k: v for k, v in r.items() if not k.startswith("_")}
+            ok = False
+            try:
+                if version_name:
+                    # AddVersion switches the item to the NEW version, so the apply
+                    # lands there and the previous version stays intact.
+                    rec["version_added"] = bool(item.AddVersion(version_name, 0))
+                graph = item.GetNodeGraph()
+                if not _has_method(graph, "ApplyGradeFromDRX"):
+                    rec["error"] = "item graph does not expose ApplyGradeFromDRX"
+                else:
+                    ok = bool(graph.ApplyGradeFromDRX(r["drx_path"], grade_mode))
+                    if not ok:
+                        rec["error"] = "ApplyGradeFromDRX returned False"
+            except Exception as exc:
+                rec["error"] = str(exc)
+            rec["status"] = "applied" if ok else "failed"
+            (applied if ok else failed).append(rec)
+    finally:
+        if page["switched"]:
+            try:
+                page["restored"] = bool(resolve.OpenPage(page["before"]))
+            except Exception as exc:
+                page["restore_error"] = str(exc)
     summary.update({"applied": len(applied), "failed": len(failed)})
     skipped = [r for r in public if r["status"] != "apply"]
     report_path = _trace_report(p, plan, "apply", {"summary": summary, "applied": applied, "failed": failed, "skipped": skipped})
@@ -27224,6 +27258,7 @@ def _apply_trace_plan(p: Dict[str, Any]) -> Dict[str, Any]:
         "timeline": live_name,
         "plan_source": plan.get("source"),
         "report_path": report_path,
+        "page": page,
         "applied": _trace_compact(applied, max_rows),
         "failed": failed,  # never truncated: every failure is actionable
         "skipped": _trace_compact(skipped, max_rows),

package/src/utils/api_truth.py

@@ -1916,6 +1916,26 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "pass-through.",
         "tags": ["silent-failure", "color", "node-graph", "layout", "drx"],
     },
+    {
+        "symbol": "TimelineItem.AddVersion / Graph.ApplyGradeFromDRX (page-dependent)",
+        "object": "TimelineItem / Graph",
+        "signature": "AddVersion(name, type) -> bool; ApplyGradeFromDRX(path, gradeMode) -> bool",
+        "reality": "Both return False for every clip while the GUI sits on the "
+                   "EDIT page, with no exception and no other signal. Measured on "
+                   "Studio 19.1.3.7 (2026-09-08) on a live conform: 12 of 12 "
+                   "clips failed from the edit page, then 12 of 12 applied after "
+                   "OpenPage('color') with nothing else changed; an earlier "
+                   "254-clip batch on the same timeline had succeeded while the "
+                   "page was color. Read-side calls (GetNodeGraph, GetNumNodes, "
+                   "GetVersionNameList) answer normally from the edit page, so "
+                   "the False cannot be told apart from a bad .drx or a locked "
+                   "clip without checking the page.",
+        "recommended": "Read GetCurrentPage() before any grade mutation; OpenPage"
+                       "('color') for the batch and restore the page afterwards. "
+                       "timeline_item_color.apply_trace_plan does this itself and "
+                       "reports {page: {before, switched, restored}}.",
+        "tags": ["silent-failure", "color", "grade", "page", "drx", "version"],
+    },
     {
         "symbol": "MediaPool.AppendToTimeline clipInfo endFrame (exclusive bound)",
         "object": "MediaPool",

package/src/utils/resolve_runtime.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 
 import os
 import platform
+import re
 import subprocess
 from typing import Any, Dict, List, Optional
 
@@ -57,40 +58,103 @@ MACOS_RESOLVE_APPS = (
 )
 
 
-def _process_lines() -> Optional[List[str]]:
-    """Every running command line, or None when that cannot be determined.
+_PID_PREFIX = re.compile(r"^\s*(\d+)\s+(.*)$")
+
 
-    None rather than an empty list on failure: an unanswerable question must not
-    become "nothing is running", which is the answer that leads to launching a
-    second instance on top of a live one.
+def _run_ps(columns: str) -> Optional[List[str]]:
+    """`ps -Awwo <columns>` as lines, or None when it cannot be run.
+
+    `-ww` on purpose: without it BSD ps may cut long command lines to the
+    terminal width, and a cut line no longer ends in the executable. Not
+    reproduced here (the Resolve path is 70 characters), but the second-
+    instance guard should not depend on where a launch argument happens to
+    fall relative to a column limit.
     """
     try:
-        if platform.system().lower() == "windows":
-            # `tasklist` prints no command line, so the flag is invisible there.
-            # WMIC does print it and is what makes headless detection possible.
-            #
-            # Decoded explicitly: `text=True` alone decodes with the locale
-            # codepage, which raises UnicodeDecodeError on a byte cp1252 has no
-            # mapping for — and this read is the input to the second-instance
-            # guard, so it must fail to "cannot tell", never to an exception.
-            # ASCII is byte-identical under both codecs, so the matching this
-            # feeds is unchanged; what WMIC emits for a non-ASCII install path
-            # on a non-English Windows is not something we can verify here.
+        out = subprocess.run(
+            ["ps", "-Awwo", columns], capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=10, check=False,
+        )
+    except Exception:  # pragma: no cover - defensive; an unknown answer is None
+        return None
+    if out.returncode != 0 and not out.stdout:
+        return None
+    return (out.stdout or "").splitlines()
+
+
+def _split_pid(line: str, index: int):
+    """(pid, field) for a `pid=,<col>=` row; a row with no pid gets a synthetic one.
+
+    The synthetic pid is the row index, so two column listings of the same
+    length join row-by-row. That is what keeps a fake process table written as
+    bare command lines (the shape every existing test uses) meaningful: it is
+    read as both the executable column and the argv column of one process.
+    """
+    match = _PID_PREFIX.match(line)
+    if match:
+        return int(match.group(1)), match.group(2)
+    return -(index + 1), line
+
+
+def _process_table() -> Optional[List[Dict[str, Optional[str]]]]:
+    """One row per process: `{pid, comm, args}`, or None when undeterminable.
+
+    Two columns because they fail independently. `args` is the argument
+    vector, the only place `-nogui` is visible — but the kernel refuses to
+    expose it for some processes (ps prints `(Resolve)` in parentheses) and a
+    launch argument after the path breaks a suffix match on it. `comm` is the
+    executable path as the kernel knows it — on macOS the full path — and it
+    is readable whenever the process is. An instance is counted on EITHER;
+    the mode is read from argv when argv is readable.
+
+    None rather than an empty list on failure: an unanswerable question must
+    not become "nothing is running", which is the answer that leads to
+    launching a second instance on top of a live one.
+    """
+    if platform.system().lower() == "windows":
+        # `tasklist` prints no command line, so the flag is invisible there.
+        # WMIC does print it and is what makes headless detection possible.
+        #
+        # Decoded explicitly: `text=True` alone decodes with the locale
+        # codepage, which raises UnicodeDecodeError on a byte cp1252 has no
+        # mapping for — and this read is the input to the second-instance
+        # guard, so it must fail to "cannot tell", never to an exception.
+        # ASCII is byte-identical under both codecs, so the matching this
+        # feeds is unchanged; what WMIC emits for a non-ASCII install path
+        # on a non-English Windows is not something we can verify here.
+        try:
             out = subprocess.run(
                 ["wmic", "process", "where", "name='Resolve.exe'", "get", "CommandLine"],
                 capture_output=True, text=True, encoding="utf-8", errors="replace",
                 timeout=10, check=False,
             )
-        else:
-            out = subprocess.run(
-                ["ps", "-Ao", "command="], capture_output=True, text=True,
-                encoding="utf-8", errors="replace", timeout=10, check=False,
-            )
+        except Exception:  # pragma: no cover - defensive; an unknown answer is None
+            return None
         if out.returncode != 0 and not out.stdout:
             return None
-        return (out.stdout or "").splitlines()
-    except Exception:  # pragma: no cover - defensive; an unknown answer is None
+        return [{"pid": -(i + 1), "comm": None, "args": line}
+                for i, line in enumerate((out.stdout or "").splitlines())]
+
+    comm_lines = _run_ps("pid=,comm=")
+    args_lines = _run_ps("pid=,args=")
+    if comm_lines is None and args_lines is None:
         return None
+    rows: Dict[int, Dict[str, Optional[str]]] = {}
+    for index, line in enumerate(comm_lines or []):
+        pid, comm = _split_pid(line, index)
+        rows.setdefault(pid, {"pid": pid, "comm": None, "args": None})["comm"] = comm
+    for index, line in enumerate(args_lines or []):
+        pid, args = _split_pid(line, index)
+        rows.setdefault(pid, {"pid": pid, "comm": None, "args": None})["args"] = args
+    return list(rows.values())
+
+
+def _process_lines() -> Optional[List[str]]:
+    """Argument vectors of every process, kept for callers that read only argv."""
+    table = _process_table()
+    if table is None:
+        return None
+    return [row["args"] for row in table if row["args"] is not None]
 
 
 def _matches_pattern(executable: str) -> bool:
@@ -137,6 +201,22 @@ def _executable_from_line(line: str) -> str:
         close = text.find('"', 1)
         if close > 1:
             return text[1:close]
+    # A launch ARGUMENT after the path — a project file, most likely — is not a
+    # flag, so the flag-stripping loop below leaves it attached and the suffix
+    # test fails. If the line STARTS with a path that ends in a Resolve pattern
+    # at a token boundary, that path is the executable, whatever follows it.
+    # The prefix must contain no quote (a launcher quoting the path) and no
+    # flag token (`/bin/sh -c /opt/resolve/bin/resolve` names Resolve without
+    # being it), which keeps the "mere mention" cases out.
+    for pattern in RESOLVE_PROCESS_PATTERNS:
+        cut = text.find(pattern)
+        while cut != -1:
+            end = cut + len(pattern)
+            prefix = text[:end]
+            at_boundary = end == len(text) or text[end].isspace()
+            if at_boundary and '"' not in prefix and " -" not in prefix:
+                return prefix
+            cut = text.find(pattern, cut + 1)
     while True:
         stripped = text.rstrip()
         cut = stripped.rfind(" -")
@@ -151,12 +231,42 @@ def _executable_from_line(line: str) -> str:
     return text
 
 
+def _argv_unreadable(args: Optional[str]) -> bool:
+    """ps prints `(name)` when the kernel will not hand over the argument vector."""
+    if args is None:
+        return True
+    text = args.strip()
+    return text.startswith("(") and text.endswith(")")
+
+
+def _resolve_rows() -> Optional[List[Dict[str, Optional[str]]]]:
+    """Process-table rows that are a running Resolve application."""
+    table = _process_table()
+    if table is None:
+        return None
+    matched = []
+    for row in table:
+        args = row.get("args")
+        comm = row.get("comm")
+        by_args = args is not None and not _argv_unreadable(args) and _is_resolve_command(args)
+        by_comm = comm is not None and _matches_pattern(comm.strip())
+        if by_args or by_comm:
+            matched.append(row)
+    return matched
+
+
 def resolve_processes() -> Optional[List[str]]:
-    """Command lines of running Resolve applications, or None if undeterminable."""
-    lines = _process_lines()
-    if lines is None:
+    """Command lines of running Resolve applications, or None if undeterminable.
+
+    A row whose argv is unreadable reports its executable path instead, so a
+    caller still sees WHICH Resolve is up even when it cannot see how it was
+    started.
+    """
+    rows = _resolve_rows()
+    if rows is None:
         return None
-    return [line for line in lines if _is_resolve_command(line)]
+    return [row["args"] if not _argv_unreadable(row.get("args")) else (row.get("comm") or "")
+            for row in rows]
 
 
 #: Where the scripting library sits relative to the Resolve executable. The
@@ -212,8 +322,8 @@ def runtime_mode() -> Dict[str, Any]:
     the process list unavailable. Callers must not read None as False; a wrong
     "it has a UI" is what makes an agent wait for a dialog that will never open.
     """
-    processes = resolve_processes()
-    if processes is None:
+    rows = _resolve_rows()
+    if rows is None:
         return {
             "determinable": False,
             "running": None,
@@ -221,7 +331,7 @@ def runtime_mode() -> Dict[str, Any]:
             "instances": None,
             "command_lines": [],
         }
-    if not processes:
+    if not rows:
         return {
             "determinable": True,
             "running": False,
@@ -229,15 +339,23 @@ def runtime_mode() -> Dict[str, Any]:
             "instances": 0,
             "command_lines": [],
         }
+    readable = [row["args"] for row in rows if not _argv_unreadable(row.get("args"))]
+    # Any headless instance makes the reachable one headless: only one Resolve
+    # can hold the singleton, so a second is a conflict to report rather than
+    # a mode to average. An instance counted on its executable path alone has
+    # an argv this process cannot read, so unless another instance shows the
+    # flag the mode is UNKNOWN — None, never False: a wrong "it has a UI" is
+    # what makes an agent wait for a dialog that will never open.
+    headless: Optional[bool] = any(HEADLESS_FLAG in line for line in readable)
+    if not headless and len(readable) < len(rows):
+        headless = None
     return {
         "determinable": True,
         "running": True,
-        # Any headless instance makes the reachable one headless: only one
-        # Resolve can hold the singleton, so a second is a conflict to report
-        # rather than a mode to average.
-        "headless": any(HEADLESS_FLAG in line for line in processes),
-        "instances": len(processes),
-        "command_lines": processes,
+        "headless": headless,
+        "instances": len(rows),
+        "command_lines": [row["args"] if not _argv_unreadable(row.get("args"))
+                          else (row.get("comm") or "") for row in rows],
     }